SSHClient Class
Properties Methods Events Configuration Settings Errors
The SSHClient class provides client-side SSH protocol functionality.
Syntax
SSHClient
Remarks
Use SSHClient to establish terminal-like connections to remote systems and run commands remotely. The component supports most of third-party implementations out there, and is capable of working in "shell" and "command" modes.
Start with assigning your sign-in credentials to Username and Password properties. Where public key authentication is to be used, assign your private authentication key to Key property (remember to set Username in this case too). Subscribe to events to be notified of the session progress. AuthFailed, AuthSucceeded, and Connect are among those particularly useful.
Special attention should be paid to setting up the server key trust. Class only allows connections to servers whose public keys are recognized as trusted, much like any other SSH clients do. Assign a path to the file containing the list of trusted keys to TrustedKeysFile property. If you don't have such file, or if you would like to make trust decisions on the fly, subscribe to KnownKeyReceived and UnknownKeyReceived events. These are fired whenever a trusted or untrusted key is received from the server. For unknown/untrusted keys, you need to set the Action parameter in your UnknownKeyReceived event handler to catAcceptOnce (1) or catAcceptPermanently (2) for the connection to proceed.
Once you are all set up, you can go ahead by calling the Connect method. This launches the SSH handshake and, if everything has been set up right, establishes a connection to the server. You can now use Send and Receive methods to exchange information with the server. You can exchange data in synchronous or asynchronous way; see the description in AsyncMode topic to learn more about each mode.
When you are done with the session, call Disconnect to shut the connection down.
Hint: If you are only interested in a quick-and-dirty execution of a simple, non-interactive command, SSHClient offers a handy shortcut. ConnectAndExec method is a self-contained mechanism which sets up a connection, performs the data exchange internally, and returns the command output. Please keep in mind that you still need to set up the server trust settings as described above for this method to work.
Property List
The following is the full list of the properties of the class with short descriptions. Click on the links for further details.
AsyncMode | Controls the SSH clients mode of work. |
AuthAttempts | Specifies the number of SSH password authentication attempts. |
Commands | Specifies the list of commands to execute. |
Connected | Specifies whether the client is connected to the SFTP server. |
ConnInfoClientKeyAlgorithm | Specifies the client's key algorithm. |
ConnInfoClientKeyBits | Specifies the length of the client's key. |
ConnInfoClientKeyFingerprint | The fingerprint (hash value) of the client's public key. |
ConnInfoCloseReason | Contains the line sent by the server just before closing the connection. |
ConnInfoCompressionAlgorithmInbound | Compression algorithm for the incoming traffic. |
ConnInfoCompressionAlgorithmOutbound | Compression algorithm for the outgoing traffic. |
ConnInfoEncryptionAlgorithmInbound | Encryption algorithm for the incoming traffic. |
ConnInfoEncryptionAlgorithmOutbound | Encryption algorithm for the outgoing traffic. |
ConnInfoInboundEncryptionKeyBits | Specifies the length of the key used to encrypt the incoming traffic. |
ConnInfoKexAlgorithm | The key exchange algorithm used during the SSH handshake. |
ConnInfoKexBits | The number of bits used by the key exchange algorithm. |
ConnInfoKexLines | The contents of the received KexInit packet. |
ConnInfoMacAlgorithmInbound | MAC algorithm used for the incoming connection. |
ConnInfoMacAlgorithmOutbound | MAC algorithm used for outbound connection. |
ConnInfoOutboundEncryptionKeyBits | Specifies the length of the key used to encrypt the outgoing traffic. |
ConnInfoPublicKeyAlgorithm | Specifies the public key algorithm which was used during the SSH handshake. |
ConnInfoServerKeyBits | Specifies the number of bits in the server's key. |
ConnInfoServerKeyFingerprint | The fingerprint (hash value) of the server's public key. |
ConnInfoServerSoftwareName | Returns the name of the SSH software running on the server side. |
ConnInfoTotalBytesReceived | Returns the total number of bytes received over this connection. |
ConnInfoTotalBytesSent | Returns the total number of bytes sent over this connection. |
ConnInfoVersion | Specifies SSH protocol version. |
ExitMessage | Contains the last commands exit message. |
ExitSignal | Contains the last commands exit signal. |
ExitStatus | Contains the last commands exit status. |
ExternalCryptoCustomParams | Custom parameters to be passed to the signing service (uninterpreted). |
ExternalCryptoData | Additional data to be included in the async state and mirrored back by the requestor. |
ExternalCryptoExternalHashCalculation | Specifies whether the message hash is to be calculated at the external endpoint. |
ExternalCryptoHashAlgorithm | Specifies the request's signature hash algorithm. |
ExternalCryptoKeyID | The ID of the pre-shared key used for DC request authentication. |
ExternalCryptoKeySecret | The pre-shared key used for DC request authentication. |
ExternalCryptoMethod | Specifies the asynchronous signing method. |
ExternalCryptoMode | Specifies the external cryptography mode. |
ExternalCryptoPublicKeyAlgorithm | Provide public key algorithm here if the certificate is not available on the pre-signing stage. |
KeyFingerprintSHA1 | Contains the SHA-1 fingerprint (hash) of the key. |
KeyFingerprintSHA256 | Contains the SHA-256 fingerprint (hash) of the key. |
KeyHandle | Allows to get or set a 'handle', a unique identifier of the underlying property object. |
Password | Specifies user's password on the server. |
ProxySettingsAddress | The IP address of the proxy server. |
ProxySettingsAuthentication | The authentication type used by the proxy server. |
ProxySettingsPassword | The password to authenticate to the proxy server. |
ProxySettingsPort | The port on the proxy server to connect to. |
ProxySettingsProxyType | The type of the proxy server. |
ProxySettingsRequestHeaders | Contains HTTP request headers for WebTunnel and HTTP proxy. |
ProxySettingsResponseBody | Contains the HTTP or HTTPS (WebTunnel) proxy response body. |
ProxySettingsResponseHeaders | Contains response headers received from an HTTP or HTTPS (WebTunnel) proxy server. |
ProxySettingsUseIPv6 | Specifies whether IPv6 should be used when connecting through the proxy. |
ProxySettingsUseProxy | Enables or disables proxy-driven connection. |
ProxySettingsUsername | Specifies the username credential for proxy authentication. |
ServerKeyAlgorithm | Specifies the key algorithm. |
ServerKeyBits | The number of bits in the key: the more the better, 2048 or 4096 are typical values. |
ServerKeyComment | The comment for the public key. |
ServerKeyCurve | Specifies the elliptical curve when EC cryptography is used. |
ServerKeyDSSG | The G (Generator) parameter of the DSS signature key. |
ServerKeyDSSP | The P (Prime) parameter of the DSS signature key. |
ServerKeyDSSQ | The Q (Prime Factor) parameter of the DSS signature key. |
ServerKeyDSSX | The X (Private key) parameter of the DSS signature key. |
ServerKeyDSSY | The Y (Public key) parameter of the DSS signature key. |
ServerKeyECCD | The value of the secret key (the order of the public key, D) if elliptic curve (EC) cryptography is used. |
ServerKeyECCQX | The value of the X coordinate of the public key if elliptic curve (EC) cryptography is used. |
ServerKeyECCQY | The value of the Y coordinate of the public key if elliptic curve (EC) cryptography is used. |
ServerKeyEdPrivate | The value of the private key if EdDSA (Edwards-curve Digital Signature Algorithm) algorithm is used. |
ServerKeyEdPublic | The value of the public key if EdDSA (Edwards-curve Digital Signature Algorithm) algorithm is used. |
ServerKeyFingerprintMD5 | Contains the MD5 fingerprint (hash) of the key. |
ServerKeyFingerprintSHA1 | Contains the SHA-1 fingerprint (hash) of the key. |
ServerKeyFingerprintSHA256 | Contains the SHA-256 fingerprint (hash) of the key. |
ServerKeyHandle | Allows to get or set a 'handle', a unique identifier of the underlying property object. |
ServerKeyIsExtractable | Whether the key is extractable (e. |
ServerKeyIsPrivate | Whether this key is a private key or not. |
ServerKeyIsPublic | Whether this key is a public key or not. |
ServerKeyKDFRounds | Returns the number of iterations of the Key Derivation Function (KDF) used to generate this key. |
ServerKeyKDFSalt | The salt value used by the Key Derivation Function (KDF) to generate this key. |
ServerKeyKeyFormat | Specifies the format in which the key is stored. |
ServerKeyKeyProtectionAlgorithm | Specifies the key protection algorithm. |
ServerKeyRSAExponent | Returns the e parameter (public exponent) of the RSA key. |
ServerKeyRSAIQMP | Returns the iqmp parameter of the RSA key. |
ServerKeyRSAModulus | Returns the m parameter (public modulus) of the RSA key. |
ServerKeyRSAP | Returns the p parameter (first factor of the common modulus n) of the RSA key. |
ServerKeyRSAPrivateExponent | Returns the d parameter (private exponent) of the RSA key. |
ServerKeyRSAQ | Returns the q parameter (second factor of the common modulus n) of the RSA key. |
ServerKeySubject | Specifies the public key owner (subject). |
SocketDNSMode | Selects the DNS resolver to use: the class's (secure) built-in one, or the one provided by the system. |
SocketDNSPort | Specifies the port number to be used for sending queries to the DNS server. |
SocketDNSQueryTimeout | The timeout (in milliseconds) for each DNS query. |
SocketDNSServers | The addresses of DNS servers to use for address resolution, separated by commas or semicolons. |
SocketDNSTotalTimeout | The timeout (in milliseconds) for the whole resolution process. |
SocketIncomingSpeedLimit | The maximum number of bytes to read from the socket, per second. |
SocketLocalAddress | The local network interface to bind the socket to. |
SocketLocalPort | The local port number to bind the socket to. |
SocketOutgoingSpeedLimit | The maximum number of bytes to write to the socket, per second. |
SocketTimeout | The maximum period of waiting, in milliseconds, after which the socket operation is considered unsuccessful. |
SocketUseIPv6 | Enables or disables IP protocol version 6. |
SSHSettingsAutoAdjustCiphers | Whether the SSH client should adjust its list of supported ciphers 'on-the-fly' for greater compatibility with the server it is connecting to. |
SSHSettingsBaseConfiguration | Allows to choose base configuration of SSH settings, tuned up for different purposes such as high security or higher compatibility. |
SSHSettingsCompressionAlgorithms | A list of session compression algorithms separated with commas or semicolons. |
SSHSettingsCompressionLevel | Possible values for the Compression Level range from 0 (minimum compression) to 9 (maximum compression). |
SSHSettingsDefaultWindowSize | The SSH window size specifies how many bytes the client can send to the server in the command channel without obtaining pre-authorization for the further send from the server. |
SSHSettingsEncryptionAlgorithms | A list of session encryption algorithms separated with commas or semicolons. |
SSHSettingsForceCompression | Whether the SSH client should explicitly request compression. |
SSHSettingsGSSAuthTypes | A comma-separated list of authentication types. |
SSHSettingsGSSDelegateCreds | Switches credential delegation on or off. |
SSHSettingsGSSHostname | The GSS host name, in form of a FQDN (e. |
SSHSettingsGSSLib | A path to the GSS-API library (DLL or SO). |
SSHSettingsGSSMechanisms | A comma-separated list of GSS mechanisms to use. |
SSHSettingsGSSProtocols | A comma-separated list of SSPI protocols. |
SSHSettingsHandshakeTimeout | Specifies the maximal time for the SSH handshake to proceed, in seconds. |
SSHSettingsKexAlgorithms | A list of key exchange algorithms separated with commas or semicolons. |
SSHSettingsMacAlgorithms | A list of MAC (for message authentication code ) algorithms separated with commas or semicolons. |
SSHSettingsMaxSSHPacketSize | Specifies the maximum length of one SSH packet in bytes. |
SSHSettingsMinWindowSize | Specifies the minimal internal window size. |
SSHSettingsObfuscateHandshake | Enables or disables handshake obfuscation. |
SSHSettingsObfuscationPassword | Specifies the password used to encrypt the handshake when ObfuscateHandshake is set. |
SSHSettingsPublicKeyAlgorithms | A list of public key algorithms separated with commas or semicolons. |
SSHSettingsRequestPasswordChange | Whether to request a password change when connecting. |
SSHSettingsSoftwareName | The name to be used by the class to identify itself. |
SSHSettingsTrustAllKeys | Enables or disables explicit trust to all server keys. |
SSHSettingsUseAuthAgent | Enables or disables the use of external key agent, such as Putty key agent. |
SSHSettingsVersions | Specifies enabled SSH protocol versions (1 or 2). |
Subsystem | Specifies the subsystem to request from the server. |
TerminalCols | Specifies the width of the pseudoterminal, in characters. |
TerminalEnvironment | Specifies the list of environment variables. |
TerminalEOLChar | Specifies the End-of-Line character or sequence. |
TerminalHeight | Specifies the height of the pseudoterminal, in pixels. |
TerminalOpcodes | Specifies the operation codes specific for the terminal. |
TerminalProtocol | The terminal protocol name. |
TerminalRequestPty | Specifies whether to request a pseudoterminal for the session. |
TerminalRows | Specifies the height of the pseudoterminal, in lines. |
TerminalWidth | Specifies the width of the pseudoterminal, in pixels. |
TrustedKeysFile | Path to the file containing public keys of authorized servers. |
Username | Specifies client's username on the server. |
Method List
The following is the full list of the methods of the class with short descriptions. Click on the links for further details.
Config | Sets or retrieves a configuration setting. |
Connect | Establishes connection to an SSH server. |
ConnectAndExec | Connects to an SSH server and executes a command in one go. |
Disconnect | Closes connection to the SSH server. |
Ping | Sends a keep-alive request to the SSH server. |
Poll | Checks whether there is any inbound data readily available. |
Receive | Reads a portion of received data into a string. |
ReceiveBytes | Reads a portion of received data into a byte array. |
ReceiveBytesFrom | Reads a portion of data received via a specific channel into a byte array. |
ReceiveFrom | Reads a portion of data received via a specific channel into a string. |
Send | Sends a string to the server. |
SendBytes | Sends an array of bytes to the server. |
SendSpecial | Sends a special character to the server or remote command. |
Event List
The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.
AuthAttempt | Fires when a single authentication attempt is performed. |
AuthFailed | Fires when a single authentication attempt is failed. |
AuthSucceeded | Reports a successful authentication. |
Banner | Reports the receipt of the Hello message from the server. |
CommandCompleted | Signifies completion of the command execution. |
CommandStart | Marks the commencement of a command execution. |
Connect | This event is fired when an SSH session has been established. |
DataReceived | Reports receipt of another chunk of data from the server. |
DataSent | Notifies the application that a piece of data has been sent to the server. |
Disconnect | This event is fired when the SFTP subsystem connection is closed. |
Error | Information about errors during SFTP connection. |
ExternalSign | Handles remote or external signing initiated by the SignExternal method or other source. |
KnownKeyReceived | This event is fired when a known SSH key is received from the server. |
Notification | This event notifies the application about an underlying control flow event. |
PasswordChangeRequest | This event is fired when a password change is requested. |
PrivateKeyNeeded | This event is fired when client's public key was accepted by the server, but the corresponding secret key is not available. |
UnknownKeyReceived | This event is fired when an unknown SSH key is received from the server. |
Configuration Settings
The following is a list of configuration settings for the class with short descriptions. Click on the links for further details.
BlockSize | The data block size. |
ErrorOrigin | Specifies whether the error is local or remote. |
ErrorSeverity | Specifies whether the error is fatal. |
LocalCharset | Charset used on the client machine. |
RemoteCharset | Charset used on the server. |
SendCommandEOF | Defines whether EOF control character should be sent after the command data. |
ThrottleControl | Enables or disables throttle control for the connection. |