com.sshtools.ssh2

Class Ssh2Client

java.lang.Object

com.sshtools.ssh2.Ssh2Client

All Implemented Interfaces:

Client, SshClient

public class Ssh2Client
extends Object
implements SshClient

Implementation of an SshClient for the SSH2 protocol; this provides the ability to create custom channels and sending/receiving of global requests in addition to the standard SshClient contract.

Author:

Lee David Painter

Constructor Summary

Constructors

Constructor and Description
Ssh2Client() Default constructor called by SshConnector.

Method Summary

Modifier and Type	Method and Description
void	addChannelFactory(ChannelFactory factory) Installs a custom channel factory so that the client may respond to channel open requests.
void	addRequestHandler(GlobalRequestHandler handler) Installs a global request handler so that the client may respond to global requests.
int	authenticate(SshAuthentication auth) Authenticate the user.
boolean	cancelRemoteForwarding(String bindAddress, int bindPort) Cancel a forwarding request.
void	connect(SshTransport io, SshContext context, SshConnector 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.
void	exit()
void	forceKeyExchange() The SSH transport protocol exchanges keys at the beginning of the session; the specification recommends that these keys be re-exchanged after each gigabyte of transmitted data or after each hour of connection time, whichever comes sooner.
String[]	getAuthenticationMethods(String username) Get a list of authentication methods for the user.
int	getChannelCount() Get the number of active channels.
String	getCipherInUseCS() Get the cipher algorithm used to encrypt data sent to the server.
String	getCipherInUseSC() Get the cipher algorithm used to decrypt data received from the server.
String	getCompressionInUseCS() Get the compression algorithm used to compress the clients outgoing data.
String	getCompressionInUseSC() Get the compression algorithm used to decompress the servers data.
SshContext	getContext() Get the context that created this client.
String	getHostKeyInUse() Returns the host key algorithm used in the last key exchange.
SshKeyExchangeClient	getKeyExchangeInstanceInUse()
String	getKeyExchangeInUse() Returns the key exchange algorithm last used.
String	getMacInUseCS() Get the MAC algorithm used to verify data sent by the client.
String	getMacInUseSC() Get the MAC algorithm used to verify data sent by the server.
String	getRemoteIdentification() Returns the identification string supplied by the server during protocol negotiation.
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.
void	openChannel(Ssh2Channel channel, byte[] requestdata) Additional method to open a custom SSH2 channel.
void	openChannel(SshAbstractChannel channel) Additional method to open a custom SSH2 channel.
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, 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.
SshSession	openSessionChannel(ChannelEventListener listener, long timeout)
Ssh2Session	openSessionChannel(int windowspace, int packetsize, ChannelEventListener listener) Additional method to open a session with SSH2 specific features.
Ssh2Session	openSessionChannel(int windowspace, int packetsize, ChannelEventListener listener, long timeout)
SshSession	openSessionChannel(long timeout)
boolean	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.
boolean	sendGlobalRequest(GlobalRequest request, boolean wantreply) Sends a global request to the remote side.
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Ssh2Client

public Ssh2Client()

Default constructor called by SshConnector.

Method Detail

connect

public void connect(SshTransport io,
                    SshContext context,
                    SshConnector connector,
                    String username,
                    String localIdentification,
                    String remoteIdentification,
                    boolean buffered)
             throws SshException

Description copied from interface: SshClient

Connect to an SSH server.

Specified by:

connect in interface SshClient

Parameters:

io - 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

getAuthenticationMethods

public String[] getAuthenticationMethods(String username)
                                  throws SshException

Get a list of authentication methods for the user.

Parameters:

username - the name of the user

Returns:

an array of authentication methods, for example { "password", "publickey" }

Throws:

SshException

authenticate

public int authenticate(SshAuthentication auth)
                 throws SshException

Description copied from interface: SshClient

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.

Specified by:

authenticate in interface SshClient

Parameters:

auth - the authentication mechanism.

Returns:

one of the constants defined in SshAuthentication which indicates the state of the current authentication process.

Throws:

SshException

isAuthenticated

public boolean isAuthenticated()

Description copied from interface: SshClient

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.

Specified by:

isAuthenticated in interface SshClient

Returns:

true if the connection is authenticated, otherwise false

disconnect

public void disconnect()

Description copied from interface: SshClient

Disconnect from the remote computer.

Specified by:

disconnect in interface SshClient

exit

public void exit()

Specified by:

exit in interface Client

isConnected

public boolean isConnected()

Description copied from interface: SshClient

Evaluate whether the connection is still alive.

Specified by:

isConnected in interface SshClient

Returns:

true if connected, otherwise false

forceKeyExchange

public void forceKeyExchange()
                      throws SshException

The SSH transport protocol exchanges keys at the beginning of the session; the specification recommends that these keys be re-exchanged after each gigabyte of transmitted data or after each hour of connection time, whichever comes sooner. This method can be called at anytime to begin the key exchange process.

Throws:

SshException

openSessionChannel

public SshSession openSessionChannel()
                              throws SshException,
                                     ChannelOpenException

Description copied from interface: SshClient

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.

Specified by:

openSessionChannel in interface SshClient

Returns:

an uninitialized session instance.

Throws:

SshException

ChannelOpenException

openSessionChannel

public SshSession openSessionChannel(long timeout)
                              throws SshException,
                                     ChannelOpenException

Throws:

SshException

ChannelOpenException

openSessionChannel

public SshSession openSessionChannel(ChannelEventListener listener,
                                     long timeout)
                              throws SshException,
                                     ChannelOpenException

Throws:

SshException

ChannelOpenException

openSessionChannel

public SshSession openSessionChannel(ChannelEventListener listener)
                              throws SshException,
                                     ChannelOpenException

Description copied from interface: SshClient

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.

Specified by:

openSessionChannel in interface SshClient

Parameters:

listener - an event listener to add before opening

Returns:

an uninitialized session instance.

Throws:

SshException

ChannelOpenException

openSessionChannel

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

Additional method to open a session with SSH2 specific features.

Parameters:

windowspace - the initial amount of window space available

packetsize - the maximum packet size

listener - an event listener to add before opening

Returns:

an open session

Throws:

SshException

ChannelOpenException

openSessionChannel

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

Throws:

ChannelOpenException

SshException

openRemoteClient

public SshClient openRemoteClient(String hostname,
                                  int port,
                                  String username,
                                  SshConnector con)
                           throws SshException,
                                  ChannelOpenException

Description copied from interface: SshClient

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.

Specified by:

openRemoteClient in interface SshClient

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(String hostname,
                                  int port,
                                  String username)
                           throws SshException,
                                  ChannelOpenException

Description copied from interface: SshClient

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.

Specified by:

openRemoteClient in interface SshClient

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

openForwardingChannel

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

Description copied from interface: SshClient

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.

Specified by:

openForwardingChannel in interface SshClient

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)

listener - an event listener that will be added to the channel before opening.

Returns:

SshTunnel

Throws:

SshException

ChannelOpenException

requestRemoteForwarding

public boolean requestRemoteForwarding(String bindAddress,
                                       int bindPort,
                                       String hostToConnect,
                                       int portToConnect,
                                       ForwardingRequestListener listener)
                                throws SshException

Description copied from interface: SshClient

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.

Specified by:

requestRemoteForwarding in interface SshClient

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:

boolean

Throws:

SshException

cancelRemoteForwarding

public boolean cancelRemoteForwarding(String bindAddress,
                                      int bindPort)
                               throws SshException

Description copied from interface: SshClient

Cancel a forwarding request.

Specified by:

cancelRemoteForwarding in interface SshClient

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

openChannel

public void openChannel(Ssh2Channel channel,
                        byte[] requestdata)
                 throws SshException,
                        ChannelOpenException

Additional method to open a custom SSH2 channel.

Parameters:

channel - the channel to open

requestdata - the request data

Throws:

SshException

ChannelOpenException

openChannel

public void openChannel(SshAbstractChannel channel)
                 throws SshException,
                        ChannelOpenException

Additional method to open a custom SSH2 channel.

Parameters:

channel - the channel to open

Throws:

SshException

ChannelOpenException

addChannelFactory

public void addChannelFactory(ChannelFactory factory)
                       throws SshException

Installs a custom channel factory so that the client may respond to channel open requests.

Parameters:

factory - the channel factory

Throws:

SshException

getContext

public SshContext getContext()

Description copied from interface: SshClient

Get the context that created this client.

Specified by:

getContext in interface SshClient

Returns:

SshContext

addRequestHandler

public void addRequestHandler(GlobalRequestHandler handler)
                       throws SshException

Installs a global request handler so that the client may respond to global requests.

Parameters:

handler - the global request handler

Throws:

SshException

sendGlobalRequest

public boolean sendGlobalRequest(GlobalRequest request,
                                 boolean wantreply)
                          throws SshException

Sends a global request to the remote side.

Parameters:

request - the global request

wantreply - specifies whether the remote side should send a success/failure message

Returns:

true if the request succeeded and wantreply=true, otherwise false

Throws:

SshException

getRemoteIdentification

public String getRemoteIdentification()

Description copied from interface: SshClient

Returns the identification string supplied by the server during protocol negotiation.

Specified by:

getRemoteIdentification in interface SshClient

Returns:

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

getUsername

public String getUsername()

Description copied from interface: SshClient

Return the username used for this connection

Specified by:

getUsername in interface SshClient

Returns:

the users name

duplicate

public SshClient duplicate()
                    throws SshException

Description copied from interface: SshClient

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

Specified by:

duplicate in interface SshClient

Returns:

SshClient

Throws:

SshException

getChannelCount

public int getChannelCount()

Description copied from interface: SshClient

Get the number of active channels.

Specified by:

getChannelCount in interface SshClient

Returns:

int

getVersion

public int getVersion()

Description copied from interface: SshClient

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

Specified by:

getVersion in interface SshClient

Returns:

int

isBuffered

public boolean isBuffered()

Description copied from interface: SshClient

Identifies whether this client is in buffered mode

Specified by:

isBuffered in interface SshClient

Returns:

boolean

getKeyExchangeInUse

public String getKeyExchangeInUse()

Returns the key exchange algorithm last used.

Returns:

String

getKeyExchangeInstanceInUse

public SshKeyExchangeClient getKeyExchangeInstanceInUse()

getHostKeyInUse

public String getHostKeyInUse()

Returns the host key algorithm used in the last key exchange.

Returns:

String

getCipherInUseCS

public String getCipherInUseCS()

Get the cipher algorithm used to encrypt data sent to the server.

Returns:

String

getCipherInUseSC

public String getCipherInUseSC()

Get the cipher algorithm used to decrypt data received from the server.

Returns:

String

getMacInUseCS

public String getMacInUseCS()

Get the MAC algorithm used to verify data sent by the client.

Returns:

String

getMacInUseSC

public String getMacInUseSC()

Get the MAC algorithm used to verify data sent by the server.

Returns:

String

getCompressionInUseCS

public String getCompressionInUseCS()

Get the compression algorithm used to compress the clients outgoing data.

Returns:

String

getCompressionInUseSC

public String getCompressionInUseSC()

Get the compression algorithm used to decompress the servers data.

Returns:

String

toString

public String toString()

Overrides:

toString in class Object