What the Class Is Used For

Use Chilkat.Ssh when an application needs direct SSH protocol access. It can run remote commands, start interactive shell sessions, open direct TCP/IP forwarding channels, connect through an existing SSH tunnel, use HTTP or SOCKS proxies, control allowed SSH algorithms, inspect host key fingerprints, and read stdout/stderr data from SSH channels.

Remote Commands Execute a command with QuickCommand, QuickCmdSend, or the lower-level OpenSessionChannel + SendReqExec sequence.

Interactive Shells Start a shell with QuickShell or by requesting a PTY and shell on a session channel.

Authentication Authenticate by password, private key, password plus private key, secure string, or keyboard-interactive prompts.

Port Forwarding Open direct-tcpip channels or connect to one SSH server through another authenticated SSH connection.

Typical Workflow

Configure connection options such as ConnectTimeoutMs, IdleTimeoutMs, proxy settings, compression, algorithm restrictions, or client identity.
Call Connect(domainName, port) to establish the SSH transport connection.
Optionally inspect the server identity with ServerIdentifier, HostKeyFingerprint, or GetHostKeyFP.
Authenticate with AuthenticatePw, AuthenticatePk, AuthenticatePwPk, secure-string variants, or keyboard-interactive authentication.
Open a channel with OpenSessionChannel, OpenDirectTcpIpChannel, or OpenCustomChannel.
Send a request such as SendReqExec, SendReqShell, SendReqSubsystem, or send channel data directly.
Read channel output with ChannelRead, ChannelReadAndPoll, ChannelReceiveToClose, or ChannelReceiveUntilMatch.
Retrieve accumulated output with GetReceivedText, GetReceivedData, GetReceivedBd, or stderr-specific methods.
Close or release channels as needed, then call Disconnect when finished.

Core Concepts

Concept	Meaning	Important Members
SSH Transport Connection	The encrypted SSH connection to the server. It is established before authentication and before any channels are opened.	Connect, Disconnect, IsConnected, CheckConnection
Authentication	The login step after connecting. Authentication can use password, private key, both password and key, secure strings, or keyboard-interactive prompts.	AuthenticatePw, AuthenticatePk, AuthenticatePwPk, StartKeyboardAuth
Channel	A logical stream inside the SSH connection. Commands, shells, subsystems, and direct TCP/IP forwarding use channels.	OpenSessionChannel, OpenDirectTcpIpChannel, ChannelRead, ChannelSendString
Exec Request	Runs one command on one session channel. It is not an interactive shell.	SendReqExec, QuickCommand, QuickCmdSend
Shell Request	Starts an interactive remote shell. Commands are sent as channel text and usually need line endings.	SendReqPty, SendReqShell, QuickShell, ChannelSendString
Buffered Output	Channel read methods usually report how many bytes are available. The application then retrieves buffered output with separate GetReceived methods.	ChannelRead, GetReceivedText, GetReceivedData, GetReceivedNumBytes
Host Key Fingerprint	Identifies the SSH server’s host key after connecting, allowing the application to verify server identity.	HostKeyFingerprint, GetHostKeyFP

Connection and Transport Settings

Need	Members	Guidance
Connect to SSH server	Connect	Connects to a domain name, IPv4 address, or IPv6 address at the specified SSH port.
Set connect timeout	ConnectTimeoutMs	Maximum time to wait when connecting to the SSH server.
Control idle timeout	IdleTimeoutMs	Operations fail if sending or receiving stops making progress for longer than this value. Default 0 waits indefinitely.
Control total read timeout	ReadTimeoutMs	Limits the total time allowed for reading data, even if data continues to arrive. Default 0 waits indefinitely.
Use a specific local IP or port	ClientIpAddress, ClientPort	Use only when a multi-homed machine or remote system requires a specific local source address or port.
Prefer IPv6	PreferIpv6	Chooses IPv6 over IPv4 when both are available for a domain.
Disable or allow SSH compression	EnableCompression	Enabled by default when the server supports it. Disable when older servers claim compression support but fail during or after connection.
Check connection health	IsConnected, CheckConnection, SendIgnore	IsConnected is the last known state. Use SendIgnore after checking it to better verify that the connection is still valid.
Close SSH connection	Disconnect	Disconnects from the SSH server.

Connection-state reminder: IsConnected can remain true after an idle server-side disconnect until the next SSH operation detects the loss. Use SendIgnore as a lightweight connection check.

Authentication Options

Authentication Type	Methods / Properties	Use When
Password	AuthenticatePw	The server accepts username/password authentication.
Public key	AuthenticatePk	The user’s public key is installed on the server and the matching private key is available as a SshKey.
Password plus private key	AuthenticatePwPk	The server requires both a password and a private key.
SecureString password	AuthenticateSecPw, AuthenticateSecPwPk	The application stores login/password values in SecureString objects.
Keyboard-interactive	StartKeyboardAuth, ContinueKeyboardAuth, UserAuthBanner	The server presents one or more prompts, possibly including a banner message.
Discover supported auth methods	GetAuthMethods	Queries supported methods such as publickey,password,keyboard-interactive. This method intentionally disconnects after querying.
Resolve credentials from secure storage	EnableSecrets	Allows supported password properties and methods to accept secret specifiers beginning with !! for Windows Credential Manager or Apple Keychain lookup.

Password-change handling: If password authentication fails and PasswordChangeRequested is true, retry authentication with the old and new password formatted as |oldPassword|newPassword|.

Authentication Diagnostics

Property	Meaning	Common Values
AuthFailReason	Explains why AuthenticatePw, AuthenticatePk, or AuthenticatePwPk failed.	Transport failure, invalid key, no matching methods, protocol error, incorrect password/private key, already authenticated, or password-change request.
PasswordChangeRequested	Indicates the server requested a password change during authentication.	Retry with old and new password wrapped in vertical bars.
UserAuthBanner	Stores a user-authentication banner received during keyboard-interactive authentication.	Check after StartKeyboardAuth.
LastErrorText	Detailed diagnostic text for the last method or property call.	Include this when reporting authentication problems.

Executing Remote Commands

Approach	Members	Best For
Simplest command execution	QuickCommand	Run one command and receive complete output as text. Internally opens a session channel, sends an exec request, receives to close, and returns text.
Send command and check later	QuickCmdSend, QuickCmdCheck	Start commands and later determine which command/channel completed.
Manual exec sequence	OpenSessionChannel, SendReqExec, ChannelReceiveToClose, GetReceivedText	Full control over command execution, channel reads, stdout/stderr handling, and exit status.
Command character encoding	ReqExecCharset	Controls the charset used for command text sent by SendReqExec, QuickCommand, and QuickCmdSend.
Control character shortcuts	CaretControl	Allows sequences such as ^C or ^D in strings sent to exec or channel-send methods to be interpreted as control characters.

One exec per channel: A session channel exists for a single exec request. Do not call SendReqExec multiple times on the same channel. Open a new session channel for each command.

Interactive Shell Sessions

An interactive shell is different from an exec request. A shell remains open and receives commands sent through the channel. Commands usually need to end with CRLF.

Task	Members	Notes
Start shell quickly	QuickShell	Opens a session channel, requests a PTY, and starts a shell. Returns the channel number.
Open shell manually	OpenSessionChannel, SendReqPty, SendReqShell	Some servers require a PTY before a shell can be started.
Send shell commands	ChannelSendString	Sends command text to the shell. Terminate commands with CRLF as required by the remote shell.
Set environment variable	SendReqSetEnv	Sets an environment variable in the remote shell.
Handle terminal window changes	SendReqWindowChange	Informs the server that the client-side terminal size changed.
Strip terminal color codes	StripColorCodes	Enabled by default. Removes terminal color escape sequences from received text.
TTY modes	SetTtyMode, ClearTtyModes	Adds terminal mode flags to the next SendReqPty call. Usually not needed.

PTY tip: For many automation scenarios, use termType = "dumb" to reduce terminal escape sequences that can interfere with output matching.

Reading Channel Output

Channel read methods do not usually return the data itself. They read data into the channel’s internal receive buffer and return a status or byte count. The application then calls a GetReceived* method to collect the buffered output.

Read Pattern	Methods	Use When
Read with idle timeout	ChannelRead	Waits up to IdleTimeoutMs for incoming data.
Poll for data	ChannelPoll	Waits up to the supplied poll timeout and returns whether more bytes are available.
Read then poll until quiet	ChannelReadAndPoll, ChannelReadAndPoll2	Useful for command output. Wait longer for the first bytes, then use shorter poll intervals once output begins.
Read until channel closes	ChannelReceiveToClose	Good for exec requests where the server closes the channel after command completion.
Read until matching text	ChannelReceiveUntilMatch, ChannelReceiveUntilMatchN	Useful for shells or prompts. Set ReadTimeoutMs to avoid an infinite wait.
Wait for any channel message	WaitForChannelMessage	Waits for data, EOF, CLOSE, or other messages on any channel.

Return Value	Meaning for ChannelRead / ChannelPoll / ChannelReadAndPoll
> 0	Data was received and that many bytes are available to pick up with GetReceivedData or GetReceivedText.
0	EOF has already been received or the channel has already closed.
-1	Error. Check IsConnected, ChannelIsOpen, and LastErrorText.
-2	No additional data arrived before the timeout.

Retrieving Buffered Output

Need	Methods	Behavior
Get received bytes	GetReceivedData, GetReceivedDataN, GetReceivedBd	Retrieves accumulated stdout/channel data and clears the internal receive buffer.
Get received text	GetReceivedText, GetReceivedTextS	Converts accumulated bytes using the supplied charset and clears the returned portion from the buffer.
Peek at received text	PeekReceivedText	Returns text without clearing the internal receive buffer.
Count buffered bytes	GetReceivedNumBytes	Returns the number of bytes currently available for a channel.
Get stderr bytes	GetReceivedStderr	Retrieves accumulated stderr bytes and clears the stderr buffer.
Get stderr text	GetReceivedStderrText	Converts accumulated stderr bytes using the supplied charset.

stdout/stderr note: StderrToStdout defaults to true, so stderr is merged into stdout. Set it to false before reading if the server sends stderr as extended data and the application needs it separately.

Channel State and Lifecycle

Task	Members	Notes
Open a normal session channel	OpenSessionChannel	Most command, shell, PTY, environment, signal, and subsystem operations use session channels.
Check whether a channel is open	ChannelIsOpen	Returns true when the specified channel remains open.
Check EOF received	ChannelReceivedEof	EOF means no more data will arrive from the server, but data may still be sent in the opposite direction.
Check CLOSE received	ChannelReceivedClose	CLOSE means the channel is closed in both directions; no more data should be sent either way.
Send EOF	ChannelSendEof	Indicates no more data will be sent on the channel, while still allowing data to be received.
Send CLOSE	ChannelSendClose	Closes both directions of the channel.
Release channel resources	ChannelRelease	Usually unnecessary, but useful when opening and closing a very large number of channels over a long-running SSH object.
Inspect open channels	NumOpenChannels, GetChannelNumber, GetChannelType	Enumerates currently open channels and their channel types.

Exit Status and Remote Process Control

Need	Members	Notes
Check whether exit status arrived	ChannelReceivedExitStatus	Returns true when an exit status code has been received for the channel.
Get exit status code	GetChannelExitStatus	Call only after ChannelReceivedExitStatus is true.
Send signal to remote process	SendReqSignal	Sends Unix-style signals such as INT, KILL, TERM, or HUP to the remote process/service.

Port Forwarding and Tunneling

Scenario	Method	Meaning
Open direct TCP/IP channel	OpenDirectTcpIpChannel	Opens a direct-tcpip channel. Data sent on the channel is forwarded by the SSH server to the target host and port.
Connect to SSH server through another SSH server	ConnectThroughSsh	Routes the connection to a second SSH server through an existing connected and authenticated SSH object. The second SSH server still requires its own authentication.
Custom channel type	OpenCustomChannel	Opens an application-defined channel type for custom SSH-protocol servers.
Run an SSH subsystem	SendReqSubsystem	Starts a predefined subsystem. SFTP is an example of a subsystem used by the Chilkat SFTP component.

Proxy Support

Proxy Type	Members	Purpose
HTTP proxy	HttpProxyHostname, HttpProxyPort, HttpProxyUsername, HttpProxyPassword, HttpProxyAuthMethod, HttpProxyDomain	Connects to the SSH server through an HTTP proxy. Proxy authentication can use Basic or NTLM.
SOCKS proxy	SocksVersion, SocksHostname, SocksPort, SocksUsername, SocksPassword	Connects through SOCKS4 or SOCKS5. Set SocksVersion to 4 or 5.
Secure proxy credentials	EnableSecrets	Allows supported proxy password properties to resolve values from Windows Credential Manager or Apple Keychain.

Algorithms and Security Controls

Need	Members	Guidance
Restrict allowed algorithms exactly	SetAllowedAlgorithms	Provides a JSON-based way to specify the exact set of algorithms allowed for the SSH connection.
Force cipher choices	ForceCipher	Specifies one cipher or a comma-separated list of acceptable ciphers. The connection fails if the server does not support any specified cipher.
Prefer a host key algorithm	HostKeyAlg	Controls the preferred host key algorithm. Change only when a server compatibility problem requires it.
Inspect host key fingerprint	HostKeyFingerprint, GetHostKeyFP	Use after connecting to verify the SSH server’s identity.
Disable weak MAC algorithms	UncommonOptions = "no-weak-mac-algs"	Removes weaker MAC algorithms from those offered during connection negotiation.
Re-enable etm MAC algorithms	UncommonOptions = "+ssh-hmac-etm"	Re-adds etm MAC algorithms that were disabled by default to mitigate the Terrapin attack.
Re-enable chacha20-poly1305	UncommonOptions = "+chacha20-poly1305@openssh.com"	Re-adds chacha20-poly1305@openssh.com, which is not included by default in newer behavior described by the reference.
Force RSA-SHA1 userauth for older servers	UncommonOptions = "ForceUserAuthRsaSha1"	Compatibility option for servers that support newer RSA SHA-2 algorithms but still require SHA-1 for public-key user authentication.

Algorithm compatibility: Restricting ciphers or algorithms can improve policy compliance, but it can also cause Connect to fail when the server does not support the allowed set.

Supported Algorithm Families

Family	Examples Listed in the Reference
Host key algorithms	ssh-ed25519, rsa-sha2-256, rsa-sha2-512, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521, ssh-rsa, ssh-dss
Key exchange algorithms	curve25519-sha256, curve25519-sha256@libssh.org, ecdh-sha2-nistp*, diffie-hellman-group14-sha256, diffie-hellman-group16-sha512, diffie-hellman-group18-sha512, diffie-hellman-group-exchange-sha256
Ciphers	aes128-ctr, aes256-ctr, aes192-ctr, aes-cbc, aes-gcm@openssh.com, twofish*-cbc, blowfish-cbc, and optionally chacha20-poly1305@openssh.com
MAC algorithms	hmac-sha2-256, hmac-sha2-512, hmac-sha1, hmac-ripemd160, hmac-sha1-96, hmac-md5, and optionally etm variants
Compression	none, zlib, zlib@openssh.com

Rekeying and Long-Lived Connections

Task	Member	Guidance
Initiate SSH re-key	ReKey	Starts a key re-exchange and returns when complete. Servers often initiate re-key automatically, and Chilkat handles it transparently.
Packet size tuning	MaxPacketSize	Defaults to 8192. Larger values such as 32768 may improve performance for large data flow.
Socket buffer tuning	SoRcvBuf, SoSndBuf	Usually left unchanged. Increase cautiously when download or upload performance requires tuning.
Small-message latency	TcpNoDelay	Enabled by default, disabling Nagle’s algorithm for better responsiveness with small SSH messages.

Disconnects, Channel Open Failures, and Diagnostics

Diagnostic Area	Members	What It Tells You
General diagnostic details	LastErrorText	Plain-text diagnostic details for the last method or property access.
Structured diagnostic data	GetLastJsonData	Retrieves JSON details for selected methods when additional structured data is available.
Session log	KeepSessionLog, SessionLog	Captures messages sent to and from the SSH server. Useful for troubleshooting.
Authentication failure	AuthFailReason	Explains why authentication failed.
Channel open failure	ChannelOpenFailCode, ChannelOpenFailReason	Reports RFC 4254 channel-open failure reasons such as administratively prohibited, connect failed, unknown channel type, or resource shortage.
Server disconnect reason	DisconnectCode, DisconnectReason	Reports the SSH disconnect code and descriptive reason sent by the server, if one was sent.
Abort long-running method	AbortCurrent, HeartbeatMs	Allows synchronous or asynchronous network operations to be aborted by the application.

Common Pitfalls

Pitfall	Better Approach
Calling SendReqExec repeatedly on one channel.	Open a new session channel for each exec command. The server closes the channel at the end of the exec request.
Expecting ChannelRead to return output text directly.	Treat the return value as a status/available-byte count, then call GetReceivedText or GetReceivedData.
Relying only on IsConnected.	Use SendIgnore to better test whether an idle connection is still usable.
Waiting forever for a prompt or match pattern.	Set ReadTimeoutMs before using ChannelReceiveUntilMatch or ChannelReceiveUntilMatchN.
Terminal escape codes disrupting shell output parsing.	Use termType = "dumb" with SendReqPty and keep StripColorCodes enabled.
Expecting stderr separation on every server.	Be aware that many SSH servers do not send stderr as extended data. Even with StderrToStdout = false, separation depends on server behavior.
Disabling compression only after authentication fails mysteriously.	For older SSH servers that disconnect after connection establishment, test with EnableCompression = false.

Best Practices

Recommendation	Reason
Set explicit timeout values for production code.	Defaults such as IdleTimeoutMs = 0 and ReadTimeoutMs = 0 can wait indefinitely.
Verify the host key fingerprint after connecting.	SSH security depends on verifying that the server host key is the expected one.
Use QuickCommand for simple one-command workflows.	It hides the channel-management details when complete command output is all that is needed.
Use manual channel methods for shells, prompts, streaming output, or exit-status handling.	Lower-level channel methods provide control over reading, polling, stderr, EOF, CLOSE, and exit status.
Use one channel per exec request.	SSH servers close the exec channel after the command completes.
Retrieve buffered output promptly.	Channel read methods accumulate data internally. Use GetReceivedText, GetReceivedData, or GetReceivedBd to collect and clear it.
Use EnableSecrets to avoid hard-coded passwords where supported.	It allows runtime credential lookup from Windows Credential Manager or Apple Keychain.
Check specialized failure properties in addition to LastErrorText.	AuthFailReason, ChannelOpenFailReason, and DisconnectReason identify the failure phase.
Use ChannelRelease for long-running applications that open many channels.	It releases per-channel internal resources before the SSH object itself is disposed.

Summary

Chilkat.Ssh is the primary SSH client class for connecting to SSH servers, authenticating users, executing commands, running shell sessions, opening port-forwarding channels, reading stdout and stderr, controlling SSH algorithms, using proxies, and diagnosing authentication, transport, channel, and disconnect problems.

For simple remote command execution, use QuickCommand. For interactive shells, prompts, streaming output, subsystems, port forwarding, and detailed channel control, use the lower-level channel methods.

Chilkat.Ssh Class Overview