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.html,v 1.5 2005/07/04 13:58:40 cplattne Exp $
Author:
Christian Plattner, plattner@inf.ethz.ch

Field Summary
static java.lang.String identification
           
static java.lang.String VERSION
           
 
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)
          After a successful connect, one has to authenticate oneself.
 boolean authenticateWithPassword(java.lang.String user, java.lang.String pass)
          After a successfull connect, one has to authenticate oneself.
 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).
 java.lang.String[] getAvailableCiphers()
          Unless you know what you are doing, you will never need this.
 java.lang.String[] getAvailableMACs()
          Unless you know what you are doing, you will never need this.
 ConnectionInfo getConnectionInfo()
          Returns a ConnectionInfo object containing the details of the connection.
 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.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

VERSION

public static final java.lang.String VERSION
See Also:
Constant Field Values

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 laster want to connect.
port - port on the server, normally 22.
Method Detail

authenticateWithDSA

public boolean authenticateWithDSA(java.lang.String user,
                                   java.lang.String pem,
                                   java.lang.String password)
                            throws java.io.IOException
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). On success, true is returned. If the server does not accept the request, false is returned and one can retry either by using this or any other authentication method. At the moment, only unencrypted and 3DES encrypted DSA private keys are supported. TODO: DES, AES-128, AES-192 and AES-256.

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

authenticateWithPassword

public boolean authenticateWithPassword(java.lang.String user,
                                        java.lang.String pass)
                                 throws java.io.IOException
After a successfull connect, one has to authenticate oneself. This method sends username and password to the server. On success, true is returned. If the server does not accept the username and password, false is returned and one can retry either by using this or any other authentication method.

Parameters:
user -
pass -
Returns:
if 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 receive 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: 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 accepted by the verifier.

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.

getAvailableCiphers

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

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.

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. One can open as many concurrent sessions as one wants.

Returns:
A Session 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.

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

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

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

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 - non null.

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 -

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 -