public class Connection extends Object
Connection is used to establish an encrypted TCP/IP
connection to a SSH-2 server.
Typically, one
Connection object.connect() method.authenticateWithPublicKey()).openSession()
method.close() method.| Modifier and Type | Field and Description |
|---|---|
static String |
identification
The identifier presented to the SSH-2 server.
|
| Constructor and Description |
|---|
Connection(String hostname)
Prepares a fresh
Connection object which can then be used
to establish a connection to the specified SSH-2 server. |
Connection(String hostname,
int port)
Prepares a fresh
Connection object which can then be used
to establish a connection to the specified SSH-2 server. |
| Modifier and Type | Method and Description |
|---|---|
void |
addConnectionMonitor(ConnectionMonitor cmon)
Add a
ConnectionMonitor to this connection. |
boolean |
authenticateWithAgent(String user,
AgentProxy proxy) |
boolean |
authenticateWithDSA(String user,
String pem,
String password)
Deprecated.
You should use one of the
authenticateWithPublicKey()
methods, this method is just a wrapper for it and will
disappear in future builds. |
boolean |
authenticateWithKeyboardInteractive(String user,
InteractiveCallback cb)
A wrapper that calls
authenticateWithKeyboardInteractivewith a null submethod
list. |
boolean |
authenticateWithKeyboardInteractive(String user,
String[] submethods,
InteractiveCallback cb)
After a successful connect, one has to authenticate oneself.
|
boolean |
authenticateWithNone(String user)
After a successful connect, one has to authenticate oneself.
|
boolean |
authenticateWithPassword(String user,
String password)
After a successful connect, one has to authenticate oneself.
|
boolean |
authenticateWithPublicKey(String user,
char[] pemPrivateKey,
String password)
After a successful connect, one has to authenticate oneself.
|
boolean |
authenticateWithPublicKey(String user,
File pemFile,
String password)
A convenience wrapper function which reads in a private key (PEM format,
either DSA or RSA) and then calls
authenticateWithPublicKey(String, char[], String). |
void |
cancelRemotePortForwarding(int bindPort)
Cancel an earlier requested remote port forwarding.
|
void |
close()
Close the connection to the SSH-2 server.
|
ConnectionInfo |
connect()
Same as
connect(null, 0, 0). |
ConnectionInfo |
connect(ServerHostKeyVerifier verifier)
Same as
connect(verifier, 0, 0). |
ConnectionInfo |
connect(ServerHostKeyVerifier verifier,
int connectTimeout,
int kexTimeout)
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. |
ConnectionInfo |
connect(ServerHostKeyVerifier verifier,
int connectTimeout,
int readTimeout,
int kexTimeout) |
LocalPortForwarder |
createLocalPortForwarder(InetSocketAddress addr,
String host_to_connect,
int port_to_connect)
Creates a new
LocalPortForwarder. |
LocalPortForwarder |
createLocalPortForwarder(int local_port,
String host_to_connect,
int port_to_connect)
Creates a new
LocalPortForwarder. |
LocalStreamForwarder |
createLocalStreamForwarder(String host_to_connect,
int port_to_connect)
Creates a new
LocalStreamForwarder. |
SCPClient |
createSCPClient()
Create a very basic
SCPClient that can be used to copy files
from/to the SSH-2 server. |
void |
enableDebugging(boolean enable,
DebugLogger logger)
Enable/disable debug logging.
|
void |
forceKeyExchange()
Force an asynchronous key re-exchange (the call does not block).
|
static String[] |
getAvailableCiphers()
Unless you know what you are doing, you will never need this.
|
static String[] |
getAvailableMACs()
Unless you know what you are doing, you will never need this.
|
static String[] |
getAvailableServerHostKeyAlgorithms()
Unless you know what you are doing, you will never need this.
|
ConnectionInfo |
getConnectionInfo()
Returns a
ConnectionInfo object containing the details of the
connection. |
String |
getHostname()
Returns the hostname that was passed to the constructor.
|
int |
getPort()
Returns the port that was passed to the constructor.
|
String[] |
getRemainingAuthMethods(String user)
After a successful connect, one has to authenticate oneself.
|
ClientServerHello |
getVersionInfo() |
boolean |
isAuthenticationComplete()
Determines if the authentication phase is complete.
|
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.
|
boolean |
isAuthMethodAvailable(String user,
String method)
Checks if a specified authentication method is available.
|
Session |
openSession()
Open a new
Session on this connection. |
void |
ping()
This method can be used to perform end-to-end connection testing.
|
void |
requestRemotePortForwarding(String bindAddress,
int bindPort,
String targetAddress,
int targetPort)
Request a remote port forwarding.
|
void |
sendIgnorePacket()
Send an SSH_MSG_IGNORE packet.
|
void |
sendIgnorePacket(byte[] data)
Send an SSH_MSG_IGNORE packet with the given data attribute.
|
void |
setClient2ServerCiphers(String[] ciphers)
Unless you know what you are doing, you will never need this.
|
void |
setClient2ServerMACs(String[] macs)
Unless you know what you are doing, you will never need this.
|
void |
setDHGexParameters(DHGexParameters dgp)
Sets the parameters for the diffie-hellman group exchange.
|
void |
setProxyData(ProxyData proxyData)
Used to tell the library that the connection shall be established through
a proxy server.
|
void |
setSecureRandom(SecureRandom rnd)
Provide your own instance of SecureRandom.
|
void |
setServer2ClientCiphers(String[] ciphers)
Unless you know what you are doing, you will never need this.
|
void |
setServer2ClientMACs(String[] macs)
Unless you know what you are doing, you will never need this.
|
void |
setServerHostKeyAlgorithms(String[] algos)
Define the set of allowed server host key algorithms to be used for the
following key exchange operations.
|
void |
setTCPNoDelay(boolean enable)
Enable/disable TCP_NODELAY (disable/enable Nagle's algorithm) on the
underlying socket.
|
public static final String identification
public Connection(String hostname)
Connection object which can then be used
to establish a connection to the specified SSH-2 server.
Same as Connection(hostname, 22).
hostname - the hostname of the SSH-2 server.public Connection(String hostname, int port)
Connection object which can then be used
to establish a connection to the specified SSH-2 server.hostname - the host where we later want to connect to.port - port on the server, normally 22.public static String[] getAvailableCiphers()
public static String[] getAvailableMACs()
public static String[] getAvailableServerHostKeyAlgorithms()
public boolean authenticateWithDSA(String user, String pem, String password) throws IOException
authenticateWithPublicKey()
methods, this method is just a wrapper for it and will
disappear in future builds.
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.IOExceptionpublic boolean authenticateWithKeyboardInteractive(String user, InteractiveCallback cb) throws IOException
authenticateWithKeyboardInteractivewith a null submethod
list.user - A String holding the username.cb - An InteractiveCallback which will be used to
determine the responses to the questions asked by the server.IOExceptionpublic boolean authenticateWithAgent(String user, AgentProxy proxy) throws IOException
IOExceptionpublic boolean authenticateWithKeyboardInteractive(String user, String[] submethods, InteractiveCallback cb) throws IOException
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.IOExceptionpublic boolean authenticateWithPassword(String user, String password) throws IOException
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.
user - password - IOExceptionpublic boolean authenticateWithNone(String user) throws IOException
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).
user - IOExceptionpublic boolean authenticateWithPublicKey(String user, char[] pemPrivateKey, String password) throws IOException
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.IOExceptionpublic boolean authenticateWithPublicKey(String user, File pemFile, String password) throws IOException
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.IOExceptionpublic void addConnectionMonitor(ConnectionMonitor cmon)
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.ConnectionMonitorpublic void close()
public ConnectionInfo connect() throws IOException
connect(null, 0, 0).connect(ServerHostKeyVerifier, int, int)
method.IOExceptionpublic ConnectionInfo connect(ServerHostKeyVerifier verifier) throws IOException
connect(verifier, 0, 0).connect(ServerHostKeyVerifier, int, int)
method.IOExceptionpublic ConnectionInfo connect(ServerHostKeyVerifier verifier, int connectTimeout, int kexTimeout) throws IOException
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.ConnectionInfo object containing the details of the
established connection.IOException - If any problem occurs, e.g., the server's host key is not
accepted by the verifier or there is problem
during the initial crypto setup (e.g., the signature sent by
the server is wrong).
In case of a timeout (either connectTimeout or kexTimeout) a SocketTimeoutException is thrown.
An exception may also be thrown if the connection was already
successfully connected (no matter if the connection broke in
the mean time) and you invoke connect() again
without having called close() first.
If a HTTP proxy is being used and the proxy refuses the
connection, then a HTTPProxyException may be thrown,
which contains the details returned by the proxy. If the
proxy is buggy and does not return a proper HTTP response,
then a normal IOException is thrown instead.
public ConnectionInfo connect(ServerHostKeyVerifier verifier, int connectTimeout, int readTimeout, int kexTimeout) throws IOException
IOExceptionpublic LocalPortForwarder createLocalPortForwarder(int local_port, String host_to_connect, int port_to_connect) throws IOException
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 portLocalPortForwarder object.IOExceptionpublic LocalPortForwarder createLocalPortForwarder(InetSocketAddress addr, String host_to_connect, int port_to_connect) throws IOException
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 portLocalPortForwarder object.IOExceptionpublic LocalStreamForwarder createLocalStreamForwarder(String host_to_connect, int port_to_connect) throws IOException
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 - LocalStreamForwarder object.IOExceptionpublic SCPClient createSCPClient() throws IOException
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.
SCPClient object.IOExceptionpublic void forceKeyExchange()
throws IOException
Note: This implementation will never start a key exchange (other than the initial one) unless you or the SSH-2 server ask for it.
IOException - In case of any failure behind the scenes.public String getHostname()
public int getPort()
public ConnectionInfo getConnectionInfo() throws IOException
ConnectionInfo object containing the details of the
connection. Can be called as soon as the connection has been established
(successfully connected).ConnectionInfo object.IOException - In case of any failure behind the scenes.public ClientServerHello getVersionInfo() throws IOException
IOExceptionpublic String[] getRemainingAuthMethods(String user) throws IOException
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.IOExceptionpublic boolean isAuthenticationComplete()
true if no further authentication steps are
needed.public boolean isAuthenticationPartialSuccess()
If you are interested in the details, then have a look at RFC4252.
public boolean isAuthMethodAvailable(String user, String method) throws IOException
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.IOExceptionpublic Session openSession() throws IOException
Session on this connection. Works only after one has
passed successfully the authentication step. There is no limit on the
number of concurrent sessions.Session object.IOExceptionpublic void sendIgnorePacket()
throws IOException
This method must only be called once the connection is established.
IOExceptionpublic void sendIgnorePacket(byte[] data)
throws IOException
This method must only be called once the connection is established.
IOExceptionpublic void setClient2ServerCiphers(String[] ciphers)
ciphers - public void setClient2ServerMACs(String[] macs)
macs - public void setDHGexParameters(DHGexParameters dgp)
DHGexParameters class.dgp - DHGexParameters, non null.public void setServer2ClientCiphers(String[] ciphers)
ciphers - public void setServer2ClientMACs(String[] macs)
macs - public void setServerHostKeyAlgorithms(String[] algos)
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.public void setTCPNoDelay(boolean enable)
throws IOException
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.IOExceptionpublic void setProxyData(ProxyData proxyData)
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).HTTPProxyDatapublic void requestRemotePortForwarding(String bindAddress, int bindPort, String targetAddress, int targetPort) throws IOException
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
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:
bindPort - port number to bind on the server (must be > 0)targetAddress - the target address (IP or hostname)targetPort - the target portIOExceptionpublic void cancelRemotePortForwarding(int bindPort)
throws IOException
bindPort - the allocated port number on the serverIOException - if the remote side refuses the cancel request or another low
level error occurs (e.g., the underlying connection is
closed)public void setSecureRandom(SecureRandom rnd)
The SecureRandom instance is used during key exchanges, public key authentication, x11 cookie generation and the like.
rnd - a SecureRandom instancepublic void enableDebugging(boolean enable,
DebugLogger logger)
For speed reasons, some static variables used to check whether debugging
is enabled are not protected with locks. In other words, if you
dynamicaly enable/disable debug logging, then some threads may still use
the old setting. To be on the safe side, enable debugging before doing
the connect() call.
enable - on/offlogger - a DebugLogger instance, null
means logging using the simple logger which logs all messages
to to stderr. Ignored if enabled is falsepublic void ping()
throws IOException
When this method throws an exception, then you can assume that the connection should be abandoned.
Note: Works only after one has passed successfully the authentication step.
Implementation details: this method sends a SSH_MSG_GLOBAL_REQUEST request ('trilead-ping') to the server and waits for the SSH_MSG_REQUEST_FAILURE reply packet from the server.
IOException - in case of any problemCopyright © 2017. All Rights Reserved.