SecureBlackbox Lite 2020 Kotlin Edition

Questions / Feedback?

SSHClient Component

Properties   Methods   Events   Configuration Settings   Errors  

The SSHClient component provides client-side SSH protocol functionality.

Syntax

secureblackboxlite.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.

AsyncModeControls the SSH clients mode of work.
AuthAttemptsSpecifies the number of SSH password authentication attempts.
CommandsSpecifies the list of commands to execute.
ConnectedSpecifies whether the client is connected to the SFTP server.
ConnectionInfoContains the secure connection info.
ExitMessageContains the last commands exit message.
ExitSignalContains the last commands exit signal.
ExitStatusContains the last commands exit status.
ExternalCryptoProvides access to external signing and DC parameters.
KeyContains client's SSH key.
PasswordSpecifies user's password on the server.
ProxyAllows connection through a proxy server.
ServerKeyReturns server's public key.
SocketSettingsManages network connection settings.
SSHSettingsProvides access to SSH connection settings.
SubsystemSpecifies the subsystem to request from the server.
TerminalProvides access to SSH terminal settings object.
TrustedKeysFilePath to the file containing public keys of authorized servers.
UsernameSpecifies 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.

ConfigSets or retrieves a configuration setting.
ConnectEstablishes connection to an SSH server.
ConnectAndExecConnects to an SSH server and executes a command in one go.
DisconnectCloses connection to the SSH server.
PingSends a keep-alive request to the SSH server.
PollChecks whether there is any inbound data readily available.
ReceiveReads a portion of received data into a string.
ReceiveBytesReads a portion of received data into a byte array.
ReceiveBytesFromReads a portion of data received via a specific channel into a byte array.
ReceiveFromReads a portion of data received via a specific channel into a string.
SendSends a string to the server.
SendBytesSends an array of bytes to the server.
SendSpecialSends 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.

AuthAttemptFires when a single authentication attempt is performed.
AuthFailedFires when a single authentication attempt is failed.
AuthSucceededReports a successful authentication.
BannerReports the receipt of the Hello message from the server.
CommandCompletedSignifies completion of the command execution.
CommandStartMarks the commencement of a command execution.
ConnectThis event is fired when an SSH session has been established.
DataReceivedReports receipt of another chunk of data from the server.
DataSentNotifies the application that a piece of data has been sent to the server.
DisconnectThis event is fired when the SFTP subsystem connection is closed.
ErrorInformation about errors during SFTP connection.
ExternalSignHandles remote or external signing initiated by the SignExternal method or other source.
KnownKeyReceivedThis event is fired when a known SSH key is received from the server.
NotificationThis event notifies the application about an underlying control flow event.
PasswordChangeRequestThis event is fired when a password change is requested.
PrivateKeyNeededThis event is fired when client's public key was accepted by the server, but the corresponding secret key is not available.
UnknownKeyReceivedThis 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.

BlockSizeThe data block size.
ErrorOriginSpecifies whether the error is local or remote.
ErrorSeveritySpecifies whether the error is fatal.
LocalCharsetCharset used on the client machine.
RemoteCharsetCharset used on the server.
SendCommandEOFDefines whether EOF control character should be sent after the command data.
ThrottleControlEnables or disables throttle control for the connection.

Copyright (c) 2022 /n software inc. - All rights reserved.
SecureBlackbox Lite 2020 Kotlin Edition - Version 20.0 [Build 8063]