## com.trilead.ssh2
Class Connection

    java.lang.Object
      com.trilead.ssh2.Connection

    public class Connection

extends java.lang.Object

A `Connection` is used to establish an encrypted TCP/IP connection to a SSH-2 server.

Typically, one

1. creates a `Connection` object.
2. calls the `connect()` method.
3. calls some of the authentication methods (e.g., `authenticateWithPublicKey()`).
4. calls one or several times the `openSession()` method.
5. finally, one must close the connection and release resources with the `close()` method.

Field Summary
`static java.lang.String` `identification` The identifier presented to the SSH-2 server.

Constructor Summary
`Connection(java.lang.String hostname)` Prepares a fresh `Connection` object which can then be used to establish a connection to the specified SSH-2 server.
`Connection(java.lang.String hostname, int port)` Prepares a fresh `Connection` object which can then be used to establish a connection to the specified SSH-2 server.

Method Summary
`void` `addConnectionMonitor(ConnectionMonitor cmon)` Add a `ConnectionMonitor` to this connection.
`boolean` `authenticateWithDSA(java.lang.String user, java.lang.String pem, java.lang.String password)` Deprecated. You should use one of the `authenticateWithPublicKey()` methods, this method is just a wrapper for it and will disappear in future builds.
`boolean` `authenticateWithKeyboardInteractive(java.lang.String user, InteractiveCallback cb)` A wrapper that calls `authenticateWithKeyboardInteractivewith` a `null` submethod list.
`boolean` `authenticateWithKeyboardInteractive(java.lang.String user, java.lang.String[] submethods, InteractiveCallback cb)` After a successful connect, one has to authenticate oneself.
`boolean` `authenticateWithNone(java.lang.String user)` After a successful connect, one has to authenticate oneself.
`boolean` `authenticateWithPassword(java.lang.String user, java.lang.String password)` After a successful connect, one has to authenticate oneself.
`boolean` `authenticateWithPublicKey(java.lang.String user, char[] pemPrivateKey, java.lang.String password)` After a successful connect, one has to authenticate oneself.
`boolean` `authenticateWithPublicKey(java.lang.String user, java.io.File pemFile, java.lang.String password)` A convenience wrapper function which reads in a private key (PEM format, either DSA or RSA) and then calls `authenticateWithPublicKey(String, char[], String)`.
`void` `cancelRemotePortForwarding(int bindPort)` Cancel an earlier requested remote port forwarding.
`void` `close()` Close the connection to the SSH-2 server.
`ConnectionInfo` `connect()` Same as `connect(null, 0, 0)`.
`ConnectionInfo` `connect(ServerHostKeyVerifier verifier)` Same as `connect(verifier, 0, 0)`.
`ConnectionInfo` `connect(ServerHostKeyVerifier verifier, int connectTimeout, int kexTimeout)` Connect to the SSH-2 server and, as soon as the server has presented its host key, use the `ServerHostKeyVerifier.verifyServerHostKey()` method of the `verifier` to ask for permission to proceed.
`LocalPortForwarder` `createLocalPortForwarder(java.net.InetSocketAddress addr, java.lang.String host_to_connect, int port_to_connect)` Creates a new `LocalPortForwarder`.
`LocalPortForwarder` `createLocalPortForwarder(int local_port, java.lang.String host_to_connect, int port_to_connect)` Creates a new `LocalPortForwarder`.
`LocalStreamForwarder` `createLocalStreamForwarder(java.lang.String host_to_connect, int port_to_connect)` Creates a new `LocalStreamForwarder`.
`SCPClient` `createSCPClient()` Create a very basic `SCPClient` that can be used to copy files from/to the SSH-2 server.
`void` `enableDebugging(boolean enable, DebugLogger logger)` Enable/disable debug logging.
`void` `forceKeyExchange()` Force an asynchronous key re-exchange (the call does not block).
`static java.lang.String[]` `getAvailableCiphers()` Unless you know what you are doing, you will never need this.
`static java.lang.String[]` `getAvailableMACs()` Unless you know what you are doing, you will never need this.
`static java.lang.String[]` `getAvailableServerHostKeyAlgorithms()` Unless you know what you are doing, you will never need this.
`ConnectionInfo` `getConnectionInfo()` Returns a `ConnectionInfo` object containing the details of the connection.
`java.lang.String` `getHostname()` Returns the hostname that was passed to the constructor.
`int` `getPort()` Returns the port that was passed to the constructor.
`java.lang.String[]` `getRemainingAuthMethods(java.lang.String user)` After a successful connect, one has to authenticate oneself.
`ClientServerHello` `getVersionInfo()`
`boolean` `isAuthenticationComplete()` Determines if the authentication phase is complete.
`boolean` `isAuthenticationPartialSuccess()` Returns true if there was at least one failed authentication request and the last failed authentication request was marked with "partial success" by the server.
`boolean` `isAuthMethodAvailable(java.lang.String user, java.lang.String method)` Checks if a specified authentication method is available.
`Session` `openSession()` Open a new `Session` on this connection.
`void` `ping()` This method can be used to perform end-to-end connection testing.
`void` `requestRemotePortForwarding(java.lang.String bindAddress, int bindPort, java.lang.String targetAddress, int targetPort)` Request a remote port forwarding.
`void` `sendIgnorePacket()` Send an SSH_MSG_IGNORE packet.
`void` `sendIgnorePacket(byte[] data)` Send an SSH_MSG_IGNORE packet with the given data attribute.
`void` `setClient2ServerCiphers(java.lang.String[] ciphers)` Unless you know what you are doing, you will never need this.
`void` `setClient2ServerMACs(java.lang.String[] macs)` Unless you know what you are doing, you will never need this.
`void` `setDHGexParameters(DHGexParameters dgp)` Sets the parameters for the diffie-hellman group exchange.
`void` `setProxyData(ProxyData proxyData)` Used to tell the library that the connection shall be established through a proxy server.
`void` `setSecureRandom(java.security.SecureRandom rnd)` Provide your own instance of SecureRandom.
`void` `setServer2ClientCiphers(java.lang.String[] ciphers)` Unless you know what you are doing, you will never need this.
`void` `setServer2ClientMACs(java.lang.String[] macs)` Unless you know what you are doing, you will never need this.
`void` `setServerHostKeyAlgorithms(java.lang.String[] algos)` Define the set of allowed server host key algorithms to be used for the following key exchange operations.
`void` `setTCPNoDelay(boolean enable)` Enable/disable TCP_NODELAY (disable/enable Nagle's algorithm) on the underlying socket.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### identification

    public static final java.lang.String identification

  The identifier presented to the SSH-2 server.

  See Also:
    Constant Field Values

Constructor Detail

### Connection

    public Connection(java.lang.String hostname)

  Prepares a fresh `Connection` object which can then be used to establish a connection to the specified SSH-2 server.

  Same as `Connection(hostname, 22)`.

  Parameters:
    `hostname` - the hostname of the SSH-2 server.

### Connection

    public Connection(java.lang.String hostname,
                      int port)

  Prepares a fresh `Connection` object which can then be used to establish a connection to the specified SSH-2 server.

  Parameters:
    `hostname` - the host where we later want to connect to.
    `port` - port on the server, normally 22.

Method Detail

### getAvailableCiphers

    public static java.lang.String[] getAvailableCiphers()

  Unless you know what you are doing, you will never need this.

  Returns:
    The list of supported cipher algorithms by this implementation.

### getAvailableMACs

    public static java.lang.String[] getAvailableMACs()

  Unless you know what you are doing, you will never need this.

  Returns:
    The list of supported MAC algorthims by this implementation.

### getAvailableServerHostKeyAlgorithms

    public static java.lang.String[] getAvailableServerHostKeyAlgorithms()

  Unless you know what you are doing, you will never need this.

  Returns:
    The list of supported server host key algorthims by this implementation.

### authenticateWithDSA

    public boolean authenticateWithDSA(java.lang.String user,
                                       java.lang.String pem,
                                       java.lang.String password)
                                throws java.io.IOException

  Deprecated. You should use one of the `authenticateWithPublicKey()` methods, this method is just a wrapper for it and will disappear in future builds.

  After a successful connect, one has to authenticate oneself. This method is based on DSA (it uses DSA to sign a challenge sent by the server).

  If the authentication phase is complete, `true` will be returned. If the server does not accept the request (or if further authentication steps are needed), `false` is returned and one can retry either by using this or any other authentication method (use the `getRemainingAuthMethods` method to get a list of the remaining possible methods).

  Parameters:
    `user` - A `String` holding the username.
    `pem` - A `String` containing the DSA private key of the user in OpenSSH key format (PEM, you can't miss the "-----BEGIN DSA PRIVATE KEY-----" tag). The string may contain linefeeds.
    `password` - If the PEM string is 3DES encrypted ("DES-EDE3-CBC"), then you must specify the password. Otherwise, this argument will be ignored and can be set to `null`.
  Returns:
    whether the connection is now authenticated.
  Throws:
    `java.io.IOException`

### authenticateWithKeyboardInteractive

    public boolean authenticateWithKeyboardInteractive(java.lang.String user,
                                                       InteractiveCallback cb)
                                                throws java.io.IOException

  A wrapper that calls `authenticateWithKeyboardInteractivewith` a `null` submethod list.

  Parameters:
    `user` - A `String` holding the username.
    `cb` - An `InteractiveCallback` which will be used to determine the responses to the questions asked by the server.
  Returns:
    whether the connection is now authenticated.
  Throws:
    `java.io.IOException`

### authenticateWithKeyboardInteractive

    public boolean authenticateWithKeyboardInteractive(java.lang.String user,
                                                       java.lang.String[] submethods,
                                                       InteractiveCallback cb)
                                                throws java.io.IOException

  After a successful connect, one has to authenticate oneself. This method is based on "keyboard-interactive", specified in draft-ietf-secsh-auth-kbdinteract-XX. Basically, you have to define a callback object which will be feeded with challenges generated by the server. Answers are then sent back to the server. It is possible that the callback will be called several times during the invocation of this method (e.g., if the server replies to the callback's answer(s) with another challenge...)

  If the authentication phase is complete, `true` will be returned. If the server does not accept the request (or if further authentication steps are needed), `false` is returned and one can retry either by using this or any other authentication method (use the `getRemainingAuthMethods` method to get a list of the remaining possible methods).

  Note: some SSH servers advertise "keyboard-interactive", however, any interactive request will be denied (without having sent any challenge to the client).

  Parameters:
    `user` - A `String` holding the username.
    `submethods` - An array of submethod names, see draft-ietf-secsh-auth-kbdinteract-XX. May be `null` to indicate an empty list.
    `cb` - An `InteractiveCallback` which will be used to determine the responses to the questions asked by the server.
  Returns:
    whether the connection is now authenticated.
  Throws:
    `java.io.IOException`

### authenticateWithPassword

    public boolean authenticateWithPassword(java.lang.String user,
                                            java.lang.String password)
                                     throws java.io.IOException

  After a successful connect, one has to authenticate oneself. This method sends username and password to the server.

  If the authentication phase is complete, `true` will be returned. If the server does not accept the request (or if further authentication steps are needed), `false` is returned and one can retry either by using this or any other authentication method (use the `getRemainingAuthMethods` method to get a list of the remaining possible methods).

  Note: if this method fails, then please double-check that it is actually offered by the server (use `getRemainingAuthMethods()`.

  Often, password authentication is disabled, but users are not aware of it. Many servers only offer "publickey" and "keyboard-interactive". However, even though "keyboard-interactive" *feels* like password authentication (e.g., when using the putty or openssh clients) it is *not* the same mechanism.

  Parameters:
    `user` -
    `password` -
  Returns:
    if the connection is now authenticated.
  Throws:
    `java.io.IOException`

### authenticateWithNone

    public boolean authenticateWithNone(java.lang.String user)
                                 throws java.io.IOException

  After a successful connect, one has to authenticate oneself. This method can be used to explicitly use the special "none" authentication method (where only a username has to be specified).

  Note 1: The "none" method may always be tried by clients, however as by the specs, the server will not explicitly announce it. In other words, the "none" token will never show up in the list returned by `getRemainingAuthMethods(String)`.

  Note 2: no matter which one of the authenticateWithXXX() methods you call, the library will always issue exactly one initial "none" authentication request to retrieve the initially allowed list of authentication methods by the server. Please read RFC 4252 for the details.

  If the authentication phase is complete, `true` will be returned. If further authentication steps are needed, `false` is returned and one can retry by any other authentication method (use the `getRemainingAuthMethods` method to get a list of the remaining possible methods).

  Parameters:
    `user` -
  Returns:
    if the connection is now authenticated.
  Throws:
    `java.io.IOException`

### authenticateWithPublicKey

    public boolean authenticateWithPublicKey(java.lang.String user,
                                             char[] pemPrivateKey,
                                             java.lang.String password)
                                      throws java.io.IOException

  After a successful connect, one has to authenticate oneself. The authentication method "publickey" works by signing a challenge sent by the server. The signature is either DSA or RSA based - it just depends on the type of private key you specify, either a DSA or RSA private key in PEM format. And yes, this is may seem to be a little confusing, the method is called "publickey" in the SSH-2 protocol specification, however since we need to generate a signature, you actually have to supply a private key =).

  The private key contained in the PEM file may also be encrypted ("Proc-Type: 4,ENCRYPTED"). The library supports DES-CBC and DES-EDE3-CBC encryption, as well as the more exotic PEM encrpytions AES-128-CBC, AES-192-CBC and AES-256-CBC.

  If the authentication phase is complete, `true` will be returned. If the server does not accept the request (or if further authentication steps are needed), `false` is returned and one can retry either by using this or any other authentication method (use the `getRemainingAuthMethods` method to get a list of the remaining possible methods).

  NOTE PUTTY USERS: Event though your key file may start with "-----BEGIN..." it is not in the expected format. You have to convert it to the OpenSSH key format by using the "puttygen" tool (can be downloaded from the Putty website). Simply load your key and then use the "Conversions/Export OpenSSH key" functionality to get a proper PEM file.

  Parameters:
    `user` - A `String` holding the username.
    `pemPrivateKey` - A `char[]` containing a DSA or RSA private key of the user in OpenSSH key format (PEM, you can't miss the "-----BEGIN DSA PRIVATE KEY-----" or "-----BEGIN RSA PRIVATE KEY-----" tag). The char array may contain linebreaks/linefeeds.
    `password` - If the PEM structure is encrypted ("Proc-Type: 4,ENCRYPTED") then you must specify a password. Otherwise, this argument will be ignored and can be set to `null`.
  Returns:
    whether the connection is now authenticated.
  Throws:
    `java.io.IOException`

### authenticateWithPublicKey

    public boolean authenticateWithPublicKey(java.lang.String user,
                                             java.io.File pemFile,
                                             java.lang.String password)
                                      throws java.io.IOException

  A convenience wrapper function which reads in a private key (PEM format, either DSA or RSA) and then calls `authenticateWithPublicKey(String, char[], String)`.

  NOTE PUTTY USERS: Event though your key file may start with "-----BEGIN..." it is not in the expected format. You have to convert it to the OpenSSH key format by using the "puttygen" tool (can be downloaded from the Putty website). Simply load your key and then use the "Conversions/Export OpenSSH key" functionality to get a proper PEM file.

  Parameters:
    `user` - A `String` holding the username.
    `pemFile` - A `File` object pointing to a file containing a DSA or RSA private key of the user in OpenSSH key format (PEM, you can't miss the "-----BEGIN DSA PRIVATE KEY-----" or "-----BEGIN RSA PRIVATE KEY-----" tag).
    `password` - If the PEM file is encrypted then you must specify the password. Otherwise, this argument will be ignored and can be set to `null`.
  Returns:
    whether the connection is now authenticated.
  Throws:
    `java.io.IOException`

### addConnectionMonitor

    public void addConnectionMonitor(ConnectionMonitor cmon)

  Add a `ConnectionMonitor` to this connection. Can be invoked at any time, but it is best to add connection monitors before invoking `connect()` to avoid glitches (e.g., you add a connection monitor after a successful connect(), but the connection has died in the mean time. Then, your connection monitor won't be notified.)

  You can add as many monitors as you like.

  Parameters:
    `cmon` - An object implementing the `ConnectionMonitor` interface.
  See Also:
    `ConnectionMonitor`

### close

    public void close()

  Close the connection to the SSH-2 server. All assigned sessions will be closed, too. Can be called at any time. Don't forget to call this once you don't need a connection anymore - otherwise the receiver thread may run forever.

### connect

    public ConnectionInfo connect()
                           throws java.io.IOException

  Same as `connect(null, 0, 0)`.

  Returns:
    see comments for the `connect(ServerHostKeyVerifier, int, int)` method.
  Throws:
    `java.io.IOException`

### connect

    public ConnectionInfo connect(ServerHostKeyVerifier verifier)
                           throws java.io.IOException

  Same as `connect(verifier, 0, 0)`.

  Returns:
    see comments for the `connect(ServerHostKeyVerifier, int, int)` method.
  Throws:
    `java.io.IOException`

### connect

    public ConnectionInfo connect(ServerHostKeyVerifier verifier,
                                  int connectTimeout,
                                  int kexTimeout)
                           throws java.io.IOException

  Connect to the SSH-2 server and, as soon as the server has presented its host key, use the `ServerHostKeyVerifier.verifyServerHostKey()` method of the `verifier` to ask for permission to proceed. If `verifier` is `null`, then any host key will be accepted - this is NOT recommended, since it makes man-in-the-middle attackes VERY easy (somebody could put a proxy SSH server between you and the real server).

  Note: The verifier will be called before doing any crypto calculations (i.e., diffie-hellman). Therefore, if you don't like the presented host key then no CPU cycles are wasted (and the evil server has less information about us).

  However, it is still possible that the server presented a fake host key: the server cheated (typically a sign for a man-in-the-middle attack) and is not able to generate a signature that matches its host key. Don't worry, the library will detect such a scenario later when checking the signature (the signature cannot be checked before having completed the diffie-hellman exchange).

  Note 2: The `ServerHostKeyVerifier.verifyServerHostKey()` method will *NOT* be called from the current thread, the call is being made from a background thread (there is a background dispatcher thread for every established connection).

  Note 3: This method will block as long as the key exchange of the underlying connection has not been completed (and you have not specified any timeouts).

  Note 4: If you want to re-use a connection object that was successfully connected, then you must call the `close()` method before invoking `connect()` again.

  Parameters:
    `verifier` - An object that implements the `ServerHostKeyVerifier` interface. Pass `null` to accept any server host key - NOT recommended.
    `connectTimeout` - Connect the underlying TCP socket to the server with the given timeout value (non-negative, in milliseconds). Zero means no timeout. If a proxy is being used (see `setProxyData(ProxyData)`), then this timeout is used for the connection establishment to the proxy.
    `kexTimeout` - Timeout for complete connection establishment (non-negative, in milliseconds). Zero means no timeout. The timeout counts from the moment you invoke the connect() method and is cancelled as soon as the first key-exchange round has finished. It is possible that the timeout event will be fired during the invocation of the `verifier` callback, but it will only have an effect after the `verifier` returns.
  Returns:
    A `ConnectionInfo` object containing the details of the established connection.
  Throws:
    `java.io.IOException` - If any problem occurs, e.g., the server's host key is not accepted by the `verifier` or there is problem during the initial crypto setup (e.g., the signature sent by the server is wrong).

    In case of a timeout (either connectTimeout or kexTimeout) a SocketTimeoutException is thrown.

    An exception may also be thrown if the connection was already successfully connected (no matter if the connection broke in the mean time) and you invoke `connect()` again without having called `close()` first.

    If a HTTP proxy is being used and the proxy refuses the connection, then a `HTTPProxyException` may be thrown, which contains the details returned by the proxy. If the proxy is buggy and does not return a proper HTTP response, then a normal IOException is thrown instead.

### createLocalPortForwarder

    public LocalPortForwarder createLocalPortForwarder(int local_port,
                                                       java.lang.String host_to_connect,
                                                       int port_to_connect)
                                                throws java.io.IOException

  Creates a new `LocalPortForwarder`. A `LocalPortForwarder` forwards TCP/IP connections that arrive at a local port via the secure tunnel to another host (which may or may not be identical to the remote SSH-2 server).

  This method must only be called after one has passed successfully the authentication step. There is no limit on the number of concurrent forwardings.

  Parameters:
    `local_port` - the local port the LocalPortForwarder shall bind to.
    `host_to_connect` - target address (IP or hostname)
    `port_to_connect` - target port
  Returns:
    A `LocalPortForwarder` object.
  Throws:
    `java.io.IOException`

### createLocalPortForwarder

    public LocalPortForwarder createLocalPortForwarder(java.net.InetSocketAddress addr,
                                                       java.lang.String host_to_connect,
                                                       int port_to_connect)
                                                throws java.io.IOException

  Creates a new `LocalPortForwarder`. A `LocalPortForwarder` forwards TCP/IP connections that arrive at a local port via the secure tunnel to another host (which may or may not be identical to the remote SSH-2 server).

  This method must only be called after one has passed successfully the authentication step. There is no limit on the number of concurrent forwardings.

  Parameters:
    `addr` - specifies the InetSocketAddress where the local socket shall be bound to.
    `host_to_connect` - target address (IP or hostname)
    `port_to_connect` - target port
  Returns:
    A `LocalPortForwarder` object.
  Throws:
    `java.io.IOException`

### createLocalStreamForwarder

    public LocalStreamForwarder createLocalStreamForwarder(java.lang.String host_to_connect,
                                                           int port_to_connect)
                                                    throws java.io.IOException

  Creates a new `LocalStreamForwarder`. A `LocalStreamForwarder` manages an Input/Outputstream pair that is being forwarded via the secure tunnel into a TCP/IP connection to another host (which may or may not be identical to the remote SSH-2 server).

  Parameters:
    `host_to_connect` -
    `port_to_connect` -
  Returns:
    A `LocalStreamForwarder` object.
  Throws:
    `java.io.IOException`

### createSCPClient

    public SCPClient createSCPClient()
                              throws java.io.IOException

  Create a very basic `SCPClient` that can be used to copy files from/to the SSH-2 server.

  Works only after one has passed successfully the authentication step. There is no limit on the number of concurrent SCP clients.

  Note: This factory method will probably disappear in the future.

  Returns:
    A `SCPClient` object.
  Throws:
    `java.io.IOException`

### forceKeyExchange

    public void forceKeyExchange()
                          throws java.io.IOException

  Force an asynchronous key re-exchange (the call does not block). The latest values set for MAC, Cipher and DH group exchange parameters will be used. If a key exchange is currently in progress, then this method has the only effect that the so far specified parameters will be used for the next (server driven) key exchange.

  Note: This implementation will never start a key exchange (other than the initial one) unless you or the SSH-2 server ask for it.

  Throws:
    `java.io.IOException` - In case of any failure behind the scenes.

### getHostname

    public java.lang.String getHostname()

  Returns the hostname that was passed to the constructor.

  Returns:
    the hostname

### getPort

    public int getPort()

  Returns the port that was passed to the constructor.

  Returns:
    the TCP port

### getConnectionInfo

    public ConnectionInfo getConnectionInfo()
                                     throws java.io.IOException

  Returns a `ConnectionInfo` object containing the details of the connection. Can be called as soon as the connection has been established (successfully connected).

  Returns:
    A `ConnectionInfo` object.
  Throws:
    `java.io.IOException` - In case of any failure behind the scenes.

### getVersionInfo

    public ClientServerHello getVersionInfo()
                                     throws java.io.IOException

  Throws:
    `java.io.IOException`

### getRemainingAuthMethods

    public java.lang.String[] getRemainingAuthMethods(java.lang.String user)
                                               throws java.io.IOException

  After a successful connect, one has to authenticate oneself. This method can be used to tell which authentication methods are supported by the server at a certain stage of the authentication process (for the given username).

  Note 1: the username will only be used if no authentication step was done so far (it will be used to ask the server for a list of possible authentication methods by sending the initial "none" request). Otherwise, this method ignores the user name and returns a cached method list (which is based on the information contained in the last negative server response).

  Note 2: the server may return method names that are not supported by this implementation.

  After a successful authentication, this method must not be called anymore.

  Parameters:
    `user` - A `String` holding the username.
  Returns:
    a (possibly emtpy) array holding authentication method names.
  Throws:
    `java.io.IOException`

### isAuthenticationComplete

    public boolean isAuthenticationComplete()

  Determines if the authentication phase is complete. Can be called at any time.

  Returns:
    `true` if no further authentication steps are needed.

### isAuthenticationPartialSuccess

    public boolean isAuthenticationPartialSuccess()

  Returns true if there was at least one failed authentication request and the last failed authentication request was marked with "partial success" by the server. This is only needed in the rare case of SSH-2 server setups that cannot be satisfied with a single successful authentication request (i.e., multiple authentication steps are needed.)

  If you are interested in the details, then have a look at RFC4252.

  Returns:
    if the there was a failed authentication step and the last one was marked as a "partial success".

### isAuthMethodAvailable

    public boolean isAuthMethodAvailable(java.lang.String user,
                                         java.lang.String method)
                                  throws java.io.IOException

  Checks if a specified authentication method is available. This method is actually just a wrapper for `getRemainingAuthMethods()`.

  Parameters:
    `user` - A `String` holding the username.
    `method` - An authentication method name (e.g., "publickey", "password", "keyboard-interactive") as specified by the SSH-2 standard.
  Returns:
    if the specified authentication method is currently available.
  Throws:
    `java.io.IOException`

### openSession

    public Session openSession()
                        throws java.io.IOException

  Open a new `Session` on this connection. Works only after one has passed successfully the authentication step. There is no limit on the number of concurrent sessions.

  Returns:
    A `Session` object.
  Throws:
    `java.io.IOException`

### sendIgnorePacket

    public void sendIgnorePacket()
                          throws java.io.IOException

  Send an SSH_MSG_IGNORE packet. This method will generate a random data attribute (length between 0 (invlusive) and 16 (exclusive) bytes, contents are random bytes).

  This method must only be called once the connection is established.

  Throws:
    `java.io.IOException`

### sendIgnorePacket

    public void sendIgnorePacket(byte[] data)
                          throws java.io.IOException

  Send an SSH_MSG_IGNORE packet with the given data attribute.

  This method must only be called once the connection is established.

  Throws:
    `java.io.IOException`

### setClient2ServerCiphers

    public void setClient2ServerCiphers(java.lang.String[] ciphers)

  Unless you know what you are doing, you will never need this.

  Parameters:
    `ciphers` -

### setClient2ServerMACs

    public void setClient2ServerMACs(java.lang.String[] macs)

  Unless you know what you are doing, you will never need this.

  Parameters:
    `macs` -

### setDHGexParameters

    public void setDHGexParameters(DHGexParameters dgp)

  Sets the parameters for the diffie-hellman group exchange. Unless you know what you are doing, you will never need this. Default values are defined in the `DHGexParameters` class.

  Parameters:
    `dgp` - `DHGexParameters`, non null.

### setServer2ClientCiphers

    public void setServer2ClientCiphers(java.lang.String[] ciphers)

  Unless you know what you are doing, you will never need this.

  Parameters:
    `ciphers` -

### setServer2ClientMACs

    public void setServer2ClientMACs(java.lang.String[] macs)

  Unless you know what you are doing, you will never need this.

  Parameters:
    `macs` -

### setServerHostKeyAlgorithms

    public void setServerHostKeyAlgorithms(java.lang.String[] algos)

  Define the set of allowed server host key algorithms to be used for the following key exchange operations.

  Unless you know what you are doing, you will never need this.

  Parameters:
    `algos` - An array of allowed server host key algorithms. SSH-2 defines `ssh-dss` and `ssh-rsa`. The entries of the array must be ordered after preference, i.e., the entry at index 0 is the most preferred one. You must specify at least one entry.

### setTCPNoDelay

    public void setTCPNoDelay(boolean enable)
                       throws java.io.IOException

  Enable/disable TCP_NODELAY (disable/enable Nagle's algorithm) on the underlying socket.

  Can be called at any time. If the connection has not yet been established then the passed value will be stored and set after the socket has been set up. The default value that will be used is `false`.

  Parameters:
    `enable` - the argument passed to the `Socket.setTCPNoDelay()` method.
  Throws:
    `java.io.IOException`

### setProxyData

    public void setProxyData(ProxyData proxyData)

  Used to tell the library that the connection shall be established through a proxy server. It only makes sense to call this method before calling the `connect()` method.

  At the moment, only HTTP proxies are supported.

  Note: This method can be called any number of times. The `connect()` method will use the value set in the last preceding invocation of this method.

  Parameters:
    `proxyData` - Connection information about the proxy. If `null`, then no proxy will be used (non surprisingly, this is also the default).
  See Also:
    `HTTPProxyData`

### requestRemotePortForwarding

    public void requestRemotePortForwarding(java.lang.String bindAddress,
                                            int bindPort,
                                            java.lang.String targetAddress,
                                            int targetPort)
                                     throws java.io.IOException

  Request a remote port forwarding. If successful, then forwarded connections will be redirected to the given target address. You can cancle a requested remote port forwarding by calling `cancelRemotePortForwarding()`.

  A call of this method will block until the peer either agreed or disagreed to your request-

  Note 1: this method typically fails if you

  - pass a port number for which the used remote user has not enough permissions (i.e., port < 1024)
  - or pass a port number that is already in use on the remote server
  - or if remote port forwarding is disabled on the server.

  Note 2: (from the openssh man page): By default, the listening socket on the server will be bound to the loopback interface only. This may be overriden by specifying a bind address. Specifying a remote bind address will only succeed if the server's GatewayPorts option is enabled (see sshd_config(5)).

  Parameters:
    `bindAddress` - address to bind to on the server:
    - "" means that connections are to be accepted on all protocol families supported by the SSH implementation
    - "0.0.0.0" means to listen on all IPv4 addresses
    - "::" means to listen on all IPv6 addresses
    - "localhost" means to listen on all protocol families supported by the SSH implementation on loopback addresses only, [RFC3330] and RFC3513]
    - "127.0.0.1" and "::1" indicate listening on the loopback interfaces for IPv4 and IPv6 respectively
    `bindPort` - port number to bind on the server (must be > 0)
    `targetAddress` - the target address (IP or hostname)
    `targetPort` - the target port
  Throws:
    `java.io.IOException`

### cancelRemotePortForwarding

    public void cancelRemotePortForwarding(int bindPort)
                                    throws java.io.IOException

  Cancel an earlier requested remote port forwarding. Currently active forwardings will not be affected (e.g., disrupted). Note that further connection forwarding requests may be received until this method has returned.

  Parameters:
    `bindPort` - the allocated port number on the server
  Throws:
    `java.io.IOException` - if the remote side refuses the cancel request or another low level error occurs (e.g., the underlying connection is closed)

### setSecureRandom

    public void setSecureRandom(java.security.SecureRandom rnd)

  Provide your own instance of SecureRandom. Can be used, e.g., if you want to seed the used SecureRandom generator manually.

  The SecureRandom instance is used during key exchanges, public key authentication, x11 cookie generation and the like.

  Parameters:
    `rnd` - a SecureRandom instance

### enableDebugging

    public void enableDebugging(boolean enable,
                                DebugLogger logger)

  Enable/disable debug logging. Only do this when requested by Trilead support.

  For speed reasons, some static variables used to check whether debugging is enabled are not protected with locks. In other words, if you dynamicaly enable/disable debug logging, then some threads may still use the old setting. To be on the safe side, enable debugging before doing the `connect()` call.

  Parameters:
    `enable` - on/off
    `logger` - a `DebugLogger` instance, `null` means logging using the simple logger which logs all messages to to stderr. Ignored if enabled is `false`

### ping

    public void ping()
              throws java.io.IOException

  This method can be used to perform end-to-end connection testing. It sends a 'ping' message to the server and waits for the 'pong' from the server.

  When this method throws an exception, then you can assume that the connection should be abandoned.

  Note: Works only after one has passed successfully the authentication step.

  Implementation details: this method sends a SSH_MSG_GLOBAL_REQUEST request ('trilead-ping') to the server and waits for the SSH_MSG_REQUEST_FAILURE reply packet from the server.

  Throws:
    `java.io.IOException` - in case of any problem