com.jcraft.jsch

Class JSch

java.lang.Object

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.

• Use getSession to start a new Session.
• Use one of the addIdentity methods for public-key authentication.
• Use setKnownHosts to enable checking of host keys.
• See setConfig for a list of configuration options.

Field Summary

Fields

Modifier and Type	Field and Description
static String	VERSION The version number.

Constructor Summary

Constructors

Constructor and Description
JSch() Creates a new JSch object.

Method Summary

Modifier and Type	Method and Description
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.
ConfigRepository	getConfigRepository()
HostKeyRepository	getHostKeyRepository() Returns the current host key repository.
Vector	getIdentityNames() Lists names of identities included in the identityRepository.
IdentityRepository	getIdentityRepository()
Session	getSession(String host) Instantiates the Session object with host.
Session	getSession(String username, String host) Instantiates the Session object with username and host.
Session	getSession(String username, String host, int port) Instantiates the Session object with given username, host and port.
void	removeAllIdentity() Removes all identities.
void	removeIdentity(Identity identity) Removes the identity from identityRepository.
void	removeIdentity(String name) Deprecated. use #removeIdentity(Identity identity)
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	setConfigRepository(ConfigRepository configRepository)
void	setHostKeyRepository(HostKeyRepository hkrepo) Sets the Host key repository.
void	setIdentityRepository(IdentityRepository identityRepository) Sets the identityRepository, which will be referred in the public key authentication.
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

Field Detail

VERSION

public static final String VERSION

The version number.

See Also:

Constant Field Values

Constructor Detail

JSch

public JSch()

Creates a new JSch object.

Method Detail

setIdentityRepository

public void setIdentityRepository(IdentityRepository identityRepository)

Sets the identityRepository, which will be referred in the public key authentication.

Parameters:

identityRepository - if null is given, the default repository, which usually refers to ~/.ssh/, will be used.

See Also:

getIdentityRepository()

getIdentityRepository

public IdentityRepository getIdentityRepository()

getConfigRepository

public ConfigRepository getConfigRepository()

setConfigRepository

public void setConfigRepository(ConfigRepository configRepository)

getSession

public Session getSession(String host)
                   throws JSchException

Instantiates the Session object with host. The user name and port number will be retrieved from ConfigRepository. If user name is not given, the system property "user.name" will be referred.

Parameters:

host - hostname

Returns:

the instance of Session class.

Throws:

JSchException - if username or host are invalid.

See Also:

getSession(String username, String host, int port), Session, ConfigRepository

getSession

public Session getSession(String username,
                          String host)
                   throws JSchException

Instantiates the Session object with username and host. The TCP port 22 will be used in making the connection. Note that the TCP connection must not be established until Session#connect().

Parameters:

username - user name

host - hostname

Returns:

the instance of Session class.

Throws:

JSchException - if username or host are invalid.

See Also:

getSession(String username, String host, int port), Session

getSession

public Session getSession(String username,
                          String host,
                          int port)
                   throws JSchException

Instantiates the Session object with given username, host and port. Note that the TCP connection must not be established until Session#connect().

Parameters:

username - user name

host - hostname

port - port number

Returns:

the instance of Session class.

Throws:

JSchException - if username or host are invalid.

See Also:

getSession(String username, String host, int port), Session

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.

Parameters:

hkrepo -

See Also:

HostKeyRepository, KnownHosts

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 - if an I/O error occurs.

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.

Returns:

current hostkey repository.

See Also:

HostKeyRepository, KnownHosts

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 - if prvkey is invalid.

See Also:

addIdentity(String prvkey, String passphrase)

addIdentity

public void addIdentity(String prvkey,
                        String passphrase)
                 throws JSchException

Adds an identity to be used for public-key authentication. Before registering it into identityRepository, it will be deciphered with passphrase.

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 - if passphrase is not right.

See Also:

addIdentity(String prvkey, byte[] passphrase)

addIdentity

public void addIdentity(String prvkey,
                        byte[] passphrase)
                 throws JSchException

Adds an identity to be used for public-key authentication. Before registering it into identityRepository, it will be deciphered with passphrase.

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 - if passphrase is not right.

See Also:

addIdentity(String prvkey, String pubkey, byte[] passphrase)

addIdentity

public void addIdentity(String prvkey,
                        String pubkey,
                        byte[] passphrase)
                 throws JSchException

Adds an identity to be used for public-key authentication. Before registering it into identityRepository, it will be deciphered with passphrase.

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 - if passphrase is not right.

addIdentity

public void addIdentity(String name,
                        byte[] prvkey,
                        byte[] pubkey,
                        byte[] passphrase)
                 throws JSchException

Adds an identity to be used for public-key authentication. Before registering it into identityRepository, it will be deciphered with passphrase.

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. Before registering it into identityRepository, it will be deciphered with passphrase.

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 - if passphrase is not right.

removeIdentity

public void removeIdentity(String name)
                    throws JSchException

Deprecated. use #removeIdentity(Identity identity)

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

removeIdentity

public void removeIdentity(Identity identity)
                    throws JSchException

Removes the identity from identityRepository.

Parameters:

identity - the indentity to be removed.

Throws:

JSchException - if identity is invalid.

getIdentityNames

public Vector getIdentityNames()
                        throws JSchException

Lists names of identities included in the identityRepository.

Returns:

names of identities (as a vector of strings).

Throws:

JSchException - if identityReposory has problems.

removeAllIdentity

public void removeAllIdentity()
                       throws JSchException

Removes all identities. Public key authentication will not work anymore until another identity is added.

Throws:

JSchException - if identityReposory has problems.

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.

Parameters:

key - key for the configuration.

Returns:

config value

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)

Elliptic curve key exchange algorithms (ECDH)

ecdh-sha2-nistp

Elliptic curve Diffie Hellmann key exchange. (RFC 5656, section 4)

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

signature.ecdsa

SignatureECDSA

keypairgen.dsa

KeyPairGenDSA

keypairgen.rsa

KeyPairGenRSA

pbkdf

PBKDF - password based key generation, using PKDF 2 with HMAC-SHA1

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.

See Also:

Logger