SshTunnel Delphi DLL Reference Documentation

SshTunnel

Current Version: 9.5.0.97

The SSH tunnel class provides for the ability to run a self-contained SSH tunnel in a background thread. It can behave as a SOCKS proxy, accepting connections from SOCKS4 or SOCK5 proxy clients and fowarding connections through an SSH tunnel. This is the "dynamic port forwarding" mode of operation. It can also behave in a static port forwarding mode (where it accepts connections and forwards the connection to a pre-defined remote destination IP:port).

Create/Dispose

var
myObject: HCkSshTunnel;

begin
myObject := CkSshTunnel_Create();

// ...

CkSshTunnel_Dispose(myObject);
end;
function CkSshTunnel_Create: HCkSshTunnel; stdcall;

Creates an instance of the HCkSshTunnel object and returns a handle (i.e. a Pointer). The handle is passed in the 1st argument for the functions listed on this page.

procedure CkSshTunnel_Dispose(handle: HCkSshTunnel); stdcall;

Objects created by calling CkSshTunnel_Create must be freed by calling this method. A memory leak occurs if a handle is not disposed by calling this function.

Properties

AbortCurrent
function CkSshTunnel_getAbortCurrent(objHandle: HCkSshTunnel): wordbool; stdcall;
procedure CkSshTunnel_putAbortCurrent(objHandle: HCkSshTunnel; newPropVal: wordbool); stdcall;
Introduced in version 9.5.0.58

When set to True, causes the currently running method to abort. Methods that always finish quickly (i.e.have no length file operations or network communications) are not affected. If no method is running, then this property is automatically reset to False when the next method is called. When the abort occurs, this property is reset to False. Both synchronous and asynchronous method calls can be aborted. (A synchronous method call could be aborted by setting this property from a separate thread.)

top
AcceptLog
procedure CkSshTunnel_getAcceptLog(objHandle: HCkSshTunnel; outPropVal: HCkString); stdcall;
procedure CkSshTunnel_putAcceptLog(objHandle: HCkSshTunnel; newPropVal: PWideChar); stdcall;
function CkSshTunnel__acceptLog(objHandle: HCkSshTunnel): PWideChar; stdcall;

Contains an in-memory log of the listen thread. This will only contain content if the KeepAcceptLog property is True.

top
AcceptLogPath
procedure CkSshTunnel_getAcceptLogPath(objHandle: HCkSshTunnel; outPropVal: HCkString); stdcall;
procedure CkSshTunnel_putAcceptLogPath(objHandle: HCkSshTunnel; newPropVal: PWideChar); stdcall;
function CkSshTunnel__acceptLogPath(objHandle: HCkSshTunnel): PWideChar; stdcall;
Introduced in version 9.5.0.50

Specifies a log file to be kept for the activity in the listen thread.

top
ClientIdentifier
procedure CkSshTunnel_getClientIdentifier(objHandle: HCkSshTunnel; outPropVal: HCkString); stdcall;
procedure CkSshTunnel_putClientIdentifier(objHandle: HCkSshTunnel; newPropVal: PWideChar); stdcall;
function CkSshTunnel__clientIdentifier(objHandle: HCkSshTunnel): PWideChar; stdcall;
Introduced in version 9.5.0.95

The client-identifier string to be used when connecting to an SSH server. Defaults to "SSH-2.0-PuTTY_Release_0.78". (This string is used to mimic PuTTY because some servers are known to disconnect from clients with unknown client identifiers.)

top
ConnectTimeoutMs
function CkSshTunnel_getConnectTimeoutMs(objHandle: HCkSshTunnel): Integer; stdcall;
procedure CkSshTunnel_putConnectTimeoutMs(objHandle: HCkSshTunnel; newPropVal: Integer); stdcall;

Maximum number of milliseconds to wait when connecting to an SSH server. The default value is 10000 (i.e. 10 seconds). A value of 0 indicates no timeout (wait forever).

top
DebugLogFilePath
procedure CkSshTunnel_getDebugLogFilePath(objHandle: HCkSshTunnel; outPropVal: HCkString); stdcall;
procedure CkSshTunnel_putDebugLogFilePath(objHandle: HCkSshTunnel; newPropVal: PWideChar); stdcall;
function CkSshTunnel__debugLogFilePath(objHandle: HCkSshTunnel): PWideChar; stdcall;

If set to a file path, causes each Chilkat method or property call to automatically append it's LastErrorText to the specified log file. The information is appended such that if a hang or crash occurs, it is possible to see the context in which the problem occurred, as well as a history of all Chilkat calls up to the point of the problem. The VerboseLogging property can be set to provide more detailed information.

This property is typically used for debugging the rare cases where a Chilkat method call hangs or generates an exception that halts program execution (i.e. crashes). A hang or crash should generally never happen. The typical causes of a hang are:

  1. a timeout related property was set to 0 to explicitly indicate that an infinite timeout is desired,
  2. the hang is actually a hang within an event callback (i.e. it is a hang within the application code), or
  3. there is an internal problem (bug) in the Chilkat code that causes the hang.

top
DestHostname
procedure CkSshTunnel_getDestHostname(objHandle: HCkSshTunnel; outPropVal: HCkString); stdcall;
procedure CkSshTunnel_putDestHostname(objHandle: HCkSshTunnel; newPropVal: PWideChar); stdcall;
function CkSshTunnel__destHostname(objHandle: HCkSshTunnel): PWideChar; stdcall;

The destination hostname or IP address (in dotted decimal notation) of the service (such as a database server). Data sent through the SSH tunnel is forwarded by the SSH server to this destination. Data received from the destination (by the SSH server) is forwarded back to the client through the SSH tunnel.

top
DestPort
function CkSshTunnel_getDestPort(objHandle: HCkSshTunnel): Integer; stdcall;
procedure CkSshTunnel_putDestPort(objHandle: HCkSshTunnel; newPropVal: Integer); stdcall;

The destination port of the service (such as a database server).

top
DynamicPortForwarding
function CkSshTunnel_getDynamicPortForwarding(objHandle: HCkSshTunnel): wordbool; stdcall;
procedure CkSshTunnel_putDynamicPortForwarding(objHandle: HCkSshTunnel; newPropVal: wordbool); stdcall;
Introduced in version 9.5.0.50

If True, then this behaves as a SOCKS proxy server for inbound connections. When this property is True, the DestHostname and DestPort properties are unused because the destination IP:port is dynamically provided by the SOCKS client. The default value of this property is False.

When dynamic port forwarding is used, the InboundSocksVersion property must be set to 4 or 5. If inbound SOCKS5 is used, then the InboundSocksUsername and InboundSocksPassword may be set to the required login/password for a client to gain access.

More Information and Examples
top
HostKeyFingerprint
procedure CkSshTunnel_getHostKeyFingerprint(objHandle: HCkSshTunnel; outPropVal: HCkString); stdcall;
function CkSshTunnel__hostKeyFingerprint(objHandle: HCkSshTunnel): PWideChar; stdcall;
Introduced in version 9.5.0.56

Set after connecting to an SSH server. The format of the fingerprint looks like this: "ssh-rsa 1024 68:ff:d1:4e:6c:ff:d7:b0:d6:58:73:85:07:bc:2e:d5"

top
HttpProxyAuthMethod
procedure CkSshTunnel_getHttpProxyAuthMethod(objHandle: HCkSshTunnel; outPropVal: HCkString); stdcall;
procedure CkSshTunnel_putHttpProxyAuthMethod(objHandle: HCkSshTunnel; newPropVal: PWideChar); stdcall;
function CkSshTunnel__httpProxyAuthMethod(objHandle: HCkSshTunnel): PWideChar; stdcall;

If an HTTP proxy requiring authentication is to be used, set this property to the HTTP proxy authentication method name. Valid choices are "Basic" or "NTLM".

Note: This is for the outbound connection to the SSH server. It is used when the outbound connection to the SSH server must go through an HTTP proxy.

top
HttpProxyDomain
procedure CkSshTunnel_getHttpProxyDomain(objHandle: HCkSshTunnel; outPropVal: HCkString); stdcall;
procedure CkSshTunnel_putHttpProxyDomain(objHandle: HCkSshTunnel; newPropVal: PWideChar); stdcall;
function CkSshTunnel__httpProxyDomain(objHandle: HCkSshTunnel): PWideChar; stdcall;

The NTLM authentication domain (optional) if NTLM authentication is used w/ the HTTP proxy.

Note: This is for the outbound connection to the SSH server. It is used when the outbound connection to the SSH server must go through an HTTP proxy.

top
HttpProxyHostname
procedure CkSshTunnel_getHttpProxyHostname(objHandle: HCkSshTunnel; outPropVal: HCkString); stdcall;
procedure CkSshTunnel_putHttpProxyHostname(objHandle: HCkSshTunnel; newPropVal: PWideChar); stdcall;
function CkSshTunnel__httpProxyHostname(objHandle: HCkSshTunnel): PWideChar; stdcall;

If an HTTP proxy is to be used, set this property to the HTTP proxy hostname or IPv4 address (in dotted decimal notation).

Note: This is for the outbound connection to the SSH server. It is used when the outbound connection to the SSH server must go through an HTTP proxy.

top
HttpProxyPassword
procedure CkSshTunnel_getHttpProxyPassword(objHandle: HCkSshTunnel; outPropVal: HCkString); stdcall;
procedure CkSshTunnel_putHttpProxyPassword(objHandle: HCkSshTunnel; newPropVal: PWideChar); stdcall;
function CkSshTunnel__httpProxyPassword(objHandle: HCkSshTunnel): PWideChar; stdcall;

If an HTTP proxy requiring authentication is to be used, set this property to the HTTP proxy password.

Note: This is for the outbound connection to the SSH server. It is used when the outbound connection to the SSH server must go through an HTTP proxy.

top
HttpProxyPort
function CkSshTunnel_getHttpProxyPort(objHandle: HCkSshTunnel): Integer; stdcall;
procedure CkSshTunnel_putHttpProxyPort(objHandle: HCkSshTunnel; newPropVal: Integer); stdcall;

If an HTTP proxy is to be used, set this property to the HTTP proxy port number. (Two commonly used HTTP proxy ports are 8080 and 3128.)

Note: This is for the outbound connection to the SSH server. It is used when the outbound connection to the SSH server must go through an HTTP proxy.

top
HttpProxyUsername
procedure CkSshTunnel_getHttpProxyUsername(objHandle: HCkSshTunnel; outPropVal: HCkString); stdcall;
procedure CkSshTunnel_putHttpProxyUsername(objHandle: HCkSshTunnel; newPropVal: PWideChar); stdcall;
function CkSshTunnel__httpProxyUsername(objHandle: HCkSshTunnel): PWideChar; stdcall;

If an HTTP proxy requiring authentication is to be used, set this property to the HTTP proxy login name.

Note: This is for the outbound connection to the SSH server. It is used when the outbound connection to the SSH server must go through an HTTP proxy.

top
IdleTimeoutMs
function CkSshTunnel_getIdleTimeoutMs(objHandle: HCkSshTunnel): Integer; stdcall;
procedure CkSshTunnel_putIdleTimeoutMs(objHandle: HCkSshTunnel; newPropVal: Integer); stdcall;

A tunnel will fail when progress for sending or receiving data halts for more than this number of milliseconds. The default value is 10,000 (which is 10 seconds). A timeout of 0 indicates an infinite wait time (i.e. no timeout).

top
InboundSocksPassword
procedure CkSshTunnel_getInboundSocksPassword(objHandle: HCkSshTunnel; outPropVal: HCkString); stdcall;
procedure CkSshTunnel_putInboundSocksPassword(objHandle: HCkSshTunnel; newPropVal: PWideChar); stdcall;
function CkSshTunnel__inboundSocksPassword(objHandle: HCkSshTunnel): PWideChar; stdcall;
Introduced in version 9.5.0.50

If dynamic port forwarding is used, then this may be set to the password required for authenticating inbound connections.

top
InboundSocksUsername
procedure CkSshTunnel_getInboundSocksUsername(objHandle: HCkSshTunnel; outPropVal: HCkString); stdcall;
procedure CkSshTunnel_putInboundSocksUsername(objHandle: HCkSshTunnel; newPropVal: PWideChar); stdcall;
function CkSshTunnel__inboundSocksUsername(objHandle: HCkSshTunnel): PWideChar; stdcall;
Introduced in version 9.5.0.50

If dynamic port forwarding is used, then this may be set to the username required for authenticating inbound connections. If no username is set, then the inbound connection needs no authentication.

top
IsAccepting
function CkSshTunnel_getIsAccepting(objHandle: HCkSshTunnel): wordbool; stdcall;

True if a background thread is running and accepting connections.

top
KeepAcceptLog
function CkSshTunnel_getKeepAcceptLog(objHandle: HCkSshTunnel): wordbool; stdcall;
procedure CkSshTunnel_putKeepAcceptLog(objHandle: HCkSshTunnel; newPropVal: wordbool); stdcall;

If True, then an in-memory log of the listen thread is kept. The default value is False.

top
KeepTunnelLog
function CkSshTunnel_getKeepTunnelLog(objHandle: HCkSshTunnel): wordbool; stdcall;
procedure CkSshTunnel_putKeepTunnelLog(objHandle: HCkSshTunnel; newPropVal: wordbool); stdcall;
Introduced in version 9.5.0.50

If True, then a log of the SSH tunnel thread activity is kept in memory. The default value is False.

top
LastErrorHtml
procedure CkSshTunnel_getLastErrorHtml(objHandle: HCkSshTunnel; outPropVal: HCkString); stdcall;
function CkSshTunnel__lastErrorHtml(objHandle: HCkSshTunnel): PWideChar; stdcall;

Provides information in HTML format about the last method/property called. If a method call returns a value indicating failure, or behaves unexpectedly, examine this property to get more information.

top
LastErrorText
procedure CkSshTunnel_getLastErrorText(objHandle: HCkSshTunnel; outPropVal: HCkString); stdcall;
function CkSshTunnel__lastErrorText(objHandle: HCkSshTunnel): PWideChar; stdcall;

Provides information in plain-text format about the last method/property called. If a method call returns a value indicating failure, or behaves unexpectedly, examine this property to get more information.

top
LastErrorXml
procedure CkSshTunnel_getLastErrorXml(objHandle: HCkSshTunnel; outPropVal: HCkString); stdcall;
function CkSshTunnel__lastErrorXml(objHandle: HCkSshTunnel): PWideChar; stdcall;

Provides information in XML format about the last method/property called. If a method call returns a value indicating failure, or behaves unexpectedly, examine this property to get more information.

top
LastMethodSuccess
function CkSshTunnel_getLastMethodSuccess(objHandle: HCkSshTunnel): wordbool; stdcall;
procedure CkSshTunnel_putLastMethodSuccess(objHandle: HCkSshTunnel; newPropVal: wordbool); stdcall;

Indicate whether the last method call succeeded or failed. A value of True indicates success, a value of False indicates failure. This property is automatically set for method calls. It is not modified by property accesses. The property is automatically set to indicate success for the following types of method calls:

  • Any method that returns a string.
  • Any method returning a Chilkat object, binary bytes, or a date/time.
  • Any method returning a standard boolean status value where success = True and failure = False.
  • Any method returning an integer where failure is defined by a return value less than zero.

Note: Methods that do not fit the above requirements will always set this property equal to True. For example, a method that returns no value (such as a "void" in C++) will technically always succeed.

top
ListenBindIpAddress
procedure CkSshTunnel_getListenBindIpAddress(objHandle: HCkSshTunnel; outPropVal: HCkString); stdcall;
procedure CkSshTunnel_putListenBindIpAddress(objHandle: HCkSshTunnel; newPropVal: PWideChar); stdcall;
function CkSshTunnel__listenBindIpAddress(objHandle: HCkSshTunnel): PWideChar; stdcall;

In most cases, this property does not need to be set. It is provided for cases where it is required to bind the listen socket to a specific IP address (usually for computers with multiple network interfaces or IP addresses). For computers with a single network interface (i.e. most computers), this property should not be set. For multihoming computers, the default IP address is automatically used if this property is not set.

top
ListenPort
function CkSshTunnel_getListenPort(objHandle: HCkSshTunnel): Integer; stdcall;

If a port number equal to 0 is passed to BeginAccepting, then this property will contain the actual allocated port number used. Otherwise it is equal to the port number passed to BeginAccepting, or 0 if BeginAccepting was never called.

top
OutboundBindIpAddress
procedure CkSshTunnel_getOutboundBindIpAddress(objHandle: HCkSshTunnel; outPropVal: HCkString); stdcall;
procedure CkSshTunnel_putOutboundBindIpAddress(objHandle: HCkSshTunnel; newPropVal: PWideChar); stdcall;
function CkSshTunnel__outboundBindIpAddress(objHandle: HCkSshTunnel): PWideChar; stdcall;

In most cases, this property does not need to be set. It is provided for cases where it is required to bind the socket that is to connect to the SSH server (in the background thread) to a specific IP address (usually for computers with multiple network interfaces or IP addresses). For computers with a single network interface (i.e. most computers), this property should not be set. For multihoming computers, the default IP address is automatically used if this property is not set.

top
OutboundBindPort
function CkSshTunnel_getOutboundBindPort(objHandle: HCkSshTunnel): Integer; stdcall;
procedure CkSshTunnel_putOutboundBindPort(objHandle: HCkSshTunnel; newPropVal: Integer); stdcall;

Unless there is a specific requirement for binding to a specific port, leave this unset (at the default value of 0). (99.9% of all users should never need to set this property.)

top
PreferIpv6
function CkSshTunnel_getPreferIpv6(objHandle: HCkSshTunnel): wordbool; stdcall;
procedure CkSshTunnel_putPreferIpv6(objHandle: HCkSshTunnel; newPropVal: wordbool); stdcall;
Introduced in version 9.5.0.70

If True, then use IPv6 over IPv4 when both are supported for a particular domain. The default value of this property is False, which will choose IPv4 over IPv6.

top
SocksHostname
procedure CkSshTunnel_getSocksHostname(objHandle: HCkSshTunnel; outPropVal: HCkString); stdcall;
procedure CkSshTunnel_putSocksHostname(objHandle: HCkSshTunnel; newPropVal: PWideChar); stdcall;
function CkSshTunnel__socksHostname(objHandle: HCkSshTunnel): PWideChar; stdcall;

The SOCKS4/SOCKS5 hostname or IPv4 address (in dotted decimal notation). This property is only used if the SocksVersion property is set to 4 or 5).

Note: This is for the outbound connection to the SSH server. It is used when the outbound connection to the SSH server must go through a SOCKS4 or SOCKS5 proxy.

top
SocksPassword
procedure CkSshTunnel_getSocksPassword(objHandle: HCkSshTunnel; outPropVal: HCkString); stdcall;
procedure CkSshTunnel_putSocksPassword(objHandle: HCkSshTunnel; newPropVal: PWideChar); stdcall;
function CkSshTunnel__socksPassword(objHandle: HCkSshTunnel): PWideChar; stdcall;

The SOCKS5 password (if required). The SOCKS4 protocol does not include the use of a password, so this does not apply to SOCKS4.

Note: This is for the outbound connection to the SSH server. It is used when the outbound connection to the SSH server must go through a SOCKS4 or SOCKS5 proxy.

top
SocksPort
function CkSshTunnel_getSocksPort(objHandle: HCkSshTunnel): Integer; stdcall;
procedure CkSshTunnel_putSocksPort(objHandle: HCkSshTunnel; newPropVal: Integer); stdcall;

The SOCKS4/SOCKS5 proxy port. The default value is 1080. This property only applies if a SOCKS proxy is used (if the SocksVersion property is set to 4 or 5).

Note: This is for the outbound connection to the SSH server. It is used when the outbound connection to the SSH server must go through a SOCKS4 or SOCKS5 proxy.

top
SocksUsername
procedure CkSshTunnel_getSocksUsername(objHandle: HCkSshTunnel; outPropVal: HCkString); stdcall;
procedure CkSshTunnel_putSocksUsername(objHandle: HCkSshTunnel; newPropVal: PWideChar); stdcall;
function CkSshTunnel__socksUsername(objHandle: HCkSshTunnel): PWideChar; stdcall;

The SOCKS4/SOCKS5 proxy username. This property is only used if the SocksVersion property is set to 4 or 5).

Note: This is for the outbound connection to the SSH server. It is used when the outbound connection to the SSH server must go through a SOCKS4 or SOCKS5 proxy.

top
SocksVersion
function CkSshTunnel_getSocksVersion(objHandle: HCkSshTunnel): Integer; stdcall;
procedure CkSshTunnel_putSocksVersion(objHandle: HCkSshTunnel; newPropVal: Integer); stdcall;

SocksVersion May be set to one of the following integer values:

0 - No SOCKS proxy is used. This is the default.
4 - Connect via a SOCKS4 proxy.
5 - Connect via a SOCKS5 proxy.

Note: This is for the outbound connection to the SSH server. It is used when the outbound connection to the SSH server must go through a SOCKS4 or SOCKS5 proxy.

top
SoRcvBuf
function CkSshTunnel_getSoRcvBuf(objHandle: HCkSshTunnel): Integer; stdcall;
procedure CkSshTunnel_putSoRcvBuf(objHandle: HCkSshTunnel; newPropVal: Integer); stdcall;

Sets the receive buffer size socket option. Normally, this property should be left unchanged. The default value is 4194304.

This property can be increased if download performance seems slow. It is recommended to be a multiple of 4096.

top
SoSndBuf
function CkSshTunnel_getSoSndBuf(objHandle: HCkSshTunnel): Integer; stdcall;
procedure CkSshTunnel_putSoSndBuf(objHandle: HCkSshTunnel; newPropVal: Integer); stdcall;

Sets the send buffer size socket option. Normally, this property should be left unchanged. The default value is 262144.

This property can be increased if upload performance seems slow. It is recommended to be a multiple of 4096. Testing with sizes such as 512K and 1MB is reasonable.

top
TcpNoDelay
function CkSshTunnel_getTcpNoDelay(objHandle: HCkSshTunnel): wordbool; stdcall;
procedure CkSshTunnel_putTcpNoDelay(objHandle: HCkSshTunnel; newPropVal: wordbool); stdcall;

Controls whether the TCP_NODELAY socket option is used for the underlying TCP/IP socket. The default value is False. Setting this property equal to True disables the Nagle algorithm and allows for better performance when small amounts of data are sent.

top
TunnelLog
procedure CkSshTunnel_getTunnelLog(objHandle: HCkSshTunnel; outPropVal: HCkString); stdcall;
procedure CkSshTunnel_putTunnelLog(objHandle: HCkSshTunnel; newPropVal: PWideChar); stdcall;
function CkSshTunnel__tunnelLog(objHandle: HCkSshTunnel): PWideChar; stdcall;
Introduced in version 9.5.0.50

Contains an in-memory log of the SSH tunnel thread. This will only contain content if the KeepTunnelLog property is True.

top
TunnelLogPath
procedure CkSshTunnel_getTunnelLogPath(objHandle: HCkSshTunnel; outPropVal: HCkString); stdcall;
procedure CkSshTunnel_putTunnelLogPath(objHandle: HCkSshTunnel; newPropVal: PWideChar); stdcall;
function CkSshTunnel__tunnelLogPath(objHandle: HCkSshTunnel): PWideChar; stdcall;
Introduced in version 9.5.0.50

Set to keep a log file of the SSH tunnel thread.

top
UncommonOptions
procedure CkSshTunnel_getUncommonOptions(objHandle: HCkSshTunnel; outPropVal: HCkString); stdcall;
procedure CkSshTunnel_putUncommonOptions(objHandle: HCkSshTunnel; newPropVal: PWideChar); stdcall;
function CkSshTunnel__uncommonOptions(objHandle: HCkSshTunnel): PWideChar; stdcall;
Introduced in version 9.5.0.73

This is a catch-all property to be used for uncommon needs. This property defaults to the empty string, and should typically remain empty.

Can be set to a list of the following comma separated keywords:

  • NoKeepAliveIgnoreMsg - Introduced in v9.5.0.76. Prevents the default behavior of the SSH tunnel sending an "ignore" message every 20 seconds to keep an unused connection alive.
  • ProtectFromVpn - Introduced in v9.5.0.80. On Android systems, will bypass any VPN that may be installed or active.
  • +ssh-hmac-etm - Introduced in v9.5.0.97. Version 9.5.0.97 disabled the *-etm MAC algorithms to mitigate the Terrapin attack. Use this keyword to include the etm MAC algorithms.
  • +chacha20-poly1305@openssh.com - Introduced in v9.5.0.97. To mitigate the Terrapin attack, chacha20-poly1305@openssh.com is no longer included by default. It can be re-added by adding this keyword.

top
VerboseLogging
function CkSshTunnel_getVerboseLogging(objHandle: HCkSshTunnel): wordbool; stdcall;
procedure CkSshTunnel_putVerboseLogging(objHandle: HCkSshTunnel; newPropVal: wordbool); stdcall;

If set to True, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is False. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.

top
Version
procedure CkSshTunnel_getVersion(objHandle: HCkSshTunnel; outPropVal: HCkString); stdcall;
function CkSshTunnel__version(objHandle: HCkSshTunnel): PWideChar; stdcall;

Version of the component/library, such as "9.5.0.94"

More Information and Examples
top

Methods

AuthenticatePk
function CkSshTunnel_AuthenticatePk(objHandle: HCkSshTunnel;
    username: PWideChar;
    privateKey: HCkSshKey): wordbool; stdcall;
Introduced in version 9.5.0.50

Authenticates with the SSH server using public-key authentication. The corresponding public key must have been installed on the SSH server for the username. Authentication will succeed if the matching privateKey is provided.

Important: When reporting problems, please send the full contents of the LastErrorText property to support@chilkatsoft.com.

Returns True for success, False for failure.

top
AuthenticatePkAsync (1)
function CkSshTunnel_AuthenticatePkAsync(objHandle: HCkSshTunnel;
    username: PWideChar;
    privateKey: HCkSshKey): HCkTask; stdcall;
Introduced in version 9.5.0.50

Creates an asynchronous task to call the AuthenticatePk method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

top
AuthenticatePw
function CkSshTunnel_AuthenticatePw(objHandle: HCkSshTunnel;
    login: PWideChar;
    password: PWideChar): wordbool; stdcall;
Introduced in version 9.5.0.50

Authenticates with the SSH server using a login and password.

An SSH session always begins by first calling Connect to connect to the SSH server, and then calling either AuthenticatePw or AuthenticatePk to login.

Important: When reporting problems, please send the full contents of the LastErrorText property to support@chilkatsoft.com.
Note: To learn about how to handle password change requests, see the PasswordChangeRequested property (above).

Returns True for success, False for failure.

top
AuthenticatePwAsync (1)
function CkSshTunnel_AuthenticatePwAsync(objHandle: HCkSshTunnel;
    login: PWideChar;
    password: PWideChar): HCkTask; stdcall;
Introduced in version 9.5.0.50

Creates an asynchronous task to call the AuthenticatePw method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

top
AuthenticatePwPk
function CkSshTunnel_AuthenticatePwPk(objHandle: HCkSshTunnel;
    username: PWideChar;
    password: PWideChar;
    privateKey: HCkSshKey): wordbool; stdcall;
Introduced in version 9.5.0.50

Authentication for SSH servers that require both a password and private key. (Most SSH servers are configured to require one or the other, but not both.)

Important: When reporting problems, please send the full contents of the LastErrorText property to support@chilkatsoft.com.

Returns True for success, False for failure.

top
AuthenticatePwPkAsync (1)
function CkSshTunnel_AuthenticatePwPkAsync(objHandle: HCkSshTunnel;
    username: PWideChar;
    password: PWideChar;
    privateKey: HCkSshKey): HCkTask; stdcall;
Introduced in version 9.5.0.50

Creates an asynchronous task to call the AuthenticatePwPk method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

top
AuthenticateSecPw
function CkSshTunnel_AuthenticateSecPw(objHandle: HCkSshTunnel;
    login: HCkSecureString;
    password: HCkSecureString): wordbool; stdcall;
Introduced in version 9.5.0.71

The same as AuthenticatePw, except the login and password strings are passed in secure string objects.

Returns True for success, False for failure.

More Information and Examples
top
AuthenticateSecPwAsync (1)
function CkSshTunnel_AuthenticateSecPwAsync(objHandle: HCkSshTunnel;
    login: HCkSecureString;
    password: HCkSecureString): HCkTask; stdcall;
Introduced in version 9.5.0.71

Creates an asynchronous task to call the AuthenticateSecPw method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

top
AuthenticateSecPwPk
function CkSshTunnel_AuthenticateSecPwPk(objHandle: HCkSshTunnel;
    username: HCkSecureString;
    password: HCkSecureString;
    privateKey: HCkSshKey): wordbool; stdcall;
Introduced in version 9.5.0.71

The same as AuthenticatePwPk, except the login and password strings are passed in secure string objects.

Returns True for success, False for failure.

top
AuthenticateSecPwPkAsync (1)
function CkSshTunnel_AuthenticateSecPwPkAsync(objHandle: HCkSshTunnel;
    username: HCkSecureString;
    password: HCkSecureString;
    privateKey: HCkSshKey): HCkTask; stdcall;
Introduced in version 9.5.0.71

Creates an asynchronous task to call the AuthenticateSecPwPk method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

top
BeginAccepting
function CkSshTunnel_BeginAccepting(objHandle: HCkSshTunnel;
    listenPort: Integer): wordbool; stdcall;

Starts a background thread for listening on listenPort. A new SSH tunnel is created and managed for each accepted connection. SSH tunnels are managed in a 2nd background thread: the SSH tunnel pool thread.

BeginAccepting starts a background thread that creates a socket, binds to the port, and begins listening. If the bind fails (meaning something else may have already bound to the same port), then the background thread exits. You may check to see if BeginAccepting succeeds by waiting a short time (perhaps 50 millisec) and then examine the IsAccepting property. If it is False, then BeginAccepting failed.

Important: The listenPort must be a port number that nothing else on the local computer is listening on.

Returns True for success, False for failure.

top
BeginAcceptingAsync (1)
function CkSshTunnel_BeginAcceptingAsync(objHandle: HCkSshTunnel;
    listenPort: Integer): HCkTask; stdcall;

Creates an asynchronous task to call the BeginAccepting method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

top
CloseTunnel
function CkSshTunnel_CloseTunnel(objHandle: HCkSshTunnel;
    waitForThreads: wordbool): wordbool; stdcall;
Introduced in version 9.5.0.50

Closes the SSH tunnel and disconnects all existing clients. If waitForThreads is True, the method will wait for the tunnel and client threads to exit before returning.

Returns True for success, False for failure.

top
Connect
function CkSshTunnel_Connect(objHandle: HCkSshTunnel;
    hostname: PWideChar;
    port: Integer): wordbool; stdcall;
Introduced in version 9.5.0.50

Connects to the SSH server to be used for SSH tunneling.

Important: Make sure to call CloseTunnel when finished with the tunnel, such as before exiting your program.

Note: Chilkat automatically sends an "ignore" message every 20 seconds to keep the connection with the SSH server alive. This can be turned off by adding the "NoKeepAliveIgnoreMsg" to the UncommonOptions property.

Returns True for success, False for failure.

More Information and Examples
top
ConnectAsync (1)
function CkSshTunnel_ConnectAsync(objHandle: HCkSshTunnel;
    hostname: PWideChar;
    port: Integer): HCkTask; stdcall;
Introduced in version 9.5.0.50

Creates an asynchronous task to call the Connect method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

top
ConnectThroughSsh
function CkSshTunnel_ConnectThroughSsh(objHandle: HCkSshTunnel;
    ssh: HCkSsh;
    hostname: PWideChar;
    port: Integer): wordbool; stdcall;
Introduced in version 9.5.0.55

Connects to an SSH server through an existing SSH connection. The ssh is an existing connected and authenticated SSH object. The connection to hostname:port is made through the existing SSH connection via port-forwarding. If successful, the connection is as follows: application => ServerSSH1 => ServerSSH2. (where ServerSSH1 is the ssh and ServerSSH2 is the SSH server at hostname:port) Once connected in this way, all communications are routed through ServerSSH1 to ServerSSH2. This includes authentication -- which means the application must still call one of the Authenticate* methods to authenticate with ServerSSH2.

Returns True for success, False for failure.

top
ConnectThroughSshAsync (1)
function CkSshTunnel_ConnectThroughSshAsync(objHandle: HCkSshTunnel;
    ssh: HCkSsh;
    hostname: PWideChar;
    port: Integer): HCkTask; stdcall;
Introduced in version 9.5.0.55

Creates an asynchronous task to call the ConnectThroughSsh method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

top
ContinueKeyboardAuth
function CkSshTunnel_ContinueKeyboardAuth(objHandle: HCkSshTunnel;
    response: PWideChar;
    outStr: HCkString): wordbool; stdcall;
function CkSshTunnel__continueKeyboardAuth(objHandle: HCkSshTunnel;
    response: PWideChar): PWideChar; stdcall;
Introduced in version 9.5.0.78

Continues keyboard-interactive authentication with the SSH server. The response is typically the password. If multiple responses are required (because there were multiple prompts in the infoRequest XML returned by StartKeyboardAuth), then the response should be formatted as XML (as shown below) otherwise the response simply contains the single response string.

<response>
    <response1>response to first prompt</response1>
    <response2>response to second prompt</response2>
    ...
    <responseN>response to Nth prompt</responseN>
</response>

If the interactive authentication completed with success or failure, the XML response will be:

<success>success_message</success>

or

<error>error_message</error>
If additional steps are required to complete the interactive authentication, then an XML string that provides the name, instruction, and prompts is returned. The XML has the following format:
 	<infoRequest numPrompts="N">
	    <name>name_string</name>
	    <instruction>instruction_string</instruction>
	    <prompt1 echo="1_or_0">prompt_string</prompt1>
	    ...
	    <promptN echo="1_or_0">prompt_string</promptN>
	</infoRequest>

Returns True for success, False for failure.

top
ContinueKeyboardAuthAsync (1)
function CkSshTunnel_ContinueKeyboardAuthAsync(objHandle: HCkSshTunnel;
    response: PWideChar): HCkTask; stdcall;
Introduced in version 9.5.0.78

Creates an asynchronous task to call the ContinueKeyboardAuth method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

top
DisconnectAllClients
function CkSshTunnel_DisconnectAllClients(objHandle: HCkSshTunnel;
    waitForThreads: wordbool): wordbool; stdcall;
Introduced in version 9.5.0.50

Disconnects all clients, keeping the SSH tunnel open. If waitForThreads is True, the method will wait for the client threads to exit before returning.

Returns True for success, False for failure.

top
GetCurrentState
function CkSshTunnel_GetCurrentState(objHandle: HCkSshTunnel;
    outStr: HCkString): wordbool; stdcall;
function CkSshTunnel__getCurrentState(objHandle: HCkSshTunnel): PWideChar; stdcall;
Introduced in version 9.5.0.65

Returns the current state of existing tunnels in an XML string.

Returns True for success, False for failure.

top
IsSshConnected
function CkSshTunnel_IsSshConnected(objHandle: HCkSshTunnel): wordbool; stdcall;
Introduced in version 9.5.0.61

Returns True if connected to the SSH server. Returns False if the connection has been lost (or was never established).

top
LoadTaskCaller
function CkSshTunnel_LoadTaskCaller(objHandle: HCkSshTunnel;
    task: HCkTask): wordbool; stdcall;
Introduced in version 9.5.0.80

Loads the caller of the task's async method.

Returns True for success, False for failure.

top
StartKeyboardAuth
function CkSshTunnel_StartKeyboardAuth(objHandle: HCkSshTunnel;
    login: PWideChar;
    outStr: HCkString): wordbool; stdcall;
function CkSshTunnel__startKeyboardAuth(objHandle: HCkSshTunnel;
    login: PWideChar): PWideChar; stdcall;
Introduced in version 9.5.0.78

Begins keyboard-interactive authentication with the SSH server. Returns an XML string providing the name, instruction, and prompts. The XML has the following format:

 	<infoRequest numPrompts="N">
	    <name>name_string</name>
	    <instruction>instruction_string</instruction>
	    <prompt1 echo="1_or_0">prompt_string</prompt1>
	    ...
	    <promptN echo="1_or_0">prompt_string</promptN>
	</infoRequest>

If the authentication immediately succeeds because no password is required, or immediately fails, the XML response can be:

<success>success_message</success>

or

<error>error_message</error>

Returns True for success, False for failure.

top
StartKeyboardAuthAsync (1)
function CkSshTunnel_StartKeyboardAuthAsync(objHandle: HCkSshTunnel;
    login: PWideChar): HCkTask; stdcall;
Introduced in version 9.5.0.78

Creates an asynchronous task to call the StartKeyboardAuth method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

top
StopAccepting
function CkSshTunnel_StopAccepting(objHandle: HCkSshTunnel;
    waitForThread: wordbool): wordbool; stdcall;

Stops the listen background thread. It is possible to continue accepting connections by re-calling BeginAccepting. If waitForThread is True, the method will wait for the listen thread to exit before returning.

Returns True for success, False for failure.

top

Events

Chilkat supports event callbacks for the Delphi DLL starting in version 9.5.0.82.

AbortCheck
function MyAbortCheck(): Integer; cdecl;
Introduced in version 9.5.0.82

Provides the opportunity for a method call to be aborted. The AbortCheck event is fired periodically based on the value of the HeartbeatMs property. If HeartbeatMs is 0, then no AbortCheck events will fire. As an example, to fire 5 AbortCheck events per second, set the HeartbeatMs property equal to 200. Return True to abort; return False to continue (not abort)

More Information and Examples
top
PercentDone
function MyPercentDone(pctDone: Integer): Integer; cdecl;
Introduced in version 9.5.0.82

Provides the percentage completed for any method that involves network communications or time-consuming processing (assuming it is a method where a percentage completion can be measured). This event is only fired when it is possible to know a percentage completion, and when it makes sense to express the operation as a percentage completed. The pctDone argument will have a value from 1 to 100. For operations (Chilkat method calls) that complete very quickly, the number of PercentDone callbacks will vary, but the final callback should have a value of 100. For long running operations, no more than one callback per percentage point will occur (for example: 1, 2, 3, ... 98, 99, 100).

The PercentDone callback counts as an AbortCheck event. For method calls that complete quickly such that PercentDone events fire, it may be that AbortCheck events don't fire because the opportunity to abort is already provided in the PercentDone callback. For time consuming operations, where the amount of time between PercentDone callbacks are long, AbortCheck callbacks may be used to allow for the operation to be aborted in a more responsive manner.

Return True to abort; return False to continue (not abort)

More Information and Examples
top
ProgressInfo
procedure MyProgressInfo(name: PWideChar; value: PWideChar) cdecl;
Introduced in version 9.5.0.82

A general name/value event that provides information about what is happening during a method call. To find out what information is available, write code to handle this event and log the name/value pairs. Most are self-explanatory.

More Information and Examples
top
TaskCompleted
procedure MyTaskCompleted(task: HCkTask) cdecl;
Introduced in version 9.5.0.82

Called in the background thread when an asynchronous task completes.

top