SecureBlackbox 2020 PHP Edition

Questions / Feedback?

SSHClient Class

Properties   Methods   Events   Configuration Settings   Errors  

The SSHClient class provides client-side SSH protocol functionality.

Class Name

SecureBlackbox_SSHClient

Procedural Interface

 secureblackbox_sshclient_open();
 secureblackbox_sshclient_close($res);
 secureblackbox_sshclient_register_callback($res, $id, $function);
 secureblackbox_sshclient_get_last_error($res);
 secureblackbox_sshclient_get_last_error_code($res);
 secureblackbox_sshclient_set($res, $id, $index, $value);
 secureblackbox_sshclient_get($res, $id, $index);
 secureblackbox_sshclient_do_config($res, $configurationstring);
 secureblackbox_sshclient_do_connect($res, $address, $port);
 secureblackbox_sshclient_do_connectandexec($res, $address, $port, $command, $wantstdout, $wantstderr);
 secureblackbox_sshclient_do_disconnect($res);
 secureblackbox_sshclient_do_ping($res);
 secureblackbox_sshclient_do_poll($res, $milliseconds);
 secureblackbox_sshclient_do_receive($res);
 secureblackbox_sshclient_do_receivebytes($res, $maxlen);
 secureblackbox_sshclient_do_receivebytesfrom($res, $channel, $maxlen);
 secureblackbox_sshclient_do_receivefrom($res, $channel);
 secureblackbox_sshclient_do_send($res, $datastr, $addeol);
 secureblackbox_sshclient_do_sendbytes($res, $data);
 secureblackbox_sshclient_do_sendspecial($res, $specialchar);

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.

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.
ConnInfoClientKeyAlgorithmSpecifies the client's key algorithm.
ConnInfoClientKeyBitsSpecifies the length of the client's key.
ConnInfoClientKeyFingerprintThe fingerprint (hash value) of the client's public key.
ConnInfoCloseReasonContains the line sent by the server just before closing the connection.
ConnInfoCompressionAlgorithmInboundCompression algorithm for the incoming traffic.
ConnInfoCompressionAlgorithmOutboundCompression algorithm for the outgoing traffic.
ConnInfoEncryptionAlgorithmInboundEncryption algorithm for the incoming traffic.
ConnInfoEncryptionAlgorithmOutboundEncryption algorithm for the outgoing traffic.
ConnInfoInboundEncryptionKeyBitsSpecifies the length of the key used to encrypt the incoming traffic.
ConnInfoKexAlgorithmThe key exchange algorithm used during the SSH handshake.
ConnInfoKexBitsThe number of bits used by the key exchange algorithm.
ConnInfoKexLinesThe contents of the received KexInit packet.
ConnInfoMacAlgorithmInboundMAC algorithm used for the incoming connection.
ConnInfoMacAlgorithmOutboundMAC algorithm used for outbound connection.
ConnInfoOutboundEncryptionKeyBitsSpecifies the length of the key used to encrypt the outgoing traffic.
ConnInfoPublicKeyAlgorithmSpecifies the public key algorithm which was used during the SSH handshake.
ConnInfoServerKeyBitsSpecifies the number of bits in the server's key.
ConnInfoServerKeyFingerprintThe fingerprint (hash value) of the server's public key.
ConnInfoServerSoftwareNameReturns the name of the SSH software running on the server side.
ConnInfoTotalBytesReceivedReturns the total number of bytes received over this connection.
ConnInfoTotalBytesSentReturns the total number of bytes sent over this connection.
ConnInfoVersionSpecifies SSH protocol version.
ExitMessageContains the last commands exit message.
ExitSignalContains the last commands exit signal.
ExitStatusContains the last commands exit status.
ExternalCryptoCustomParamsCustom parameters to be passed to the signing service (uninterpreted).
ExternalCryptoDataAdditional data to be included in the async state and mirrored back by the requestor.
ExternalCryptoExternalHashCalculationSpecifies whether the message hash is to be calculated at the external endpoint.
ExternalCryptoHashAlgorithmSpecifies the request's signature hash algorithm.
ExternalCryptoKeyIDThe ID of the pre-shared key used for DC request authentication.
ExternalCryptoKeySecretThe pre-shared key used for DC request authentication.
ExternalCryptoMethodSpecifies the asynchronous signing method.
ExternalCryptoModeSpecifies the external cryptography mode.
ExternalCryptoPublicKeyAlgorithmProvide public key algorithm here if the certificate is not available on the pre-signing stage.
KeyFingerprintSHA1Contains the SHA-1 fingerprint (hash) of the key.
KeyFingerprintSHA256Contains the SHA-256 fingerprint (hash) of the key.
KeyHandleAllows to get or set a 'handle', a unique identifier of the underlying property object.
PasswordSpecifies user's password on the server.
ProxySettingsAddressThe IP address of the proxy server.
ProxySettingsAuthenticationThe authentication type used by the proxy server.
ProxySettingsPasswordThe password to authenticate to the proxy server.
ProxySettingsPortThe port on the proxy server to connect to.
ProxySettingsProxyTypeThe type of the proxy server.
ProxySettingsRequestHeadersContains HTTP request headers for WebTunnel and HTTP proxy.
ProxySettingsResponseBodyContains the HTTP or HTTPS (WebTunnel) proxy response body.
ProxySettingsResponseHeadersContains response headers received from an HTTP or HTTPS (WebTunnel) proxy server.
ProxySettingsUseIPv6Specifies whether IPv6 should be used when connecting through the proxy.
ProxySettingsUseProxyEnables or disables proxy-driven connection.
ProxySettingsUsernameSpecifies the username credential for proxy authentication.
ServerKeyAlgorithmSpecifies the key algorithm.
ServerKeyBitsThe number of bits in the key: the more the better, 2048 or 4096 are typical values.
ServerKeyCommentThe comment for the public key.
ServerKeyCurveSpecifies the elliptical curve when EC cryptography is used.
ServerKeyDSSGThe G (Generator) parameter of the DSS signature key.
ServerKeyDSSPThe P (Prime) parameter of the DSS signature key.
ServerKeyDSSQThe Q (Prime Factor) parameter of the DSS signature key.
ServerKeyDSSXThe X (Private key) parameter of the DSS signature key.
ServerKeyDSSYThe Y (Public key) parameter of the DSS signature key.
ServerKeyECCDThe value of the secret key (the order of the public key, D) if elliptic curve (EC) cryptography is used.
ServerKeyECCQXThe value of the X coordinate of the public key if elliptic curve (EC) cryptography is used.
ServerKeyECCQYThe value of the Y coordinate of the public key if elliptic curve (EC) cryptography is used.
ServerKeyEdPrivateThe value of the private key if EdDSA (Edwards-curve Digital Signature Algorithm) algorithm is used.
ServerKeyEdPublicThe value of the public key if EdDSA (Edwards-curve Digital Signature Algorithm) algorithm is used.
ServerKeyFingerprintMD5Contains the MD5 fingerprint (hash) of the key.
ServerKeyFingerprintSHA1Contains the SHA-1 fingerprint (hash) of the key.
ServerKeyFingerprintSHA256Contains the SHA-256 fingerprint (hash) of the key.
ServerKeyHandleAllows to get or set a 'handle', a unique identifier of the underlying property object.
ServerKeyIsExtractableWhether the key is extractable (e.
ServerKeyIsPrivateWhether this key is a private key or not.
ServerKeyIsPublicWhether this key is a public key or not.
ServerKeyKDFRoundsReturns the number of iterations of the Key Derivation Function (KDF) used to generate this key.
ServerKeyKDFSaltThe salt value used by the Key Derivation Function (KDF) to generate this key.
ServerKeyKeyFormatSpecifies the format in which the key is stored.
ServerKeyKeyProtectionAlgorithmSpecifies the key protection algorithm.
ServerKeyRSAExponentReturns the e parameter (public exponent) of the RSA key.
ServerKeyRSAIQMPReturns the iqmp parameter of the RSA key.
ServerKeyRSAModulusReturns the m parameter (public modulus) of the RSA key.
ServerKeyRSAPReturns the p parameter (first factor of the common modulus n) of the RSA key.
ServerKeyRSAPrivateExponentReturns the d parameter (private exponent) of the RSA key.
ServerKeyRSAQReturns the q parameter (second factor of the common modulus n) of the RSA key.
ServerKeySubjectSpecifies the public key owner (subject).
SocketDNSModeSelects the DNS resolver to use: the class's (secure) built-in one, or the one provided by the system.
SocketDNSPortSpecifies the port number to be used for sending queries to the DNS server.
SocketDNSQueryTimeoutThe timeout (in milliseconds) for each DNS query.
SocketDNSServersThe addresses of DNS servers to use for address resolution, separated by commas or semicolons.
SocketDNSTotalTimeoutThe timeout (in milliseconds) for the whole resolution process.
SocketIncomingSpeedLimitThe maximum number of bytes to read from the socket, per second.
SocketLocalAddressThe local network interface to bind the socket to.
SocketLocalPortThe local port number to bind the socket to.
SocketOutgoingSpeedLimitThe maximum number of bytes to write to the socket, per second.
SocketTimeoutThe maximum period of waiting, in milliseconds, after which the socket operation is considered unsuccessful.
SocketUseIPv6Enables or disables IP protocol version 6.
SSHSettingsAutoAdjustCiphersWhether the SSH client should adjust its list of supported ciphers 'on-the-fly' for greater compatibility with the server it is connecting to.
SSHSettingsBaseConfigurationAllows to choose base configuration of SSH settings, tuned up for different purposes such as high security or higher compatibility.
SSHSettingsCompressionAlgorithmsA list of session compression algorithms separated with commas or semicolons.
SSHSettingsCompressionLevelPossible values for the Compression Level range from 0 (minimum compression) to 9 (maximum compression).
SSHSettingsDefaultWindowSizeThe 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.
SSHSettingsEncryptionAlgorithmsA list of session encryption algorithms separated with commas or semicolons.
SSHSettingsForceCompressionWhether the SSH client should explicitly request compression.
SSHSettingsGSSAuthTypesA comma-separated list of authentication types.
SSHSettingsGSSDelegateCredsSwitches credential delegation on or off.
SSHSettingsGSSHostnameThe GSS host name, in form of a FQDN (e.
SSHSettingsGSSLibA path to the GSS-API library (DLL or SO).
SSHSettingsGSSMechanismsA comma-separated list of GSS mechanisms to use.
SSHSettingsGSSProtocolsA comma-separated list of SSPI protocols.
SSHSettingsHandshakeTimeoutSpecifies the maximal time for the SSH handshake to proceed, in seconds.
SSHSettingsKexAlgorithmsA list of key exchange algorithms separated with commas or semicolons.
SSHSettingsMacAlgorithmsA list of MAC (for message authentication code ) algorithms separated with commas or semicolons.
SSHSettingsMaxSSHPacketSizeSpecifies the maximum length of one SSH packet in bytes.
SSHSettingsMinWindowSizeSpecifies the minimal internal window size.
SSHSettingsObfuscateHandshakeEnables or disables handshake obfuscation.
SSHSettingsObfuscationPasswordSpecifies the password used to encrypt the handshake when ObfuscateHandshake is set.
SSHSettingsPublicKeyAlgorithmsA list of public key algorithms separated with commas or semicolons.
SSHSettingsRequestPasswordChangeWhether to request a password change when connecting.
SSHSettingsSoftwareNameThe name to be used by the class to identify itself.
SSHSettingsTrustAllKeysEnables or disables explicit trust to all server keys.
SSHSettingsUseAuthAgentEnables or disables the use of external key agent, such as Putty key agent.
SSHSettingsVersionsSpecifies enabled SSH protocol versions (1 or 2).
SubsystemSpecifies the subsystem to request from the server.
TerminalColsSpecifies the width of the pseudoterminal, in characters.
TerminalEnvironmentSpecifies the list of environment variables.
TerminalEOLCharSpecifies the End-of-Line character or sequence.
TerminalHeightSpecifies the height of the pseudoterminal, in pixels.
TerminalOpcodesSpecifies the operation codes specific for the terminal.
TerminalProtocolThe terminal protocol name.
TerminalRequestPtySpecifies whether to request a pseudoterminal for the session.
TerminalRowsSpecifies the height of the pseudoterminal, in lines.
TerminalWidthSpecifies the width of the pseudoterminal, in pixels.
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 class 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 class 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 class 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.
CheckKeyIntegrityBeforeUseEnables or disable private key integrity check before use.
CookieCachingSpecifies whether a cookie cache should be used for HTTP(S) transports.
CookiesGets or sets local cookies for the class (supported for HTTPClient, RESTClient and SOAPClient only).
DefDeriveKeyIterationsSpecifies the default key derivation algorithm iteration count.
EnableClientSideSSLFFDHEEnables or disables finite field DHE key exchange support in TLS clients.
GlobalCookiesGets or sets global cookies for all the HTTP transports.
HttpUserAgentSpecifies the user agent name to be used by all HTTP clients.
LogDestinationSpecifies the debug log destination.
LogDetailsSpecifies the debug log details to dump.
LogFileSpecifies the debug log filename.
LogFiltersSpecifies the debug log filters.
LogFlushModeSpecifies the log flush mode.
LogLevelSpecifies the debug log level.
LogMaxEventCountSpecifies the maximum number of events to cache before further action is taken.
LogRotationModeSpecifies the log rotation mode.
MaxASN1BufferLengthSpecifies the maximal allowed length for ASN.1 primitive tag data.
MaxASN1TreeDepthSpecifies the maximal depth for processed ASN.1 trees.
OCSPHashAlgorithmSpecifies the hash algorithm to be used to identify certificates in OCSP requests.
UseOwnDNSResolverSpecifies whether the client classes should use own DNS resolver.
UseSharedSystemStoragesSpecifies whether the validation engine should use a global per-process copy of the system certificate stores.
UseSystemOAEPAndPSSEnforces or disables the use of system-driven RSA OAEP and PSS computations.
UseSystemRandomEnables or disables the use of the OS PRNG.

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