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:
Constant 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_SSL Either SSL 2.0 or SSL 3.0 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, TLS will be excluded from the list of supported protocols. Both SSL 2.0 and 3.0 have been deprecated and will never be used unless explicitly specified. It is not recommended that you enable either of these protocols for secure connections because it will cause most servers to reject your connection request, even if a version of TLS is also specified.
SECURITY_PROTOCOL_TLS Either the TLS 1.0, 1.1 or 1.2 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 that 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 is the recommended version of TLS to use with secure connections.
SECURITY_PROTOCOL_SSH Either version 1.0 or 2.0 of the Secure Shell protocol should be used when establishing the connection. The correct protocol is automatically selected based on the version of the protocol that is supported by the server.
SECURITY_PROTOCOL_SSH1 The Secure Shell 1.0 protocol should be used when establishing the connection. This is an older version of the protocol which should not be used unless explicitly required by the server. Most modern SSH server support version 2.0 of the protocol.
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 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:
Constant 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 PKCS12 (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 VeriSign and Thawte 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 VeriSign and Thawte 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 function 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 function 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 function 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 GetLastError.

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: cstools10.h
Import Library: csftpv10.lib
Unicode: Implemented as Unicode and ANSI versions.

See Also

Connect, DeleteSecurityCredentials, GetSecurityInformation, SECURITYCREDENTIALS

  
 

Copyright © 2023 Catalyst Development Corporation. All rights reserved.