com.maverick.ssh

Interface SshClient

All Superinterfaces:

Client

All Known Implementing Classes:

Ssh1Client, Ssh2Client

public interface SshClient
extends Client

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

Modifier and Type	Method and Description
void	addAttribute(String key, Object attribute) Add an attribute to this connection object.
void	addListener(SshClientListener listener) Add a listener to this client.
int	authenticate(SshAuthentication auth) Authenticate the user.
boolean	cancelRemoteForwarding(String bindAddress, int bindPort) Cancel a forwarding request.
void	connect(SshTransport transport, SshContext context, SshClientConnector connector, String username, String localIdentification, 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.
Object	getAttribute(String key) Get a previously added attribute from this object.
<T> T	getAttribute(String key, T defaultValue) Get an attribute or default
int	getChannelCount() Get the number of active channels.
SshContext	getContext() Get the context that created this client.
String	getHost() Public accessor method for getTransport().getHost().
String	getIdent() The SSH identifier for this host.
String	getRemoteIdentification() Returns the identification string supplied by the server during protocol negotiation.
SshTransport	getTransport() Get the transport this client is running over
String	getUsername() Return the username used for this connection
String	getUuid()
int	getVersion() Returns the version for this client.
boolean	hasAttribute(String key) Determine if connection already has an attribute for given key.
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(String hostname, int port, String listeningAddress, int listeningPort, String originatingHost, int originatingPort, SshTransport transport, ChannelEventListener listener) Open a TCPIP forwarding channel to the remote computer.
SshClient	openRemoteClient(String hostname, int port, String username) Open up an SSH client from the remote machine to another remote server.
SshClient	openRemoteClient(String hostname, int port, String username, SshClientConnector 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.
SshSession	openSessionChannel(ChannelEventListener listener, long timeout) Open a session on the remote computer.
SshSession	openSessionChannel(int windowspace, int packetsize, ChannelEventListener listener)
SshSession	openSessionChannel(int windowspace, int packetsize, ChannelEventListener listener, long timeout)
SshSession	openSessionChannel(long timeout) Open a session on the remote computer.
int	requestRemoteForwarding(String bindAddress, int bindPort, String hostToConnect, int portToConnect, ForwardingRequestListener listener) Requests that the remote computer accepts socket connections and forward them to the local computer.

Methods inherited from interface com.maverick.ssh.Client

exit

Method Detail

connect

void connect(SshTransport transport,
             SshContext context,
             SshClientConnector connector,
             String username,
             String localIdentification,
             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

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

openSessionChannel

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

SshSession openSessionChannel(long timeout)
                       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:

timeout - this is an advanced option and should be set to anything other than zero with caution. This is not a socket timeout.

Returns:

an uninitialized session instance.

Throws:

SshException

ChannelOpenException

openSessionChannel

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

openSessionChannel

SshSession openSessionChannel(ChannelEventListener listener,
                              long timeout)
                       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

timeout -

Returns:

an uninitialized session instance.

Throws:

SshException

ChannelOpenException

openSessionChannel

SshSession openSessionChannel(int windowspace,
                              int packetsize,
                              ChannelEventListener listener)
                       throws ChannelOpenException,
                              SshException

Parameters:

windowspace -

packetsize -

listener -

Returns:

Throws:

ChannelOpenException

SshException

openSessionChannel

SshSession openSessionChannel(int windowspace,
                              int packetsize,
                              ChannelEventListener listener,
                              long timeout)
                       throws ChannelOpenException,
                              SshException

Parameters:

windowspace -

packetsize -

listener -

timeout -

Returns:

Throws:

ChannelOpenException

SshException

openForwardingChannel

SshTunnel openForwardingChannel(String hostname,
                                int port,
                                String listeningAddress,
                                int listeningPort,
                                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:

SshTunnel

Throws:

SshException

ChannelOpenException

openRemoteClient

SshClient openRemoteClient(String hostname,
                           int port,
                           String username,
                           SshClientConnector 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

SshClient openRemoteClient(String hostname,
                           int port,
                           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

int requestRemoteForwarding(String bindAddress,
                            int bindPort,
                            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:

int the port number bound on the remote server

Throws:

SshException

cancelRemoteForwarding

boolean cancelRemoteForwarding(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.

Returns:

true if the forwarding was cancelled, otherwise false

Throws:

SshException

disconnect

void disconnect()

Disconnect from the remote computer.

addListener

void addListener(SshClientListener listener)

Add a listener to this client.

Parameters:

listener -

isAuthenticated

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

boolean isConnected()

Evaluate whether the connection is still alive.

Returns:

true if connected, otherwise false

getRemoteIdentification

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

String getUsername()

Return the username used for this connection

Returns:

the users name

duplicate

SshClient duplicate()
             throws SshException

Create an identical version of an SshClient using cached authentication information and the SshTransport duplicate method.

Returns:

SshClient

Throws:

SshException

getContext

SshContext getContext()

Get the context that created this client.

Returns:

SshContext

getChannelCount

int getChannelCount()

Get the number of active channels.

Returns:

int

getVersion

int getVersion()

Returns the version for this client. The value will be either 1 for SSH1 or 2 for SSH2.

Returns:

int

isBuffered

boolean isBuffered()

Identifies whether this client is in buffered mode

Returns:

boolean

getTransport

SshTransport getTransport()

Get the transport this client is running over

Returns:

addAttribute

void addAttribute(String key,
                  Object attribute)

Add an attribute to this connection object.

Parameters:

key -

attribute -

getAttribute

Object getAttribute(String key)

Get a previously added attribute from this object.

Parameters:

key -

Returns:

getAttribute

<T> T getAttribute(String key,
                   T defaultValue)

Get an attribute or default

Parameters:

key -

defaultValue -

Returns:

hasAttribute

boolean hasAttribute(String key)

Determine if connection already has an attribute for given key.

Parameters:

key -

Returns:

getIdent

String getIdent()

The SSH identifier for this host. This is a striped version of remote identification field that returns a consistent identifier to use to detect the remote software type and version e.g OpenSSH_8.1

Returns:

getHost

String getHost()

Public accessor method for getTransport().getHost().

Returns:

getUuid

String getUuid()