com.maverick.ssh
Interface SshClient

All Known Implementing Classes:
Ssh1Client, Ssh2Client

public interface SshClient

This interface defines the general contract for an SSH client that is compatible for both the SSH1 and SSH2 protocols. This provides general authentication and the opening of sessions. Further features may be available depending upon the version of the SSH server and installed protocol support.

IMPORTANT NOTE: Caution should be applied when writing applications that are to support both protocol versions; there are slight differences in the way that SSH1 and SSH2 handle user sessions. SSH1 only supports a single session channel on each connection where as SSH2 supports multiple sessions. When calling openSessionChannel on this interface with an SSH2 connection, a new session is opened for each call and the variable returned can be used independently of other sessions. For example you can execute multiple commands on the remote host by simply opening a session channel for each command. If the connection is SSH1 then calling openSessionChannel will result in the same session being returned each time. Since you can only execute one command, or start the users shell once on each session, code written to handle the case of an SSH2 connection will fail.

Author:
Lee David Painter

Method Summary
 int authenticate(SshAuthentication auth)
          Authenticate the user.
 boolean cancelRemoteForwarding(java.lang.String bindAddress, int bindPort)
          Cancel a forwarding request.
 void connect(SshTransport transport, SshContext context, SshConnector connector, java.lang.String username, java.lang.String localIdentification, java.lang.String remoteIdentification, boolean buffered)
          Connect to an SSH server.
 void disconnect()
          Disconnect from the remote computer.
 SshClient duplicate()
          Create an identical version of an SshClient using cached authentication information and the SshTransport duplicate method.
 int getChannelCount()
          Get the number of active channels.
 SshContext getContext()
          Get the context that created this client.
 java.lang.String getRemoteIdentification()
          Returns the identification string supplied by the server during protocol negotiation.
 java.lang.String getUsername()
          Return the username used for this connection
 int getVersion()
          Returns the version for this client.
 boolean isAuthenticated()
          Evaluate whether the user has been authenticated.
 boolean isBuffered()
          Identifies whether this client is in buffered mode
 boolean isConnected()
          Evaluate whether the connection is still alive.
 SshTunnel openForwardingChannel(java.lang.String hostname, int port, java.lang.String listeningAddress, int listeningPort, java.lang.String originatingHost, int originatingPort, SshTransport transport, ChannelEventListener listener)
          Open a TCPIP forwarding channel to the remote computer.
 SshClient openRemoteClient(java.lang.String hostname, int port, java.lang.String username)
          Open up an SSH client from the remote machine to another remote server.
 SshClient openRemoteClient(java.lang.String hostname, int port, java.lang.String username, SshConnector con)
          Open up an SSH client from the remote machine to another remote server.
 SshSession openSessionChannel()
          Open a session on the remote computer.
 SshSession openSessionChannel(ChannelEventListener listener)
          Open a session on the remote computer.
 boolean requestRemoteForwarding(java.lang.String bindAddress, int bindPort, java.lang.String hostToConnect, int portToConnect, ForwardingRequestListener listener)
          Requests that the remote computer accepts socket connections and forward them to the local computer.
 

Method Detail

connect

public void connect(SshTransport transport,
                    SshContext context,
                    SshConnector connector,
                    java.lang.String username,
                    java.lang.String localIdentification,
                    java.lang.String remoteIdentification,
                    boolean buffered)
             throws SshException
Connect to an SSH server.

Parameters:
transport - the transport layer
context - an SSH context
username - the users name
localIdentification - the local identification string
remoteIdentification - the remotes identification string
buffered - should the connection be buffered (threaded)
Throws:
SshException

authenticate

public int authenticate(SshAuthentication auth)
                 throws SshException

Authenticate the user. Once connected call to authenticate the user. When a connection is made no other operations can be performed until the user has been authenticated.

Parameters:
auth - the authentication mechanism.
Returns:
one of the constants defined in SshAuthentication which indicates the state of the current authentication process.
Throws:
SshException
See Also:
PasswordAuthentication

openSessionChannel

public SshSession openSessionChannel()
                              throws SshException,
                                     ChannelOpenException

Open a session on the remote computer. This can only be called once the user has been authenticated. The session returned is uninitialized and will be opened when either a command is executed or the users shell has been started.

Returns:
an uninitialized session instance.
Throws:
SshException
ChannelOpenException

openSessionChannel

public SshSession openSessionChannel(ChannelEventListener listener)
                              throws SshException,
                                     ChannelOpenException

Open a session on the remote computer. This can only be called once the user has been authenticated. The session returned is uninitialized and will be opened when either a command is executed or the users shell has been started.

Parameters:
listener - an event listener to add before opening
Returns:
an uninitialized session instance.
Throws:
SshException
ChannelOpenException

openForwardingChannel

public SshTunnel openForwardingChannel(java.lang.String hostname,
                                       int port,
                                       java.lang.String listeningAddress,
                                       int listeningPort,
                                       java.lang.String originatingHost,
                                       int originatingPort,
                                       SshTransport transport,
                                       ChannelEventListener listener)
                                throws SshException,
                                       ChannelOpenException

Open a TCPIP forwarding channel to the remote computer. If successful the remote computer will open a socket to the host/port specified and return a channel which can be used to forward TCPIP data from the local computer to the remotley connected socket.

It should be noted that this is a low level API method and it does not connect the transport to the channel as this would require some threading. The transport is passed here so that it can be attached to the SshTunnel that is returned. If you want to have the API automatically connect the channel to the transport you should use the ForwardingClient which provides management of forwarding connections and threads.

Parameters:
hostname - the host to connect to
port - the port to connect to
originatingHost - the originating host (informational only)
originatingPort - the originating port (informational only)
transport -
listener - an event listener that will be added to the channel before opening.
Returns:
Throws:
SshException
ChannelOpenException

openRemoteClient

public SshClient openRemoteClient(java.lang.String hostname,
                                  int port,
                                  java.lang.String username,
                                  SshConnector con)
                           throws SshException,
                                  ChannelOpenException
Open up an SSH client from the remote machine to another remote server. This method is useful if your firewall only forwards SSH connections to a single machine. Once connected to the exposed machine you can call this to obtain an SshClient instance to any other machine on the same network.

Parameters:
hostname - the name of the remote host
port - the port of the remote host
username - the name of the user on the remote host
con - an SshConnector instance that will be used to connect the client. This does not have to be the same instance that created this client.
Returns:
SshClient
Throws:
SshException
ChannelOpenException

openRemoteClient

public SshClient openRemoteClient(java.lang.String hostname,
                                  int port,
                                  java.lang.String username)
                           throws SshException,
                                  ChannelOpenException
Open up an SSH client from the remote machine to another remote server. This method is useful if your firewall only forwards SSH connections to a single machine. Once connected to the exposed machine you can call this to obtain an SshClient instance to any other machine on the same network.

Parameters:
hostname - the name of the remote host
port - the port of the remote host
username - the name of the user on the remote host
Returns:
SshClient
Throws:
SshException
ChannelOpenException

requestRemoteForwarding

public boolean requestRemoteForwarding(java.lang.String bindAddress,
                                       int bindPort,
                                       java.lang.String hostToConnect,
                                       int portToConnect,
                                       ForwardingRequestListener listener)
                                throws SshException
Requests that the remote computer accepts socket connections and forward them to the local computer. The ForwardingRequestListener provides callback methods to create the connections and to initialize the tunnel.

Parameters:
bindAddress - the address that the remote computer should listen on
bindPort - the port that the remote computer should listen on
hostToConnect - the host to connect when a connection is established
portToConnect - the port to connect when a connection is established
listener - a callback interface
Returns:
Throws:
SshException

cancelRemoteForwarding

public boolean cancelRemoteForwarding(java.lang.String bindAddress,
                                      int bindPort)
                               throws SshException
Cancel a forwarding request.

Parameters:
bindAddress - the address that the remote computer is listening on.
bindPort - the port that the remote computer is listening on.
Throws:
SshException

disconnect

public void disconnect()
Disconnect from the remote computer.


isAuthenticated

public boolean isAuthenticated()
Evaluate whether the user has been authenticated. If the server does not require the user to authenticate; this may return true immediatley after connection. No other operations can be perform until the user has been authenticated.

Returns:
true if the connection is authenticated, otherwise false

isConnected

public boolean isConnected()
Evaluate whether the connection is still alive.

Returns:
true if connected, otherwise false

getRemoteIdentification

public java.lang.String getRemoteIdentification()
Returns the identification string supplied by the server during protocol negotiation.

Returns:
the servers identification String, for example "SSH-1.99-OpenSSH_3.7p"

getUsername

public java.lang.String getUsername()
Return the username used for this connection

Returns:
the users name

duplicate

public SshClient duplicate()
                    throws SshException
Create an identical version of an SshClient using cached authentication information and the SshTransport duplicate method.

Returns:
Throws:
SshException

getContext

public SshContext getContext()
Get the context that created this client.

Returns:

getChannelCount

public int getChannelCount()
Get the number of active channels.

Returns:

getVersion

public int getVersion()
Returns the version for this client. The value will be either 1 for SSH1 or 2 for SSH2.

Returns:
int

isBuffered

public boolean isBuffered()
Identifies whether this client is in buffered mode

Returns:
boolean


Copyright © 2003 3SP LTD. All Rights Reserved.