com.mindbright.ssh2
Class SSH2Connection

java.lang.Object
  extended bycom.mindbright.ssh2.SSH2Connection
All Implemented Interfaces:
java.lang.Runnable

public final class SSH2Connection
extends java.lang.Object
implements java.lang.Runnable

This class implements the connection layer of the secure shell version 2 (ssh2) protocol stack. This layer contains the multiplexing of the secure connection to the server into several different channels which can be used for port forwarding and terminal sessions as defined in the connection protocol spec.

To create a SSH2Connection instance a connected SSH2Transport along with an authenticated SSH2UserAuth must be created first to be passed to the constructor. Optionally a SSH2ConnectionEventHandler can be supplied to be able to monitor and control the connection layer. A log handler can also be set, though by default the connection layer uses the same log handler as the transport layer. All preferences are taken from the SSH2Preferences set in the transport layer.

The connection layer must be hooked into the transport layer explicitly by calling the method setConnection on the SSH2Transport. Once the connection layer is hooked up to the transport layer channels can be created. There are basically four types of channels: session, local forward, remote forward, and X11 forward. There are methods for creating local and remote forwards aswell as session channels, however, X11 channels must be created through session channels.

See Also:
SSH2Transport, SSH2UserAuth, SSH2ConnectionEventHandler, SSH2Preferences, SSH2Channel, SSH2Connector, SSH2Listener

Field Summary
static java.lang.String CH_REQ_AUTH_AGENT
           
static java.lang.String CH_REQ_AUTH_AGENT1
           
static java.lang.String CH_REQ_BREAK
           
static java.lang.String CH_REQ_ENV
           
static java.lang.String CH_REQ_EXEC
           
static java.lang.String CH_REQ_EXIT_SIG
           
static java.lang.String CH_REQ_EXIT_STAT
           
static java.lang.String CH_REQ_OPENSSH_KEEPALIVE
           
static java.lang.String CH_REQ_PTY
           
static java.lang.String CH_REQ_SHELL
           
static java.lang.String CH_REQ_SIGNAL
           
static java.lang.String CH_REQ_SUBSYSTEM
           
static java.lang.String CH_REQ_WINCH
           
static java.lang.String CH_REQ_X11
           
static java.lang.String CH_REQ_XONOFF
           
static int CH_TYPE_AUTH_AGENT
           
static int CH_TYPE_DIR_TCPIP
           
static int CH_TYPE_FWD_TCPIP
           
static int CH_TYPE_SESSION
           
static int CH_TYPE_X11
           
static java.lang.String CHAN_AUTH_AGENT
           
static java.lang.String CHAN_DIRECT_TCPIP
           
static java.lang.String CHAN_FORWARDED_TCPIP
           
static java.lang.String CHAN_SESSION
           
static java.lang.String CHAN_X11
           
static java.lang.String GL_REQ_CANCEL_FORWARD
           
static java.lang.String GL_REQ_START_FORWARD
           
static int MAX_ACTIVE_CHANNELS
           
 
Constructor Summary
SSH2Connection(SSH2UserAuth userAuth, SSH2Transport transport)
          Basic constructor used when there is no need for event handler.
SSH2Connection(SSH2UserAuth userAuth, SSH2Transport transport, SSH2ConnectionEventHandler eventHandler)
          Constructor used when there need for event handler.
 
Method Summary
 void connectLocalChannel(SSH2Channel channel, java.lang.String remoteAddr, int remotePort, java.lang.String originAddr, int originPort)
           
 void deleteLocalForward(java.lang.String localAddr, int localPort)
          Deletes the local forward identified by the given local address and port pair.
 void deleteRemoteForward(java.lang.String remoteAddr, int remotePort)
          Deletes the remote forward identified by the given remote address and port pair.
 void fatalDisconnect(int reason, java.lang.String description)
          Disconnects from peer using the DISCONNECT packet type with the given reason and description.
 SSH2Connector getConnector()
          Gets the singleton instance of the SSH2Connector which is used by the connection layer to connect remote forwards through to local hosts when they are opened.
 SSH2ConnectionEventHandler getEventHandler()
          Gets the event handler currently in use.
 SSH2StreamFilterFactory getForwardFilterFactory(java.lang.String remoteAddr, int remotePort)
          Gets the filter factory instance for a remote forward identified by the given remote address and port pair.
 java.lang.String[] getForwardTarget(java.lang.String remoteAddr, int remotePort)
          Gets the local target host address and port pair of a remote forward identified by the given remote address and port pair.
 SSH2Listener getLocalListener(java.lang.String localAddr, int localPort)
          Gets the SSH2Listener instance of a local forward if it is set up.
 Log getLog()
          Gets the log handler currently in use.
 SSH2Preferences getPreferences()
          Gets the preferences set in the transport layer.
 SecureRandom getSecureRandom()
          Gets the SecureRandom currently in use (i.e.
 SSH2Transport getTransport()
          Gets our transport layer.
 SSH2Listener newLocalForward(java.lang.String localAddr, int localPort, java.lang.String remoteAddr, int remotePort)
          Creates a new local forward from the given local address and port to the remote address and port on the server side.
 SSH2Listener newLocalForward(java.lang.String localAddr, int localPort, java.lang.String remoteAddr, int remotePort, SSH2StreamFilterFactory filterFactory)
          Creates a new local forward from the given local address and port to the remote address and port on the server side using the given filter factory to insert filters in the input/output streams of the forwarded channels.
 SSH2InternalChannel newLocalInternalForward(java.lang.String remoteAddr, int remotePort)
          Creates a new internal forward to the remote address and port on the server side.
 SSH2InternalChannel newLocalInternalForward(java.lang.String remoteAddr, int remotePort, SSH2StreamFilterFactory filterFactory)
          Creates a new internal forward to remote address and port on the server side using the given filter factory to insert filters in the input/output streams of the forwarded channels.
 void newRemoteForward(java.lang.String remoteAddr, int remotePort, java.lang.String localAddr, int localPort)
          Creates a new remote forward from the given remote address and port on the server to the local address and port.
 void newRemoteForward(java.lang.String remoteAddr, int remotePort, java.lang.String localAddr, int localPort, SSH2StreamFilterFactory filterFactory)
          Creates a new remote forward from the given remote address and port on the server to the local address and port using the given filter factory to insert filters in the input/output streams of the forwarded channels.
 boolean newRemoteForwardBlocking(java.lang.String remoteAddr, int remotePort, java.lang.String localAddr, int localPort, SSH2StreamFilterFactory filterFactory)
          Creates a new remote forward from the given remote address and port on the server to the local address and port using the given filter factory to insert filters in the input/output streams of the forwarded channel.
 SSH2SessionChannel newSession()
          Creates a new session channel.
 SSH2SessionChannel newSession(SSH2StreamFilterFactory filterFactory)
          Creates a new session channel using the given filter for filtering the standard input/output streams of the session.
 SSH2SessionChannel newTerminal(SSH2TerminalAdapter termAdapter)
          Creates a new session channel attaching its standard input/output streams to the given terminal adapter.
 void run()
          The run routine which implements the channel reaper.
 void setEventHandler(SSH2ConnectionEventHandler eventHandler)
          Sets the event handler to use.
 void setLog(Log log)
          Sets the log handler to use.
 void setSocketOptions(java.lang.String desc, java.net.Socket sock)
           
protected  void startChannelReaper()
          Start a new thread which repeatedly tries to kill channels which should be killed.
protected  void stopChannelReaper()
          Stop the channel reaper.
 void transmit(SSH2TransportPDU pdu)
          Transmits the given PDU (by sending it to the transport layer, no processing is needed at this point).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

MAX_ACTIVE_CHANNELS

public static final int MAX_ACTIVE_CHANNELS
See Also:
Constant Field Values

GL_REQ_START_FORWARD

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

GL_REQ_CANCEL_FORWARD

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

CH_REQ_PTY

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

CH_REQ_X11

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

CH_REQ_ENV

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

CH_REQ_SHELL

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

CH_REQ_EXEC

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

CH_REQ_SUBSYSTEM

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

CH_REQ_WINCH

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

CH_REQ_XONOFF

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

CH_REQ_SIGNAL

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

CH_REQ_EXIT_STAT

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

CH_REQ_EXIT_SIG

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

CH_REQ_AUTH_AGENT

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

CH_REQ_AUTH_AGENT1

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

CH_REQ_BREAK

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

CH_REQ_OPENSSH_KEEPALIVE

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

CHAN_FORWARDED_TCPIP

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

CHAN_DIRECT_TCPIP

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

CHAN_SESSION

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

CHAN_X11

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

CHAN_AUTH_AGENT

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

CH_TYPE_FWD_TCPIP

public static final int CH_TYPE_FWD_TCPIP
See Also:
Constant Field Values

CH_TYPE_DIR_TCPIP

public static final int CH_TYPE_DIR_TCPIP
See Also:
Constant Field Values

CH_TYPE_SESSION

public static final int CH_TYPE_SESSION
See Also:
Constant Field Values

CH_TYPE_X11

public static final int CH_TYPE_X11
See Also:
Constant Field Values

CH_TYPE_AUTH_AGENT

public static final int CH_TYPE_AUTH_AGENT
See Also:
Constant Field Values
Constructor Detail

SSH2Connection

public SSH2Connection(SSH2UserAuth userAuth,
                      SSH2Transport transport)
Basic constructor used when there is no need for event handler.

Parameters:
userAuth - the authentication layer
transport - the transport layer

SSH2Connection

public SSH2Connection(SSH2UserAuth userAuth,
                      SSH2Transport transport,
                      SSH2ConnectionEventHandler eventHandler)
Constructor used when there need for event handler.

Parameters:
userAuth - the authentication layer
transport - the transport layer
eventHandler - the event handler (may be null)
See Also:
SSH2ConnectionEventHandler
Method Detail

getTransport

public SSH2Transport getTransport()
Gets our transport layer.

Returns:
the transport layer

setEventHandler

public void setEventHandler(SSH2ConnectionEventHandler eventHandler)
Sets the event handler to use.

Parameters:
eventHandler - the event handler to use

getEventHandler

public SSH2ConnectionEventHandler getEventHandler()
Gets the event handler currently in use.

Returns:
the event handler currently in use

getPreferences

public SSH2Preferences getPreferences()
Gets the preferences set in the transport layer.

Returns:
the preferences

getLog

public Log getLog()
Gets the log handler currently in use.

Returns:
the log handler currently in use

setLog

public void setLog(Log log)
Sets the log handler to use.


getSecureRandom

public SecureRandom getSecureRandom()
Gets the SecureRandom currently in use (i.e. from the transport layer).

Returns:
the SecureRandom in use

transmit

public void transmit(SSH2TransportPDU pdu)
Transmits the given PDU (by sending it to the transport layer, no processing is needed at this point).

Parameters:
pdu - packet to send

fatalDisconnect

public void fatalDisconnect(int reason,
                            java.lang.String description)
Disconnects from peer using the DISCONNECT packet type with the given reason and description. See the class SSH2 for reason codes. This is only a convenience method which calls the same method on the transport layer.

Parameters:
reason - the reason code
description - the textual description for the cause of disconnect
See Also:
SSH2

getConnector

public SSH2Connector getConnector()
Gets the singleton instance of the SSH2Connector which is used by the connection layer to connect remote forwards through to local hosts when they are opened.

Returns:
the singleton connector

getForwardTarget

public java.lang.String[] getForwardTarget(java.lang.String remoteAddr,
                                           int remotePort)
Gets the local target host address and port pair of a remote forward identified by the given remote address and port pair. This function is used to locate the local target of a remote forward when it is opened.

Parameters:
remoteAddr - the remote address of the forward
remotePort - the remote port of the forward
Returns:
the address and port, the address beeing at index 0 and the port beeing at inde 1.

getForwardFilterFactory

public SSH2StreamFilterFactory getForwardFilterFactory(java.lang.String remoteAddr,
                                                       int remotePort)
Gets the filter factory instance for a remote forward identified by the given remote address and port pair.

Parameters:
remoteAddr - the remote address of the forward
remotePort - the remote port of the forward
Returns:
the stream filter factory instance

getLocalListener

public SSH2Listener getLocalListener(java.lang.String localAddr,
                                     int localPort)
Gets the SSH2Listener instance of a local forward if it is set up.

Parameters:
localAddr - the local address of the forward
Returns:
the listener instance for the given forward or null if none is set

newRemoteForward

public void newRemoteForward(java.lang.String remoteAddr,
                             int remotePort,
                             java.lang.String localAddr,
                             int localPort)
Creates a new remote forward from the given remote address and port on the server to the local address and port.

Parameters:
remoteAddr - the remote address where the server listens
remotePort - the remote port where the server listens
localAddr - the local address to connect through to

newRemoteForward

public void newRemoteForward(java.lang.String remoteAddr,
                             int remotePort,
                             java.lang.String localAddr,
                             int localPort,
                             SSH2StreamFilterFactory filterFactory)
Creates a new remote forward from the given remote address and port on the server to the local address and port using the given filter factory to insert filters in the input/output streams of the forwarded channels.

Parameters:
remoteAddr - the remote address where the server listens
remotePort - the remote port where the server listens
localAddr - the local address to connect through to
filterFactory - the filter factory instance to use for producing filters.

newRemoteForwardBlocking

public boolean newRemoteForwardBlocking(java.lang.String remoteAddr,
                                        int remotePort,
                                        java.lang.String localAddr,
                                        int localPort,
                                        SSH2StreamFilterFactory filterFactory)
Creates a new remote forward from the given remote address and port on the server to the local address and port using the given filter factory to insert filters in the input/output streams of the forwarded channel. This is a blocking version of the method newRemoteForward with the same parameters which waits until a result is reported from the server which indicates whether the forward could be set up or not.

Parameters:
remoteAddr - the remote address where the server listens
remotePort - the remote port where the server listens
localAddr - the local address to connect through to
filterFactory - the filter factory instance to use for producing filters.

deleteRemoteForward

public void deleteRemoteForward(java.lang.String remoteAddr,
                                int remotePort)
Deletes the remote forward identified by the given remote address and port pair. Note that the channels that was previously opened through this forward are not deleted, only a CANCEL_FORWARD request is sent to the server which deletes the forward on the server preventing further channels to be opened through this forward.

Parameters:
remoteAddr - the remote address of the forward
remotePort - the remote port of the forward

newLocalForward

public SSH2Listener newLocalForward(java.lang.String localAddr,
                                    int localPort,
                                    java.lang.String remoteAddr,
                                    int remotePort)
                             throws java.io.IOException
Creates a new local forward from the given local address and port to the remote address and port on the server side.

Parameters:
localAddr - the local address to listen to
remoteAddr - the remote address where the connects to
remotePort - the remote port where the connects to
Returns:
a listener instance accepting connections to forward
Throws:
java.io.IOException

newLocalForward

public SSH2Listener newLocalForward(java.lang.String localAddr,
                                    int localPort,
                                    java.lang.String remoteAddr,
                                    int remotePort,
                                    SSH2StreamFilterFactory filterFactory)
                             throws java.io.IOException
Creates a new local forward from the given local address and port to the remote address and port on the server side using the given filter factory to insert filters in the input/output streams of the forwarded channels.

Parameters:
localAddr - the local address to listen to
remoteAddr - the remote address where the connects to
remotePort - the remote port where the connects to
filterFactory - the filter factory instance to use for producing filters.
Returns:
a listener instance accepting connections to forward
Throws:
java.io.IOException

newLocalInternalForward

public SSH2InternalChannel newLocalInternalForward(java.lang.String remoteAddr,
                                                   int remotePort)
Creates a new internal forward to the remote address and port on the server side.

Parameters:
remoteAddr - the remote address where the connects to
remotePort - the remote port where the connects to
Returns:
an internal channel

newLocalInternalForward

public SSH2InternalChannel newLocalInternalForward(java.lang.String remoteAddr,
                                                   int remotePort,
                                                   SSH2StreamFilterFactory filterFactory)
Creates a new internal forward to remote address and port on the server side using the given filter factory to insert filters in the input/output streams of the forwarded channels.

Parameters:
remoteAddr - the remote address where the connects to
remotePort - the remote port where the connects to
filterFactory - the filter factory instance to use for producing filters.
Returns:
an internal channel

deleteLocalForward

public void deleteLocalForward(java.lang.String localAddr,
                               int localPort)
Deletes the local forward identified by the given local address and port pair. Note that the channels that was previously opened through this forward are not deleted, only the corresponding listener is stopped preventing further channels to be opened through this forward.

Parameters:
localAddr - the local address of the forward

newSession

public SSH2SessionChannel newSession()
Creates a new session channel.

Returns:
the new session channel

newSession

public SSH2SessionChannel newSession(SSH2StreamFilterFactory filterFactory)
Creates a new session channel using the given filter for filtering the standard input/output streams of the session.

Returns:
the new session channel

newTerminal

public SSH2SessionChannel newTerminal(SSH2TerminalAdapter termAdapter)
Creates a new session channel attaching its standard input/output streams to the given terminal adapter. It is up to the terminal adapter implementation to attach itself to the I/O streams of the session channel. For this purpose the interface method attach is called before the channel open message is sent to the server so the terminal adapter is attached before I/O is started.

Parameters:
termAdapter - the terminal adapter to attach to the session
Returns:
the new session channel

setSocketOptions

public void setSocketOptions(java.lang.String desc,
                             java.net.Socket sock)
                      throws java.io.IOException
Throws:
java.io.IOException

connectLocalChannel

public void connectLocalChannel(SSH2Channel channel,
                                java.lang.String remoteAddr,
                                int remotePort,
                                java.lang.String originAddr,
                                int originPort)

startChannelReaper

protected void startChannelReaper()
Start a new thread which repeatedly tries to kill channels which should be killed.


stopChannelReaper

protected void stopChannelReaper()
Stop the channel reaper.


run

public void run()
The run routine which implements the channel reaper.

Specified by:
run in interface java.lang.Runnable