com.maverick.ssh
Class SshConnector

java.lang.Object
  extended bycom.maverick.ssh.SshConnector

public final class SshConnector
extends java.lang.Object

Connecting to an SSH server STARTS HERE!. This utility class establishes a connection with an SSH server, determines which SSH protocol versions are supported and creates an initialized connection ready for authentication. Both SSH1 and SSH2 protocol support is included, however it is possible to restrict either version by removing the maverick-ssh1.jar or maverick-ssh2.jar from your classpath or by using the setSupportedVersions(int versions) method.

Each call to getInstance() returns a new instance of the connector with a pair of configuration contexts, one for SSH1 and another for SSH2. These contexts are represented by the interface SshContext and have a default set of configuration methods; further protocol specific configuration methods can be obtained by casting the values returned by getContext(int version) into either the Ssh1Context or Ssh2Context implementations.

To connect to an SSH server you need to provide an SshTransport which provides the transport layer communication. In most cases this will be a Socket however since this API is designed for many different platforms, a Socket may not always be available so this simple interface is used to allow you to specify the source IO streams. The SshTransport documentation provides a simple example for a Socket called SocketTransport which is used in the following examples.

To create a connection and authentication using password authentication with default configuration contexts use:

 SshConnector con = SshConnector.getInstance();
 SshClient ssh = con.connect(
			new SocketTransport("beagle2.3sp.net", 22),
			"martianx");

	PasswordAuthentication pwd = new PasswordAuthentication();
	pwd.setPassword("likeidgivethataway!");

	if(ssh.authenticate(pwd)==SshAuthentication.COMPLETE) {
		System.out.println("Authentication succeeded");
         SshSession sesison = ssh.openSessionChannel();
	} else {
		System.out.println("Authentication failed");
	}

To configure host key verification for a connector use the following code:

 SshConnector con = SshConnector.getInstance();

 HostKeyVerification hkv = new HostKeyVerification() {
   public boolean verifyHost(String name, SshPublicKey key)
              throws IOException {
      // Verify the host somehow???
      return true;
   }
 };
 SshContext context = con.getContext(SshConnector.SSH1);
 context.setHostKeyVerification(hkv);

 context = con.getContext(SshConnector.SSH2);
 context.setHostKeyVerification(hkv);

 SshClient ssh = con.connect(
			new SocketTransport("beagle2.3sp.net", 22),
			"martianx");

  .......
 
You can then create as many connections are required using the same configuration contexts.

To configure protocol specific features, for example the showing of authentication banners from SSH2 servers use:

 SshConnector con = SshConnector.getInstance();

 Ssh2Context context = (Ssh2Context) con.getContext(SshConnector.SSH2);
 context.setBannerDisplay(new BannerDisplay() {
   public void displayBanner(String message) {
     // Popup a dialog with the message??
   }
 });

 SshClient ssh = con.connect(
			new SocketTransport("beagle2.3sp.net", 22),
			"martianx");

 ......
 

Author:
Lee David Painter

Field Summary
static int SSH1
          Constant for the SSH protocol version 1
static int SSH2
          Constant for the SSH protocol version 2
 
Method Summary
 SshClient connect(SshTransport transport, java.lang.String username)
          Create a new connection to an SSH server over the specified transport.
 SshClient connect(SshTransport transport, java.lang.String username, boolean buffered)
          See connect(SshTransport, String) for full details.
 SshClient connect(SshTransport transport, java.lang.String username, boolean buffered, SshContext context)
          See connect(SshTransport, String) for full details.
 SshClient connect(SshTransport transport, java.lang.String username, SshContext context)
          See connect(SshTransport, String) for full details.
 int determineVersion(SshTransport transport)
          Determine the version of the server connected to the SshTransport.
 SshContext getContext(int version)
          Get the configuration context for a specific SSH version.
static SshConnector getInstance()
          Returns an instance of the SshConnector.
static java.util.Date getReleaseDate()
          Returns the release date of the current version.
 int getSupportedVersions()
          Returns the supported protocol flags.
static java.lang.String getVersion()
          Returns the current version of the API.
 boolean isLicensed()
          Indicates whether the API is licensed or not
 void setKnownHosts(HostKeyVerification hkv)
          Set the HostKeyVerification instance for both protocols.
 void setSoftwareVersionComments(java.lang.String softwareComments)
          Set the software/version/comments field of the SSH identification string
 void setSupportedVersions(int supported)
          Sets the protocol versions supported by this connector.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SSH1

public static final int SSH1
Constant for the SSH protocol version 1

See Also:
Constant Field Values

SSH2

public static final int SSH2
Constant for the SSH protocol version 2

See Also:
Constant Field Values
Method Detail

getInstance

public static SshConnector getInstance()
                                throws SshException
Returns an instance of the SshConnector. Each instance is initialized with a pair of default contexts.

Returns:
a new instance
Throws:
SshException

isLicensed

public final boolean isLicensed()
Indicates whether the API is licensed or not

Returns:
boolean

getContext

public SshContext getContext(int version)
                      throws SshException

Get the configuration context for a specific SSH version.

 SshConnector con = SshConnector.getInstance();
 SshContext context = con.getContext(SshConnector.SSH1);
 
or
 SshContext context = con.getContext(SshConnector.SSH2);
 
You can cast the returned value into the context implementation to get access to protocol specific configuration.
 Ssh2Context context = (Ssh2Context)con.getContext(SshConnector.SSH2);
 

Parameters:
version - either SshConnector.SSH1 or SshConnector.SSH2
Returns:
the version context
Throws:
SshException

setSupportedVersions

public void setSupportedVersions(int supported)
                          throws SshException

Sets the protocol versions supported by this connector. When the connector is created, the supported flags are set to whichever protocol support is installed. You can restrict support by setting the support to an individual version using this method. For example you could restrict access to SSH2 by using the following code:

 SshConnector con = SshConnector.getInstance();
 con.setSupportedVersions(SshConnector.SSH2);
 
or switch back to full support:
 con.setSupportedVersions(SshConnector.SSH1 | SshConnector.SSH2);
 

Parameters:
supported -
Throws:
SshException

getSupportedVersions

public int getSupportedVersions()
Returns the supported protocol flags.

Returns:
a bit mask of the supported protocol versions for example SshConnector.SSH1 & SshConnector.SSH2

setKnownHosts

public void setKnownHosts(HostKeyVerification hkv)
Set the HostKeyVerification instance for both protocols. You can use this method to configure both protocols at once instead of using seperate calls on each of the SshContext's.

Parameters:
hkv -

connect

public SshClient connect(SshTransport transport,
                         java.lang.String username)
                  throws SshException

Create a new connection to an SSH server over the specified transport. This method reads the remote servers identification and determines which protocol support is required. An SshClient instance is then created, initialized and returned. If both protocol versions are supported by the remote server the connector will always operate using SSH2.

The SshTransport interface is used here to allow different types of transport mechanisms. Typically this would be a Socket however since this API is targeted at all Java platforms a Socket cannot be used directly. See the SshTransport documentation for an example Socket implementation.

To take advantage of protocol specific features you can test the instance returned which will either be an Ssh1Client or Ssh2Client.

Parameters:
transport - the transport for the connection.
username - the name of the user connecting
Returns:
a connected SshClient instance ready for authentication.
Throws:
SshException
See Also:
Ssh1Client, Ssh2Client

connect

public SshClient connect(SshTransport transport,
                         java.lang.String username,
                         boolean buffered)
                  throws SshException
See connect(SshTransport, String) for full details. This method optionally allows you to specify the buffered state of the connection. When the connection is buffered a background thread is started to act as a message pump; this has the benefit of routing data as soon as it arrives and helps in circumstances where you require a channel to fill up with data without calling its InputStream's read method. This also will enable the InputStreams available method to work as expected.

Parameters:
transport - SshTransport
username - String
buffered - boolean
Returns:
SshClient
Throws:
SshException

connect

public SshClient connect(SshTransport transport,
                         java.lang.String username,
                         SshContext context)
                  throws SshException
See connect(SshTransport, String) for full details. This method optionally allows you to specify a context to use. Normally you would reused an SshConnector instead of calling this method directly.

Parameters:
transport - SshTransport
username - String
context - SshContext
Returns:
SshClient
Throws:
SshException

setSoftwareVersionComments

public void setSoftwareVersionComments(java.lang.String softwareComments)
Set the software/version/comments field of the SSH identification string

Parameters:
softwareComments - String

connect

public SshClient connect(SshTransport transport,
                         java.lang.String username,
                         boolean buffered,
                         SshContext context)
                  throws SshException
See connect(SshTransport, String) for full details.

This method optionally allows you to specify the buffered state of the connection. When the connection is buffered a background thread is started to act as a message pump; this has the benefit of routing data as soon as it arrives and helps in circumstances where you require a channel to fill up with data without calling its InputStream's read method. This also will enable the InputStreams available method to work as expected.

This method also allows you to specify a context to use. Normally you would reused an SshConnector instead of calling this method directly.

Parameters:
transport - SshTransport
username - String
buffered - boolean
context - SshContext
Returns:
SshClient
Throws:
SshException

getVersion

public static java.lang.String getVersion()
Returns the current version of the API.


getReleaseDate

public static java.util.Date getReleaseDate()
Returns the release date of the current version.


determineVersion

public int determineVersion(SshTransport transport)
                     throws SshException
Determine the version of the server connected to the SshTransport. This method will close the transport before completing. Only use for informational purposes.

Parameters:
transport -
Returns:
a bit mask of the supported versions.
Throws:
SshException


Copyright © 2003 3SP LTD. All Rights Reserved.