CFtpClient::CreateSecurityCredentials Method  
 
BOOL CreateSecurityCredentials(
  DWORD dwProtocol,  
  DWORD dwOptions,  
  LPCTSTR lpszUserName,  
  LPCTSTR lpszPassword,  
  LPCTSTR lpszCertStore,  
  LPCTSTR lpszCertName  
);
BOOL CreateSecurityCredentials(
  LPCTSTR lpszCertStore,  
  LPCTSTR lpszCertName  
);
BOOL CreateSecurityCredentials(
  LPCTSTR lpszCertName  
);

The CreateSecurityCredentials method establishes the security credentials for the client session.

Parameters

dwProtocol
A bitmask of supported security protocols. This parameter is constructed by using a bitwise operator with any of the following values:
Value Description
SECURITY_PROTOCOL_DEFAULT The default security protocol will be used when establishing a connection. This option will always request the latest version of the preferred security protocol and is the recommended value. Currently the default security protocol is TLS 1.2.
SECURITY_PROTOCOL_TLS Either the TLS 1.2 or 1.3 protocol should be used when establishing a secure connection. The correct protocol is automatically selected, based on what version of the protocol is supported by the server. If this is the only protocol specified, SSL will be excluded from the list of supported protocols. This may be necessary for some servers which reject any attempt to use the older SSL protocol and require that only TLS be used.
SECURITY_PROTOCOL_TLS10 The TLS 1.0 protocol should be used when establishing a secure connection. This version is supported on all Windows platforms, however some servers may reject connections using version 1.0 in favor of using version 1.2. This version should only be used for backwards compatibility with older servers that have not been updated to use the current version of TLS.
SECURITY_PROTOCOL_TLS11 The TLS 1.1 protocol should be used when establishing a secure connection. This version is supported on Windows 7 and later desktop platforms, and Windows Server 2008 R2 and later server platforms. Some servers may reject connections using version 1.1 in favor of using version 1.2. This version should only be used for backwards compatibility with older servers that have not been updated to use the current version of TLS.
SECURITY_PROTOCOL_TLS12 The TLS 1.2 protocol should be used when establishing a secure connection. This version is supported on Windows 7 and later desktop platforms, and Windows Server 2008 R2 and later server platforms. This version of TLS offers the broadest compatibility with most servers.
SECURITY_PROTOCOL_TLS13 The TLS 1.3 protocol should be used when establishing a secure connection. This is the newest version of the protocol and is only supported on Windows 11, Windows Server 2022 and later versions of Windows. If this version is not supported by the operating system, TLS 1.2 will be used instead.
SECURITY_PROTOCOL_SSH2 The Secure Shell 2.0 protocol should be used when establishing the connection. This is the default version of the protocol that is supported by most SSH servers.
dwOptions
A value which specifies one or more options. This value should always be zero for connections using SSH. This member is constructed by using a bitwise operator with any of the following values:
Value Description
CREDENTIAL_STORE_CURRENT_USER The library will attempt to open a store for the current user using the certificate store name provided in this structure. If no options are specified, then this is the default behavior.
CREDENTIAL_STORE_LOCAL_MACHINE The library will attempt to open a local machine store using the certificate store name provided in this structure. If this option is specified, the library will always search for a local machine store before searching for the store by that name for the current user.
CREDENTIAL_STORE_FILENAME The certificate store name is a file that contains the certificate and private key that will be used.
lpszUserName
A pointer to a string which specifies the certificate owner's username. A value of NULL specifies that no username is required. Currently this parameter is not used and any value specified will be ignored.
lpszPassword
A pointer to a string which specifies the certificate owner's password. A value of NULL specifies that no password is required.  This parameter is only used if a PKCS #12 (PFX) certificate file is specified and that certificate has been secured with a password. This value will be ignored the current user or local machine certificate store is specified.
lpszCertStore
A pointer to a string which specifies the name of the certificate store to open. A certificate store is a collection of certificates and their private keys, typically organized by how they are used. If this value is NULL or points to an empty string, the default certificate store "MY" will be used.
Store Name Description
CA Certification authority certificates. These are certificates that are issued by entities which are entrusted to issue certificates to other individuals or organizations. Companies such as Comodo and DigiCert act as certification authorities.
MY Personal certificates and their associated private keys for the current user. This store typically holds the client certificates used to establish a user's credentials. This corresponds to the "Personal" store that is displayed by the certificate manager utility and is the default store used by the library.
ROOT Certificates that have been self-signed by a certificate authority. Root certificates for a number of different certification authorities such as Comodo and DigiCert are installed as part of the operating system and periodically updated by Microsoft.
lpszCertName
A pointer to a null terminated string which specifies the name of the certificate to use. The method will first search the certificate store for a certificate with a matching "friendly name"; this is a name for the certificate that is assigned by the user. Note that the name must match completely, but the comparison is not case sensitive. If no matching certificate is found, the method will then attempt to find a certificate that has a matching common name (also called the certificate subject). This comparison is less stringent, and the first partial match will be returned. If this second search fails, the method will return an error indicating that the certificate could not be found.

Return Value

If the method succeeds, the return value is non-zero. If the method fails, the return value is zero. To get extended error information, call the GetLastError method.

Remarks

A client application only needs to call this method if the server requires that the client provide a certificate as part of the process of negotiating the secure session. If a certificate is required, note that it must have a private key associated with it. Attempting to use a certificate that does not have a private key will result in an error during the connection process indicating that the client credentials could not be established.

If you are using a local certificate store, with the certificate and private key stored in the registry, you can explicitly specify whether the certificate store for the current user or the local machine (all users) should be used. This is done by prefixing the certificate store name with "HKCU:" for the current user, or "HKLM:" for the local machine. For example, a certificate store name of "HKLM:MY" would specify the personal certificate store for the local machine, rather than the current user. If neither prefix is specified, then it will default to the certificate store for the current user. You can manage these certificates using the CertMgr.msc Microsoft Management Console (MMC) snap-in.

It is possible to load the certificate from a file rather than from current user's certificate store. The dwOptions parameter should be set to CREDENTIAL_STORE_FILENAME and the lpszCertStore parameter should specify the name of the file that contains the certificate and its private key. The file must be in Private Information Exchange (PFX) format, also known as PKCS #12.These certificate files typically have an extension of .pfx or .p12. If a password was specified when the certificate was created, it must be provided in the lpszPassword parameter or the library will be unable to access the certificate.

Note that the lpszUserName and lpszPassword parameters are optional values which are used to access the certificate store or client certificate. They are not the credentials which are used when establishing the connection with the remote host or authenticating the client session. In most cases, these parameters can be NULL or omitted.

Example

pClient->CreateSecurityCredentials(
            SECURITY_PROTOCOL_DEFAULT,
            0,
            NULL,
            NULL,
            lpszCertStore,
            lpszCertName);

bConnected = pClient->Connect(lpszHostName,
                              FTP_PORT_SECURE,
                              FTP_TIMEOUT,
                              FTP_OPTION_SECURE);

Requirements

Minimum Desktop Platform: Windows 7 Service Pack 1
Minimum Server Platform: Windows Server 2008 R2 Service Pack 1
Header File: cstools11.h
Import Library: csftpv11.lib
Unicode: Implemented as Unicode and ANSI versions

See Also

Connect, DeleteSecurityCredentials, GetSecurityInformation, SECURITYCREDENTIALS

  
 

Copyright © 2025 Catalyst Development Corporation. All rights reserved.