2 * Copyright (c) 2006-2011 Christian Plattner. All rights reserved.
3 * Please refer to the LICENSE.txt for licensing details.
8 import java.io.CharArrayWriter;
10 import java.io.FileReader;
11 import java.io.IOException;
12 import java.net.InetSocketAddress;
13 import java.net.SocketTimeoutException;
14 import java.security.SecureRandom;
15 import java.util.List;
16 import java.util.Vector;
18 import ch.ethz.ssh2.auth.AuthenticationManager;
19 import ch.ethz.ssh2.channel.ChannelManager;
20 import ch.ethz.ssh2.crypto.CryptoWishList;
21 import ch.ethz.ssh2.crypto.cipher.BlockCipherFactory;
22 import ch.ethz.ssh2.crypto.digest.MAC;
23 import ch.ethz.ssh2.packets.PacketIgnore;
24 import ch.ethz.ssh2.transport.KexManager;
25 import ch.ethz.ssh2.transport.TransportManager;
26 import ch.ethz.ssh2.util.TimeoutService;
27 import ch.ethz.ssh2.util.TimeoutService.TimeoutToken;
30 * A <code>Connection</code> is used to establish an encrypted TCP/IP
31 * connection to a SSH-2 server.
35 * <li>creates a {@link #Connection(String) Connection} object.</li>
36 * <li>calls the {@link #connect() connect()} method.</li>
37 * <li>calls some of the authentication methods (e.g., {@link #authenticateWithPublicKey(String, File, String) authenticateWithPublicKey()}).</li>
38 * <li>calls one or several times the {@link #openSession() openSession()} method.</li>
39 * <li>finally, one must close the connection and release resources with the {@link #close() close()} method.</li>
42 * @author Christian Plattner
43 * @version $Id: Connection.java 69 2013-08-09 06:39:56Z dkocher@sudo.ch $
46 public class Connection
49 * The identifier presented to the SSH-2 server. This is the same
50 * as the "softwareversion" defined in RFC 4253.
52 * <b>NOTE: As per the RFC, the "softwareversion" string MUST consist of printable
53 * US-ASCII characters, with the exception of whitespace characters and the minus sign (-).</b>
55 private String softwareversion = String.format("Ganymed_%s", Version.getSpecification());
57 /* Will be used to generate all random data needed for the current connection.
58 * Note: SecureRandom.nextBytes() is thread safe.
61 private SecureRandom generator;
63 private Socket precreatedSocket;
65 public Connection(Socket socket) {
66 this.precreatedSocket = socket;
67 this.hostname = socket.getInetAddress().getHostName();
68 this.port = socket.getPort();
72 * Unless you know what you are doing, you will never need this.
74 * @return The list of supported cipher algorithms by this implementation.
76 public static synchronized String[] getAvailableCiphers()
78 return BlockCipherFactory.getDefaultCipherList();
82 * Unless you know what you are doing, you will never need this.
84 * @return The list of supported MAC algorthims by this implementation.
86 public static synchronized String[] getAvailableMACs()
88 return MAC.getMacList();
92 * Unless you know what you are doing, you will never need this.
94 * @return The list of supported server host key algorthims by this implementation.
96 public static synchronized String[] getAvailableServerHostKeyAlgorithms()
98 return KexManager.getDefaultServerHostkeyAlgorithmList();
101 private AuthenticationManager am;
103 private boolean authenticated = false;
104 private ChannelManager cm;
106 private CryptoWishList cryptoWishList = new CryptoWishList();
108 private DHGexParameters dhgexpara = new DHGexParameters();
110 private final String hostname;
112 private final int port;
114 private TransportManager tm;
116 private boolean tcpNoDelay = false;
118 private ProxyData proxyData = null;
120 private List<ConnectionMonitor> connectionMonitors = new Vector<ConnectionMonitor>();
123 * Prepares a fresh <code>Connection</code> object which can then be used
124 * to establish a connection to the specified SSH-2 server.
126 * Same as {@link #Connection(String, int) Connection(hostname, 22)}.
128 * @param hostname the hostname of the SSH-2 server.
130 public Connection(String hostname)
136 * Prepares a fresh <code>Connection</code> object which can then be used
137 * to establish a connection to the specified SSH-2 server.
140 * the host where we later want to connect to.
142 * port on the server, normally 22.
144 public Connection(String hostname, int port)
146 this.hostname = hostname;
151 * Prepares a fresh <code>Connection</code> object which can then be used
152 * to establish a connection to the specified SSH-2 server.
155 * the host where we later want to connect to.
157 * port on the server, normally 22.
158 * @param softwareversion
159 * Allows you to set a custom "softwareversion" string as defined in RFC 4253.
160 * <b>NOTE: As per the RFC, the "softwareversion" string MUST consist of printable
161 * US-ASCII characters, with the exception of whitespace characters and the minus sign (-).</b>
163 public Connection(String hostname, int port, String softwareversion)
165 this.hostname = hostname;
167 this.softwareversion = softwareversion;
171 * After a successful connect, one has to authenticate oneself. This method
172 * is based on DSA (it uses DSA to sign a challenge sent by the server).
174 * If the authentication phase is complete, <code>true</code> will be
175 * returned. If the server does not accept the request (or if further
176 * authentication steps are needed), <code>false</code> is returned and
177 * one can retry either by using this or any other authentication method
178 * (use the <code>getRemainingAuthMethods</code> method to get a list of
179 * the remaining possible methods).
182 * A <code>String</code> holding the username.
184 * A <code>String</code> containing the DSA private key of the
185 * user in OpenSSH key format (PEM, you can't miss the
186 * "-----BEGIN DSA PRIVATE KEY-----" tag). The string may contain
189 * If the PEM string is 3DES encrypted ("DES-EDE3-CBC"), then you
190 * must specify the password. Otherwise, this argument will be
191 * ignored and can be set to <code>null</code>.
193 * @return whether the connection is now authenticated.
194 * @throws IOException
196 * @deprecated You should use one of the {@link #authenticateWithPublicKey(String, File, String) authenticateWithPublicKey()}
197 * methods, this method is just a wrapper for it and will
198 * disappear in future builds.
201 public synchronized boolean authenticateWithDSA(String user, String pem, String password) throws IOException
204 throw new IllegalStateException("Connection is not established!");
207 throw new IllegalStateException("Connection is already authenticated!");
210 am = new AuthenticationManager(tm);
213 cm = new ChannelManager(tm);
216 throw new IllegalArgumentException("user argument is null");
219 throw new IllegalArgumentException("pem argument is null");
221 authenticated = am.authenticatePublicKey(user, pem.toCharArray(), password, getOrCreateSecureRND());
223 return authenticated;
227 * A wrapper that calls {@link #authenticateWithKeyboardInteractive(String, String[], InteractiveCallback)
228 * authenticateWithKeyboardInteractivewith} a <code>null</code> submethod list.
231 * A <code>String</code> holding the username.
233 * An <code>InteractiveCallback</code> which will be used to
234 * determine the responses to the questions asked by the server.
235 * @return whether the connection is now authenticated.
236 * @throws IOException
238 public synchronized boolean authenticateWithKeyboardInteractive(String user, InteractiveCallback cb)
241 return authenticateWithKeyboardInteractive(user, null, cb);
245 * After a successful connect, one has to authenticate oneself. This method
246 * is based on "keyboard-interactive", specified in
247 * draft-ietf-secsh-auth-kbdinteract-XX. Basically, you have to define a
248 * callback object which will be feeded with challenges generated by the
249 * server. Answers are then sent back to the server. It is possible that the
250 * callback will be called several times during the invocation of this
251 * method (e.g., if the server replies to the callback's answer(s) with
252 * another challenge...)
254 * If the authentication phase is complete, <code>true</code> will be
255 * returned. If the server does not accept the request (or if further
256 * authentication steps are needed), <code>false</code> is returned and
257 * one can retry either by using this or any other authentication method
258 * (use the <code>getRemainingAuthMethods</code> method to get a list of
259 * the remaining possible methods).
261 * Note: some SSH servers advertise "keyboard-interactive", however, any
262 * interactive request will be denied (without having sent any challenge to
266 * A <code>String</code> holding the username.
268 * An array of submethod names, see
269 * draft-ietf-secsh-auth-kbdinteract-XX. May be <code>null</code>
270 * to indicate an empty list.
272 * An <code>InteractiveCallback</code> which will be used to
273 * determine the responses to the questions asked by the server.
275 * @return whether the connection is now authenticated.
276 * @throws IOException
278 public synchronized boolean authenticateWithKeyboardInteractive(String user, String[] submethods,
279 InteractiveCallback cb) throws IOException
282 throw new IllegalArgumentException("Callback may not ne NULL!");
285 throw new IllegalStateException("Connection is not established!");
288 throw new IllegalStateException("Connection is already authenticated!");
291 am = new AuthenticationManager(tm);
294 cm = new ChannelManager(tm);
297 throw new IllegalArgumentException("user argument is null");
299 authenticated = am.authenticateInteractive(user, submethods, cb);
301 return authenticated;
305 * After a successful connect, one has to authenticate oneself. This method
306 * sends username and password to the server.
308 * If the authentication phase is complete, <code>true</code> will be
309 * returned. If the server does not accept the request (or if further
310 * authentication steps are needed), <code>false</code> is returned and
311 * one can retry either by using this or any other authentication method
312 * (use the <code>getRemainingAuthMethods</code> method to get a list of
313 * the remaining possible methods).
315 * Note: if this method fails, then please double-check that it is actually
316 * offered by the server (use {@link #getRemainingAuthMethods(String) getRemainingAuthMethods()}.
318 * Often, password authentication is disabled, but users are not aware of it.
319 * Many servers only offer "publickey" and "keyboard-interactive". However,
320 * even though "keyboard-interactive" *feels* like password authentication
321 * (e.g., when using the putty or openssh clients) it is *not* the same mechanism.
325 * @return if the connection is now authenticated.
326 * @throws IOException
328 public synchronized boolean authenticateWithPassword(String user, String password) throws IOException
331 throw new IllegalStateException("Connection is not established!");
334 throw new IllegalStateException("Connection is already authenticated!");
337 am = new AuthenticationManager(tm);
340 cm = new ChannelManager(tm);
343 throw new IllegalArgumentException("user argument is null");
345 if (password == null)
346 throw new IllegalArgumentException("password argument is null");
348 authenticated = am.authenticatePassword(user, password);
350 return authenticated;
354 * After a successful connect, one has to authenticate oneself.
355 * This method can be used to explicitly use the special "none"
356 * authentication method (where only a username has to be specified).
358 * Note 1: The "none" method may always be tried by clients, however as by
359 * the specs, the server will not explicitly announce it. In other words,
360 * the "none" token will never show up in the list returned by
361 * {@link #getRemainingAuthMethods(String)}.
363 * Note 2: no matter which one of the authenticateWithXXX() methods
364 * you call, the library will always issue exactly one initial "none"
365 * authentication request to retrieve the initially allowed list of
366 * authentication methods by the server. Please read RFC 4252 for the
369 * If the authentication phase is complete, <code>true</code> will be
370 * returned. If further authentication steps are needed, <code>false</code>
371 * is returned and one can retry by any other authentication method
372 * (use the <code>getRemainingAuthMethods</code> method to get a list of
373 * the remaining possible methods).
376 * @return if the connection is now authenticated.
377 * @throws IOException
379 public synchronized boolean authenticateWithNone(String user) throws IOException
382 throw new IllegalStateException("Connection is not established!");
385 throw new IllegalStateException("Connection is already authenticated!");
388 am = new AuthenticationManager(tm);
391 cm = new ChannelManager(tm);
394 throw new IllegalArgumentException("user argument is null");
396 /* Trigger the sending of the PacketUserauthRequestNone packet */
397 /* (if not already done) */
399 authenticated = am.authenticateNone(user);
401 return authenticated;
405 * After a successful connect, one has to authenticate oneself.
406 * The authentication method "publickey" works by signing a challenge
407 * sent by the server. The signature is either DSA or RSA based - it
408 * just depends on the type of private key you specify, either a DSA
409 * or RSA private key in PEM format. And yes, this is may seem to be a
410 * little confusing, the method is called "publickey" in the SSH-2 protocol
411 * specification, however since we need to generate a signature, you
412 * actually have to supply a private key =).
414 * The private key contained in the PEM file may also be encrypted ("Proc-Type: 4,ENCRYPTED").
415 * The library supports DES-CBC and DES-EDE3-CBC encryption, as well
416 * as the more exotic PEM encrpytions AES-128-CBC, AES-192-CBC and AES-256-CBC.
418 * If the authentication phase is complete, <code>true</code> will be
419 * returned. If the server does not accept the request (or if further
420 * authentication steps are needed), <code>false</code> is returned and
421 * one can retry either by using this or any other authentication method
422 * (use the <code>getRemainingAuthMethods</code> method to get a list of
423 * the remaining possible methods).
425 * NOTE PUTTY USERS: Event though your key file may start with "-----BEGIN..."
426 * it is not in the expected format. You have to convert it to the OpenSSH
427 * key format by using the "puttygen" tool (can be downloaded from the Putty
428 * website). Simply load your key and then use the "Conversions/Export OpenSSH key"
429 * functionality to get a proper PEM file.
432 * A <code>String</code> holding the username.
433 * @param pemPrivateKey
434 * A <code>char[]</code> containing a DSA or RSA private key of the
435 * user in OpenSSH key format (PEM, you can't miss the
436 * "-----BEGIN DSA PRIVATE KEY-----" or "-----BEGIN RSA PRIVATE KEY-----"
437 * tag). The char array may contain linebreaks/linefeeds.
439 * If the PEM structure is encrypted ("Proc-Type: 4,ENCRYPTED") then
440 * you must specify a password. Otherwise, this argument will be ignored
441 * and can be set to <code>null</code>.
443 * @return whether the connection is now authenticated.
444 * @throws IOException
446 public synchronized boolean authenticateWithPublicKey(String user, char[] pemPrivateKey, String password)
450 throw new IllegalStateException("Connection is not established!");
453 throw new IllegalStateException("Connection is already authenticated!");
456 am = new AuthenticationManager(tm);
459 cm = new ChannelManager(tm);
462 throw new IllegalArgumentException("user argument is null");
464 if (pemPrivateKey == null)
465 throw new IllegalArgumentException("pemPrivateKey argument is null");
467 authenticated = am.authenticatePublicKey(user, pemPrivateKey, password, getOrCreateSecureRND());
469 return authenticated;
473 * A convenience wrapper function which reads in a private key (PEM format, either DSA or RSA)
474 * and then calls <code>authenticateWithPublicKey(String, char[], String)</code>.
476 * NOTE PUTTY USERS: Event though your key file may start with "-----BEGIN..."
477 * it is not in the expected format. You have to convert it to the OpenSSH
478 * key format by using the "puttygen" tool (can be downloaded from the Putty
479 * website). Simply load your key and then use the "Conversions/Export OpenSSH key"
480 * functionality to get a proper PEM file.
483 * A <code>String</code> holding the username.
485 * A <code>File</code> object pointing to a file containing a DSA or RSA
486 * private key of the user in OpenSSH key format (PEM, you can't miss the
487 * "-----BEGIN DSA PRIVATE KEY-----" or "-----BEGIN RSA PRIVATE KEY-----"
490 * If the PEM file is encrypted then you must specify the password.
491 * Otherwise, this argument will be ignored and can be set to <code>null</code>.
493 * @return whether the connection is now authenticated.
494 * @throws IOException
496 public synchronized boolean authenticateWithPublicKey(String user, File pemFile, String password)
500 throw new IllegalArgumentException("pemFile argument is null");
502 char[] buff = new char[256];
504 CharArrayWriter cw = new CharArrayWriter();
506 FileReader fr = new FileReader(pemFile);
510 int len = fr.read(buff);
513 cw.write(buff, 0, len);
518 return authenticateWithPublicKey(user, cw.toCharArray(), password);
522 * Add a {@link ConnectionMonitor} to this connection. Can be invoked at any time,
523 * but it is best to add connection monitors before invoking
524 * <code>connect()</code> to avoid glitches (e.g., you add a connection monitor after
525 * a successful connect(), but the connection has died in the mean time. Then,
526 * your connection monitor won't be notified.)
528 * You can add as many monitors as you like. If a monitor has already been added, then
529 * this method does nothing.
531 * @see ConnectionMonitor
533 * @param cmon An object implementing the {@link ConnectionMonitor} interface.
535 public synchronized void addConnectionMonitor(ConnectionMonitor cmon)
538 throw new IllegalArgumentException("cmon argument is null");
540 if (!connectionMonitors.contains(cmon))
542 connectionMonitors.add(cmon);
545 tm.setConnectionMonitors(connectionMonitors);
550 * Remove a {@link ConnectionMonitor} from this connection.
553 * @return whether the monitor could be removed
555 public synchronized boolean removeConnectionMonitor(ConnectionMonitor cmon)
558 throw new IllegalArgumentException("cmon argument is null");
560 boolean existed = connectionMonitors.remove(cmon);
563 tm.setConnectionMonitors(connectionMonitors);
569 * Close the connection to the SSH-2 server. All assigned sessions will be
570 * closed, too. Can be called at any time. Don't forget to call this once
571 * you don't need a connection anymore - otherwise the receiver thread may
574 public synchronized void close()
576 Throwable t = new Throwable("Closed due to user request.");
580 public synchronized void close(Throwable t, boolean hard)
583 cm.closeAllChannels();
587 tm.close(t, hard == false);
592 authenticated = false;
596 * Same as {@link #connect(ServerHostKeyVerifier, int, int) connect(null, 0, 0)}.
598 * @return see comments for the {@link #connect(ServerHostKeyVerifier, int, int) connect(ServerHostKeyVerifier, int, int)} method.
599 * @throws IOException
601 public synchronized ConnectionInfo connect() throws IOException
603 return connect(null, 0, 0);
607 * Same as {@link #connect(ServerHostKeyVerifier, int, int) connect(verifier, 0, 0)}.
609 * @return see comments for the {@link #connect(ServerHostKeyVerifier, int, int) connect(ServerHostKeyVerifier, int, int)} method.
610 * @throws IOException
612 public synchronized ConnectionInfo connect(ServerHostKeyVerifier verifier) throws IOException
614 return connect(verifier, 0, 0);
618 * Connect to the SSH-2 server and, as soon as the server has presented its
619 * host key, use the {@link ServerHostKeyVerifier#verifyServerHostKey(String,
620 * int, String, byte[]) ServerHostKeyVerifier.verifyServerHostKey()}
621 * method of the <code>verifier</code> to ask for permission to proceed.
622 * If <code>verifier</code> is <code>null</code>, then any host key will be
623 * accepted - this is NOT recommended, since it makes man-in-the-middle attackes
624 * VERY easy (somebody could put a proxy SSH server between you and the real server).
626 * Note: The verifier will be called before doing any crypto calculations
627 * (i.e., diffie-hellman). Therefore, if you don't like the presented host key then
628 * no CPU cycles are wasted (and the evil server has less information about us).
630 * However, it is still possible that the server presented a fake host key: the server
631 * cheated (typically a sign for a man-in-the-middle attack) and is not able to generate
632 * a signature that matches its host key. Don't worry, the library will detect such
633 * a scenario later when checking the signature (the signature cannot be checked before
634 * having completed the diffie-hellman exchange).
636 * Note 2: The {@link ServerHostKeyVerifier#verifyServerHostKey(String,
637 * int, String, byte[]) ServerHostKeyVerifier.verifyServerHostKey()} method
638 * will *NOT* be called from the current thread, the call is being made from a
639 * background thread (there is a background dispatcher thread for every
640 * established connection).
642 * Note 3: This method will block as long as the key exchange of the underlying connection
643 * has not been completed (and you have not specified any timeouts).
645 * Note 4: If you want to re-use a connection object that was successfully connected,
646 * then you must call the {@link #close()} method before invoking <code>connect()</code> again.
649 * An object that implements the
650 * {@link ServerHostKeyVerifier} interface. Pass <code>null</code>
651 * to accept any server host key - NOT recommended.
653 * @param connectTimeout
654 * Connect the underlying TCP socket to the server with the given timeout
655 * value (non-negative, in milliseconds). Zero means no timeout. If a proxy is being
656 * used (see {@link #setProxyData(ProxyData)}), then this timeout is used for the
657 * connection establishment to the proxy.
660 * Timeout for complete connection establishment (non-negative,
661 * in milliseconds). Zero means no timeout. The timeout counts from the
662 * moment you invoke the connect() method and is cancelled as soon as the
663 * first key-exchange round has finished. It is possible that
664 * the timeout event will be fired during the invocation of the
665 * <code>verifier</code> callback, but it will only have an effect after
666 * the <code>verifier</code> returns.
668 * @return A {@link ConnectionInfo} object containing the details of
669 * the established connection.
671 * @throws IOException
672 * If any problem occurs, e.g., the server's host key is not
673 * accepted by the <code>verifier</code> or there is problem during
674 * the initial crypto setup (e.g., the signature sent by the server is wrong).
676 * In case of a timeout (either connectTimeout or kexTimeout)
677 * a SocketTimeoutException is thrown.
679 * An exception may also be thrown if the connection was already successfully
680 * connected (no matter if the connection broke in the mean time) and you invoke
681 * <code>connect()</code> again without having called {@link #close()} first.
683 * If a HTTP proxy is being used and the proxy refuses the connection,
684 * then a {@link HTTPProxyException} may be thrown, which
685 * contains the details returned by the proxy. If the proxy is buggy and does
686 * not return a proper HTTP response, then a normal IOException is thrown instead.
688 public synchronized ConnectionInfo connect(ServerHostKeyVerifier verifier, int connectTimeout, int kexTimeout)
691 final class TimeoutState
693 boolean isCancelled = false;
694 boolean timeoutSocketClosed = false;
698 throw new IOException("Connection to " + hostname + " is already in connected state!");
700 if (connectTimeout < 0)
701 throw new IllegalArgumentException("connectTimeout must be non-negative!");
704 throw new IllegalArgumentException("kexTimeout must be non-negative!");
706 final TimeoutState state = new TimeoutState();
708 tm = new TransportManager();
709 tm.setSoTimeout(connectTimeout);
710 tm.setConnectionMonitors(connectionMonitors);
712 /* Make sure that the runnable below will observe the new value of "tm"
713 * and "state" (the runnable will be executed in a different thread, which
714 * may be already running, that is why we need a memory barrier here).
715 * See also the comment in Channel.java if you
716 * are interested in the details.
718 * OKOK, this is paranoid since adding the runnable to the todo list
719 * of the TimeoutService will ensure that all writes have been flushed
720 * before the Runnable reads anything
721 * (there is a synchronized block in TimeoutService.addTimeoutHandler).
726 /* We could actually synchronize on anything. */
731 TimeoutToken token = null;
735 final Runnable timeoutHandler = new Runnable()
741 if (state.isCancelled)
743 state.timeoutSocketClosed = true;
744 tm.close(new SocketTimeoutException("The connect timeout expired"), false);
749 long timeoutHorizont = System.currentTimeMillis() + kexTimeout;
751 token = TimeoutService.addTimeoutHandler(timeoutHorizont, timeoutHandler);
757 if (precreatedSocket != null) {
758 tm.clientInit(precreatedSocket, softwareversion, cryptoWishList, verifier, dhgexpara,
759 getOrCreateSecureRND());
761 tm.clientInit(hostname, port, softwareversion, cryptoWishList, verifier, dhgexpara, connectTimeout,
762 getOrCreateSecureRND(), proxyData);
765 catch (SocketTimeoutException se)
767 throw (SocketTimeoutException) new SocketTimeoutException(
768 "The connect() operation on the socket timed out.").initCause(se);
771 tm.setTcpNoDelay(tcpNoDelay);
773 /* Wait until first KEX has finished */
775 ConnectionInfo ci = tm.getConnectionInfo(1);
777 /* Now try to cancel the timeout, if needed */
781 TimeoutService.cancelTimeoutHandler(token);
783 /* Were we too late? */
787 if (state.timeoutSocketClosed)
788 throw new IOException("This exception will be replaced by the one below =)");
789 /* Just in case the "cancelTimeoutHandler" invocation came just a little bit
790 * too late but the handler did not enter the semaphore yet - we can
793 state.isCancelled = true;
799 catch (SocketTimeoutException ste)
803 catch (IOException e1)
805 /* This will also invoke any registered connection monitors */
806 close(new Throwable("There was a problem during connect."), false);
810 /* Show a clean exception, not something like "the socket is closed!?!" */
811 if (state.timeoutSocketClosed)
812 throw new SocketTimeoutException("The kexTimeout (" + kexTimeout + " ms) expired.");
815 /* Do not wrap a HTTPProxyException */
816 if (e1 instanceof HTTPProxyException)
819 throw (IOException) new IOException("There was a problem while connecting to " + hostname + ":" + port)
825 * Creates a new {@link LocalPortForwarder}.
826 * A <code>LocalPortForwarder</code> forwards TCP/IP connections that arrive at a local
827 * port via the secure tunnel to another host (which may or may not be
828 * identical to the remote SSH-2 server).
830 * This method must only be called after one has passed successfully the authentication step.
831 * There is no limit on the number of concurrent forwardings.
833 * @param local_port the local port the LocalPortForwarder shall bind to.
834 * @param host_to_connect target address (IP or hostname)
835 * @param port_to_connect target port
836 * @return A {@link LocalPortForwarder} object.
837 * @throws IOException
839 public synchronized LocalPortForwarder createLocalPortForwarder(int local_port, String host_to_connect,
840 int port_to_connect) throws IOException
843 throw new IllegalStateException("Cannot forward ports, you need to establish a connection first.");
846 throw new IllegalStateException("Cannot forward ports, connection is not authenticated.");
848 return new LocalPortForwarder(cm, local_port, host_to_connect, port_to_connect);
852 * Creates a new {@link LocalPortForwarder}.
853 * A <code>LocalPortForwarder</code> forwards TCP/IP connections that arrive at a local
854 * port via the secure tunnel to another host (which may or may not be
855 * identical to the remote SSH-2 server).
857 * This method must only be called after one has passed successfully the authentication step.
858 * There is no limit on the number of concurrent forwardings.
860 * @param addr specifies the InetSocketAddress where the local socket shall be bound to.
861 * @param host_to_connect target address (IP or hostname)
862 * @param port_to_connect target port
863 * @return A {@link LocalPortForwarder} object.
864 * @throws IOException
866 public synchronized LocalPortForwarder createLocalPortForwarder(InetSocketAddress addr, String host_to_connect,
867 int port_to_connect) throws IOException
870 throw new IllegalStateException("Cannot forward ports, you need to establish a connection first.");
873 throw new IllegalStateException("Cannot forward ports, connection is not authenticated.");
875 return new LocalPortForwarder(cm, addr, host_to_connect, port_to_connect);
879 * Creates a new {@link LocalStreamForwarder}.
880 * A <code>LocalStreamForwarder</code> manages an Input/Outputstream pair
881 * that is being forwarded via the secure tunnel into a TCP/IP connection to another host
882 * (which may or may not be identical to the remote SSH-2 server).
884 * @param host_to_connect
885 * @param port_to_connect
886 * @return A {@link LocalStreamForwarder} object.
887 * @throws IOException
889 public synchronized LocalStreamForwarder createLocalStreamForwarder(String host_to_connect, int port_to_connect)
893 throw new IllegalStateException("Cannot forward, you need to establish a connection first.");
896 throw new IllegalStateException("Cannot forward, connection is not authenticated.");
898 return new LocalStreamForwarder(cm, host_to_connect, port_to_connect);
902 * Create a very basic {@link SCPClient} that can be used to copy
903 * files from/to the SSH-2 server.
905 * Works only after one has passed successfully the authentication step.
906 * There is no limit on the number of concurrent SCP clients.
908 * Note: This factory method will probably disappear in the future.
910 * @return A {@link SCPClient} object.
911 * @throws IOException
913 public synchronized SCPClient createSCPClient() throws IOException
916 throw new IllegalStateException("Cannot create SCP client, you need to establish a connection first.");
919 throw new IllegalStateException("Cannot create SCP client, connection is not authenticated.");
921 return new SCPClient(this);
925 * Force an asynchronous key re-exchange (the call does not block). The
926 * latest values set for MAC, Cipher and DH group exchange parameters will
927 * be used. If a key exchange is currently in progress, then this method has
928 * the only effect that the so far specified parameters will be used for the
929 * next (server driven) key exchange.
931 * Note: This implementation will never start a key exchange (other than the initial one)
932 * unless you or the SSH-2 server ask for it.
934 * @throws IOException
935 * In case of any failure behind the scenes.
937 public synchronized void forceKeyExchange() throws IOException
940 throw new IllegalStateException("You need to establish a connection first.");
942 tm.forceKeyExchange(cryptoWishList, dhgexpara, null, null);
946 * Returns the hostname that was passed to the constructor.
948 * @return the hostname
950 public synchronized String getHostname()
956 * Returns the port that was passed to the constructor.
958 * @return the TCP port
960 public synchronized int getPort()
966 * Returns a {@link ConnectionInfo} object containing the details of
967 * the connection. Can be called as soon as the connection has been
968 * established (successfully connected).
970 * @return A {@link ConnectionInfo} object.
971 * @throws IOException
972 * In case of any failure behind the scenes.
974 public synchronized ConnectionInfo getConnectionInfo() throws IOException
977 throw new IllegalStateException(
978 "Cannot get details of connection, you need to establish a connection first.");
979 return tm.getConnectionInfo(1);
983 * After a successful connect, one has to authenticate oneself. This method
984 * can be used to tell which authentication methods are supported by the
985 * server at a certain stage of the authentication process (for the given
988 * Note 1: the username will only be used if no authentication step was done
989 * so far (it will be used to ask the server for a list of possible
990 * authentication methods by sending the initial "none" request). Otherwise,
991 * this method ignores the user name and returns a cached method list
992 * (which is based on the information contained in the last negative server response).
994 * Note 2: the server may return method names that are not supported by this
997 * After a successful authentication, this method must not be called
1001 * A <code>String</code> holding the username.
1003 * @return a (possibly emtpy) array holding authentication method names.
1004 * @throws IOException
1006 public synchronized String[] getRemainingAuthMethods(String user) throws IOException
1009 throw new IllegalArgumentException("user argument may not be NULL!");
1012 throw new IllegalStateException("Connection is not established!");
1015 throw new IllegalStateException("Connection is already authenticated!");
1018 am = new AuthenticationManager(tm);
1021 cm = new ChannelManager(tm);
1023 return am.getRemainingMethods(user);
1027 * Determines if the authentication phase is complete. Can be called at any
1030 * @return <code>true</code> if no further authentication steps are
1033 public synchronized boolean isAuthenticationComplete()
1035 return authenticated;
1039 * Returns true if there was at least one failed authentication request and
1040 * the last failed authentication request was marked with "partial success"
1041 * by the server. This is only needed in the rare case of SSH-2 server setups
1042 * that cannot be satisfied with a single successful authentication request
1043 * (i.e., multiple authentication steps are needed.)
1045 * If you are interested in the details, then have a look at RFC4252.
1047 * @return if the there was a failed authentication step and the last one
1048 * was marked as a "partial success".
1050 public synchronized boolean isAuthenticationPartialSuccess()
1055 return am.getPartialSuccess();
1059 * Checks if a specified authentication method is available. This method is
1060 * actually just a wrapper for {@link #getRemainingAuthMethods(String)
1061 * getRemainingAuthMethods()}.
1064 * A <code>String</code> holding the username.
1066 * An authentication method name (e.g., "publickey", "password",
1067 * "keyboard-interactive") as specified by the SSH-2 standard.
1068 * @return if the specified authentication method is currently available.
1069 * @throws IOException
1071 public synchronized boolean isAuthMethodAvailable(String user, String method) throws IOException
1074 throw new IllegalArgumentException("method argument may not be NULL!");
1076 String methods[] = getRemainingAuthMethods(user);
1078 for (int i = 0; i < methods.length; i++)
1080 if (methods[i].compareTo(method) == 0)
1087 private SecureRandom getOrCreateSecureRND()
1089 if (generator == null)
1090 generator = new SecureRandom();
1096 * Open a new {@link Session} on this connection. Works only after one has passed
1097 * successfully the authentication step. There is no limit on the number of
1098 * concurrent sessions.
1100 * @return A {@link Session} object.
1101 * @throws IOException
1103 public synchronized Session openSession() throws IOException
1106 throw new IllegalStateException("Cannot open session, you need to establish a connection first.");
1109 throw new IllegalStateException("Cannot open session, connection is not authenticated.");
1111 return new Session(cm, getOrCreateSecureRND());
1115 * Send an SSH_MSG_IGNORE packet. This method will generate a random data attribute
1116 * (length between 0 (invlusive) and 16 (exclusive) bytes, contents are random bytes).
1118 * This method must only be called once the connection is established.
1120 * @throws IOException
1122 public synchronized void sendIgnorePacket() throws IOException
1124 SecureRandom rnd = getOrCreateSecureRND();
1126 byte[] data = new byte[rnd.nextInt(16)];
1127 rnd.nextBytes(data);
1129 sendIgnorePacket(data);
1133 * Send an SSH_MSG_IGNORE packet with the given data attribute.
1135 * This method must only be called once the connection is established.
1137 * @throws IOException
1139 public synchronized void sendIgnorePacket(byte[] data) throws IOException
1142 throw new IllegalArgumentException("data argument must not be null.");
1145 throw new IllegalStateException(
1146 "Cannot send SSH_MSG_IGNORE packet, you need to establish a connection first.");
1148 PacketIgnore pi = new PacketIgnore();
1151 tm.sendMessage(pi.getPayload());
1155 * Removes duplicates from a String array, keeps only first occurence
1156 * of each element. Does not destroy order of elements; can handle nulls.
1157 * Uses a very efficient O(N^2) algorithm =)
1159 * @param list a String array.
1160 * @return a cleaned String array.
1162 private String[] removeDuplicates(String[] list)
1164 if ((list == null) || (list.length < 2))
1167 String[] list2 = new String[list.length];
1171 for (int i = 0; i < list.length; i++)
1173 boolean duplicate = false;
1175 String element = list[i];
1177 for (int j = 0; j < count; j++)
1179 if (((element == null) && (list2[j] == null)) || ((element != null) && (element.equals(list2[j]))))
1189 list2[count++] = list[i];
1192 if (count == list2.length)
1195 String[] tmp = new String[count];
1196 System.arraycopy(list2, 0, tmp, 0, count);
1202 * Unless you know what you are doing, you will never need this.
1206 public synchronized void setClient2ServerCiphers(String[] ciphers)
1208 if ((ciphers == null) || (ciphers.length == 0))
1209 throw new IllegalArgumentException();
1210 ciphers = removeDuplicates(ciphers);
1211 BlockCipherFactory.checkCipherList(ciphers);
1212 cryptoWishList.c2s_enc_algos = ciphers;
1216 * Unless you know what you are doing, you will never need this.
1220 public synchronized void setClient2ServerMACs(String[] macs)
1222 if ((macs == null) || (macs.length == 0))
1223 throw new IllegalArgumentException();
1224 macs = removeDuplicates(macs);
1225 MAC.checkMacList(macs);
1226 cryptoWishList.c2s_mac_algos = macs;
1230 * Sets the parameters for the diffie-hellman group exchange. Unless you
1231 * know what you are doing, you will never need this. Default values are
1232 * defined in the {@link DHGexParameters} class.
1234 * @param dgp {@link DHGexParameters}, non null.
1237 public synchronized void setDHGexParameters(DHGexParameters dgp)
1240 throw new IllegalArgumentException();
1246 * Unless you know what you are doing, you will never need this.
1250 public synchronized void setServer2ClientCiphers(String[] ciphers)
1252 if ((ciphers == null) || (ciphers.length == 0))
1253 throw new IllegalArgumentException();
1254 ciphers = removeDuplicates(ciphers);
1255 BlockCipherFactory.checkCipherList(ciphers);
1256 cryptoWishList.s2c_enc_algos = ciphers;
1260 * Unless you know what you are doing, you will never need this.
1264 public synchronized void setServer2ClientMACs(String[] macs)
1266 if ((macs == null) || (macs.length == 0))
1267 throw new IllegalArgumentException();
1269 macs = removeDuplicates(macs);
1270 MAC.checkMacList(macs);
1271 cryptoWishList.s2c_mac_algos = macs;
1275 * Define the set of allowed server host key algorithms to be used for
1276 * the following key exchange operations.
1278 * Unless you know what you are doing, you will never need this.
1280 * @param algos An array of allowed server host key algorithms.
1281 * SSH-2 defines <code>ssh-dss</code> and <code>ssh-rsa</code>.
1282 * The entries of the array must be ordered after preference, i.e.,
1283 * the entry at index 0 is the most preferred one. You must specify
1284 * at least one entry.
1286 public synchronized void setServerHostKeyAlgorithms(String[] algos)
1288 if ((algos == null) || (algos.length == 0))
1289 throw new IllegalArgumentException();
1291 algos = removeDuplicates(algos);
1292 KexManager.checkServerHostkeyAlgorithmsList(algos);
1293 cryptoWishList.serverHostKeyAlgorithms = algos;
1297 * Enable/disable TCP_NODELAY (disable/enable Nagle's algorithm) on the underlying socket.
1299 * Can be called at any time. If the connection has not yet been established
1300 * then the passed value will be stored and set after the socket has been set up.
1301 * The default value that will be used is <code>false</code>.
1303 * @param enable the argument passed to the <code>Socket.setTCPNoDelay()</code> method.
1304 * @throws IOException
1306 public synchronized void setTCPNoDelay(boolean enable) throws IOException
1308 tcpNoDelay = enable;
1311 tm.setTcpNoDelay(enable);
1315 * Used to tell the library that the connection shall be established through a proxy server.
1316 * It only makes sense to call this method before calling the {@link #connect() connect()}
1319 * At the moment, only HTTP proxies are supported.
1321 * Note: This method can be called any number of times. The {@link #connect() connect()}
1322 * method will use the value set in the last preceding invocation of this method.
1324 * @see HTTPProxyData
1326 * @param proxyData Connection information about the proxy. If <code>null</code>, then
1327 * no proxy will be used (non surprisingly, this is also the default).
1329 public synchronized void setProxyData(ProxyData proxyData)
1331 this.proxyData = proxyData;
1335 * Request a remote port forwarding.
1336 * If successful, then forwarded connections will be redirected to the given target address.
1337 * You can cancle a requested remote port forwarding by calling
1338 * {@link #cancelRemotePortForwarding(int) cancelRemotePortForwarding()}.
1340 * A call of this method will block until the peer either agreed or disagreed to your request-
1342 * Note 1: this method typically fails if you
1344 * <li>pass a port number for which the used remote user has not enough permissions (i.e., port
1346 * <li>or pass a port number that is already in use on the remote server</li>
1347 * <li>or if remote port forwarding is disabled on the server.</li>
1350 * Note 2: (from the openssh man page): By default, the listening socket on the server will be
1351 * bound to the loopback interface only. This may be overriden by specifying a bind address.
1352 * Specifying a remote bind address will only succeed if the server's <b>GatewayPorts</b> option
1353 * is enabled (see sshd_config(5)).
1355 * @param bindAddress address to bind to on the server:
1357 * <li>"" means that connections are to be accepted on all protocol families
1358 * supported by the SSH implementation</li>
1359 * <li>"0.0.0.0" means to listen on all IPv4 addresses</li>
1360 * <li>"::" means to listen on all IPv6 addresses</li>
1361 * <li>"localhost" means to listen on all protocol families supported by the SSH
1362 * implementation on loopback addresses only, [RFC3330] and RFC3513]</li>
1363 * <li>"127.0.0.1" and "::1" indicate listening on the loopback interfaces for
1364 * IPv4 and IPv6 respectively</li>
1366 * @param bindPort port number to bind on the server (must be > 0)
1367 * @param targetAddress the target address (IP or hostname)
1368 * @param targetPort the target port
1369 * @throws IOException
1371 public synchronized void requestRemotePortForwarding(String bindAddress, int bindPort, String targetAddress,
1372 int targetPort) throws IOException
1375 throw new IllegalStateException("You need to establish a connection first.");
1378 throw new IllegalStateException("The connection is not authenticated.");
1380 if ((bindAddress == null) || (targetAddress == null) || (bindPort <= 0) || (targetPort <= 0))
1381 throw new IllegalArgumentException();
1383 cm.requestGlobalForward(bindAddress, bindPort, targetAddress, targetPort);
1387 * Cancel an earlier requested remote port forwarding.
1388 * Currently active forwardings will not be affected (e.g., disrupted).
1389 * Note that further connection forwarding requests may be received until
1390 * this method has returned.
1392 * @param bindPort the allocated port number on the server
1393 * @throws IOException if the remote side refuses the cancel request or another low
1394 * level error occurs (e.g., the underlying connection is closed)
1396 public synchronized void cancelRemotePortForwarding(int bindPort) throws IOException
1399 throw new IllegalStateException("You need to establish a connection first.");
1402 throw new IllegalStateException("The connection is not authenticated.");
1404 cm.requestCancelGlobalForward(bindPort);
1408 * Provide your own instance of SecureRandom. Can be used, e.g., if you
1409 * want to seed the used SecureRandom generator manually.
1411 * The SecureRandom instance is used during key exchanges, public key authentication,
1412 * x11 cookie generation and the like.
1414 * @param rnd a SecureRandom instance
1416 public synchronized void setSecureRandom(SecureRandom rnd)
1419 throw new IllegalArgumentException();
1421 this.generator = rnd;