Package com.chilkatsoft.chilkat2

Class SshTunnel

java.lang.Object
com.chilkatsoft.chilkat2.ChilkatObject
com.chilkatsoft.chilkat2.SshTunnel
All Implemented Interfaces:
AutoCloseable
public class SshTunnel extends ChilkatObject
<section class="sshtunnel-summary">

Create SSH tunnels for secure local, fixed-destination, dynamic, and multi-hop forwarding.

Chilkat.SshTunnel creates SSH tunnels for forwarding local client connections through an SSH server to a destination service, such as a database server or other TCP service. It supports fixed destination forwarding, dynamic SOCKS-style port forwarding, password and public-key authentication, keyboard-interactive authentication, proxy connections to the SSH server, multi-hop SSH connections, background accept threads, tunnel/client logging, secure secret lookup, and connection diagnostics.

Local port forwarding

Listen on a local port and forward accepted client connections through an SSH server to a configured destination host and port.

Dynamic forwarding

Enable SOCKS-style dynamic port forwarding when each client connection should choose its own destination through the tunnel.

SSH authentication

Authenticate to the SSH server using passwords, public keys, password-plus-key, secure password lookup, or keyboard-interactive authentication.

Proxy and multi-hop access

Reach the SSH server through HTTP or SOCKS proxies, or build tunnels through an existing SSH connection for multi-hop scenarios.

Accept and manage clients

Start accepting client connections in the background, inspect current state, stop accepting new clients, and disconnect active tunnel clients.

Logging and diagnostics

Use accept logs, tunnel logs, current-state XML, and LastErrorText to troubleshoot SSH connection, forwarding, authentication, or client-connection problems.

Common pattern: Configure the SSH server, authentication method, local listen settings, and destination forwarding options, then call BeginAccepting to start the tunnel. Local client applications connect to the tunnel's listen port, and SshTunnel forwards the traffic through SSH. Use Chilkat.SshTunnel for port forwarding; use Chilkat.Ssh for direct SSH sessions, commands, channels, and shell access.

Start with the SSH Tunneling Guide

Learn how static forwarding, dynamic SOCKS forwarding, multi-hop tunneling, proxies, background threads, lifecycle management, and troubleshooting fit together.

Open the SshTunnel Guide

A shorter API-focused introduction is also available in the SshTunnel Class Overview.

</section>

Event-capable: long-running methods report progress through a ProgressListener installed with setProgressListener(ProgressListener), onAbortCheck(BooleanSupplier), onPercentDone(IntPredicate) or onProgressInfo(BiConsumer).

Instances hold a native Chilkat object: close them with ChilkatObject.close() (try-with-resources) when done; an unclosed instance is freed when it becomes unreachable.

See Also:
Online reference

  • Constructor Details

    • SshTunnel

      public SshTunnel()
      Creates a new SshTunnel object.

  • Method Details

    • getAbortCurrent

      public boolean getAbortCurrent()
      Set this property to true from another thread to request that the currently running foreground operation be aborted. For example, it can interrupt a synchronous connect(String, int) that is waiting for an SSH server response.

      This property does not stop the background listener or terminate established background tunnel clients.

      Do not assume the property is automatically reset after an operation is aborted. It may remain true; set it back to false before starting another operation.

      Returns:
      the value of the AbortCurrent property

    • setAbortCurrent

      public void setAbortCurrent​(boolean value)
      Sets the AbortCurrent property; see getAbortCurrent().
      Parameters:
      value - the new value

    • getAcceptLog

      public String getAcceptLog()
      Contains the in-memory activity log for the background listener thread started by beginAccepting(int).

      The log is populated only when getKeepAcceptLog() is true.

      Returns:
      the value of the AcceptLog property

    • setAcceptLog

      public void setAcceptLog​(String value)
      Sets the AcceptLog property; see getAcceptLog().
      Parameters:
      value - the new value (not null)

    • getAcceptLogPath

      public String getAcceptLogPath()
      Specifies the local file path where activity from the background listener thread is written.

      This file-based log is separate from the in-memory getAcceptLog().

      Returns:
      the value of the AcceptLogPath property

    • setAcceptLogPath

      public void setAcceptLogPath​(String value)
      Sets the AcceptLogPath property; see getAcceptLogPath().
      Parameters:
      value - the new value (not null)

    • getClientIdentifier

      public String getClientIdentifier()
      Specifies the SSH client-identification string sent when connecting to the SSH server.

      Starting in Chilkat v9.5.0.99, the default is SSH-2.0-Chilkat_ followed by the Chilkat version number, such as SSH-2.0-Chilkat_9.5.0.99.

      The identifier should begin with SSH-2.0-. Some SSH servers disconnect clients that send an invalid identification string.

      Returns:
      the value of the ClientIdentifier property

    • setClientIdentifier

      public void setClientIdentifier​(String value)
      Sets the ClientIdentifier property; see getClientIdentifier().
      Parameters:
      value - the new value (not null)

    • getClientLogDir

      public String getClientLogDir()
      Specifies the local directory where a separate log file is created for each tunnel client.

      When this property is not empty, files are named using the pattern tunnel_client_log_{random_id}.txt.

      Returns:
      the value of the ClientLogDir property

    • setClientLogDir

      public void setClientLogDir​(String value)
      Sets the ClientLogDir property; see getClientLogDir().
      Parameters:
      value - the new value (not null)

    • getConnectTimeoutMs

      public int getConnectTimeoutMs()
      Specifies the maximum number of milliseconds allowed for establishing the SSH connection.
      • The default value is 30000 milliseconds (30 seconds).
      • A value of 0 disables the connection timeout and allows an unlimited wait.

      The timeout applies to more than the initial TCP connection. It also covers connection setup performed through an HTTP or SOCKS proxy and waiting for the SSH server identification string after the TCP connection has been established.

      Returns:
      the value of the ConnectTimeoutMs property

    • setConnectTimeoutMs

      public void setConnectTimeoutMs​(int value)
      Sets the ConnectTimeoutMs property; see getConnectTimeoutMs().
      Parameters:
      value - the new value

    • getDestHostname

      public String getDestHostname()
      Specifies the destination hostname or IP address for fixed-destination port forwarding. This is typically the host running the database server or other TCP service that local clients need to reach.

      The destination is interpreted from the SSH server's network environment. For example, localhost and 127.0.0.1 refer to the SSH server itself, not the computer running the application. Hostname resolution is therefore performed as part of the forwarding request on the SSH-server side.

      Traffic accepted by the local listener is carried through SSH, forwarded by the SSH server to this destination, and returned through the same tunnel.

      This property is ignored when getDynamicPortForwarding() is true. Changing the destination while the listener is running affects new clients only; existing clients remain connected to the destination selected when they were accepted.

      Returns:
      the value of the DestHostname property

    • setDestHostname

      public void setDestHostname​(String value)
      Sets the DestHostname property; see getDestHostname().
      Parameters:
      value - the new value (not null)

    • getDestPort

      public int getDestPort()
      Specifies the TCP port of the destination service used for fixed-destination forwarding, such as the port of a database server.

      It is used together with getDestHostname() and is ignored when getDynamicPortForwarding() is true.

      Returns:
      the value of the DestPort property

    • setDestPort

      public void setDestPort​(int value)
      Sets the DestPort property; see getDestPort().
      Parameters:
      value - the new value

    • getDynamicPortForwarding

      public boolean getDynamicPortForwarding()
      Controls whether the listener performs fixed-destination or dynamic port forwarding.
      • When false (the default), every accepted connection is forwarded to getDestHostname() and getDestPort().
      • When true, the listener acts as a SOCKS proxy and each inbound client supplies its own destination.

      The SOCKS version is detected independently from each inbound client handshake; there is no separate inbound SOCKS-version property. SOCKS4 and SOCKS5 CONNECT requests are supported. SOCKS5 BIND and UDP association are not supported.

      Leave getInboundSocksUsername() empty to allow SOCKS5 clients to use the no-authentication method. Set the inbound username and password to require SOCKS5 username/password authentication. For SOCKS4, only the user ID can be checked because SOCKS4 has no password field.

      SOCKS4a hostname-form requests are not supported. Use a numeric IPv4 address with SOCKS4, or use SOCKS5 when the client needs to supply a domain name.

      Returns:
      the value of the DynamicPortForwarding property

    • setDynamicPortForwarding

      public void setDynamicPortForwarding​(boolean value)
      Sets the DynamicPortForwarding property; see getDynamicPortForwarding().
      Parameters:
      value - the new value

    • getEnableSecrets

      public boolean getEnableSecrets()
      Enables automatic resolution of credentials from secure storage provided by the operating system.

      When set to true, supported password properties and methods may receive a secret specification string beginning with !! instead of a literal password. Chilkat resolves the secret from:

      • Windows Credential Manager on Windows.
      • Apple Keychain on macOS.

      The specification format is: !![appName|]service[|domain]|username

      This applies to getHttpProxyPassword(), getSocksPassword(), authenticatePw(String, String), and authenticatePwPk(String, String, SshKey).

      The default value is false.

      Returns:
      the value of the EnableSecrets property

    • setEnableSecrets

      public void setEnableSecrets​(boolean value)
      Sets the EnableSecrets property; see getEnableSecrets().
      Parameters:
      value - the new value

    • getHostKeyFingerprint

      public String getHostKeyFingerprint()
      Contains the SSH server host-key fingerprint after connect(String, int) or connectThroughSsh(Ssh, String, int) establishes the SSH connection. The value is available before user authentication.

      Example: ssh-ed25519 256 e0:33:b1:81:a5:c6:9a:d2:2e:c9:d3:15:60:ea:cf:4c

      Compare this value with a trusted expected fingerprint to verify the identity of the SSH server. For connectThroughSsh(Ssh, String, int), the fingerprint is for the final SSH server, not the first-hop server.

      The value may remain populated after closeTunnel(boolean) or after the connection is lost. Use isSshConnected() to determine current connection state.

      Returns:
      the value of the HostKeyFingerprint property (read-only)

    • getHttpProxyAuthMethod

      public String getHttpProxyAuthMethod()
      Specifies the authentication method to use when the outbound connection to the SSH server passes through an HTTP proxy that requires authentication.

      Valid values are Basic and NTLM.

      If getSocksVersion() is set to 4 or 5, the SOCKS proxy takes precedence and these HTTP proxy settings are ignored. The proxies are not chained.

      Returns:
      the value of the HttpProxyAuthMethod property

    • setHttpProxyAuthMethod

      public void setHttpProxyAuthMethod​(String value)
      Sets the HttpProxyAuthMethod property; see getHttpProxyAuthMethod().
      Parameters:
      value - the new value (not null)

    • getHttpProxyDomain

      public String getHttpProxyDomain()
      Specifies the optional Windows domain used for NTLM authentication with the HTTP proxy.

      This applies only to the outbound proxy connection used to reach the SSH server, and only when getHttpProxyAuthMethod() is NTLM.

      If getSocksVersion() is set to 4 or 5, the SOCKS proxy takes precedence and these HTTP proxy settings are ignored. The proxies are not chained.

      Returns:
      the value of the HttpProxyDomain property

    • setHttpProxyDomain

      public void setHttpProxyDomain​(String value)
      Sets the HttpProxyDomain property; see getHttpProxyDomain().
      Parameters:
      value - the new value (not null)

    • getHttpProxyHostname

      public String getHttpProxyHostname()
      Specifies the hostname or IPv4 address of the HTTP proxy through which the outbound connection to the SSH server is made.

      Leave this property empty when no HTTP proxy is required.

      If getSocksVersion() is set to 4 or 5, the SOCKS proxy takes precedence and these HTTP proxy settings are ignored. The proxies are not chained.

      Returns:
      the value of the HttpProxyHostname property

    • setHttpProxyHostname

      public void setHttpProxyHostname​(String value)
      Sets the HttpProxyHostname property; see getHttpProxyHostname().
      Parameters:
      value - the new value (not null)

    • getHttpProxyPassword

      public String getHttpProxyPassword()
      Specifies the password used to authenticate with the HTTP proxy for the outbound connection to the SSH server.

      If getSocksVersion() is set to 4 or 5, the SOCKS proxy takes precedence and these HTTP proxy settings are ignored. The proxies are not chained.

      Returns:
      the value of the HttpProxyPassword property

    • setHttpProxyPassword

      public void setHttpProxyPassword​(String value)
      Sets the HttpProxyPassword property; see getHttpProxyPassword().
      Parameters:
      value - the new value (not null)

    • getHttpProxyPort

      public int getHttpProxyPort()
      Specifies the TCP port of the HTTP proxy used for the outbound connection to the SSH server.

      Common HTTP proxy ports include 8080 and 3128.

      If getSocksVersion() is set to 4 or 5, the SOCKS proxy takes precedence and these HTTP proxy settings are ignored. The proxies are not chained.

      Returns:
      the value of the HttpProxyPort property

    • setHttpProxyPort

      public void setHttpProxyPort​(int value)
      Sets the HttpProxyPort property; see getHttpProxyPort().
      Parameters:
      value - the new value

    • getHttpProxyUsername

      public String getHttpProxyUsername()
      Specifies the username used to authenticate with the HTTP proxy for the outbound connection to the SSH server.

      If getSocksVersion() is set to 4 or 5, the SOCKS proxy takes precedence and these HTTP proxy settings are ignored. The proxies are not chained.

      Returns:
      the value of the HttpProxyUsername property

    • setHttpProxyUsername

      public void setHttpProxyUsername​(String value)
      Sets the HttpProxyUsername property; see getHttpProxyUsername().
      Parameters:
      value - the new value (not null)

    • getIdleTimeoutMs

      public int getIdleTimeoutMs()
      Specifies a stall timeout, in milliseconds, for tunnel data-transfer operations. The default value is 30000 milliseconds (30 seconds). A value of 0 disables the timeout.

      This property is not a general inactivity timer for established background tunnel clients. An otherwise idle client, or a client with data queued while an SSH channel is flow-controlled, may remain connected beyond this interval. Applications should not rely on this property to disconnect clients merely because no application data is flowing.

      Returns:
      the value of the IdleTimeoutMs property

    • setIdleTimeoutMs

      public void setIdleTimeoutMs​(int value)
      Sets the IdleTimeoutMs property; see getIdleTimeoutMs().
      Parameters:
      value - the new value

    • getInboundSocksPassword

      public String getInboundSocksPassword()
      Specifies the password required from inbound SOCKS5 clients when getDynamicPortForwarding() is true.

      This property is used together with getInboundSocksUsername(). It does not apply to SOCKS4 because the SOCKS4 protocol has no password field.

      Returns:
      the value of the InboundSocksPassword property

    • setInboundSocksPassword

      public void setInboundSocksPassword​(String value)
      Sets the InboundSocksPassword property; see getInboundSocksPassword().
      Parameters:
      value - the new value (not null)

    • getInboundSocksUsername

      public String getInboundSocksUsername()
      Specifies the username required from inbound SOCKS clients when getDynamicPortForwarding() is true.
      • For SOCKS5, setting this property enables username/password authentication.
      • For SOCKS4, the value is compared with the client-supplied user ID.
      • Leave it empty to require no inbound SOCKS username.

      Returns:
      the value of the InboundSocksUsername property

    • setInboundSocksUsername

      public void setInboundSocksUsername​(String value)
      Sets the InboundSocksUsername property; see getInboundSocksUsername().
      Parameters:
      value - the new value (not null)

    • getIsAccepting

      public boolean getIsAccepting()
      true when the local listener thread is running and accepting inbound TCP connections; otherwise false.

      This property describes only the local listener. It can remain true after the SSH connection is lost or after closeTunnel(boolean) is called. In those states a client may connect to the local port even though its traffic cannot be forwarded.

      Use isSshConnected() separately when the application also needs to know whether the SSH transport is available.

      Returns:
      the value of the IsAccepting property (read-only)

    • getKeepAcceptLog

      public boolean getKeepAcceptLog()
      Controls whether activity from the background listener thread is retained in memory.

      The default value is false. When enabled, retrieve the log from getAcceptLog().

      Returns:
      the value of the KeepAcceptLog property

    • setKeepAcceptLog

      public void setKeepAcceptLog​(boolean value)
      Sets the KeepAcceptLog property; see getKeepAcceptLog().
      Parameters:
      value - the new value

    • getKeepTunnelLog

      public boolean getKeepTunnelLog()
      Controls whether SSH tunnel-thread activity is retained in memory.

      The default value is false. When enabled, retrieve the log from getTunnelLog().

      Returns:
      the value of the KeepTunnelLog property

    • setKeepTunnelLog

      public void setKeepTunnelLog​(boolean value)
      Sets the KeepTunnelLog property; see getKeepTunnelLog().
      Parameters:
      value - the new value

    • getListenBindIpAddress

      public String getListenBindIpAddress()
      Specifies the local IPv4 address to which the tunnel's listening socket is bound.

      Value Listener exposure

      Empty string Binds to 0.0.0.0 and accepts connections on all local IPv4 interfaces, subject to firewall rules.

      127.0.0.1 Accepts connections only from the local computer through loopback.

      A specific local LAN address Accepts connections through that interface only; loopback is not included automatically.

      For a tunnel intended only for local applications, explicitly set this property to 127.0.0.1. Leaving it empty may expose the listening port to other computers on the network.

      If the value is malformed or is not assigned to a local interface, beginAccepting(int) returns false and the bind failure is available in LastErrorText and the accept log.

      Returns:
      the value of the ListenBindIpAddress property

    • setListenBindIpAddress

      public void setListenBindIpAddress​(String value)
      Sets the ListenBindIpAddress property; see getListenBindIpAddress().
      Parameters:
      value - the new value (not null)

    • getListenPort

      public int getListenPort()
      Contains the local TCP port used by the listener started by beginAccepting(int).
      • If BeginAccepting succeeds with a nonzero requested port, this property contains that port.
      • If BeginAccepting succeeds with 0, the operating system chooses an available port and this property contains the allocated port when the method returns.
      • After a bind failure for an explicitly requested port, this property may still contain the requested port even though getIsAccepting() is false.
      • The value is initially 0.

      Returns:
      the value of the ListenPort property (read-only)

    • getOutboundBindIpAddress

      public String getOutboundBindIpAddress()
      Specifies the local IP address to which the outbound socket is bound before connecting to the SSH server.

      Most applications should leave this property empty. Set it only on a multihomed computer when the SSH connection must originate from a specific local network interface or IP address.

      Returns:
      the value of the OutboundBindIpAddress property

    • setOutboundBindIpAddress

      public void setOutboundBindIpAddress​(String value)
      Sets the OutboundBindIpAddress property; see getOutboundBindIpAddress().
      Parameters:
      value - the new value (not null)

    • getOutboundBindPort

      public int getOutboundBindPort()
      Specifies the local TCP port to bind before making the outbound connection to the SSH server.

      The default value is 0, which allows the operating system to choose an available ephemeral port. Nearly all applications should leave this property unchanged.

      Returns:
      the value of the OutboundBindPort property

    • setOutboundBindPort

      public void setOutboundBindPort​(int value)
      Sets the OutboundBindPort property; see getOutboundBindPort().
      Parameters:
      value - the new value

    • getPreferIpv6

      public boolean getPreferIpv6()
      Controls which IP version is preferred when a hostname resolves to both IPv4 and IPv6 addresses.
      • false (the default) prefers IPv4.
      • true prefers IPv6.

      Returns:
      the value of the PreferIpv6 property

    • setPreferIpv6

      public void setPreferIpv6​(boolean value)
      Sets the PreferIpv6 property; see getPreferIpv6().
      Parameters:
      value - the new value

    • getSoRcvBuf

      public int getSoRcvBuf()
      Sets the receive-buffer size for the underlying TCP socket.

      The default value is 4194304 bytes. Normally this property should remain unchanged. If receive performance is unusually slow, testing a larger value that is a multiple of 4096 may help.

      Returns:
      the value of the SoRcvBuf property

    • setSoRcvBuf

      public void setSoRcvBuf​(int value)
      Sets the SoRcvBuf property; see getSoRcvBuf().
      Parameters:
      value - the new value

    • getSoSndBuf

      public int getSoSndBuf()
      Sets the send-buffer size for the underlying TCP socket.

      The default value is 262144 bytes. Normally this property should remain unchanged. If send performance is unusually slow, testing values such as 524288 or 1048576 may help. A multiple of 4096 is recommended.

      Returns:
      the value of the SoSndBuf property

    • setSoSndBuf

      public void setSoSndBuf​(int value)
      Sets the SoSndBuf property; see getSoSndBuf().
      Parameters:
      value - the new value

    • getSocksHostname

      public String getSocksHostname()
      Specifies the hostname or IPv4 address of the outbound SOCKS4 or SOCKS5 proxy used to reach the SSH server.

      This property is used only when getSocksVersion() is 4 or 5.

      Returns:
      the value of the SocksHostname property

    • setSocksHostname

      public void setSocksHostname​(String value)
      Sets the SocksHostname property; see getSocksHostname().
      Parameters:
      value - the new value (not null)

    • getSocksPassword

      public String getSocksPassword()
      Specifies the password for authenticating with an outbound SOCKS5 proxy used to reach the SSH server.

      SOCKS4 does not support password authentication, so this property does not apply when getSocksVersion() is 4.

      Returns:
      the value of the SocksPassword property

    • setSocksPassword

      public void setSocksPassword​(String value)
      Sets the SocksPassword property; see getSocksPassword().
      Parameters:
      value - the new value (not null)

    • getSocksPort

      public int getSocksPort()
      Specifies the TCP port of the outbound SOCKS4 or SOCKS5 proxy used to reach the SSH server.

      The default value is 1080. This property is used only when getSocksVersion() is 4 or 5.

      Returns:
      the value of the SocksPort property

    • setSocksPort

      public void setSocksPort​(int value)
      Sets the SocksPort property; see getSocksPort().
      Parameters:
      value - the new value

    • getSocksUsername

      public String getSocksUsername()
      Specifies the username for the outbound SOCKS4 or SOCKS5 proxy used to reach the SSH server.

      This property is used only when getSocksVersion() is 4 or 5.

      Returns:
      the value of the SocksUsername property

    • setSocksUsername

      public void setSocksUsername​(String value)
      Sets the SocksUsername property; see getSocksUsername().
      Parameters:
      value - the new value (not null)

    • getSocksVersion

      public int getSocksVersion()
      Selects whether the outbound connection to the SSH server is made through a SOCKS proxy.

      Value Behavior

      0 Do not use a SOCKS proxy. This is the default.

      4 Connect through a SOCKS4 proxy.

      5 Connect through a SOCKS5 proxy.

      When this property is 4 or 5, the SOCKS proxy settings take precedence over the HTTP proxy settings. The SOCKS and HTTP proxies are not chained.

      Returns:
      the value of the SocksVersion property

    • setSocksVersion

      public void setSocksVersion​(int value)
      Sets the SocksVersion property; see getSocksVersion().
      Parameters:
      value - the new value

    • getTcpNoDelay

      public boolean getTcpNoDelay()
      Controls the TCP_NODELAY socket option for the underlying TCP connection.

      The default value is false. Setting it to true disables the Nagle algorithm, which can reduce latency when many small amounts of data are sent.

      Returns:
      the value of the TcpNoDelay property

    • setTcpNoDelay

      public void setTcpNoDelay​(boolean value)
      Sets the TcpNoDelay property; see getTcpNoDelay().
      Parameters:
      value - the new value

    • getTunnelLog

      public String getTunnelLog()
      Contains the in-memory activity log for the SSH tunnel and client-manager threads. The log is populated only when getKeepTunnelLog() is true.

      Treat this log as sensitive diagnostic data. It can contain hostnames, ports, usernames, proxy details, SOCKS handshake information, and authentication failure values. Do not publish or persist it without reviewing and protecting its contents.

      Returns:
      the value of the TunnelLog property

    • setTunnelLog

      public void setTunnelLog​(String value)
      Sets the TunnelLog property; see getTunnelLog().
      Parameters:
      value - the new value (not null)

    • getTunnelLogPath

      public String getTunnelLogPath()
      Specifies the local file path where SSH tunnel-thread activity is written.

      This file-based log is separate from the in-memory getTunnelLog().

      Returns:
      the value of the TunnelLogPath property

    • setTunnelLogPath

      public void setTunnelLogPath​(String value)
      Sets the TunnelLogPath property; see getTunnelLogPath().
      Parameters:
      value - the new value (not null)

    • getUncommonOptions

      public String getUncommonOptions()
      Provides optional behavior for uncommon requirements. The default value is an empty string, which is appropriate for most applications.

      To enable more than one option, provide a comma-separated list of keywords.

      Keyword Effect

      ForceUserAuthRsaSha1 Forces rsa-sha1 for public-key user authentication. Set this before connecting. Added in v9.5.0.98.

      NoKeepAliveIgnoreMsg Disables the default SSH ignore message sent every 20 seconds to keep an idle connection alive. Added in v9.5.0.76.

      no-weak-mac-algs Removes hmac-sha1-96, hmac-sha1, hmac-md5, and hmac-ripemd160 from the offered MAC algorithms. Added in v9.5.0.98.

      ProtectFromVpn On Android, bypasses an installed or active VPN. Added in v9.5.0.80.

      +ssh-hmac-etm Re-enables SSH encrypt-then-MAC algorithms that were disabled by default in v9.5.0.97 as part of the Terrapin mitigation.

      +chacha20-poly1305@openssh.com Re-enables chacha20-poly1305@openssh.com, which was removed from the default offer in v9.5.0.97 as part of the Terrapin mitigation.

      Returns:
      the value of the UncommonOptions property

    • setUncommonOptions

      public void setUncommonOptions​(String value)
      Sets the UncommonOptions property; see getUncommonOptions().
      Parameters:
      value - the new value (not null)

    • authenticatePk

      public void authenticatePk​(String username, SshKey privateKey)
      Authenticates with the SSH server using public-key authentication.

      The public key corresponding to privateKey must already be installed for username on the SSH server.

      Call connect(String, int) or connectThroughSsh(Ssh, String, int) before calling this method.

      When requesting support for an authentication failure, include the complete LastErrorText.

      Parameters:
      username - the username argument (not null)
      privateKey - the privateKey argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • authenticatePw

      public void authenticatePw​(String login, String password)
      Authenticates with the SSH server using login and password.

      Establish the SSH connection first by calling connect(String, int) or connectThroughSsh(Ssh, String, int). After authentication succeeds, call beginAccepting(int) to begin accepting tunnel clients.

      • A rejected username or password does not close the SSH connection; the application may correct the credentials and call this method again.
      • Calling this method again after authentication has already succeeded returns false with an “Already authenticated” error.

      When requesting support for an authentication failure, include the complete LastErrorText captured immediately after the failed call.

      Parameters:
      login - the login argument (not null)
      password - the password argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • authenticatePwPk

      public void authenticatePwPk​(String username, String password, SshKey privateKey)
      Authenticates with an SSH server that requires both a password and a private key.

      The public key corresponding to privateKey must already be installed for username on the SSH server. Most SSH servers require either password authentication or public-key authentication rather than both.

      When requesting support for an authentication failure, include the complete LastErrorText.

      Parameters:
      username - the username argument (not null)
      password - the password argument (not null)
      privateKey - the privateKey argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • authenticateSecPw

      public void authenticateSecPw​(SecureString login, SecureString password)
      Performs the same password authentication as authenticatePw(String, String), but receives the login and password in SecureString objects.
      Parameters:
      login - the login argument (not null)
      password - the password argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • authenticateSecPwPk

      public void authenticateSecPwPk​(SecureString username, SecureString password, SshKey privateKey)
      Performs the same combined password-and-private-key authentication as authenticatePwPk(String, String, SshKey), but receives the username and password in SecureString objects.
      Parameters:
      username - the username argument (not null)
      password - the password argument (not null)
      privateKey - the privateKey argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • beginAccepting

      public void beginAccepting​(int listenPort)
      Creates and starts the local listener on listenPort.

      The SSH connection must already have been established. Although the listener can be started before user authentication, clients accepted in that state cannot be forwarded. The recommended sequence is to connect, authenticate, and then call this method.

      • The requested port must not already be in use on the selected local interface.
      • Pass 0 to let the operating system choose an available port, then read getListenPort().
      • Calling this method while the listener is already running returns false.

      The method waits for the initial bind-and-listen result. It returns false for errors such as an occupied port, a malformed bind address, or an address that is not assigned to the local computer. Details are available immediately in LastErrorText and, when enabled, the accept log.

      A successful return means the listener was bound and started. No additional fixed delay is required merely to discover an initial bind failure.

      Parameters:
      listenPort - the listenPort argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • closeTunnel

      public void closeTunnel​(boolean waitForThreads)
      Disconnects active tunnel clients and stops the tunnel-manager thread.

      When waitForThreads is true, the method waits for the client and tunnel-manager threads to exit. It returns false if a worker thread does not stop; capture LastErrorText immediately for details.

      This method does not stop the local listener and does not disconnect or reset the underlying SSH transport. Call stopAccepting(boolean) separately to stop accepting local TCP connections. After this method returns, the listener may still accept a local connection even though the connection cannot be forwarded.

      Calling this method more than once is allowed. However, it does not reset the object for a new call to connect(String, int). Use a new SshTunnel object when connecting to a different SSH server.

      Parameters:
      waitForThreads - the waitForThreads argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • connect

      public void connect​(String hostname, int port)
      Establishes the SSH connection that will carry tunneled traffic. This method performs the TCP or proxy connection, the SSH protocol handshake, and host-key negotiation, but it does not authenticate the SSH user.

      After connecting, verify getHostKeyFingerprint(), then authenticate by calling one of the Authenticate* methods. Finally, call beginAccepting(int) to start the local listener.

      The host-key fingerprint is available immediately after this method succeeds, before user authentication. Calling Connect again while an SSH tunnel already exists returns false.

      Chilkat sends an SSH ignore message every 20 seconds to help keep an unused SSH connection alive. To disable this behavior, add NoKeepAliveIgnoreMsg to getUncommonOptions() before connecting.

      Parameters:
      hostname - the hostname argument (not null)
      port - the port argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • connectThroughSsh

      public void connectThroughSsh​(Ssh ssh, String hostname, int port)
      Connects to a second SSH server through the existing connected and authenticated Ssh object supplied in ssh. 
      application -> first SSH server -> second SSH server

      hostname and port identify the second SSH server. After this method succeeds, call an authentication method on this SshTunnel object to authenticate with the second server.

      The supplied Ssh object is borrowed, not copied. It must remain alive, connected, and authenticated for as long as this tunnel is used. If the first-hop object is disconnected, existing forwarded clients stop working and new local connections cannot be forwarded. The local listener may nevertheless remain active until explicitly stopped.

      getHostKeyFingerprint() reports the fingerprint of the second SSH server. After the connection is established, fixed forwarding destinations such as 127.0.0.1 are interpreted from the second server's network environment.

      Parameters:
      ssh - the ssh argument (not null)
      hostname - the hostname argument (not null)
      port - the port argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • continueKeyboardAuth

      public String continueKeyboardAuth​(String response)
      Continues a keyboard-interactive authentication exchange started by startKeyboardAuth(String).

      If the server requested one response, pass that value directly in response. If it requested multiple responses, pass XML in the following form: 

      _LT_response_GT_
   _LT_response1_GT_response to first prompt_LT_/response1_GT_
   _LT_response2_GT_response to second prompt_LT_/response2_GT_
   ...
   _LT_responseN_GT_response to Nth prompt_LT_/responseN_GT_
 _LT_/response_GT_

      When authentication completes, the returned XML indicates success or failure: 

      _LT_success_GT_success message_LT_/success_GT_
 
 _LT_error_GT_error message_LT_/error_GT_

      If another challenge is required, the method returns another infoRequest XML document containing the next set of prompts.

      Parameters:
      response - the response argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • disconnectAllClients

      public void disconnectAllClients​(boolean waitForThreads)
      Disconnects all active tunnel clients while leaving the local listener and SSH connection available.

      When waitForThreads is true, the method waits for the current client threads to exit before returning. The listener continues accepting new clients, and newly accepted clients can be forwarded normally.

      Parameters:
      waitForThreads - the waitForThreads argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getCurrentState

      public String getCurrentState()
      Returns an XML snapshot describing the tunnel manager, SSH channels, and current tunnel clients. The returned data is intended for diagnostics and monitoring.

      A typical result has the following structure: 

      _LT_CurrentState_GT_
   _LT_tunnelManager rcvByteCount="433" sndByteCount="34"
       threadRunning="1" dynamicPortForwarding="0"
       staticDestHost="localhost" staticDestPort="18080"_GT_
     _LT_openChannels count="1"_GT_
       _LT_channel num="101" channelType="direct-tcpip"
           clientWinSize="2096927" serverWinSize="2097127" /_GT_
     _LT_/openChannels_GT_
     _LT_closedChannels count="0" /_GT_
   _LT_/tunnelManager_GT_
   _LT_clients count="1"_GT_
     _LT_client destIp="localhost" destPort="18080"
         sshChannelNum="101" threadRunning="1"
         rcvByteCount="25" sndByteCount="225" /_GT_
   _LT_/clients_GT_
 _LT_/CurrentState_GT_

      The exact child elements can vary with state. For example, channel collections may be empty, and some transport details may be omitted before the tunnel is started or after it stops.

      Section Information

      tunnelManager Aggregate byte counts, worker-thread state, forwarding mode, and configured fixed destination.

      openChannels and closedChannels SSH channel numbers, close/EOF flags, packet sizes, and flow-control window sizes.

      clients Per-client destination, SSH channel number, worker state, age/activity counters, pending-data flags, and byte counts.

      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • isSshConnected

      public boolean isSshConnected()
      Returns true when the SSH transport used by this tunnel is connected; otherwise returns false.

      This is independent of the local listener state. The listener may still be accepting local TCP connections when this method returns false, but those connections cannot be forwarded until a usable SSH transport exists.

      For a tunnel created with connectThroughSsh(Ssh, String, int), this method becomes false when the borrowed first-hop Ssh connection is disconnected.

      Returns:
      the result; this method never throws ChilkatException

    • setAllowedAlgorithms

      public void setAllowedAlgorithms​(JsonObject json)
      Restricts the SSH connection to the algorithms specified in json.

      This allows an application to define the exact algorithm set that may be used during SSH negotiation.

      Parameters:
      json - the json argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • startKeyboardAuth

      public String startKeyboardAuth​(String login)
      Begins keyboard-interactive authentication for login.

      When the server requests one or more responses, the returned XML contains the request name, instructions, and prompts: 

      _LT_infoRequest numPrompts="N"_GT_
   _LT_name_GT_name text_LT_/name_GT_
   _LT_instruction_GT_instruction text_LT_/instruction_GT_
   _LT_prompt1 echo="1_or_0"_GT_prompt text_LT_/prompt1_GT_
   ...
   _LT_promptN echo="1_or_0"_GT_prompt text_LT_/promptN_GT_
 _LT_/infoRequest_GT_

      The echo attribute indicates whether the response should be displayed while entered.

      If authentication immediately succeeds or fails without requiring a response, the returned XML has one of these forms: 

      _LT_success_GT_success message_LT_/success_GT_
 
 _LT_error_GT_error message_LT_/error_GT_

      Pass the requested response or responses to continueKeyboardAuth(String).

      Parameters:
      login - the login argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • stopAccepting

      public void stopAccepting​(boolean waitForThread)
      Stops the local listener so that no new client connections are accepted. Existing forwarded clients remain connected and continue exchanging data.
      • When waitForThread is true, the method waits for the listener thread to exit before returning.
      • When it is false, shutdown is asynchronous and getIsAccepting() may remain true briefly after the method returns.

      Call beginAccepting(int) again to resume accepting connections. The listener can be restarted on the same port after the previous listener has stopped.

      Parameters:
      waitForThread - the waitForThread argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setProgressListener

      public void setProgressListener​(ProgressListener listener)
      Installs the listener that receives this object's progress events (abortCheck, percentDone, progressInfo) during its long-running methods; replaces any listener or lambda installed before; null removes it.
      Parameters:
      listener - the listener, or null
      Throws:
      IllegalStateException - if called from inside one of this object's own callbacks

    • getProgressListener

      public ProgressListener getProgressListener()
      Returns the installed listener, or null.
      Returns:
      the listener installed with setProgressListener(ProgressListener) or one of the on... methods

    • onAbortCheck

      public void onAbortCheck​(BooleanSupplier callback)
      Installs a listener whose only callback is abortCheck: called every HeartbeatMs milliseconds during a long-running method; return true to abort it. Replaces any listener installed before.
      Parameters:
      callback - the callback, or null to remove the listener

    • onPercentDone

      public void onPercentDone​(IntPredicate callback)
      Installs a listener whose only callback is percentDone: called with the completion percentage (0..100) as a long-running method progresses; return true to abort it. Replaces any listener installed before.
      Parameters:
      callback - the callback, or null to remove the listener

    • onProgressInfo

      public void onProgressInfo​(BiConsumer<String,​String> callback)
      Installs a listener whose only callback is progressInfo: called with a name/value pair of progress information as a long-running method proceeds. Replaces any listener installed before.
      Parameters:
      callback - the callback, or null to remove the listener