SECURITYCREDENTIALS

The SECURITYCREDENTIALS structure specifies the information needed by the library to specify additional security credentials, such as a client certificate or private key, when establishing a secure connection.

typedef struct _SECURITYCREDENTIALS
{
    DWORD    dwSize;
    DWORD    dwProtocol;
    DWORD    dwOptions;
    DWORD    dwReserved;
    LPCTSTR  lpszHostName;
    LPCTSTR  lpszUserName;
    LPCTSTR  lpszPassword;
    LPCTSTR  lpszCertStore;
    LPCTSTR  lpszCertName;
    LPCTSTR  lpszKeyFile;
} SECURITYCREDENTIALS, *LPSECURITYCREDENTIALS;

Members

dwSize

Size of this structure. If the structure is being allocated dynamically, this member must be set to the size of the structure.

dwProtocol

A value which specifies which security protocols are supported:

Value Description

SECURITY_PROTOCOL_SSH2 Version 2.0 of the protocol will be used when establishing the connection. Currently, this is the only supported protocol option for SSH connections. In older versions of SocketTools, you had the option of selecting either version 1.0 or 2.0; however, version 1.0 is no longer considered secure and is not supported.

dwOptions

This structure member is reserved for use with TLS connections and should always be initialized to zero.

dwReserved

This structure member is reserved for future use and should always be initialized to zero.

lpszHostName

A pointer to a null terminated string which specifies the hostname that will be used when validating a server certificate. This member should always be initialized as a NULL pointer for connections using the SSH protocol.

lpszUserName

A pointer to a null terminated string which identifies the owner of client certificate. Currently this member is not used by the library and should always be initialized as a NULL pointer.

lpszPassword

A pointer to a null terminated string which specifies the password needed to access the certificate. Currently this member is only used if a private key file has been specified. If there is no password associated with the certificate, then this member should be initialized as a NULL pointer.

lpszCertStore

A pointer to a null terminated string which specifies the name of the certificate store to open. Although this member can be used to specify the path to a public key file in the OpenSSH format, this is not required. In most cases this member should be initialized as a NULL pointer for connections using the SSH protocol.

lpszCertName

A pointer to a null terminated string which specifies the name of the certificate to use. This member should always be initialized as a NULL pointer for connections using the SSH protocol.

lpszKeyFile

A pointer to a null terminated string which specifies the name of the file which contains the private key required to establish the connection. This member is only used with the SSH protocol. If the member is NULL, then no private key is used. The private key file must be in the standard PEM format defined in RFC 1422. Both the standard RSA private key format and the proprietary OpenSSH format are supported.

Remarks

When using the C++ class, you do not need to explicitly define this structure. Instead, you can use the CreateSecurityCredentials method to specify the private key file. If the private key is protected with a password, the lpszPassword parameter must specify that value or the connection request will fail with an authentication error.

The lpszKeyFile path can use environment variables enclosed in percent symbols, and the path to the private key file will be normalized. It is recommended you always use an absolute path to the private key file. If you do not include a path, it will use the current working directory for the process. This can produce inconsistent results with multithreaded applications because the current working directory for a process is a global value and it can be changed by any thread at any time.

Example

CSshClient sshClient;
LPCTSTR lpszKeyFile = _T("%USERPROFILE%\\.ssh\\id_rsa.pem");

// Create the SECURITYCREDENTIALS structure and specify the
// path to the private key file for the current user
if (!sshClient.CreateSecurityCredentials(lpszKeyFile))
{
    sshClient.ShowError();
    return;
}

// Establish a connection with the SSH server on port 22
bConnected = sshClient.Connect(strHostName,
                               SSH_PORT_DEFAULT,
                               strUserName,
                               NULL, // No password, using a private key file
                               SSH_TIMEOUT,
                               SSH_OPTION_KEEPALIVE);

// If the connection attempt fails, then get a description of
// the error and display it in a message box

if (!bConnected)
{
    sshClient.ShowError();
    return;
}

In this example, the path to the private key file will be expanded to an absolute path because the USERPROFILE environment variable defines the home directory for the current user. The path must resolve to a normal file which that can be read by the current process. If the file does not exist, or it does not specify a PEM formatted file which contains an RSA or OpenSSH private key, the connection will fail and the last error code will be set to ST_ERROR_INVALID_PRIVATE_KEY.

Requirements

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

Members

Remarks

Example

Requirements

See Also