Ganymed SSH2 for Java

ch.ethz.ssh2
Class Connection

java.lang.Object
  extended bych.ethz.ssh2.Connection

public class Connection
extends java.lang.Object

A Connection is used to establish an encrypted TCP/IP connection to a SSH2 server.

Typically, one

Version:
$Id: Connection.java,v 1.12 2005/08/24 17:54:10 cplattne Exp $
Author:
Christian Plattner, plattner@inf.ethz.ch

Field Summary
static java.lang.String identification
           
 
Constructor Summary
Connection(java.lang.String hostname)
          Same as Connection(hostname, 22).
Connection(java.lang.String hostname, int port)
          Prepares a fresh Connection object which can then be used to establish a connection to the specified SSH2 server.
 
Method Summary
 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 authenticateWithKeyboardInteractive() with 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 authenticateWithPassword(java.lang.String user, java.lang.String password)
          After a successfull 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 close()
          Close the connection to the SSH2 server.
 ConnectionInfo connect()
          Same as connect(null).
 ConnectionInfo connect(ServerHostKeyVerifier verifier)
          Connect to the SSH2 server and, as soon as the server has presented its host key, use the verifyServerHostKey method of the verifier to ask for permission to proceed.
 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 SSH2 server.
 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[] getRemainingAuthMethods(java.lang.String user)
          After a successful connect, one has to authenticate oneself.
 boolean isAuthenticationComplete()
          Determines if the authentication phase is complete.
 boolean isAuthenticationPartialSuccess()
          Returns true if there was at least on 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 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 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.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

identification

public static final java.lang.String identification
See Also:
Constant Field Values
Constructor Detail

Connection

public Connection(java.lang.String hostname)
Same as Connection(hostname, 22).

Parameters:
hostname - the hostname of the SSH2 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 SSH2 server.

Parameters:
hostname - the host where we later want to connect.
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 authenticateWithKeyboardInteractive() with 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 successfull 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).

Parameters:
user -
password -
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 SSH2 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).

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).

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

close

public void close()
Close the connection to the SSH2 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 will run forever.


connect

public ConnectionInfo connect()
                       throws java.io.IOException
Same as connect(null).

Returns:
see comments for the connect(null) method.
Throws:
java.io.IOException

connect

public ConnectionInfo connect(ServerHostKeyVerifier verifier)
                       throws java.io.IOException
Connect to the SSH2 server and, as soon as the server has presented its host key, use the verifyServerHostKey method of the verifier to ask for permission to proceed. Only correctly signed host keys will be passed to the verifier. If verifier is null, then any correctly signed host key will be accepted - this is NOT recommended, since it makes man-in-the-middle attackes VERY easy.

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

Note 2: as long as the key exchange of the underlying connection has not been completed, this call will block.

Parameters:
verifier - An object that implements the ServerHostKeyVerifier interface.
Returns:
A ConnectionInfo object containg the details of the established connection.
Throws:
java.io.IOException - If any problem occurs, e.g., the server's host key is not correctly signed or not accepted by the verifier.

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 to a local port via the secure tunnel to another host (which may or may not be identical to the remote SSH2 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.

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 forwards an Input- and Outputstream pair via the secure tunnel to another host (which may or may not be identical to the remote SSH2 server).

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 SSH2 server.

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

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 SSH2 server ask for it.

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

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.

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). 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 on 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 SSH2 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 draft-ietf-secsh-userauth-XX.txt.

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

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. SSH2 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.

Ganymed SSH2 for Java