|
Ganymed SSH2 for Java | ||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectch.ethz.ssh2.Connection
A Connection
is used to establish an encrypted TCP/IP
connection to a SSH2 server.
Typically, one
Connection
object.connect
method.openSession
,
createPortForwarder
or similar methods.close
method.
Field Summary | |
static java.lang.String |
identification
|
Constructor Summary | |
Connection(java.lang.String hostname)
Same as Connection(hostname, 22) . |
|
Connection(java.lang.String hostname,
int port)
Prepares a fresh Connection object which can then be used
to establish a connection to the specified SSH2 server. |
Method Summary | |
boolean |
authenticateWithDSA(java.lang.String user,
java.lang.String pem,
java.lang.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(java.lang.String user,
InteractiveCallback cb)
A wrapper that calls authenticateWithKeyboardInteractive()
with a null submethod list. |
boolean |
authenticateWithKeyboardInteractive(java.lang.String user,
java.lang.String[] submethods,
InteractiveCallback cb)
After a successful connect, one has to authenticate oneself. |
boolean |
authenticateWithPassword(java.lang.String user,
java.lang.String password)
After a successfull connect, one has to authenticate oneself. |
boolean |
authenticateWithPublicKey(java.lang.String user,
char[] pemPrivateKey,
java.lang.String password)
After a successful connect, one has to authenticate oneself. |
boolean |
authenticateWithPublicKey(java.lang.String user,
java.io.File pemFile,
java.lang.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 |
close()
Close the connection to the SSH2 server. |
ConnectionInfo |
connect()
Same as connect(null) . |
ConnectionInfo |
connect(ServerHostKeyVerifier verifier)
Connect to the SSH2 server and, as soon as the server has presented its host key, use the verifyServerHostKey method of the
verifier to ask for permission to proceed. |
LocalPortForwarder |
createLocalPortForwarder(int local_port,
java.lang.String host_to_connect,
int port_to_connect)
Creates a new LocalPortForwarder . |
LocalStreamForwarder |
createLocalStreamForwarder(java.lang.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 SSH2 server. |
void |
forceKeyExchange()
Force an asynchronous key re-exchange (the call does not block). |
static java.lang.String[] |
getAvailableCiphers()
Unless you know what you are doing, you will never need this. |
static java.lang.String[] |
getAvailableMACs()
Unless you know what you are doing, you will never need this. |
static java.lang.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. |
java.lang.String[] |
getRemainingAuthMethods(java.lang.String user)
After a successful connect, one has to authenticate oneself. |
boolean |
isAuthenticationComplete()
Determines if the authentication phase is complete. |
boolean |
isAuthenticationPartialSuccess()
Returns true if there was at least on failed authentication request and the last failed authentication request was marked with "partial success" by the server. |
boolean |
isAuthMethodAvailable(java.lang.String user,
java.lang.String method)
Checks if a specified authentication method is available. |
Session |
openSession()
Open a new session on this connection. |
void |
setClient2ServerCiphers(java.lang.String[] ciphers)
Unless you know what you are doing, you will never need this. |
void |
setClient2ServerMACs(java.lang.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 |
setServer2ClientCiphers(java.lang.String[] ciphers)
Unless you know what you are doing, you will never need this. |
void |
setServer2ClientMACs(java.lang.String[] macs)
Unless you know what you are doing, you will never need this. |
void |
setServerHostKeyAlgorithms(java.lang.String[] algos)
Define the set of allowed server host key algorithms to be used for the following key exchange operations. |
Methods inherited from class java.lang.Object |
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
public static final java.lang.String identification
Constructor Detail |
public Connection(java.lang.String hostname)
Connection(hostname, 22)
.
hostname
- the hostname of the SSH2 server.public Connection(java.lang.String hostname, int port)
Connection
object which can then be used
to establish a connection to the specified SSH2 server.
hostname
- the host where we later want to connect.port
- port on the server, normally 22.Method Detail |
public static java.lang.String[] getAvailableCiphers()
public static java.lang.String[] getAvailableMACs()
public static java.lang.String[] getAvailableServerHostKeyAlgorithms()
public boolean authenticateWithDSA(java.lang.String user, java.lang.String pem, java.lang.String password) throws java.io.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
.
java.io.IOException
public boolean authenticateWithKeyboardInteractive(java.lang.String user, InteractiveCallback cb) throws java.io.IOException
authenticateWithKeyboardInteractive()
with 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.
java.io.IOException
public boolean authenticateWithKeyboardInteractive(java.lang.String user, java.lang.String[] submethods, InteractiveCallback cb) throws java.io.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.
java.io.IOException
public boolean authenticateWithPassword(java.lang.String user, java.lang.String password) throws java.io.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).
user
- password
-
java.io.IOException
public boolean authenticateWithPublicKey(java.lang.String user, char[] pemPrivateKey, java.lang.String password) throws java.io.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).
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
.
java.io.IOException
public boolean authenticateWithPublicKey(java.lang.String user, java.io.File pemFile, java.lang.String password) throws java.io.IOException
authenticateWithPublicKey(String, char[], String)
.
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
.
java.io.IOException
public void close()
public ConnectionInfo connect() throws java.io.IOException
connect(null)
.
connect(null)
method.
java.io.IOException
public ConnectionInfo connect(ServerHostKeyVerifier verifier) throws java.io.IOException
verifyServerHostKey
method of the
verifier
to ask for permission to proceed. Only correctly
signed host keys will be passed to the verifier
. If
verifier
is null
, then any correctly
signed host key will be accepted - this is NOT recommended, since it
makes man-in-the-middle attackes VERY easy.
Note: The verifyServerHostKey
method will NOT be called
from the current thread, the call is being made from a
background thread (there is a background worker thread for every
established connection).
Note 2: as long as the key exchange of the underlying connection has not been completed, this call will block.
verifier
- An object that implements the
ServerHostKeyVerifier
interface.
ConnectionInfo
object containg the details of
the established connection.
java.io.IOException
- If any problem occurs, e.g., the server's host key is not
correctly signed or not accepted by the verifier
.public LocalPortForwarder createLocalPortForwarder(int local_port, java.lang.String host_to_connect, int port_to_connect) throws java.io.IOException
LocalPortForwarder
. A
LocalPortForwarder
forwards TCP/IP connections to a local
port via the secure tunnel to another host (which may or may not be
identical to the remote SSH2 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.
LocalPortForwarder
object.
java.io.IOException
public LocalStreamForwarder createLocalStreamForwarder(java.lang.String host_to_connect, int port_to_connect) throws java.io.IOException
LocalStreamForwarder
. A
LocalStreamForwarder
forwards an Input- and Outputstream
pair via the secure tunnel to another host (which may or may not be
identical to the remote SSH2 server).
LocalStreamForwarder
object.
java.io.IOException
public SCPClient createSCPClient() throws java.io.IOException
SCPClient
that can be used to copy
files from/to the SSH2 server.
Works only after one has passed successfully the authentication step. There is no limit on the number of concurrent SCP clients.
SCPClient
object.
java.io.IOException
public void forceKeyExchange() throws java.io.IOException
java.io.IOException
- In case of any failure behind the scenes.public ConnectionInfo getConnectionInfo() throws java.io.IOException
ConnectionInfo
object containing the details of
the connection. Can be called as soon as the connection has been
established (successfully connected).
ConnectionInfo
object.
java.io.IOException
- In case of any failure behind the scenes.public java.lang.String[] getRemainingAuthMethods(java.lang.String user) throws java.io.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). 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.
java.io.IOException
public 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 draft-ietf-secsh-userauth-XX.txt.
public boolean isAuthMethodAvailable(java.lang.String user, java.lang.String method) throws java.io.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.
java.io.IOException
public Session openSession() throws java.io.IOException
Session
object.
java.io.IOException
public void setClient2ServerCiphers(java.lang.String[] ciphers)
ciphers
- public void setClient2ServerMACs(java.lang.String[] macs)
macs
- public void setDHGexParameters(DHGexParameters dgp)
DHGexParameters
class.
dgp
- DHGexParameters
, non null.public void setServer2ClientCiphers(java.lang.String[] ciphers)
ciphers
- public void setServer2ClientMACs(java.lang.String[] macs)
macs
- public void setServerHostKeyAlgorithms(java.lang.String[] algos)
Unless you know what you are doing, you will never need this.
algos
- An array of allowed server host key algorithms.
SSH2 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.
|
Ganymed SSH2 for Java | ||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |