net.schmizz.sshj
Class SSHClient

java.lang.Object
  extended by net.schmizz.sshj.SocketClient
      extended by net.schmizz.sshj.SSHClient
All Implemented Interfaces:
Closeable, SessionFactory

public class SSHClient
extends SocketClient
implements Closeable, SessionFactory

Secure SHell client API.

Before connection is established, host key verification needs to be accounted for. This is done by specifying one or more HostKeyVerifier objects. Database of known hostname-key pairs in the OpenSSH "known_hosts" format can be loaded for host key verification.

User authentication can be performed by any of the auth*() method.

startSession() caters to the most typical use case of starting a session channel and executing a remote command, starting a subsystem, etc. If you wish to request X11 forwarding for some session, first register a ConnectListener for x11 channels.

Local and remote port forwarding is possible. There are also utility method for easily creating SCP and SFTP implementations.

A simple example:

 final SSHClient client = new SSHClient();
 client.loadKnownHosts();
 client.connect("hostname");
 try {
     client.authPassword("username", "password");
     final Session session = client.startSession();
     try {
          final Command cmd = session.exec("true");
          cmd.join(1, TimeUnit.SECONDS);
     } finally {
          session.close();
     }
 } finally {
      client.disconnect();
 }
 

Where a password or passphrase is required, if you're extra-paranoid use the char[] based method. The char[] will be blanked out after use.


Field Summary
protected  UserAuth auth
          ssh-userauth service
protected  Connection conn
          ssh-connection service
static int DEFAULT_PORT
          Default port for SSH
protected  org.slf4j.Logger log
          Logger
protected  Transport trans
          Transport layer
 
Constructor Summary
SSHClient()
          Default constructor.
SSHClient(Config config)
          Constructor that allows specifying a config to be used.
 
Method Summary
 void addHostKeyVerifier(HostKeyVerifier hostKeyVerifier)
          Add a HostKeyVerifier which will be invoked for verifying host key during connection establishment and future key exchanges.
 void addHostKeyVerifier(String fingerprint)
          Add a HostKeyVerifier that will verify any host that's able to claim a host key with the given fingerprint, e.g.
 void auth(String username, AuthMethod... methods)
          Authenticate username using the supplied methods.
 void auth(String username, Iterable<AuthMethod> methods)
          Authenticate username using the supplied methods.
 void authPassword(String username, char[] password)
          Authenticate username using the "password" authentication method and as a fallback basic challenge-response authentication..
 void authPassword(String username, PasswordFinder pfinder)
          Authenticate username using the "password" authentication method and as a fallback basic challenge-response authentication.
 void authPassword(String username, String password)
          Authenticate username using the "password" authentication method and as a fallback basic challenge-response authentication.
 void authPublickey(String username)
          Authenticate username using the "publickey" authentication method, with keys from some common locations on the file system.
 void authPublickey(String username, Iterable<KeyProvider> keyProviders)
          Authenticate username using the "publickey" authentication method.
 void authPublickey(String username, KeyProvider... keyProviders)
          Authenticate username using the "publickey" authentication method.
 void authPublickey(String username, String... locations)
          Authenticate username using the "publickey" authentication method, with keys from one or more locations in the file system.
 void close()
          Same as disconnect().
 void disconnect()
          Disconnects from the connected SSH server.
protected  void doKex()
          Do key exchange.
 Connection getConnection()
           
 RemotePortForwarder getRemotePortForwarder()
           
 Transport getTransport()
           
 UserAuth getUserAuth()
           
 boolean isAuthenticated()
           
 boolean isConnected()
           
 KeyProvider loadKeys(KeyPair kp)
          Creates a KeyProvider from supplied KeyPair.
 KeyProvider loadKeys(String location)
          Returns a KeyProvider instance created from a location on the file system where an unencrypted private key file (does not require a passphrase) can be found.
 KeyProvider loadKeys(String location, char[] passphrase)
          Utility function for createing a KeyProvider instance from given location on the file system.
 KeyProvider loadKeys(String location, PasswordFinder passwordFinder)
          Creates a KeyProvider instance from given location on the file system.
 KeyProvider loadKeys(String location, String passphrase)
          Convenience method for creating a KeyProvider instance from a location where an encrypted key file is located.
 KeyProvider loadKeys(String privateKey, String publicKey, PasswordFinder passwordFinder)
          Creates a KeyProvider instance from passed strings.
 void loadKnownHosts()
          Attempts loading the user's known_hosts file from the default locations, i.e.
 void loadKnownHosts(File location)
          Adds a OpenSSHKnownHosts object created from the specified location as a host key verifier.
 LocalPortForwarder newLocalPortForwarder(LocalPortForwarder.Parameters parameters, ServerSocket serverSocket)
          Create a LocalPortForwarder that will listen based on parameters using the bound serverSocket and forward incoming connections to the server; which will further forward them to host:port.
 SCPFileTransfer newSCPFileTransfer()
           
 SFTPClient newSFTPClient()
           
protected  void onConnect()
          On connection establishment, also initializes the SSH transport via Transport.init(java.lang.String, int, java.io.InputStream, java.io.OutputStream) and doKex().
 X11Forwarder registerX11Forwarder(ConnectListener listener)
          Register a listener for handling forwarded X11 channels.
 void rekey()
          Does key re-exchange.
 Session startSession()
          Opens a session channel.
 void useCompression()
          Adds zlib compression to preferred compression algorithms.
 
Methods inherited from class net.schmizz.sshj.SocketClient
connect, connect, connect, connect, connect, connect, getConnectTimeout, getLocalAddress, getLocalPort, getRemoteAddress, getRemoteHostname, getRemotePort, getSocket, getSocketFactory, getTimeout, setConnectTimeout, setSocketFactory, setTimeout
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_PORT

public static final int DEFAULT_PORT
Default port for SSH

See Also:
Constant Field Values

log

protected final org.slf4j.Logger log
Logger


trans

protected final Transport trans
Transport layer


auth

protected final UserAuth auth
ssh-userauth service


conn

protected final Connection conn
ssh-connection service

Constructor Detail

SSHClient

public SSHClient()
Default constructor. Initializes this object using DefaultConfig.


SSHClient

public SSHClient(Config config)
Constructor that allows specifying a config to be used.

Parameters:
config - Config instance
Method Detail

addHostKeyVerifier

public void addHostKeyVerifier(HostKeyVerifier hostKeyVerifier)
Add a HostKeyVerifier which will be invoked for verifying host key during connection establishment and future key exchanges.

Parameters:
hostKeyVerifier - HostKeyVerifier instance

addHostKeyVerifier

public void addHostKeyVerifier(String fingerprint)
Add a HostKeyVerifier that will verify any host that's able to claim a host key with the given fingerprint, e.g. "4b:69:6c:72:6f:79:20:77:61:73:20:68:65:72:65:21"

Parameters:
fingerprint - expected fingerprint in colon-delimited format (16 octets in hex delimited by a colon)
See Also:
SecurityUtils.getFingerprint(java.security.PublicKey)

auth

public void auth(String username,
                 AuthMethod... methods)
          throws UserAuthException,
                 TransportException
Authenticate username using the supplied methods.

Parameters:
username - user to authenticate
methods - one or more authentication method
Throws:
UserAuthException - in case of authentication failure
TransportException - if there was a transport-layer error

auth

public void auth(String username,
                 Iterable<AuthMethod> methods)
          throws UserAuthException,
                 TransportException
Authenticate username using the supplied methods.

Parameters:
username - user to authenticate
methods - one or more authentication method
Throws:
UserAuthException - in case of authentication failure
TransportException - if there was a transport-layer error

authPassword

public void authPassword(String username,
                         String password)
                  throws UserAuthException,
                         TransportException
Authenticate username using the "password" authentication method and as a fallback basic challenge-response authentication.

Parameters:
username - user to authenticate
password - the password to use for authentication
Throws:
UserAuthException - in case of authentication failure
TransportException - if there was a transport-layer error

authPassword

public void authPassword(String username,
                         char[] password)
                  throws UserAuthException,
                         TransportException
Authenticate username using the "password" authentication method and as a fallback basic challenge-response authentication.. The password array is blanked out after use.

Parameters:
username - user to authenticate
password - the password to use for authentication
Throws:
UserAuthException - in case of authentication failure
TransportException - if there was a transport-layer error

authPassword

public void authPassword(String username,
                         PasswordFinder pfinder)
                  throws UserAuthException,
                         TransportException
Authenticate username using the "password" authentication method and as a fallback basic challenge-response authentication.

Parameters:
username - user to authenticate
pfinder - the PasswordFinder to use for authentication
Throws:
UserAuthException - in case of authentication failure
TransportException - if there was a transport-layer error

authPublickey

public void authPublickey(String username)
                   throws UserAuthException,
                          TransportException
Authenticate username using the "publickey" authentication method, with keys from some common locations on the file system. This method relies on ~/.ssh/id_rsa and ~/.ssh/id_dsa.

This method does not provide a way to specify a passphrase.

Parameters:
username - user to authenticate
Throws:
UserAuthException - in case of authentication failure
TransportException - if there was a transport-layer error

authPublickey

public void authPublickey(String username,
                          Iterable<KeyProvider> keyProviders)
                   throws UserAuthException,
                          TransportException
Authenticate username using the "publickey" authentication method.

KeyProvider instances can be created using any of the of the loadKeys() method provided in this class. In case multiple keyProviders are specified; authentication is attempted in order as long as the "publickey" authentication method is available.

Parameters:
username - user to authenticate
keyProviders - one or more KeyProvider instances
Throws:
UserAuthException - in case of authentication failure
TransportException - if there was a transport-layer error

authPublickey

public void authPublickey(String username,
                          KeyProvider... keyProviders)
                   throws UserAuthException,
                          TransportException
Authenticate username using the "publickey" authentication method.

KeyProvider instances can be created using any of the loadKeys() method provided in this class. In case multiple keyProviders are specified; authentication is attempted in order as long as the "publickey" authentication method is available.

Parameters:
username - user to authenticate
keyProviders - one or more KeyProvider instances
Throws:
UserAuthException - in case of authentication failure
TransportException - if there was a transport-layer error

authPublickey

public void authPublickey(String username,
                          String... locations)
                   throws UserAuthException,
                          TransportException
Authenticate username using the "publickey" authentication method, with keys from one or more locations in the file system.

In case multiple locations are specified; authentication is attempted in order as long as the "publickey" authentication method is available. If there is an error loading keys from any of them (e.g. file could not be read, file format not recognized) that key file it is ignored.

This method does not provide a way to specify a passphrase.

Parameters:
username - user to authenticate
locations - one or more locations in the file system containing the private key
Throws:
UserAuthException - in case of authentication failure
TransportException - if there was a transport-layer error

disconnect

public void disconnect()
                throws IOException
Disconnects from the connected SSH server. SSHClient objects are not reusable therefore it is incorrect to attempt connection after this method has been called.

This method should be called from a finally construct after connection is established; so that proper cleanup is done and the thread spawned by the transport layer for dealing with incoming packets is stopped.

Overrides:
disconnect in class SocketClient
Throws:
IOException

getConnection

public Connection getConnection()
Returns:
the associated Connection instance.

getRemotePortForwarder

public RemotePortForwarder getRemotePortForwarder()
Returns:
a RemotePortForwarder that allows requesting remote forwarding over this connection.

getTransport

public Transport getTransport()
Returns:
the associated Transport instance.

getUserAuth

public UserAuth getUserAuth()
Returns:
the associated UserAuth instance. This allows access to information like the authentication banner, whether authentication was at least partially successful, and any saved exceptions that were ignored because there were more authentication method that could be tried.

isAuthenticated

public boolean isAuthenticated()
Returns:
whether authenticated.

isConnected

public boolean isConnected()
Overrides:
isConnected in class SocketClient
Returns:
whether connected.

loadKeys

public KeyProvider loadKeys(KeyPair kp)
Creates a KeyProvider from supplied KeyPair.

Parameters:
kp - the key pair
Returns:
the key provider ready for use in authentication

loadKeys

public KeyProvider loadKeys(String location)
                     throws IOException
Returns a KeyProvider instance created from a location on the file system where an unencrypted private key file (does not require a passphrase) can be found. Simply calls loadKeys(String, PasswordFinder) with the PasswordFinder argument as null.

Parameters:
location - the location for the key file
Returns:
the key provider ready for use in authentication
Throws:
SSHException - if there was no suitable key provider available for the file format; typically because BouncyCastle is not in the classpath
IOException - if the key file format is not known, if the file could not be read, etc.

loadKeys

public KeyProvider loadKeys(String location,
                            char[] passphrase)
                     throws IOException
Utility function for createing a KeyProvider instance from given location on the file system. Creates a one-off PasswordFinder using PasswordUtils.createOneOff(char[]), and calls loadKeys(String, PasswordFinder).

Parameters:
location - location of the key file
passphrase - passphrase as a char-array
Returns:
the key provider ready for use in authentication
Throws:
SSHException - if there was no suitable key provider available for the file format; typically because BouncyCastle is not in the classpath
IOException - if the key file format is not known, if the file could not be read, etc.

loadKeys

public KeyProvider loadKeys(String location,
                            PasswordFinder passwordFinder)
                     throws IOException
Creates a KeyProvider instance from given location on the file system. Currently only PKCS8 format private key files are supported (OpenSSH uses this format).

Parameters:
location - the location of the key file
passwordFinder - the PasswordFinder that can supply the passphrase for decryption (may be null in case keyfile is not encrypted)
Returns:
the key provider ready for use in authentication
Throws:
SSHException - if there was no suitable key provider available for the file format; typically because BouncyCastle is not in the classpath
IOException - if the key file format is not known, if the file could not be read, etc.

loadKeys

public KeyProvider loadKeys(String location,
                            String passphrase)
                     throws IOException
Convenience method for creating a KeyProvider instance from a location where an encrypted key file is located. Calls loadKeys(String, char[]) with a character array created from the supplied passphrase string.

Parameters:
location - location of the key file
passphrase - passphrase as a string
Returns:
the key provider for use in authentication
Throws:
IOException - if the key file format is not known, if the file could not be read etc.

loadKeys

public KeyProvider loadKeys(String privateKey,
                            String publicKey,
                            PasswordFinder passwordFinder)
                     throws IOException
Creates a KeyProvider instance from passed strings. Currently only PKCS8 format private key files are supported (OpenSSH uses this format).

Parameters:
privateKey - the private key as a string
publicKey - the public key as a string if it's not included with the private key
passwordFinder - the PasswordFinder that can supply the passphrase for decryption (may be null in case keyfile is not encrypted)
Returns:
the key provider ready for use in authentication
Throws:
SSHException - if there was no suitable key provider available for the file format; typically because BouncyCastle is not in the classpath
IOException - if the key file format is not known, etc.

loadKnownHosts

public void loadKnownHosts()
                    throws IOException
Attempts loading the user's known_hosts file from the default locations, i.e. ~/.ssh/known_hosts and ~/.ssh/known_hosts2 on most platforms. Adds the resulting OpenSSHKnownHosts object as a host key verifier.

For finer control over which file is used, see loadKnownHosts(File).

Throws:
IOException - if there is an error loading from both locations

loadKnownHosts

public void loadKnownHosts(File location)
                    throws IOException
Adds a OpenSSHKnownHosts object created from the specified location as a host key verifier.

Parameters:
location - location for known_hosts file
Throws:
IOException - if there is an error loading from any of these locations

newLocalPortForwarder

public LocalPortForwarder newLocalPortForwarder(LocalPortForwarder.Parameters parameters,
                                                ServerSocket serverSocket)
Create a LocalPortForwarder that will listen based on parameters using the bound serverSocket and forward incoming connections to the server; which will further forward them to host:port.

The returned forwarder's listen() method should be called to actually start listening, this method just creates an instance.

Parameters:
parameters - parameters for the forwarding setup
serverSocket - bound server socket
Returns:
a LocalPortForwarder

registerX11Forwarder

public X11Forwarder registerX11Forwarder(ConnectListener listener)
Register a listener for handling forwarded X11 channels. Without having done this, an incoming X11 forwarding will be summarily rejected.

It should be clarified that multiple listeners for X11 forwarding over a single SSH connection are not supported (and don't make much sense). So a subsequent call to this method is only going to replace the registered listener.

Parameters:
listener - the ConnectListener that should be delegated the responsibility of handling forwarded X11Forwarder.X11Channel 's
Returns:
an X11Forwarder that allows to stop acting on X11 requests from server

newSCPFileTransfer

public SCPFileTransfer newSCPFileTransfer()
Returns:
Instantiated SCPFileTransfer implementation.

newSFTPClient

public SFTPClient newSFTPClient()
                         throws IOException
Returns:
Instantiated SFTPClient implementation.
Throws:
IOException - if there is an error starting the sftp subsystem
See Also:
StatefulSFTPClient

rekey

public void rekey()
           throws TransportException
Does key re-exchange.

Throws:
TransportException - if an error occurs during key exchange

startSession

public Session startSession()
                     throws ConnectionException,
                            TransportException
Description copied from interface: SessionFactory
Opens a session channel. The returned Session instance allows executing a remote command, starting a subsystem, or starting a shell.

Specified by:
startSession in interface SessionFactory
Returns:
the opened session channel
Throws:
ConnectionException
TransportException
See Also:
Session

useCompression

public void useCompression()
                    throws TransportException
Adds zlib compression to preferred compression algorithms. There is no guarantee that it will be successfully negotiatied.

If the client is already connected renegotiation is done; otherwise this method simply returns (and compression will be negotiated during connection establishment).

Throws:
ClassNotFoundException - if JZlib is not in classpath
TransportException - if an error occurs during renegotiation

onConnect

protected void onConnect()
                  throws IOException
On connection establishment, also initializes the SSH transport via Transport.init(java.lang.String, int, java.io.InputStream, java.io.OutputStream) and doKex().

Throws:
IOException

doKex

protected void doKex()
              throws TransportException
Do key exchange.

Throws:
TransportException - if error during kex

close

public void close()
           throws IOException
Same as disconnect().

Specified by:
close in interface Closeable
Throws:
IOException


Copyright © 2009-2012. All Rights Reserved.