com.jcraft.jsch
Class JSch

java.lang.Object
  extended by com.jcraft.jsch.JSch

public class JSch
extends Object

This class serves as a central configuration point, and as a factory for Session objects configured with these settings.


Constructor Summary
JSch()
          Creates a new JSch object.
 
Method Summary
 void addIdentity(Identity identity, byte[] passphrase)
          Adds an identity to be used for public-key authentication.
 void addIdentity(String prvkey)
          Adds an identity to be used for public-key authentication.
 void addIdentity(String prvkey, byte[] passphrase)
          Adds an identity to be used for public-key authentication.
 void addIdentity(String name, byte[] prvkey, byte[] pubkey, byte[] passphrase)
          Adds an identity to be used for public-key authentication.
 void addIdentity(String prvkey, String passphrase)
          Adds an identity to be used for public-key authentication.
 void addIdentity(String prvkey, String pubkey, byte[] passphrase)
          Adds an identity to be used for public-key authentication.
protected  void addSession(Session session)
          Adds a session to our session pool.
static String getConfig(String key)
          Retrieves a default configuration option.
 HostKeyRepository getHostKeyRepository()
          Returns the current host key repository.
 Vector getIdentityNames()
          lists the names of the identities available.
 Session getSession(String username, String host)
          Creates a new Session on port 22.
 Session getSession(String username, String host, int port)
          Creates a new Session.
 void removeAllIdentity()
          Removes all identities.
 void removeIdentity(String name)
          Removes an identity by name.
protected  boolean removeSession(Session session)
          Removes a session from our session pool.
static void setConfig(Hashtable newconf)
          Sets multiple default configuration options at once.
static void setConfig(String key, String value)
          Sets a default configuration option.
 void setHostKeyRepository(HostKeyRepository hkrepo)
          Sets the Host key repository.
 void setKnownHosts(InputStream stream)
          Creates a Host key repository from an InputStream.
 void setKnownHosts(String filename)
          Creates a host key repository from a file name.
static void setLogger(Logger logger)
          sets the Logger to be used by this library.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

JSch

public JSch()
Creates a new JSch object.

Method Detail

getSession

public Session getSession(String username,
                          String host)
                   throws JSchException
Creates a new Session on port 22.

Parameters:
username - the remote user name to use.
host - the host to connect to.
Returns:
The new session object. It is not yet connected.
Throws:
JSchException

getSession

public Session getSession(String username,
                          String host,
                          int port)
                   throws JSchException
Creates a new Session.

Parameters:
username - the remote user name to use.
host - the host to connect to.
port - the port number used for the TCP connection.
Returns:
The new session object. It is not yet connected.
Throws:
JSchException

addSession

protected void addSession(Session session)
Adds a session to our session pool. This is invoked by the sessions on Session.connect(), and should supposedly have package-access.


removeSession

protected boolean removeSession(Session session)
Removes a session from our session pool. This is invoked by the sessions on Session.disconnect(), and should supposedly have package-access.


setHostKeyRepository

public void setHostKeyRepository(HostKeyRepository hkrepo)
Sets the Host key repository. This will be used by sessions connected in the future to validate the host keys offered by the remote hosts.


setKnownHosts

public void setKnownHosts(String filename)
                   throws JSchException
Creates a host key repository from a file name. This method uses the same format as OpenSSH's known_hosts file (I hope).

This has no effect if setHostKeyRepository(com.jcraft.jsch.HostKeyRepository) was already called with an object which is not of class KnownHosts.

Parameters:
filename - the name of the file to be loaded.
Throws:
JSchException

setKnownHosts

public void setKnownHosts(InputStream stream)
                   throws JSchException
Creates a Host key repository from an InputStream. This method uses the same format as OpenSSH's known_hosts file (I hope).

This has no effect if setHostKeyRepository(com.jcraft.jsch.HostKeyRepository) was already called with an object which is not of class KnownHosts.

Parameters:
stream - an InputStream with the list of known hosts.
Throws:
JSchException

getHostKeyRepository

public HostKeyRepository getHostKeyRepository()
Returns the current host key repository. If this was not yet set by one of the methods setKnownHosts(InputStream), setKnownHosts(String) or setHostKeyRepository(com.jcraft.jsch.HostKeyRepository), this creates a new (empty) repository of class KnownHosts, sets this as the current repository and returns it.


addIdentity

public void addIdentity(String prvkey)
                 throws JSchException
Adds an identity to be used for public-key authentication.

Parameters:
prvkey - the file name of the private key file. This is also used as the identifying name of the key. The corresponding public key is assumed to be in a file with the same name with suffix .pub.
Throws:
JSchException

addIdentity

public void addIdentity(String prvkey,
                        String passphrase)
                 throws JSchException
Adds an identity to be used for public-key authentication.

Parameters:
prvkey - the file name of the private key file. This is also used as the identifying name of the key. The corresponding public key is assumed to be in a file with the same name with suffix .pub.
passphrase - the passphrase necessary to access the key. The String will be encoded in UTF-8 to get the actual passphrase.
Throws:
JSchException

addIdentity

public void addIdentity(String prvkey,
                        byte[] passphrase)
                 throws JSchException
Adds an identity to be used for public-key authentication.

Parameters:
prvkey - the file name of the private key file. This is also used as the identifying name of the key. The corresponding public key is assumed to be in a file with the same name with suffix .pub.
passphrase - the passphrase necessary to access the key.
Throws:
JSchException

addIdentity

public void addIdentity(String prvkey,
                        String pubkey,
                        byte[] passphrase)
                 throws JSchException
Adds an identity to be used for public-key authentication.

Parameters:
prvkey - the file name of the private key file. This is also used as the identifying name of the key.
pubkey - the file name of the public key file.
passphrase - the passphrase necessary to access the private key.
Throws:
JSchException

addIdentity

public void addIdentity(String name,
                        byte[] prvkey,
                        byte[] pubkey,
                        byte[] passphrase)
                 throws JSchException
Adds an identity to be used for public-key authentication.

Parameters:
name - a name identifying the key pair.
prvkey - the private key data. This will be zeroed out after creating the Identity object.
pubkey - the public key data.
passphrase - the passphrase necessary to access the private key.
Throws:
JSchException

addIdentity

public void addIdentity(Identity identity,
                        byte[] passphrase)
                 throws JSchException
Adds an identity to be used for public-key authentication.

Parameters:
identity - the Identity object encapsulating the key pair and algorithm (or a hardware device containing them).
passphrase - the passphrase necessary to access the private key.
Throws:
JSchException

removeIdentity

public void removeIdentity(String name)
                    throws JSchException
Removes an identity by name. (The name is the result of the getName method of the Identity object.) This identity will not be used for future connections anymore. (We also clear the identity, causing it to forget its passphrase.)

Parameters:
name - the name of the identity to remove.
Throws:
JSchException

getIdentityNames

public Vector getIdentityNames()
                        throws JSchException
lists the names of the identities available.

Returns:
a vector of strings, each being the name of one of the added identities.
Throws:
JSchException

removeAllIdentity

public void removeAllIdentity()
                       throws JSchException
Removes all identities. Public key authentication will not work anymore until another identity is added.

Throws:
JSchException

getConfig

public static String getConfig(String key)
Retrieves a default configuration option. This method is used to retrieve default values if a session does not have a specific option set.

See Also:
Session.getConfig(java.lang.String), setConfig(String, String)

setConfig

public static void setConfig(Hashtable newconf)
Sets multiple default configuration options at once. The given hashtable should only contain Strings.

Throws:
ClassCastException - if the Hashtable contains keys or values which are not Strings. In this case some string key-value pairs may already have been set.
See Also:
setConfig(String, String)

setConfig

public static void setConfig(String key,
                             String value)
Sets a default configuration option. This option is used by all sessions, if for these sessions was not set a specific value for this key with session.setConfig.

Here is the list of configuration options used by the program. They all have sensible default values (use the source if you want to know the defaults).

Algorithm lists

These options contain a (comma-separated, without spaces) list of algorithms, which will be offered to the server, and from which one will be selected by negotiation during key exchange. These should confirm to the format defined by RFC 4250, and be accompanied by an "implementation" option.

kex
Key exchange algorithms
server_host_key
Algorithms supported for the server host key.
cipher.s2c
encryption algorithms used for server-to-client transport. See CheckCiphers.
cipher.c2s
encryption algorithms used for client-to-server transport. See CheckCiphers.
mac.c2s
message authentication code algorithms for client-to-server transport.
mac.s2c
message authentication code algorithms for server-to-client transport.
compression.c2s
Compression algorithms for client-to-server transport. The default is "none", but this library also supports "zlib" and "zlib@openssh.com". (Other compression algorithms can't be put in, it seems.)
compression.s2c
Compression algorithms for server-to-client transport. The default is "none", but this library also supports "zlib" and "zlib@openssh.com". (Other compression algorithms can't be put in, it seems.)
lang.s2c
Language preferences for server-to-client human readable messages (should normally be empty)
lang.c2s
Language preferences for client-to-server human readable messages (should normally be empty)

During key exchange, the first option in the client's list (i.e. the option value) which also appears on the server's list will be choosen for each algorithm. Thus the order matters here.

Implementation classes

The following options contain the class name of classes implementing a specific algorithm. They should implement the interface or abstract class mentioned here.

The classes must be findable using the class loader which loaded the JSch library (e.g. by a simple Class.forName(java.lang.String) inside the library classes), and must have a no-argument constructor, which will be called to instantiate the objects needed. Then the actual interface methods will be used.

Key exchange algorithms (KeyExchange)

diffie-hellman-group-exchange-sha1
Diffie-Hellman Key Exchange with a group chosen by the server (RFC 4419).
diffie-hellman-group1-sha1
Diffie-Hellman key exchange with a fixed group. (RFC 4253, section 7)

Symmetric Encryption algorithms (Cipher)

(The mentioned ones have implementations included in the library, of course you can add more, adding them to cipher.s2c and/or cipher.c2s. The RFC mentioned is the RFC which defined the keywords, here with links: RFC 4253, SSH Transport Layer Protocol, Section 6.3 Encryption, RFC 4344, SSH Transport Layer Encryption Modes (which defines the CTR mode for most of the ciphers of RFC 4253), and RFC 4345, Improved Arcfour Modes for SSH.)

3des-cbc
three-key 3DES in CBC mode (RFC 4253)
3des-ctr
blowfish-cbc
Blowfish in CBC mode (RFC 4253)
aes256-cbc
AES in CBC mode, with a 256-bit key (RFC 4253)
aes192-cbc
AES with a 192-bit key (RFC 4253)
aes128-cbc
AES with a 128-bit key (RFC 4253)
aes128-ctr
AES (Rijndael) in SDCTR mode, with 128-bit key (RFC 4344)
aes192-ctr
AES with 192-bit key (RFC 4344)
aes256-ctr
AES with 256-bit key (RFC 4344)
arcfour
the ARCFOUR stream cipher with a 128-bit key (RFC 4253)
arcfour128
a variant of the ARCFOUR cipher (still with 128-bit key), which discards the first 1536 bytes of keystream before encryption will begin. (RFC 4345)
arcfour256
Like arcfour128, but with a 256-bit key. (RFC 4345).
none
The null cipher (i.e. no encryption) (RFC 4345, RFC 2410)

Message Authentication Code algorithms (MAC)

These keywords are defined in RFC 4253, section 6.4 Data Integrity. The basic HMAC algorithm is defined in RFC 2104.

hmac-sha1
HMAC-SHA1 (digest length = key length = 20)
hmac-sha1-96
first 96 bits of HMAC-SHA1 (digest length = 12, key length = 20)
hmac-md5
HMAC-MD5 (digest length = key length = 16)
hmac-md5-96
first 96 bits of HMAC-MD5 (digest length = 12, key length = 16)

Compression methods (Compression)

(It is now hardcoded that only these two (and none) are actually accepted, even if providing more ones with compression.s2c or compression.c2s. I think the reason is the special handling necessary for zlib@openssh.com.)

zlib
zlib compression as defined by RFC 1950+1951
zlib@openssh.com
A variant of the zlib compression where the compression only starts after the client user is authenticated. This is described in the Internet-Draft draft-miller-secsh-compression-delayed-00.

User Authentication methods (UserAuth)

Here the user sends a list of methods, and we have a list of methods in the option PreferredAuthentications (in preference order). We take the first of our methods which is supported by the server, get the userauth.method variable to load the implementing class, and try to authenticate. This will repeat until we are authenticated or no more methods left.

The following ones are built in:

userauth.none
mainly for getting the list of methods the server supports.
userauth.password
usual password authentication.
userauth.keyboard-interactive
Using the generic message exchange authentication mechanism, as defined in RFC 4256.
userauth.publickey
public key authentication, using an Identity.
userauth.gssapi-with-mic
Using the GSS-API (see below) as defined in RFC 4462, section 3.

For the GSS-API mechanism we need an implementation of GSSContext to refer to, which will be chosen by the configuration option gssapi-with-mic.method, the method being chosen from a list given by the server. For now, we (hardcoded) only support the krb5 method, resulting in:

gssapi-with-mic.krb5
Kerberos 5 authentication.

Miscellaneous algorithms

The following options do not correspond to algorithm names as defined in the SSH protocols, but are used to implement the underlying cryptographic functions.

dh
DH - Diffie-Hellman mathematics.
random
Random - random number generation.
signature.dss
SignatureDSA
signature.rsa
SignatureRSA
keypairgen.dsa
KeyPairGenDSA
keypairgen.rsa
KeyPairGenRSA

And the cryptographic hash algorithms (HASH):

sha-1
The Secure Hash Algorithm, version 1.
md5
The Message Digest 5 algorithm.

Other options

Here are options not fitting in any of the other categories.

compression_level
The compression level for client-to-server transport. This will only be used if the negotiated compression method is one of zlib and zlib@openssh.com (other methods are not supported anyway).
PreferredAuthentications
A preference order of our preferred authentication methods. Each of them should have a corresponding userauth.method configuration option defining the implementation class.
StrictHostKeyChecking
Indicates what to do if the server's host key changed or the server is unknown. One of yes (refuse connection), ask (ask the user whether to add/change the key) and no (always insert the new key).
HashKnownHosts
If this is "yes" and we are using the default known-hosts file implementation, new added server keys will be hashed.
CheckCiphers
A list of Ciphers which should be first checked for availability. All ciphers in this list which are not working will be removed from the ciphers.c2s and ciphers.s2c before sending these lists to the server in a KEX_INIT message.

Parameters:
key - the option name.
value - the option value.
See Also:
Session.setConfig(java.util.Properties), getConfig(java.lang.String)

setLogger

public static void setLogger(Logger logger)
sets the Logger to be used by this library.

Parameters:
logger - the new logger. If null, we use a buildt-in Logger which logs nothing.


This is a simplified version of the inofficial Javadoc created by PaĆ­lo Ebermann. Have a look at the official homepage.