addConnectionMonitor
public void addConnectionMonitor(ConnectionMonitor cmon)
Add a
ConnectionMonitor
to this connection. Can be invoked at any time,
but it is best to add connection monitors before invoking
connect()
to avoid glitches (e.g., you add a connection monitor after
a successful connect(), but the connection has died in the mean time. Then,
your connection monitor won't be notified.)
You can add as many monitors as you like.
cmon
- An object implementing the ConnectionMonitor
interface.
authenticateWithDSA
public boolean authenticateWithDSA(String user,
String pem,
String password)
throws IOException
You should use one of the authenticateWithPublicKey()
methods, this method is just a wrapper for it and will
disappear in future builds.
After a successful connect, one has to authenticate oneself. This method
is based on DSA (it uses DSA to sign a challenge sent by the server).
If the authentication phase is complete,
true
will be
returned. If the server does not accept the request (or if further
authentication steps are needed),
false
is returned and
one can retry either by using this or any other authentication method
(use the
getRemainingAuthMethods
method to get a list of
the remaining possible methods).
user
- A String
holding the username.pem
- A String
containing the DSA private key of the
user in OpenSSH key format (PEM, you can't miss the
"-----BEGIN DSA PRIVATE KEY-----" tag). The string may contain
linefeeds.password
- If the PEM string is 3DES encrypted ("DES-EDE3-CBC"), then you
must specify the password. Otherwise, this argument will be
ignored and can be set to null
.
- whether the connection is now authenticated.
authenticateWithKeyboardInteractive
public boolean authenticateWithKeyboardInteractive(String user,
String[] submethods,
InteractiveCallback cb)
throws IOException
After a successful connect, one has to authenticate oneself. This method
is based on "keyboard-interactive", specified in
draft-ietf-secsh-auth-kbdinteract-XX. Basically, you have to define a
callback object which will be feeded with challenges generated by the
server. Answers are then sent back to the server. It is possible that the
callback will be called several times during the invocation of this
method (e.g., if the server replies to the callback's answer(s) with
another challenge...)
If the authentication phase is complete,
true
will be
returned. If the server does not accept the request (or if further
authentication steps are needed),
false
is returned and
one can retry either by using this or any other authentication method
(use the
getRemainingAuthMethods
method to get a list of
the remaining possible methods).
Note: some SSH servers advertise "keyboard-interactive", however, any
interactive request will be denied (without having sent any challenge to
the client).
user
- A String
holding the username.submethods
- An array of submethod names, see
draft-ietf-secsh-auth-kbdinteract-XX. May be null
to indicate an empty list.cb
- An InteractiveCallback
which will be used to
determine the responses to the questions asked by the server.
- whether the connection is now authenticated.
authenticateWithKeyboardInteractive
public boolean authenticateWithKeyboardInteractive(String user,
InteractiveCallback cb)
throws IOException
user
- A String
holding the username.cb
- An InteractiveCallback
which will be used to
determine the responses to the questions asked by the server.
- whether the connection is now authenticated.
authenticateWithNone
public boolean authenticateWithNone(String user)
throws IOException
After a successful connect, one has to authenticate oneself.
This method can be used to explicitly use the special "none"
authentication method (where only a username has to be specified).
Note 1: The "none" method may always be tried by clients, however as by
the specs, the server will not explicitly announce it. In other words,
the "none" token will never show up in the list returned by
getRemainingAuthMethods(String)
.
Note 2: no matter which one of the authenticateWithXXX() methods
you call, the library will always issue exactly one initial "none"
authentication request to retrieve the initially allowed list of
authentication methods by the server. Please read RFC 4252 for the
details.
If the authentication phase is complete,
true
will be
returned. If further authentication steps are needed,
false
is returned and one can retry by any other authentication method
(use the
getRemainingAuthMethods
method to get a list of
the remaining possible methods).
- if the connection is now authenticated.
authenticateWithPassword
public boolean authenticateWithPassword(String user,
String password)
throws IOException
After a successful connect, one has to authenticate oneself. This method
sends username and password to the server.
If the authentication phase is complete,
true
will be
returned. If the server does not accept the request (or if further
authentication steps are needed),
false
is returned and
one can retry either by using this or any other authentication method
(use the
getRemainingAuthMethods
method to get a list of
the remaining possible methods).
Note: if this method fails, then please double-check that it is actually
offered by the server (use
getRemainingAuthMethods()
.
Often, password authentication is disabled, but users are not aware of it.
Many servers only offer "publickey" and "keyboard-interactive". However,
even though "keyboard-interactive" *feels* like password authentication
(e.g., when using the putty or openssh clients) it is *not* the same mechanism.
- if the connection is now authenticated.
authenticateWithPublicKey
public boolean authenticateWithPublicKey(String user,
File pemFile,
String password)
throws IOException
A convenience wrapper function which reads in a private key (PEM format, either DSA or RSA)
and then calls
authenticateWithPublicKey(String, char[], String)
.
NOTE PUTTY USERS: Event though your key file may start with "-----BEGIN..."
it is not in the expected format. You have to convert it to the OpenSSH
key format by using the "puttygen" tool (can be downloaded from the Putty
website). Simply load your key and then use the "Conversions/Export OpenSSH key"
functionality to get a proper PEM file.
user
- A String
holding the username.pemFile
- A File
object pointing to a file containing a DSA or RSA
private key of the user in OpenSSH key format (PEM, you can't miss the
"-----BEGIN DSA PRIVATE KEY-----" or "-----BEGIN RSA PRIVATE KEY-----"
tag).password
- If the PEM file is encrypted then you must specify the password.
Otherwise, this argument will be ignored and can be set to null
.
- whether the connection is now authenticated.
authenticateWithPublicKey
public boolean authenticateWithPublicKey(String user,
char[] pemPrivateKey,
String password)
throws IOException
After a successful connect, one has to authenticate oneself.
The authentication method "publickey" works by signing a challenge
sent by the server. The signature is either DSA or RSA based - it
just depends on the type of private key you specify, either a DSA
or RSA private key in PEM format. And yes, this is may seem to be a
little confusing, the method is called "publickey" in the SSH-2 protocol
specification, however since we need to generate a signature, you
actually have to supply a private key =).
The private key contained in the PEM file may also be encrypted ("Proc-Type: 4,ENCRYPTED").
The library supports DES-CBC and DES-EDE3-CBC encryption, as well
as the more exotic PEM encrpytions AES-128-CBC, AES-192-CBC and AES-256-CBC.
If the authentication phase is complete,
true
will be
returned. If the server does not accept the request (or if further
authentication steps are needed),
false
is returned and
one can retry either by using this or any other authentication method
(use the
getRemainingAuthMethods
method to get a list of
the remaining possible methods).
NOTE PUTTY USERS: Event though your key file may start with "-----BEGIN..."
it is not in the expected format. You have to convert it to the OpenSSH
key format by using the "puttygen" tool (can be downloaded from the Putty
website). Simply load your key and then use the "Conversions/Export OpenSSH key"
functionality to get a proper PEM file.
user
- A String
holding the username.pemPrivateKey
- A char[]
containing a DSA or RSA private key of the
user in OpenSSH key format (PEM, you can't miss the
"-----BEGIN DSA PRIVATE KEY-----" or "-----BEGIN RSA PRIVATE KEY-----"
tag). The char array may contain linebreaks/linefeeds.password
- If the PEM structure is encrypted ("Proc-Type: 4,ENCRYPTED") then
you must specify a password. Otherwise, this argument will be ignored
and can be set to null
.
- whether the connection is now authenticated.
cancelRemotePortForwarding
public void cancelRemotePortForwarding(int bindPort)
throws IOException
Cancel an earlier requested remote port forwarding.
Currently active forwardings will not be affected (e.g., disrupted).
Note that further connection forwarding requests may be received until
this method has returned.
bindPort
- the allocated port number on the server
close
public void close()
Close the connection to the SSH-2 server. All assigned sessions will be
closed, too. Can be called at any time. Don't forget to call this once
you don't need a connection anymore - otherwise the receiver thread may
run forever.
connect
public ConnectionInfo connect(ServerHostKeyVerifier verifier,
int connectTimeout,
int kexTimeout)
throws IOException
Connect to the SSH-2 server and, as soon as the server has presented its
host key, use the
ServerHostKeyVerifier.verifyServerHostKey()
method of the
verifier
to ask for permission to proceed.
If
verifier
is
null
, then any host key will be
accepted - this is NOT recommended, since it makes man-in-the-middle attackes
VERY easy (somebody could put a proxy SSH server between you and the real server).
Note: The verifier will be called before doing any crypto calculations
(i.e., diffie-hellman). Therefore, if you don't like the presented host key then
no CPU cycles are wasted (and the evil server has less information about us).
However, it is still possible that the server presented a fake host key: the server
cheated (typically a sign for a man-in-the-middle attack) and is not able to generate
a signature that matches its host key. Don't worry, the library will detect such
a scenario later when checking the signature (the signature cannot be checked before
having completed the diffie-hellman exchange).
Note 2: The
ServerHostKeyVerifier.verifyServerHostKey()
method
will *NOT* be called from the current thread, the call is being made from a
background thread (there is a background dispatcher thread for every
established connection).
Note 3: This method will block as long as the key exchange of the underlying connection
has not been completed (and you have not specified any timeouts).
Note 4: If you want to re-use a connection object that was successfully connected,
then you must call the
close()
method before invoking
connect()
again.
verifier
- An object that implements the
ServerHostKeyVerifier
interface. Pass null
to accept any server host key - NOT recommended.connectTimeout
- Connect the underlying TCP socket to the server with the given timeout
value (non-negative, in milliseconds). Zero means no timeout. If a proxy is being
used (see setProxyData(ProxyData)
), then this timeout is used for the
connection establishment to the proxy.kexTimeout
- Timeout for complete connection establishment (non-negative,
in milliseconds). Zero means no timeout. The timeout counts from the
moment you invoke the connect() method and is cancelled as soon as the
first key-exchange round has finished. It is possible that
the timeout event will be fired during the invocation of the
verifier
callback, but it will only have an effect after
the verifier
returns.
- A
ConnectionInfo
object containing the details of
the established connection.
createLocalPortForwarder
public LocalPortForwarder createLocalPortForwarder(InetSocketAddress addr,
String host_to_connect,
int port_to_connect)
throws IOException
Creates a new
LocalPortForwarder
.
A
LocalPortForwarder
forwards TCP/IP connections that arrive at a local
port via the secure tunnel to another host (which may or may not be
identical to the remote SSH-2 server).
This method must only be called after one has passed successfully the authentication step.
There is no limit on the number of concurrent forwardings.
addr
- specifies the InetSocketAddress where the local socket shall be bound to.host_to_connect
- target address (IP or hostname)port_to_connect
- target port
createLocalPortForwarder
public LocalPortForwarder createLocalPortForwarder(int local_port,
String host_to_connect,
int port_to_connect)
throws IOException
Creates a new
LocalPortForwarder
.
A
LocalPortForwarder
forwards TCP/IP connections that arrive at a local
port via the secure tunnel to another host (which may or may not be
identical to the remote SSH-2 server).
This method must only be called after one has passed successfully the authentication step.
There is no limit on the number of concurrent forwardings.
local_port
- the local port the LocalPortForwarder shall bind to.host_to_connect
- target address (IP or hostname)port_to_connect
- target port
createLocalStreamForwarder
public LocalStreamForwarder createLocalStreamForwarder(String host_to_connect,
int port_to_connect)
throws IOException
Creates a new
LocalStreamForwarder
.
A
LocalStreamForwarder
manages an Input/Outputstream pair
that is being forwarded via the secure tunnel into a TCP/IP connection to another host
(which may or may not be identical to the remote SSH-2 server).
host_to_connect
- port_to_connect
-
createSCPClient
public SCPClient createSCPClient()
throws IOException
Create a very basic
SCPClient
that can be used to copy
files from/to the SSH-2 server.
Works only after one has passed successfully the authentication step.
There is no limit on the number of concurrent SCP clients.
Note: This factory method will probably disappear in the future.
forceKeyExchange
public void forceKeyExchange()
throws IOException
Force an asynchronous key re-exchange (the call does not block). The
latest values set for MAC, Cipher and DH group exchange parameters will
be used. If a key exchange is currently in progress, then this method has
the only effect that the so far specified parameters will be used for the
next (server driven) key exchange.
Note: This implementation will never start a key exchange (other than the initial one)
unless you or the SSH-2 server ask for it.
getAvailableCiphers
public static String[] getAvailableCiphers()
Unless you know what you are doing, you will never need this.
- The list of supported cipher algorithms by this implementation.
getAvailableMACs
public static String[] getAvailableMACs()
Unless you know what you are doing, you will never need this.
- The list of supported MAC algorthims by this implementation.
getAvailableServerHostKeyAlgorithms
public static String[] getAvailableServerHostKeyAlgorithms()
Unless you know what you are doing, you will never need this.
- The list of supported server host key algorthims by this implementation.
getConnectionInfo
public ConnectionInfo getConnectionInfo()
throws IOException
Returns a
ConnectionInfo
object containing the details of
the connection. Can be called as soon as the connection has been
established (successfully connected).
getHostname
public String getHostname()
Returns the hostname that was passed to the constructor.
getPort
public int getPort()
Returns the port that was passed to the constructor.
getRemainingAuthMethods
public String[] getRemainingAuthMethods(String user)
throws IOException
After a successful connect, one has to authenticate oneself. This method
can be used to tell which authentication methods are supported by the
server at a certain stage of the authentication process (for the given
username).
Note 1: the username will only be used if no authentication step was done
so far (it will be used to ask the server for a list of possible
authentication methods by sending the initial "none" request). Otherwise,
this method ignores the user name and returns a cached method list
(which is based on the information contained in the last negative server response).
Note 2: the server may return method names that are not supported by this
implementation.
After a successful authentication, this method must not be called
anymore.
user
- A String
holding the username.
- a (possibly emtpy) array holding authentication method names.
isAuthMethodAvailable
public boolean isAuthMethodAvailable(String user,
String method)
throws IOException
Checks if a specified authentication method is available. This method is
actually just a wrapper for
getRemainingAuthMethods()
.
user
- A String
holding the username.method
- An authentication method name (e.g., "publickey", "password",
"keyboard-interactive") as specified by the SSH-2 standard.
- if the specified authentication method is currently available.
isAuthenticationComplete
public boolean isAuthenticationComplete()
Determines if the authentication phase is complete. Can be called at any
time.
true
if no further authentication steps are
needed.
isAuthenticationPartialSuccess
public boolean isAuthenticationPartialSuccess()
Returns true if there was at least one failed authentication request and
the last failed authentication request was marked with "partial success"
by the server. This is only needed in the rare case of SSH-2 server setups
that cannot be satisfied with a single successful authentication request
(i.e., multiple authentication steps are needed.)
If you are interested in the details, then have a look at RFC4252.
- if the there was a failed authentication step and the last one
was marked as a "partial success".
openSession
public Session openSession()
throws IOException
Open a new
Session
on this connection. Works only after one has passed
successfully the authentication step. There is no limit on the number of
concurrent sessions.
requestRemotePortForwarding
public void requestRemotePortForwarding(String bindAddress,
int bindPort,
String targetAddress,
int targetPort)
throws IOException
Request a remote port forwarding.
If successful, then forwarded connections will be redirected to the given target address.
You can cancle a requested remote port forwarding by calling
cancelRemotePortForwarding()
.
A call of this method will block until the peer either agreed or disagreed to your request-
Note 1: this method typically fails if you
- pass a port number for which the used remote user has not enough permissions (i.e., port
< 1024)
- or pass a port number that is already in use on the remote server
- or if remote port forwarding is disabled on the server.
Note 2: (from the openssh man page): By default, the listening socket on the server will be
bound to the loopback interface only. This may be overriden by specifying a bind address.
Specifying a remote bind address will only succeed if the server's
GatewayPorts option
is enabled (see sshd_config(5)).
bindAddress
- address to bind to on the server:
- "" means that connections are to be accepted on all protocol families
supported by the SSH implementation
- "0.0.0.0" means to listen on all IPv4 addresses
- "::" means to listen on all IPv6 addresses
- "localhost" means to listen on all protocol families supported by the SSH
implementation on loopback addresses only, [RFC3330] and RFC3513]
- "127.0.0.1" and "::1" indicate listening on the loopback interfaces for
IPv4 and IPv6 respectively
bindPort
- port number to bind on the server (must be > 0)targetAddress
- the target address (IP or hostname)targetPort
- the target port
sendIgnorePacket
public void sendIgnorePacket()
throws IOException
Send an SSH_MSG_IGNORE packet. This method will generate a random data attribute
(length between 0 (invlusive) and 16 (exclusive) bytes, contents are random bytes).
This method must only be called once the connection is established.
sendIgnorePacket
public void sendIgnorePacket(byte[] data)
throws IOException
Send an SSH_MSG_IGNORE packet with the given data attribute.
This method must only be called once the connection is established.
setClient2ServerCiphers
public void setClient2ServerCiphers(String[] ciphers)
Unless you know what you are doing, you will never need this.
setClient2ServerMACs
public void setClient2ServerMACs(String[] macs)
Unless you know what you are doing, you will never need this.
setDHGexParameters
public void setDHGexParameters(DHGexParameters dgp)
Sets the parameters for the diffie-hellman group exchange. Unless you
know what you are doing, you will never need this. Default values are
defined in the
DHGexParameters
class.
setProxyData
public void setProxyData(ProxyData proxyData)
Used to tell the library that the connection shall be established through a proxy server.
It only makes sense to call this method before calling the
connect()
method.
At the moment, only HTTP proxies are supported.
Note: This method can be called any number of times. The
connect()
method will use the value set in the last preceding invocation of this method.
proxyData
- Connection information about the proxy. If null
, then
no proxy will be used (non surprisingly, this is also the default).
setSecureRandom
public void setSecureRandom(SecureRandom rnd)
Provide your own instance of SecureRandom. Can be used, e.g., if you
want to seed the used SecureRandom generator manually.
The SecureRandom instance is used during key exchanges, public key authentication,
x11 cookie generation and the like.
rnd
- a SecureRandom instance
setServer2ClientCiphers
public void setServer2ClientCiphers(String[] ciphers)
Unless you know what you are doing, you will never need this.
setServer2ClientMACs
public void setServer2ClientMACs(String[] macs)
Unless you know what you are doing, you will never need this.
setServerHostKeyAlgorithms
public void setServerHostKeyAlgorithms(String[] algos)
Define the set of allowed server host key algorithms to be used for
the following key exchange operations.
Unless you know what you are doing, you will never need this.
algos
- An array of allowed server host key algorithms.
SSH-2 defines ssh-dss
and ssh-rsa
.
The entries of the array must be ordered after preference, i.e.,
the entry at index 0 is the most preferred one. You must specify
at least one entry.
setTCPNoDelay
public void setTCPNoDelay(boolean enable)
throws IOException
Enable/disable TCP_NODELAY (disable/enable Nagle's algorithm) on the underlying socket.
Can be called at any time. If the connection has not yet been established
then the passed value will be stored and set after the socket has been set up.
The default value that will be used is
false
.
enable
- the argument passed to the Socket.setTCPNoDelay()
method.