SSHClient Component
Properties Methods Events Configuration Settings Errors
The SSHClient component provides client-side SSH protocol functionality.
Syntax
secureblackbox.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. Component 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 component 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. |
ConnectionInfo | Contains the secure connection info. |
ExitMessage | Contains the last commands exit message. |
ExitSignal | Contains the last commands exit signal. |
ExitStatus | Contains the last commands exit status. |
ExternalCrypto | Provides access to external signing and DC parameters. |
Key | Contains client's SSH key. |
Password | Specifies user's password on the server. |
Proxy | Allows connection through a proxy server. |
ServerKey | Returns server's public key. |
SocketSettings | Manages network connection settings. |
SSHSettings | Provides access to SSH connection settings. |
Subsystem | Specifies the subsystem to request from the server. |
Terminal | Provides access to SSH terminal settings object. |
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 component 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 component 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 component 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. |
CheckKeyIntegrityBeforeUse | Enables or disable private key integrity check before use. |
CookieCaching | Specifies whether a cookie cache should be used for HTTP(S) transports. |
Cookies | Gets or sets local cookies for the component (supported for HTTPClient, RESTClient and SOAPClient only). |
DefDeriveKeyIterations | Specifies the default key derivation algorithm iteration count. |
EnableClientSideSSLFFDHE | Enables or disables finite field DHE key exchange support in TLS clients. |
GlobalCookies | Gets or sets global cookies for all the HTTP transports. |
HttpUserAgent | Specifies the user agent name to be used by all HTTP clients. |
LogDestination | Specifies the debug log destination. |
LogDetails | Specifies the debug log details to dump. |
LogFile | Specifies the debug log filename. |
LogFilters | Specifies the debug log filters. |
LogFlushMode | Specifies the log flush mode. |
LogLevel | Specifies the debug log level. |
LogMaxEventCount | Specifies the maximum number of events to cache before further action is taken. |
LogRotationMode | Specifies the log rotation mode. |
MaxASN1BufferLength | Specifies the maximal allowed length for ASN.1 primitive tag data. |
MaxASN1TreeDepth | Specifies the maximal depth for processed ASN.1 trees. |
OCSPHashAlgorithm | Specifies the hash algorithm to be used to identify certificates in OCSP requests. |
UseOwnDNSResolver | Specifies whether the client components should use own DNS resolver. |
UseSharedSystemStorages | Specifies whether the validation engine should use a global per-process copy of the system certificate stores. |
UseSystemOAEPAndPSS | Enforces or disables the use of system-driven RSA OAEP and PSS computations. |
UseSystemRandom | Enables or disables the use of the OS PRNG. |