Mercurial > 510Connectbot

comparison app/src/main/java/ch/ethz/ssh2/Connection.java @ 438:d29cce60f393

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
migrate from Eclipse to Android Studio
author Carl Byington <carl@five-ten-sg.com>
date Thu, 03 Dec 2015 11:23:55 -0800
parents src/ch/ethz/ssh2/Connection.java@2768eb029d73
children 7953570e5210
comparison
equal deleted inserted replaced
437:208b31032318 438:d29cce60f393
1 /*
2 * Copyright (c) 2006-2011 Christian Plattner. All rights reserved.
3 * Please refer to the LICENSE.txt for licensing details.
4 */
5
6 package ch.ethz.ssh2;
7
8 import java.io.CharArrayWriter;
9 import java.io.File;
10 import java.io.FileReader;
11 import java.io.IOException;
12 import java.net.InetSocketAddress;
13 import java.net.Socket;
14 import java.net.SocketTimeoutException;
15 import java.security.KeyPair;
16 import java.util.ArrayList;
17 import java.util.List;
18 import java.util.Set;
19
20 import ch.ethz.ssh2.auth.AgentProxy;
21 import ch.ethz.ssh2.auth.AuthenticationManager;
22 import ch.ethz.ssh2.channel.ChannelManager;
23 import ch.ethz.ssh2.compression.CompressionFactory;
24 import ch.ethz.ssh2.crypto.CryptoWishList;
25 import ch.ethz.ssh2.crypto.SecureRandomFix;
26 import ch.ethz.ssh2.crypto.cipher.BlockCipherFactory;
27 import ch.ethz.ssh2.crypto.digest.MAC;
28 import ch.ethz.ssh2.log.Logger;
29 import ch.ethz.ssh2.packets.PacketIgnore;
30 import ch.ethz.ssh2.transport.ClientTransportManager;
31 import ch.ethz.ssh2.transport.HTTPProxyClientTransportManager;
32 import ch.ethz.ssh2.transport.KexManager;
33 import ch.ethz.ssh2.util.TimeoutService.TimeoutToken;
34 import ch.ethz.ssh2.util.TimeoutService;
35
36 /**
37 * A <code>Connection</code> is used to establish an encrypted TCP/IP
38 * connection to a SSH-2 server.
39 * <p/>
40 * Typically, one
41 * <ol>
42 * <li>creates a {@link #Connection(String) Connection} object.</li>
43 * <li>calls the {@link #connect() connect()} method.</li>
44 * <li>calls some of the authentication methods (e.g., {@link #authenticateWithPublicKey(String, File, String) authenticateWithPublicKey()}).</li>
45 * <li>calls one or several times the {@link #openSession() openSession()} method.</li>
46 * <li>finally, one must close the connection and release resources with the {@link #close() close()} method.</li>
47 * </ol>
48 *
49 * @author Christian Plattner
50 * @version $Id: Connection.java 160 2014-05-01 14:30:26Z dkocher@sudo.ch $
51 */
52
53 public class Connection {
54 protected static final Logger log = Logger.getLogger(Connection.class);
55
56 /**
57 * The identifier presented to the SSH-2 server. This is the same
58 * as the "softwareversion" defined in RFC 4253.
59 * <p/>
60 * <b>NOTE: As per the RFC, the "softwareversion" string MUST consist of printable
61 * US-ASCII characters, with the exception of whitespace characters and the minus sign (-).</b>
62 */
63 private String softwareversion
64 = String.format("Ganymed_%s", Version.getSpecification());
65
66 /* Will be used to generate all random data needed for the current connection.
67 * Note: SecureRandom.nextBytes() is thread safe.
68 */
69
70 private SecureRandomFix generator;
71
72 /**
73 * Unless you know what you are doing, you will never need this.
74 *
75 * @return The list of supported cipher algorithms by this implementation.
76 */
77
78 public static synchronized String[] getAvailableCiphers() {
79 return BlockCipherFactory.getDefaultCipherList();
80 }
81
82 /**
83 * Unless you know what you are doing, you will never need this.
84 *
85 * @return The list of supported MAC algorthims by this implementation.
86 */
87
88 public static synchronized String[] getAvailableMACs() {
89 return MAC.getMacList();
90 }
91
92 /**
93 * Unless you know what you are doing, you will never need this.
94 *
95 * @return The list of supported server host key algorthims by this implementation.
96 */
97
98 public static synchronized String[] getAvailableServerHostKeyAlgorithms() {
99 return KexManager.getDefaultServerHostkeyAlgorithmList();
100 }
101
102 private AuthenticationManager am;
103
104 private boolean authenticated;
105 private ChannelManager cm;
106
107 private CryptoWishList cryptoWishList
108 = new CryptoWishList();
109
110 private DHGexParameters dhgexpara
111 = new DHGexParameters();
112
113 private final String hostname;
114
115 private final int port;
116
117 private ClientTransportManager tm;
118
119 private boolean tcpNoDelay = false;
120
121 private HTTPProxyData proxy;
122
123 private List<ConnectionMonitor> connectionMonitors
124 = new ArrayList<ConnectionMonitor>();
125
126 /**
127 * Prepares a fresh <code>Connection</code> object which can then be used
128 * to establish a connection to the specified SSH-2 server.
129 * <p/>
130 * Same as {@link #Connection(String, int) Connection(hostname, 22)}.
131 *
132 * @param hostname the hostname of the SSH-2 server.
133 */
134 public Connection(String hostname) {
135 this(hostname, 22);
136 }
137
138 /**
139 * Prepares a fresh <code>Connection</code> object which can then be used
140 * to establish a connection to the specified SSH-2 server.
141 *
142 * @param hostname the host where we later want to connect to.
143 * @param port port on the server, normally 22.
144 */
145 public Connection(String hostname, int port) {
146 this.hostname = hostname;
147 this.port = port;
148 }
149
150 /**
151 * Prepares a fresh <code>Connection</code> object which can then be used
152 * to establish a connection to the specified SSH-2 server.
153 *
154 * @param hostname the host where we later want to connect to.
155 * @param port port on the server, normally 22.
156 * @param softwareversion Allows you to set a custom "softwareversion" string as defined in RFC 4253.
157 * <b>NOTE: As per the RFC, the "softwareversion" string MUST consist of printable
158 * US-ASCII characters, with the exception of whitespace characters and the minus sign (-).</b>
159 */
160 public Connection(String hostname, int port, String softwareversion) {
161 this.hostname = hostname;
162 this.port = port;
163 this.softwareversion = softwareversion;
164 }
165
166 public Connection(String hostname, int port, final HTTPProxyData proxy) {
167 this.hostname = hostname;
168 this.port = port;
169 this.proxy = proxy;
170 }
171
172 public Connection(String hostname, int port, String softwareversion, final HTTPProxyData proxy) {
173 this.hostname = hostname;
174 this.port = port;
175 this.softwareversion = softwareversion;
176 this.proxy = proxy;
177 }
178
179 /**
180 * After a successful connect, one has to authenticate oneself. This method
181 * is based on DSA (it uses DSA to sign a challenge sent by the server).
182 * <p/>
183 * If the authentication phase is complete, <code>true</code> will be
184 * returned. If the server does not accept the request (or if further
185 * authentication steps are needed), <code>false</code> is returned and
186 * one can retry either by using this or any other authentication method
187 * (use the <code>getRemainingAuthMethods</code> method to get a list of
188 * the remaining possible methods).
189 *
190 * @param user A <code>String</code> holding the username.
191 * @param pem A <code>String</code> containing the DSA private key of the
192 * user in OpenSSH key format (PEM, you can't miss the
193 * "-----BEGIN DSA PRIVATE KEY-----" tag). The string may contain
194 * linefeeds.
195 * @param password If the PEM string is 3DES encrypted ("DES-EDE3-CBC"), then you
196 * must specify the password. Otherwise, this argument will be
197 * ignored and can be set to <code>null</code>.
198 * @return whether the connection is now authenticated.
199 * @throws IOException
200 * @deprecated You should use one of the {@link #authenticateWithPublicKey(String, File, String) authenticateWithPublicKey()}
201 * methods, this method is just a wrapper for it and will
202 * disappear in future builds.
203 */
204 @Deprecated
205
206 public synchronized boolean authenticateWithDSA(String user, String pem, String password) throws IOException {
207 if (tm == null) {
208 throw new IllegalStateException("Connection is not established!");
209 }
210
211 if (authenticated) {
212 throw new IllegalStateException("Connection is already authenticated!");
213 }
214
215 if (am == null) {
216 am = new AuthenticationManager(tm);
217 }
218
219 if (cm == null) {
220 cm = new ChannelManager(tm);
221 }
222
223 if (user == null) {
224 throw new IllegalArgumentException("user argument is null");
225 }
226
227 if (pem == null) {
228 throw new IllegalArgumentException("pem argument is null");
229 }
230
231 authenticated = am.authenticatePublicKey(user, pem.toCharArray(), password, getOrCreateSecureRND());
232 return authenticated;
233 }
234
235 /**
236 * A wrapper that calls {@link #authenticateWithKeyboardInteractive(String, String[], InteractiveCallback)
237 * authenticateWithKeyboardInteractivewith} a <code>null</code> submethod list.
238 *
239 * @param user A <code>String</code> holding the username.
240 * @param cb An <code>InteractiveCallback</code> which will be used to
241 * determine the responses to the questions asked by the server.
242 * @return whether the connection is now authenticated.
243 * @throws IOException
244 */
245
246 public synchronized boolean authenticateWithKeyboardInteractive(String user, InteractiveCallback cb)
247 throws IOException {
248 return authenticateWithKeyboardInteractive(user, null, cb);
249 }
250
251 /**
252 * After a successful connect, one has to authenticate oneself. This method
253 * is based on "keyboard-interactive", specified in
254 * draft-ietf-secsh-auth-kbdinteract-XX. Basically, you have to define a
255 * callback object which will be feeded with challenges generated by the
256 * server. Answers are then sent back to the server. It is possible that the
257 * callback will be called several times during the invocation of this
258 * method (e.g., if the server replies to the callback's answer(s) with
259 * another challenge...)
260 * <p/>
261 * If the authentication phase is complete, <code>true</code> will be
262 * returned. If the server does not accept the request (or if further
263 * authentication steps are needed), <code>false</code> is returned and
264 * one can retry either by using this or any other authentication method
265 * (use the <code>getRemainingAuthMethods</code> method to get a list of
266 * the remaining possible methods).
267 * <p/>
268 * Note: some SSH servers advertise "keyboard-interactive", however, any
269 * interactive request will be denied (without having sent any challenge to
270 * the client).
271 *
272 * @param user A <code>String</code> holding the username.
273 * @param submethods An array of submethod names, see
274 * draft-ietf-secsh-auth-kbdinteract-XX. May be <code>null</code>
275 * to indicate an empty list.
276 * @param cb An <code>InteractiveCallback</code> which will be used to
277 * determine the responses to the questions asked by the server.
278 * @return whether the connection is now authenticated.
279 * @throws IOException
280 */
281
282 public synchronized boolean authenticateWithKeyboardInteractive(String user, String[] submethods,
283 InteractiveCallback cb) throws IOException {
284 if (cb == null) {
285 throw new IllegalArgumentException("Callback may not ne NULL!");
286 }
287
288 if (tm == null) {
289 throw new IllegalStateException("Connection is not established!");
290 }
291
292 if (authenticated) {
293 throw new IllegalStateException("Connection is already authenticated!");
294 }
295
296 if (am == null) {
297 am = new AuthenticationManager(tm);
298 }
299
300 if (cm == null) {
301 cm = new ChannelManager(tm);
302 }
303
304 if (user == null) {
305 throw new IllegalArgumentException("user argument is null");
306 }
307
308 authenticated = am.authenticateInteractive(user, submethods, cb);
309 return authenticated;
310 }
311
312 public synchronized boolean authenticateWithAgent(String user, AgentProxy proxy) throws IOException {
313 if (tm == null) {
314 throw new IllegalStateException("Connection is not established!");
315 }
316
317 if (authenticated) {
318 throw new IllegalStateException("Connection is already authenticated!");
319 }
320
321 if (am == null) {
322 am = new AuthenticationManager(tm);
323 }
324
325 if (cm == null) {
326 cm = new ChannelManager(tm);
327 }
328
329 if (user == null) {
330 throw new IllegalArgumentException("user argument is null");
331 }
332
333 authenticated = am.authenticatePublicKey(user, proxy);
334 return authenticated;
335 }
336
337 /**
338 * After a successful connect, one has to authenticate oneself. This method
339 * sends username and password to the server.
340 * <p/>
341 * If the authentication phase is complete, <code>true</code> will be
342 * returned. If the server does not accept the request (or if further
343 * authentication steps are needed), <code>false</code> is returned and
344 * one can retry either by using this or any other authentication method
345 * (use the <code>getRemainingAuthMethods</code> method to get a list of
346 * the remaining possible methods).
347 * <p/>
348 * Note: if this method fails, then please double-check that it is actually
349 * offered by the server (use {@link #getRemainingAuthMethods(String) getRemainingAuthMethods()}.
350 * <p/>
351 * Often, password authentication is disabled, but users are not aware of it.
352 * Many servers only offer "publickey" and "keyboard-interactive". However,
353 * even though "keyboard-interactive" *feels* like password authentication
354 * (e.g., when using the putty or openssh clients) it is *not* the same mechanism.
355 *
356 * @param user
357 * @param password
358 * @return if the connection is now authenticated.
359 * @throws IOException
360 */
361
362 public synchronized boolean authenticateWithPassword(String user, String password) throws IOException {
363 if (tm == null) {
364 throw new IllegalStateException("Connection is not established!");
365 }
366
367 if (authenticated) {
368 throw new IllegalStateException("Connection is already authenticated!");
369 }
370
371 if (am == null) {
372 am = new AuthenticationManager(tm);
373 }
374
375 if (cm == null) {
376 cm = new ChannelManager(tm);
377 }
378
379 if (user == null) {
380 throw new IllegalArgumentException("user argument is null");
381 }
382
383 if (password == null) {
384 throw new IllegalArgumentException("password argument is null");
385 }
386
387 authenticated = am.authenticatePassword(user, password);
388 return authenticated;
389 }
390
391 /**
392 * After a successful connect, one has to authenticate oneself.
393 * This method can be used to explicitly use the special "none"
394 * authentication method (where only a username has to be specified).
395 * <p/>
396 * Note 1: The "none" method may always be tried by clients, however as by
397 * the specs, the server will not explicitly announce it. In other words,
398 * the "none" token will never show up in the list returned by
399 * {@link #getRemainingAuthMethods(String)}.
400 * <p/>
401 * Note 2: no matter which one of the authenticateWithXXX() methods
402 * you call, the library will always issue exactly one initial "none"
403 * authentication request to retrieve the initially allowed list of
404 * authentication methods by the server. Please read RFC 4252 for the
405 * details.
406 * <p/>
407 * If the authentication phase is complete, <code>true</code> will be
408 * returned. If further authentication steps are needed, <code>false</code>
409 * is returned and one can retry by any other authentication method
410 * (use the <code>getRemainingAuthMethods</code> method to get a list of
411 * the remaining possible methods).
412 *
413 * @param user
414 * @return if the connection is now authenticated.
415 * @throws IOException
416 */
417
418 public synchronized boolean authenticateWithNone(String user) throws IOException {
419 if (tm == null) {
420 throw new IllegalStateException("Connection is not established!");
421 }
422
423 if (authenticated) {
424 throw new IllegalStateException("Connection is already authenticated!");
425 }
426
427 if (am == null) {
428 am = new AuthenticationManager(tm);
429 }
430
431 if (cm == null) {
432 cm = new ChannelManager(tm);
433 }
434
435 if (user == null) {
436 throw new IllegalArgumentException("user argument is null");
437 }
438
439 /* Trigger the sending of the PacketUserauthRequestNone packet */
440 /* (if not already done) */
441 authenticated = am.authenticateNone(user);
442 return authenticated;
443 }
444
445 /**
446 * After a successful connect, one has to authenticate oneself.
447 * The authentication method "publickey" works by signing a challenge
448 * sent by the server. The signature is either DSA or RSA based - it
449 * just depends on the type of private key you specify, either a DSA
450 * or RSA private key in PEM format. And yes, this is may seem to be a
451 * little confusing, the method is called "publickey" in the SSH-2 protocol
452 * specification, however since we need to generate a signature, you
453 * actually have to supply a private key =).
454 * <p/>
455 * The private key contained in the PEM file may also be encrypted ("Proc-Type: 4,ENCRYPTED").
456 * The library supports DES-CBC and DES-EDE3-CBC encryption, as well
457 * as the more exotic PEM encrpytions AES-128-CBC, AES-192-CBC and AES-256-CBC.
458 * <p/>
459 * If the authentication phase is complete, <code>true</code> will be
460 * returned. If the server does not accept the request (or if further
461 * authentication steps are needed), <code>false</code> is returned and
462 * one can retry either by using this or any other authentication method
463 * (use the <code>getRemainingAuthMethods</code> method to get a list of
464 * the remaining possible methods).
465 * <p/>
466 * NOTE PUTTY USERS: Event though your key file may start with "-----BEGIN..."
467 * it is not in the expected format. You have to convert it to the OpenSSH
468 * key format by using the "puttygen" tool (can be downloaded from the Putty
469 * website). Simply load your key and then use the "Conversions/Export OpenSSH key"
470 * functionality to get a proper PEM file.
471 *
472 * @param user A <code>String</code> holding the username.
473 * @param pemPrivateKey A <code>char[]</code> containing a DSA or RSA private key of the
474 * user in OpenSSH key format (PEM, you can't miss the
475 * "-----BEGIN DSA PRIVATE KEY-----" or "-----BEGIN RSA PRIVATE KEY-----"
476 * tag). The char array may contain linebreaks/linefeeds.
477 * @param password If the PEM structure is encrypted ("Proc-Type: 4,ENCRYPTED") then
478 * you must specify a password. Otherwise, this argument will be ignored
479 * and can be set to <code>null</code>.
480 * @return whether the connection is now authenticated.
481 * @throws IOException
482 */
483
484 public synchronized boolean authenticateWithPublicKey(String user, char[] pemPrivateKey, String password)
485 throws IOException {
486 if (tm == null) {
487 throw new IllegalStateException("Connection is not established!");
488 }
489
490 if (authenticated) {
491 throw new IllegalStateException("Connection is already authenticated!");
492 }
493
494 if (am == null) {
495 am = new AuthenticationManager(tm);
496 }
497
498 if (cm == null) {
499 cm = new ChannelManager(tm);
500 }
501
502 if (user == null) {
503 throw new IllegalArgumentException("user argument is null");
504 }
505
506 if (pemPrivateKey == null) {
507 throw new IllegalArgumentException("pemPrivateKey argument is null");
508 }
509
510 authenticated = am.authenticatePublicKey(user, pemPrivateKey, password, getOrCreateSecureRND());
511 return authenticated;
512 }
513
514 /**
515 * After a successful connect, one has to authenticate oneself. The
516 * authentication method "publickey" works by signing a challenge sent by
517 * the server. The signature is either DSA or RSA based - it just depends on
518 * the type of private key you specify, either a DSA or RSA private key in
519 * PEM format. And yes, this is may seem to be a little confusing, the
520 * method is called "publickey" in the SSH-2 protocol specification, however
521 * since we need to generate a signature, you actually have to supply a
522 * private key =).
523 * <p>
524 * If the authentication phase is complete, <code>true</code> will be
525 * returned. If the server does not accept the request (or if further
526 * authentication steps are needed), <code>false</code> is returned and
527 * one can retry either by using this or any other authentication method
528 * (use the <code>getRemainingAuthMethods</code> method to get a list of
529 * the remaining possible methods).
530 *
531 * @param user
532 * A <code>String</code> holding the username.
533 * @param pair
534 * A <code>RSAPrivateKey</code> or <code>DSAPrivateKey</code>
535 * containing a DSA or RSA private key of
536 * the user in Trilead object format.
537 *
538 * @return whether the connection is now authenticated.
539 * @throws IOException
540 */
541
542 public synchronized boolean authenticateWithPublicKey(String user, KeyPair pair)
543 throws IOException {
544 if (tm == null)
545 throw new IllegalStateException("Connection is not established!");
546
547 if (authenticated)
548 throw new IllegalStateException("Connection is already authenticated!");
549
550 if (am == null)
551 am = new AuthenticationManager(tm);
552
553 if (cm == null)
554 cm = new ChannelManager(tm);
555
556 if (user == null)
557 throw new IllegalArgumentException("user argument is null");
558
559 if (pair == null)
560 throw new IllegalArgumentException("Key pair argument is null");
561
562 authenticated = am.authenticatePublicKey(user, pair, getOrCreateSecureRND());
563 return authenticated;
564 }
565
566 /**
567 * A convenience wrapper function which reads in a private key (PEM format, either DSA or RSA)
568 * and then calls <code>authenticateWithPublicKey(String, char[], String)</code>.
569 * <p/>
570 * NOTE PUTTY USERS: Event though your key file may start with "-----BEGIN..."
571 * it is not in the expected format. You have to convert it to the OpenSSH
572 * key format by using the "puttygen" tool (can be downloaded from the Putty
573 * website). Simply load your key and then use the "Conversions/Export OpenSSH key"
574 * functionality to get a proper PEM file.
575 *
576 * @param user A <code>String</code> holding the username.
577 * @param pemFile A <code>File</code> object pointing to a file containing a DSA or RSA
578 * private key of the user in OpenSSH key format (PEM, you can't miss the
579 * "-----BEGIN DSA PRIVATE KEY-----" or "-----BEGIN RSA PRIVATE KEY-----"
580 * tag).
581 * @param password If the PEM file is encrypted then you must specify the password.
582 * Otherwise, this argument will be ignored and can be set to <code>null</code>.
583 * @return whether the connection is now authenticated.
584 * @throws IOException
585 */
586
587 public synchronized boolean authenticateWithPublicKey(String user, File pemFile, String password)
588 throws IOException {
589 if (pemFile == null) {
590 throw new IllegalArgumentException("pemFile argument is null");
591 }
592
593 char[] buff = new char[256];
594 CharArrayWriter cw = new CharArrayWriter();
595 FileReader fr = new FileReader(pemFile);
596
597 while (true) {
598 int len = fr.read(buff);
599
600 if (len < 0) {
601 break;
602 }
603
604 cw.write(buff, 0, len);
605 }
606
607 fr.close();
608 return authenticateWithPublicKey(user, cw.toCharArray(), password);
609 }
610
611 /**
612 * Add a {@link ConnectionMonitor} to this connection. Can be invoked at any time,
613 * but it is best to add connection monitors before invoking
614 * <code>connect()</code> to avoid glitches (e.g., you add a connection monitor after
615 * a successful connect(), but the connection has died in the mean time. Then,
616 * your connection monitor won't be notified.)
617 * <p/>
618 * You can add as many monitors as you like. If a monitor has already been added, then
619 * this method does nothing.
620 *
621 * @param cmon An object implementing the {@link ConnectionMonitor} interface.
622 * @see ConnectionMonitor
623 */
624
625 public synchronized void addConnectionMonitor(ConnectionMonitor cmon) {
626 if (!connectionMonitors.contains(cmon)) {
627 connectionMonitors.add(cmon);
628
629 if (tm != null) {
630 tm.setConnectionMonitors(connectionMonitors);
631 }
632 }
633 }
634
635 /**
636 * Remove a {@link ConnectionMonitor} from this connection.
637 *
638 * @param cmon
639 * @return whether the monitor could be removed
640 */
641
642 public synchronized boolean removeConnectionMonitor(ConnectionMonitor cmon) {
643 boolean existed = connectionMonitors.remove(cmon);
644
645 if (tm != null) {
646 tm.setConnectionMonitors(connectionMonitors);
647 }
648
649 return existed;
650 }
651
652 /**
653 * Controls whether compression is used on the link or not.
654 * <p>
655 * Note: This can only be called before connect()
656 * @param enabled whether to enable compression
657 * @throws IOException
658 */
659
660 public synchronized void setCompression(boolean enabled) throws IOException {
661 if (tm != null)
662 throw new IOException("Connection to " + hostname + " is already in connected state!");
663
664 if (enabled) enableCompression();
665 else disableCompression();
666 }
667
668 /**
669 * Close the connection to the SSH-2 server. All assigned sessions will be
670 * closed, too. Can be called at any time. Don't forget to call this once
671 * you don't need a connection anymore - otherwise the receiver thread may
672 * run forever.
673 */
674
675 // cannot be synchronized, since Connection.connect() is synchronized, and
676 // if the key exchange fails, another thread will try to close().
677
678 public void close() {
679 log.debug("Connection.close()");
680 Throwable t = new Throwable("Closed due to user request.");
681 close(t, false);
682 }
683
684 public void close(Throwable t, boolean hard) {
685 log.debug(String.format("Connection.close(%s hard=%b)", t.getMessage(), hard));
686 if (cm != null) {
687 cm.closeAllChannels();
688 }
689
690 if (tm != null) {
691 tm.close(t, hard == false);
692 tm = null;
693 }
694
695 am = null;
696 cm = null;
697 authenticated = false;
698 }
699
700 /**
701 * Same as {@link #connect(ServerHostKeyVerifier, int, int) connect(null, 0, 0)}.
702 *
703 * @return see comments for the {@link #connect(ServerHostKeyVerifier, int, int) connect(ServerHostKeyVerifier, int, int)} method.
704 * @throws IOException
705 */
706
707 public synchronized ConnectionInfo connect() throws IOException {
708 return connect(null, 0, 0);
709 }
710
711 /**
712 * Same as {@link #connect(ServerHostKeyVerifier, int, int) connect(verifier, 0, 0)}.
713 *
714 * @return see comments for the {@link #connect(ServerHostKeyVerifier, int, int) connect(ServerHostKeyVerifier, int, int)} method.
715 * @throws IOException
716 */
717
718 public synchronized ConnectionInfo connect(ServerHostKeyVerifier verifier) throws IOException {
719 return connect(verifier, 0, 0);
720 }
721
722 /**
723 * Connect to the SSH-2 server and, as soon as the server has presented its
724 * host key, use the {@link ServerHostKeyVerifier#verifyServerHostKey(String,
725 * int, String, byte[]) ServerHostKeyVerifier.verifyServerHostKey()}
726 * method of the <code>verifier</code> to ask for permission to proceed.
727 * If <code>verifier</code> is <code>null</code>, then any host key will be
728 * accepted - this is NOT recommended, since it makes man-in-the-middle attackes
729 * VERY easy (somebody could put a proxy SSH server between you and the real server).
730 * <p/>
731 * Note: The verifier will be called before doing any crypto calculations
732 * (i.e., diffie-hellman). Therefore, if you don't like the presented host key then
733 * no CPU cycles are wasted (and the evil server has less information about us).
734 * <p/>
735 * However, it is still possible that the server presented a fake host key: the server
736 * cheated (typically a sign for a man-in-the-middle attack) and is not able to generate
737 * a signature that matches its host key. Don't worry, the library will detect such
738 * a scenario later when checking the signature (the signature cannot be checked before
739 * having completed the diffie-hellman exchange).
740 * <p/>
741 * Note 2: The {@link ServerHostKeyVerifier#verifyServerHostKey(String,
742 * int, String, byte[]) ServerHostKeyVerifier.verifyServerHostKey()} method
743 * will *NOT* be called from the current thread, the call is being made from a
744 * background thread (there is a background dispatcher thread for every
745 * established connection).
746 * <p/>
747 * Note 3: This method will block as long as the key exchange of the underlying connection
748 * has not been completed (and you have not specified any timeouts).
749 * <p/>
750 * Note 4: If you want to re-use a connection object that was successfully connected,
751 * then you must call the {@link #close()} method before invoking <code>connect()</code> again.
752 *
753 * @param verifier An object that implements the
754 * {@link ServerHostKeyVerifier} interface. Pass <code>null</code>
755 * to accept any server host key - NOT recommended.
756 * @param connectTimeout Connect the underlying TCP socket to the server with the given timeout
757 * value (non-negative, in milliseconds). Zero means no timeout.
758 * @param kexTimeout Timeout for complete connection establishment (non-negative,
759 * in milliseconds). Zero means no timeout. The timeout counts from the
760 * moment you invoke the connect() method and is cancelled as soon as the
761 * first key-exchange round has finished. It is possible that
762 * the timeout event will be fired during the invocation of the
763 * <code>verifier</code> callback, but it will only have an effect after
764 * the <code>verifier</code> returns.
765 * @return A {@link ConnectionInfo} object containing the details of
766 * the established connection.
767 * @throws IOException If any problem occurs, e.g., the server's host key is not
768 * accepted by the <code>verifier</code> or there is problem during
769 * the initial crypto setup (e.g., the signature sent by the server is wrong).
770 * <p/>
771 * In case of a timeout (either connectTimeout or kexTimeout)
772 * a SocketTimeoutException is thrown.
773 * <p/>
774 * An exception may also be thrown if the connection was already successfully
775 * connected (no matter if the connection broke in the mean time) and you invoke
776 * <code>connect()</code> again without having called {@link #close()} first.
777 * <p/>
778 * If a HTTP proxy is being used and the proxy refuses the connection,
779 * then a {@link HTTPProxyException} may be thrown, which
780 * contains the details returned by the proxy. If the proxy is buggy and does
781 * not return a proper HTTP response, then a normal IOException is thrown instead.
782 */
783
784 public synchronized ConnectionInfo connect(ServerHostKeyVerifier verifier, int connectTimeout, int kexTimeout)
785 throws IOException {
786 final class TimeoutState {
787 boolean isCancelled = false;
788 boolean timeoutSocketClosed = false;
789 }
790
791 if (tm != null) {
792 throw new IllegalStateException(String.format("Connection to %s is already in connected state", hostname));
793 }
794
795 if (connectTimeout < 0) {
796 throw new IllegalArgumentException("connectTimeout must be non-negative!");
797 }
798
799 if (kexTimeout < 0) {
800 throw new IllegalArgumentException("kexTimeout must be non-negative!");
801 }
802
803 final TimeoutState state = new TimeoutState();
804
805 if (null == proxy) {
806 tm = new ClientTransportManager(new Socket());
807 }
808 else {
809 tm = new HTTPProxyClientTransportManager(new Socket(), proxy);
810 }
811
812 tm.setSoTimeout(connectTimeout);
813 tm.setTcpNoDelay(tcpNoDelay);
814 tm.setConnectionMonitors(connectionMonitors);
815
816 try {
817 TimeoutToken token = null;
818
819 if (kexTimeout > 0) {
820 final Runnable timeoutHandler = new Runnable() {
821 public void run() {
822 synchronized (state) {
823 if (state.isCancelled) {
824 return;
825 }
826
827 state.timeoutSocketClosed = true;
828 tm.close(new SocketTimeoutException("The connect timeout expired"), false);
829 }
830 }
831 };
832 long timeoutHorizont = System.currentTimeMillis() + kexTimeout;
833 token = TimeoutService.addTimeoutHandler(timeoutHorizont, timeoutHandler);
834 }
835
836 tm.connect(hostname, port, softwareversion, cryptoWishList, verifier, dhgexpara, connectTimeout,
837 getOrCreateSecureRND());
838 /* Wait until first KEX has finished */
839 ConnectionInfo ci = tm.getConnectionInfo(1);
840
841 /* Now try to cancel the timeout, if needed */
842
843 if (token != null) {
844 TimeoutService.cancelTimeoutHandler(token);
845
846 /* Were we too late? */
847
848 synchronized (state) {
849 if (state.timeoutSocketClosed) {
850 throw new IOException("This exception will be replaced by the one below =)");
851 }
852
853 /* Just in case the "cancelTimeoutHandler" invocation came just a little bit
854 * too late but the handler did not enter the semaphore yet - we can
855 * still stop it.
856 */
857 state.isCancelled = true;
858 }
859 }
860
861 return ci;
862 }
863 catch (SocketTimeoutException e) {
864 throw e;
865 }
866 catch (HTTPProxyException e) {
867 throw e;
868 }
869 catch (IOException e) {
870 // This will also invoke any registered connection monitors
871 close(e, false);
872
873 synchronized (state) {
874 /* Show a clean exception, not something like "the socket is closed!?!" */
875 if (state.timeoutSocketClosed) {
876 throw new SocketTimeoutException(String.format("The kexTimeout (%d ms) expired.", kexTimeout));
877 }
878 }
879
880 throw e;
881 }
882 }
883
884 /**
885 * Creates a new {@link LocalPortForwarder}.
886 * A <code>LocalPortForwarder</code> forwards TCP/IP connections that arrive at a local
887 * port via the secure tunnel to another host (which may or may not be
888 * identical to the remote SSH-2 server).
889 * <p/>
890 * This method must only be called after one has passed successfully the authentication step.
891 * There is no limit on the number of concurrent forwardings.
892 *
893 * @param local_port the local port the LocalPortForwarder shall bind to.
894 * @param host_to_connect target address (IP or hostname)
895 * @param port_to_connect target port
896 * @return A {@link LocalPortForwarder} object.
897 * @throws IOException
898 */
899
900 public synchronized LocalPortForwarder createLocalPortForwarder(int local_port, String host_to_connect,
901 int port_to_connect) throws IOException {
902 this.checkConnection();
903 return new LocalPortForwarder(cm, local_port, host_to_connect, port_to_connect);
904 }
905
906 /**
907 * Creates a new {@link LocalPortForwarder}.
908 * A <code>LocalPortForwarder</code> forwards TCP/IP connections that arrive at a local
909 * port via the secure tunnel to another host (which may or may not be
910 * identical to the remote SSH-2 server).
911 * <p/>
912 * This method must only be called after one has passed successfully the authentication step.
913 * There is no limit on the number of concurrent forwardings.
914 *
915 * @param addr specifies the InetSocketAddress where the local socket shall be bound to.
916 * @param host_to_connect target address (IP or hostname)
917 * @param port_to_connect target port
918 * @return A {@link LocalPortForwarder} object.
919 * @throws IOException
920 */
921
922 public synchronized LocalPortForwarder createLocalPortForwarder(InetSocketAddress addr, String host_to_connect,
923 int port_to_connect) throws IOException {
924 this.checkConnection();
925 return new LocalPortForwarder(cm, addr, host_to_connect, port_to_connect);
926 }
927
928 /**
929 * Creates a new {@link LocalStreamForwarder}.
930 * A <code>LocalStreamForwarder</code> manages an Input/Outputstream pair
931 * that is being forwarded via the secure tunnel into a TCP/IP connection to another host
932 * (which may or may not be identical to the remote SSH-2 server).
933 *
934 * @param host_to_connect
935 * @param port_to_connect
936 * @return A {@link LocalStreamForwarder} object.
937 * @throws IOException
938 */
939
940 public synchronized LocalStreamForwarder createLocalStreamForwarder(String host_to_connect, int port_to_connect)
941 throws IOException {
942 this.checkConnection();
943 return new LocalStreamForwarder(cm, host_to_connect, port_to_connect);
944 }
945
946 /**
947 * Creates a new {@link DynamicPortForwarder}. A
948 * <code>DynamicPortForwarder</code> forwards TCP/IP connections that arrive
949 * at a local port via the secure tunnel to another host that is chosen via
950 * the SOCKS protocol.
951 * <p>
952 * This method must only be called after one has passed successfully the
953 * authentication step. There is no limit on the number of concurrent
954 * forwardings.
955 *
956 * @param local_port
957 * @return A {@link DynamicPortForwarder} object.
958 * @throws IOException
959 */
960
961 public synchronized DynamicPortForwarder createDynamicPortForwarder(int local_port) throws IOException {
962 if (tm == null)
963 throw new IllegalStateException("Cannot forward ports, you need to establish a connection first.");
964
965 if (!authenticated)
966 throw new IllegalStateException("Cannot forward ports, connection is not authenticated.");
967
968 return new DynamicPortForwarder(cm, local_port);
969 }
970
971 /**
972 * Creates a new {@link DynamicPortForwarder}. A
973 * <code>DynamicPortForwarder</code> forwards TCP/IP connections that arrive
974 * at a local port via the secure tunnel to another host that is chosen via
975 * the SOCKS protocol.
976 * <p>
977 * This method must only be called after one has passed successfully the
978 * authentication step. There is no limit on the number of concurrent
979 * forwardings.
980 *
981 * @param addr
982 * specifies the InetSocketAddress where the local socket shall
983 * be bound to.
984 * @return A {@link DynamicPortForwarder} object.
985 * @throws IOException
986 */
987
988 public synchronized DynamicPortForwarder createDynamicPortForwarder(InetSocketAddress addr) throws IOException {
989 if (tm == null)
990 throw new IllegalStateException("Cannot forward ports, you need to establish a connection first.");
991
992 if (!authenticated)
993 throw new IllegalStateException("Cannot forward ports, connection is not authenticated.");
994
995 return new DynamicPortForwarder(cm, addr);
996 }
997
998 /**
999 * Create a very basic {@link SCPClient} that can be used to copy
1000 * files from/to the SSH-2 server.
1001 * <p/>
1002 * Works only after one has passed successfully the authentication step.
1003 * There is no limit on the number of concurrent SCP clients.
1004 * <p/>
1005 * Note: This factory method will probably disappear in the future.
1006 *
1007 * @return A {@link SCPClient} object.
1008 * @throws IOException
1009 */
1010
1011 public synchronized SCPClient createSCPClient() throws IOException {
1012 this.checkConnection();
1013 return new SCPClient(this);
1014 }
1015
1016 /**
1017 * Force an asynchronous key re-exchange (the call does not block). The
1018 * latest values set for MAC, Cipher and DH group exchange parameters will
1019 * be used. If a key exchange is currently in progress, then this method has
1020 * the only effect that the so far specified parameters will be used for the
1021 * next (server driven) key exchange.
1022 * <p/>
1023 * Note: This implementation will never start a key exchange (other than the initial one)
1024 * unless you or the SSH-2 server ask for it.
1025 *
1026 * @throws IOException In case of any failure behind the scenes.
1027 */
1028
1029 public synchronized void forceKeyExchange() throws IOException {
1030 this.checkConnection();
1031 tm.forceKeyExchange(cryptoWishList, dhgexpara, null, null, null);
1032 }
1033
1034 /**
1035 * Returns the hostname that was passed to the constructor.
1036 *
1037 * @return the hostname
1038 */
1039
1040 public synchronized String getHostname() {
1041 return hostname;
1042 }
1043
1044 /**
1045 * Returns the port that was passed to the constructor.
1046 *
1047 * @return the TCP port
1048 */
1049
1050 public synchronized int getPort() {
1051 return port;
1052 }
1053
1054 /**
1055 * Returns a {@link ConnectionInfo} object containing the details of
1056 * the connection. Can be called as soon as the connection has been
1057 * established (successfully connected).
1058 *
1059 * @return A {@link ConnectionInfo} object.
1060 * @throws IOException In case of any failure behind the scenes.
1061 */
1062
1063 public synchronized ConnectionInfo getConnectionInfo() throws IOException {
1064 this.checkConnection();
1065 return tm.getConnectionInfo(1);
1066 }
1067
1068 /**
1069 * After a successful connect, one has to authenticate oneself. This method
1070 * can be used to tell which authentication methods are supported by the
1071 * server at a certain stage of the authentication process (for the given
1072 * username).
1073 * <p/>
1074 * Note 1: the username will only be used if no authentication step was done
1075 * so far (it will be used to ask the server for a list of possible
1076 * authentication methods by sending the initial "none" request). Otherwise,
1077 * this method ignores the user name and returns a cached method list
1078 * (which is based on the information contained in the last negative server response).
1079 * <p/>
1080 * Note 2: the server may return method names that are not supported by this
1081 * implementation.
1082 * <p/>
1083 * After a successful authentication, this method must not be called
1084 * anymore.
1085 *
1086 * @param user A <code>String</code> holding the username.
1087 * @return a (possibly emtpy) array holding authentication method names.
1088 * @throws IOException
1089 */
1090
1091 public synchronized String[] getRemainingAuthMethods(String user) throws IOException {
1092 if (user == null) {
1093 throw new IllegalArgumentException("user argument may not be NULL!");
1094 }
1095
1096 if (tm == null) {
1097 throw new IllegalStateException("Connection is not established!");
1098 }
1099
1100 if (authenticated) {
1101 throw new IllegalStateException("Connection is already authenticated!");
1102 }
1103
1104 if (am == null) {
1105 am = new AuthenticationManager(tm);
1106 }
1107
1108 if (cm == null) {
1109 cm = new ChannelManager(tm);
1110 }
1111
1112 final Set<String> remainingMethods = am.getRemainingMethods(user);
1113 return remainingMethods.toArray(new String[remainingMethods.size()]);
1114 }
1115
1116 /**
1117 * Determines if the authentication phase is complete. Can be called at any
1118 * time.
1119 *
1120 * @return <code>true</code> if no further authentication steps are
1121 * needed.
1122 */
1123
1124 public synchronized boolean isAuthenticationComplete() {
1125 return authenticated;
1126 }
1127
1128 /**
1129 * Returns true if there was at least one failed authentication request and
1130 * the last failed authentication request was marked with "partial success"
1131 * by the server. This is only needed in the rare case of SSH-2 server setups
1132 * that cannot be satisfied with a single successful authentication request
1133 * (i.e., multiple authentication steps are needed.)
1134 * <p/>
1135 * If you are interested in the details, then have a look at RFC4252.
1136 *
1137 * @return if the there was a failed authentication step and the last one
1138 * was marked as a "partial success".
1139 */
1140
1141 public synchronized boolean isAuthenticationPartialSuccess() {
1142 if (am == null) {
1143 return false;
1144 }
1145
1146 return am.getPartialSuccess();
1147 }
1148
1149 /**
1150 * Checks if a specified authentication method is available. This method is
1151 * actually just a wrapper for {@link #getRemainingAuthMethods(String)
1152 * getRemainingAuthMethods()}.
1153 *
1154 * @param user A <code>String</code> holding the username.
1155 * @param method An authentication method name (e.g., "publickey", "password",
1156 * "keyboard-interactive") as specified by the SSH-2 standard.
1157 * @return if the specified authentication method is currently available.
1158 * @throws IOException
1159 */
1160
1161 public synchronized boolean isAuthMethodAvailable(String user, String method) throws IOException {
1162 String methods[] = getRemainingAuthMethods(user);
1163
1164 for (final String m : methods) {
1165 if (m.compareTo(method) == 0) {
1166 return true;
1167 }
1168 }
1169
1170 return false;
1171 }
1172
1173 private SecureRandomFix getOrCreateSecureRND() {
1174 if (generator == null) {
1175 generator = new SecureRandomFix();
1176 }
1177
1178 return generator;
1179 }
1180
1181 /**
1182 * Open a new {@link Session} on this connection. Works only after one has passed
1183 * successfully the authentication step. There is no limit on the number of
1184 * concurrent sessions.
1185 *
1186 * @return A {@link Session} object.
1187 * @throws IOException
1188 */
1189
1190 public synchronized Session openSession() throws IOException {
1191 this.checkConnection();
1192 return new Session(cm, getOrCreateSecureRND());
1193 }
1194
1195 /**
1196 * Send an SSH_MSG_IGNORE packet. This method will generate a random data attribute
1197 * (length between 0 (invlusive) and 16 (exclusive) bytes, contents are random bytes).
1198 * <p/>
1199 * This method must only be called once the connection is established.
1200 *
1201 * @throws IOException
1202 */
1203
1204 public synchronized void sendIgnorePacket() throws IOException {
1205 SecureRandomFix rnd = getOrCreateSecureRND();
1206 byte[] data = new byte[rnd.nextInt(16)];
1207 rnd.nextBytes(data);
1208 sendIgnorePacket(data);
1209 }
1210
1211 /**
1212 * Send an SSH_MSG_IGNORE packet with the given data attribute.
1213 * <p/>
1214 * This method must only be called once the connection is established.
1215 *
1216 * @throws IOException
1217 */
1218
1219 public synchronized void sendIgnorePacket(byte[] data) throws IOException {
1220 this.checkConnection();
1221 PacketIgnore pi = new PacketIgnore(data);
1222 tm.sendMessage(pi.getPayload());
1223 }
1224
1225 /**
1226 * Controls whether compression is used on the link or not.
1227 */
1228
1229 public synchronized void setCompression(String[] algorithms) {
1230 CompressionFactory.checkCompressorList(algorithms);
1231 cryptoWishList.c2s_comp_algos = algorithms;
1232 }
1233
1234 public synchronized void enableCompression() {
1235 cryptoWishList.c2s_comp_algos = CompressionFactory.getDefaultCompressorList();
1236 cryptoWishList.s2c_comp_algos = CompressionFactory.getDefaultCompressorList();
1237 }
1238
1239 public synchronized void disableCompression() {
1240 cryptoWishList.c2s_comp_algos = new String[] {"none"};
1241 cryptoWishList.s2c_comp_algos = new String[] {"none"};
1242 }
1243
1244 /**
1245 * Unless you know what you are doing, you will never need this.
1246 */
1247
1248 public synchronized void setClient2ServerCiphers(final String[] ciphers) {
1249 if ((ciphers == null) || (ciphers.length == 0)) {
1250 throw new IllegalArgumentException();
1251 }
1252
1253 BlockCipherFactory.checkCipherList(ciphers);
1254 cryptoWishList.c2s_enc_algos = ciphers;
1255 }
1256
1257 /**
1258 * Unless you know what you are doing, you will never need this.
1259 */
1260
1261 public synchronized void setClient2ServerMACs(final String[] macs) {
1262 MAC.checkMacList(macs);
1263 cryptoWishList.c2s_mac_algos = macs;
1264 }
1265
1266 /**
1267 * Sets the parameters for the diffie-hellman group exchange. Unless you
1268 * know what you are doing, you will never need this. Default values are
1269 * defined in the {@link DHGexParameters} class.
1270 *
1271 * @param dgp {@link DHGexParameters}, non null.
1272 */
1273
1274 public synchronized void setDHGexParameters(DHGexParameters dgp) {
1275 if (dgp == null) {
1276 throw new IllegalArgumentException();
1277 }
1278
1279 dhgexpara = dgp;
1280 }
1281
1282 /**
1283 * Unless you know what you are doing, you will never need this.
1284 */
1285
1286 public synchronized void setServer2ClientCiphers(final String[] ciphers) {
1287 BlockCipherFactory.checkCipherList(ciphers);
1288 cryptoWishList.s2c_enc_algos = ciphers;
1289 }
1290
1291 /**
1292 * Unless you know what you are doing, you will never need this.
1293 */
1294
1295 public synchronized void setServer2ClientMACs(final String[] macs) {
1296 MAC.checkMacList(macs);
1297 cryptoWishList.s2c_mac_algos = macs;
1298 }
1299
1300 /**
1301 * Define the set of allowed server host key algorithms to be used for
1302 * the following key exchange operations.
1303 * <p/>
1304 * Unless you know what you are doing, you will never need this.
1305 *
1306 * @param algos An array of allowed server host key algorithms.
1307 * SSH-2 defines <code>ssh-dss</code> and <code>ssh-rsa</code>.
1308 * The entries of the array must be ordered after preference, i.e.,
1309 * the entry at index 0 is the most preferred one. You must specify
1310 * at least one entry.
1311 */
1312
1313 public synchronized void setServerHostKeyAlgorithms(final String[] algos) {
1314 KexManager.checkServerHostkeyAlgorithmsList(algos);
1315 cryptoWishList.serverHostKeyAlgorithms = algos;
1316 }
1317
1318 /**
1319 * Enable/disable TCP_NODELAY (disable/enable Nagle's algorithm) on the underlying socket.
1320 * <p/>
1321 * Can be called at any time. If the connection has not yet been established
1322 * then the passed value will be stored and set after the socket has been set up.
1323 * The default value that will be used is <code>false</code>.
1324 *
1325 * @param enable the argument passed to the <code>Socket.setTCPNoDelay()</code> method.
1326 * @throws IOException
1327 */
1328
1329 public synchronized void setTCPNoDelay(boolean enable) throws IOException {
1330 tcpNoDelay = enable;
1331
1332 if (tm != null) {
1333 tm.setTcpNoDelay(enable);
1334 }
1335 }
1336
1337 /**
1338 * Used to tell the library that the connection shall be established through
1339 * a proxy server. It only makes sense to call this method before calling
1340 * the {@link #connect() connect()} method.
1341 * <p>
1342 * At the moment, only HTTP proxies are supported.
1343 * <p>
1344 * Note: This method can be called any number of times. The
1345 * {@link #connect() connect()} method will use the value set in the last
1346 * preceding invocation of this method.
1347 *
1348 * @see HTTPProxyData
1349 *
1350 * @param proxy
1351 * Connection information about the proxy. If <code>null</code>,
1352 * then no proxy will be used (non surprisingly, this is also the
1353 * default).
1354 */
1355
1356 public synchronized void setProxyData(HTTPProxyData proxy) {
1357 this.proxy = proxy;
1358 }
1359
1360 /**
1361 * Request a remote port forwarding.
1362 * If successful, then forwarded connections will be redirected to the given target address.
1363 * You can cancle a requested remote port forwarding by calling
1364 * {@link #cancelRemotePortForwarding(int) cancelRemotePortForwarding()}.
1365 * <p/>
1366 * A call of this method will block until the peer either agreed or disagreed to your request-
1367 * <p/>
1368 * Note 1: this method typically fails if you
1369 * <ul>
1370 * <li>pass a port number for which the used remote user has not enough permissions (i.e., port
1371 * &lt; 1024)</li>
1372 * <li>or pass a port number that is already in use on the remote server</li>
1373 * <li>or if remote port forwarding is disabled on the server.</li>
1374 * </ul>
1375 * <p/>
1376 * Note 2: (from the openssh man page): By default, the listening socket on the server will be
1377 * bound to the loopback interface only. This may be overriden by specifying a bind address.
1378 * Specifying a remote bind address will only succeed if the server's <b>GatewayPorts</b> option
1379 * is enabled (see sshd_config(5)).
1380 *
1381 * @param bindAddress address to bind to on the server:
1382 * <ul>
1383 * <li>"" means that connections are to be accepted on all protocol families
1384 * supported by the SSH implementation</li>
1385 * <li>"0.0.0.0" means to listen on all IPv4 addresses</li>
1386 * <li>"::" means to listen on all IPv6 addresses</li>
1387 * <li>"localhost" means to listen on all protocol families supported by the SSH
1388 * implementation on loopback addresses only, [RFC3330] and RFC3513]</li>
1389 * <li>"127.0.0.1" and "::1" indicate listening on the loopback interfaces for
1390 * IPv4 and IPv6 respectively</li>
1391 * </ul>
1392 * @param bindPort port number to bind on the server (must be &gt; 0)
1393 * @param targetAddress the target address (IP or hostname)
1394 * @param targetPort the target port
1395 * @throws IOException
1396 */
1397
1398 public synchronized void requestRemotePortForwarding(String bindAddress, int bindPort, String targetAddress,
1399 int targetPort) throws IOException {
1400 this.checkConnection();
1401
1402 if ((bindAddress == null) || (targetAddress == null) || (bindPort <= 0) || (targetPort <= 0)) {
1403 throw new IllegalArgumentException();
1404 }
1405
1406 cm.requestGlobalForward(bindAddress, bindPort, targetAddress, targetPort);
1407 }
1408
1409 /**
1410 * Cancel an earlier requested remote port forwarding.
1411 * Currently active forwardings will not be affected (e.g., disrupted).
1412 * Note that further connection forwarding requests may be received until
1413 * this method has returned.
1414 *
1415 * @param bindPort the allocated port number on the server
1416 * @throws IOException if the remote side refuses the cancel request or another low
1417 * level error occurs (e.g., the underlying connection is closed)
1418 */
1419
1420 public synchronized void cancelRemotePortForwarding(int bindPort) throws IOException {
1421 this.checkConnection();
1422 cm.requestCancelGlobalForward(bindPort);
1423 }
1424
1425 /**
1426 * Provide your own instance of SecureRandom. Can be used, e.g., if you
1427 * want to seed the used SecureRandom generator manually.
1428 * <p/>
1429 * The SecureRandom instance is used during key exchanges, public key authentication,
1430 * x11 cookie generation and the like.
1431 *
1432 * @param rnd a SecureRandom instance
1433 */
1434
1435 public synchronized void setSecureRandom(SecureRandomFix rnd) {
1436 if (rnd == null) {
1437 throw new IllegalArgumentException();
1438 }
1439
1440 this.generator = rnd;
1441 }
1442
1443 private void checkConnection() throws IllegalStateException {
1444 if (tm == null) {
1445 throw new IllegalStateException("You need to establish a connection first.");
1446 }
1447
1448 if (!authenticated) {
1449 throw new IllegalStateException("The connection is not authenticated.");
1450 }
1451 }
1452 }