1 /*
2 * Copyright 1997-2008 Sun Microsystems, Inc. All Rights Reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26
27 package javax.net.ssl;
28
29 import java.io.IOException;
30 import java.net;
31 import java.util.Enumeration;
32 import java.util.Vector;
33
34
35 /**
36 * This class extends <code>Socket</code>s and provides secure
37 * socket using protocols such as the "Secure
38 * Sockets Layer" (SSL) or IETF "Transport Layer Security" (TLS) protocols.
39 * <P>
40 * Such sockets are normal stream sockets, but they
41 * add a layer of security protections over the underlying network transport
42 * protocol, such as TCP. Those protections include: <UL>
43 *
44 * <LI> <em>Integrity Protection</em>. SSL protects against
45 * modification of messages by an active wiretapper.
46 *
47 * <LI> <em>Authentication</em>. In most modes, SSL provides
48 * peer authentication. Servers are usually authenticated,
49 * and clients may be authenticated as requested by servers.
50 *
51 * <LI> <em>Confidentiality (Privacy Protection)</em>. In most
52 * modes, SSL encrypts data being sent between client and server.
53 * This protects the confidentiality of data, so that passive
54 * wiretappers won't see sensitive data such as financial
55 * information or personal information of many kinds.
56 *
57 * </UL>
58 *
59 * <P>These kinds of protection are specified by a "cipher suite", which
60 * is a combination of cryptographic algorithms used by a given SSL connection.
61 * During the negotiation process, the two endpoints must agree on
62 * a ciphersuite that is available in both environments.
63 * If there is no such suite in common, no SSL connection can
64 * be established, and no data can be exchanged.
65 *
66 * <P> The cipher suite used is established by a negotiation process
67 * called "handshaking". The goal of this
68 * process is to create or rejoin a "session", which may protect many
69 * connections over time. After handshaking has completed, you can access
70 * session attributes by using the <em>getSession</em> method.
71 * The initial handshake on this connection can be initiated in
72 * one of three ways: <UL>
73 *
74 * <LI> calling <code>startHandshake</code> which explicitly
75 * begins handshakes, or
76 * <LI> any attempt to read or write application data on
77 * this socket causes an implicit handshake, or
78 * <LI> a call to <code>getSession</code> tries to set up a session
79 * if there is no currently valid session, and
80 * an implicit handshake is done.
81 * </UL>
82 *
83 * <P>If handshaking fails for any reason, the <code>SSLSocket</code>
84 * is closed, and no futher communications can be done.
85 *
86 * <P>There are two groups of cipher suites which you will need to know
87 * about when managing cipher suites: <UL>
88 *
89 * <LI> <em>Supported</em> cipher suites: all the suites which are
90 * supported by the SSL implementation. This list is reported
91 * using <em>getSupportedCipherSuites</em>.
92 *
93 * <LI> <em>Enabled</em> cipher suites, which may be fewer
94 * than the full set of supported suites. This group is
95 * set using the <em>setEnabledCipherSuites</em> method, and
96 * queried using the <em>getEnabledCipherSuites</em> method.
97 * Initially, a default set of cipher suites will be enabled on
98 * a new socket that represents the minimum suggested configuration.
99 *
100 * </UL>
101 *
102 * <P> Implementation defaults require that only cipher
103 * suites which authenticate servers and provide confidentiality
104 * be enabled by default.
105 * Only if both sides explicitly agree to unauthenticated and/or
106 * non-private (unencrypted) communications will such a ciphersuite be
107 * selected.
108 *
109 * <P>When <code>SSLSocket</code>s are first created, no handshaking
110 * is done so that applications may first set their communication
111 * preferences: what cipher suites to use, whether the socket should be
112 * in client or server mode, etc.
113 * However, security is always provided by the time that application data
114 * is sent over the connection.
115 *
116 * <P> You may register to receive event notification of handshake
117 * completion. This involves
118 * the use of two additional classes. <em>HandshakeCompletedEvent</em>
119 * objects are passed to <em>HandshakeCompletedListener</em> instances,
120 * which are registered by users of this API.
121 *
122 * <code>SSLSocket</code>s are created by <code>SSLSocketFactory</code>s,
123 * or by <code>accept</code>ing a connection from a
124 * <code>SSLServerSocket</code>.
125 *
126 * <P>A SSL socket must choose to operate in the client or server mode.
127 * This will determine who begins the handshaking process, as well
128 * as which messages should be sent by each party. Each
129 * connection must have one client and one server, or handshaking
130 * will not progress properly. Once the initial handshaking has started, a
131 * socket can not switch between client and server modes, even when
132 * performing renegotiations.
133 *
134 * @see java.net.Socket
135 * @see SSLServerSocket
136 * @see SSLSocketFactory
137 *
138 * @since 1.4
139 * @author David Brownell
140 */
141 public abstract class SSLSocket extends Socket
142 {
143 /**
144 * Used only by subclasses.
145 * Constructs an uninitialized, unconnected TCP socket.
146 */
147 protected SSLSocket()
148 { super(); }
149
150
151 /**
152 * Used only by subclasses.
153 * Constructs a TCP connection to a named host at a specified port.
154 * This acts as the SSL client.
155 * <p>
156 * If there is a security manager, its <code>checkConnect</code>
157 * method is called with the host address and <code>port</code>
158 * as its arguments. This could result in a SecurityException.
159 *
160 * @param host name of the host with which to connect, or
161 * <code>null</code> for the loopback address.
162 * @param port number of the server's port
163 * @throws IOException if an I/O error occurs when creating the socket
164 * @throws SecurityException if a security manager exists and its
165 * <code>checkConnect</code> method doesn't allow the operation.
166 * @throws UnknownHostException if the host is not known
167 * @throws IllegalArgumentException if the port parameter is outside the
168 * specified range of valid port values, which is between 0 and
169 * 65535, inclusive.
170 * @see SecurityManager#checkConnect
171 */
172 protected SSLSocket(String host, int port)
173 throws IOException, UnknownHostException
174 { super(host, port); }
175
176
177 /**
178 * Used only by subclasses.
179 * Constructs a TCP connection to a server at a specified address
180 * and port. This acts as the SSL client.
181 * <p>
182 * If there is a security manager, its <code>checkConnect</code>
183 * method is called with the host address and <code>port</code>
184 * as its arguments. This could result in a SecurityException.
185 *
186 * @param address the server's host
187 * @param port its port
188 * @throws IOException if an I/O error occurs when creating the socket
189 * @throws SecurityException if a security manager exists and its
190 * <code>checkConnect</code> method doesn't allow the operation.
191 * @throws IllegalArgumentException if the port parameter is outside the
192 * specified range of valid port values, which is between 0 and
193 * 65535, inclusive.
194 * @throws NullPointerException if <code>address</code> is null.
195 * @see SecurityManager#checkConnect
196 */
197 protected SSLSocket(InetAddress address, int port)
198 throws IOException
199 { super(address, port); }
200
201
202 /**
203 * Used only by subclasses.
204 * Constructs an SSL connection to a named host at a specified port,
205 * binding the client side of the connection a given address and port.
206 * This acts as the SSL client.
207 * <p>
208 * If there is a security manager, its <code>checkConnect</code>
209 * method is called with the host address and <code>port</code>
210 * as its arguments. This could result in a SecurityException.
211 *
212 * @param host name of the host with which to connect, or
213 * <code>null</code> for the loopback address.
214 * @param port number of the server's port
215 * @param clientAddress the client's address the socket is bound to, or
216 * <code>null</code> for the <code>anyLocal</code> address.
217 * @param clientPort the client's port the socket is bound to, or
218 * <code>zero</code> for a system selected free port.
219 * @throws IOException if an I/O error occurs when creating the socket
220 * @throws SecurityException if a security manager exists and its
221 * <code>checkConnect</code> method doesn't allow the operation.
222 * @throws UnknownHostException if the host is not known
223 * @throws IllegalArgumentException if the port parameter or clientPort
224 * parameter is outside the specified range of valid port values,
225 * which is between 0 and 65535, inclusive.
226 * @see SecurityManager#checkConnect
227 */
228 protected SSLSocket(String host, int port,
229 InetAddress clientAddress, int clientPort)
230 throws IOException, UnknownHostException
231 { super(host, port, clientAddress, clientPort); }
232
233
234 /**
235 * Used only by subclasses.
236 * Constructs an SSL connection to a server at a specified address
237 * and TCP port, binding the client side of the connection a given
238 * address and port. This acts as the SSL client.
239 * <p>
240 * If there is a security manager, its <code>checkConnect</code>
241 * method is called with the host address and <code>port</code>
242 * as its arguments. This could result in a SecurityException.
243 *
244 * @param address the server's host
245 * @param port its port
246 * @param clientAddress the client's address the socket is bound to, or
247 * <code>null</code> for the <code>anyLocal</code> address.
248 * @param clientPort the client's port the socket is bound to, or
249 * <code>zero</code> for a system selected free port.
250 * @throws IOException if an I/O error occurs when creating the socket
251 * @throws SecurityException if a security manager exists and its
252 * <code>checkConnect</code> method doesn't allow the operation.
253 * @throws IllegalArgumentException if the port parameter or clientPort
254 * parameter is outside the specified range of valid port values,
255 * which is between 0 and 65535, inclusive.
256 * @throws NullPointerException if <code>address</code> is null.
257 * @see SecurityManager#checkConnect
258 */
259 protected SSLSocket(InetAddress address, int port,
260 InetAddress clientAddress, int clientPort)
261 throws IOException
262 { super(address, port, clientAddress, clientPort); }
263
264
265 /**
266 * Returns the names of the cipher suites which could be enabled for use
267 * on this connection. Normally, only a subset of these will actually
268 * be enabled by default, since this list may include cipher suites which
269 * do not meet quality of service requirements for those defaults. Such
270 * cipher suites might be useful in specialized applications.
271 *
272 * @return an array of cipher suite names
273 * @see #getEnabledCipherSuites()
274 * @see #setEnabledCipherSuites(String [])
275 */
276 public abstract String [] getSupportedCipherSuites();
277
278
279 /**
280 * Returns the names of the SSL cipher suites which are currently
281 * enabled for use on this connection. When an SSLSocket is first
282 * created, all enabled cipher suites support a minimum quality of
283 * service. Thus, in some environments this value might be empty.
284 * <P>
285 * Even if a suite has been enabled, it might never be used. (For
286 * example, the peer does not support it, the requisite certificates
287 * (and private keys) for the suite are not available, or an
288 * anonymous suite is enabled but authentication is required.
289 *
290 * @return an array of cipher suite names
291 * @see #getSupportedCipherSuites()
292 * @see #setEnabledCipherSuites(String [])
293 */
294 public abstract String [] getEnabledCipherSuites();
295
296
297 /**
298 * Sets the cipher suites enabled for use on this connection.
299 * <P>
300 * Each cipher suite in the <code>suites</code> parameter must have
301 * been listed by getSupportedCipherSuites(), or the method will
302 * fail. Following a successful call to this method, only suites
303 * listed in the <code>suites</code> parameter are enabled for use.
304 * <P>
305 * See {@link #getEnabledCipherSuites()} for more information
306 * on why a specific ciphersuite may never be used on a connection.
307 *
308 * @param suites Names of all the cipher suites to enable
309 * @throws IllegalArgumentException when one or more of the ciphers
310 * named by the parameter is not supported, or when the
311 * parameter is null.
312 * @see #getSupportedCipherSuites()
313 * @see #getEnabledCipherSuites()
314 */
315 public abstract void setEnabledCipherSuites(String suites []);
316
317
318 /**
319 * Returns the names of the protocols which could be enabled for use
320 * on an SSL connection.
321 *
322 * @return an array of protocols supported
323 */
324 public abstract String [] getSupportedProtocols();
325
326
327 /**
328 * Returns the names of the protocol versions which are currently
329 * enabled for use on this connection.
330 * @see #setEnabledProtocols(String [])
331 * @return an array of protocols
332 */
333 public abstract String [] getEnabledProtocols();
334
335
336 /**
337 * Sets the protocol versions enabled for use on this connection.
338 * <P>
339 * The protocols must have been listed by
340 * <code>getSupportedProtocols()</code> as being supported.
341 * Following a successful call to this method, only protocols listed
342 * in the <code>protocols</code> parameter are enabled for use.
343 *
344 * @param protocols Names of all the protocols to enable.
345 * @throws IllegalArgumentException when one or more of
346 * the protocols named by the parameter is not supported or
347 * when the protocols parameter is null.
348 * @see #getEnabledProtocols()
349 */
350 public abstract void setEnabledProtocols(String protocols[]);
351
352
353 /**
354 * Returns the SSL Session in use by this connection. These can
355 * be long lived, and frequently correspond to an entire login session
356 * for some user. The session specifies a particular cipher suite
357 * which is being actively used by all connections in that session,
358 * as well as the identities of the session's client and server.
359 * <P>
360 * This method will initiate the initial handshake if
361 * necessary and then block until the handshake has been
362 * established.
363 * <P>
364 * If an error occurs during the initial handshake, this method
365 * returns an invalid session object which reports an invalid
366 * cipher suite of "SSL_NULL_WITH_NULL_NULL".
367 *
368 * @return the <code>SSLSession</code>
369 */
370 public abstract SSLSession getSession();
371
372
373 /**
374 * Registers an event listener to receive notifications that an
375 * SSL handshake has completed on this connection.
376 *
377 * @param listener the HandShake Completed event listener
378 * @see #startHandshake()
379 * @see #removeHandshakeCompletedListener(HandshakeCompletedListener)
380 * @throws IllegalArgumentException if the argument is null.
381 */
382 public abstract void addHandshakeCompletedListener(
383 HandshakeCompletedListener listener);
384
385
386 /**
387 * Removes a previously registered handshake completion listener.
388 *
389 * @param listener the HandShake Completed event listener
390 * @throws IllegalArgumentException if the listener is not registered,
391 * or the argument is null.
392 * @see #addHandshakeCompletedListener(HandshakeCompletedListener)
393 */
394 public abstract void removeHandshakeCompletedListener(
395 HandshakeCompletedListener listener);
396
397
398 /**
399 * Starts an SSL handshake on this connection. Common reasons include
400 * a need to use new encryption keys, to change cipher suites, or to
401 * initiate a new session. To force complete reauthentication, the
402 * current session could be invalidated before starting this handshake.
403 *
404 * <P> If data has already been sent on the connection, it continues
405 * to flow during this handshake. When the handshake completes, this
406 * will be signaled with an event.
407 *
408 * This method is synchronous for the initial handshake on a connection
409 * and returns when the negotiated handshake is complete. Some
410 * protocols may not support multiple handshakes on an existing socket
411 * and may throw an IOException.
412 *
413 * @throws IOException on a network level error
414 * @see #addHandshakeCompletedListener(HandshakeCompletedListener)
415 */
416 public abstract void startHandshake() throws IOException;
417
418
419 /**
420 * Configures the socket to use client (or server) mode when
421 * handshaking.
422 * <P>
423 * This method must be called before any handshaking occurs.
424 * Once handshaking has begun, the mode can not be reset for the
425 * life of this socket.
426 * <P>
427 * Servers normally authenticate themselves, and clients
428 * are not required to do so.
429 *
430 * @param mode true if the socket should start its handshaking
431 * in "client" mode
432 * @throws IllegalArgumentException if a mode change is attempted
433 * after the initial handshake has begun.
434 * @see #getUseClientMode()
435 */
436 public abstract void setUseClientMode(boolean mode);
437
438
439 /**
440 * Returns true if the socket is set to use client mode when
441 * handshaking.
442 *
443 * @return true if the socket should do handshaking
444 * in "client" mode
445 * @see #setUseClientMode(boolean)
446 */
447 public abstract boolean getUseClientMode();
448
449
450 /**
451 * Configures the socket to <i>require</i> client authentication. This
452 * option is only useful for sockets in the server mode.
453 * <P>
454 * A socket's client authentication setting is one of the following:
455 * <ul>
456 * <li> client authentication required
457 * <li> client authentication requested
458 * <li> no client authentication desired
459 * </ul>
460 * <P>
461 * Unlike {@link #setWantClientAuth(boolean)}, if this option is set and
462 * the client chooses not to provide authentication information
463 * about itself, <i>the negotiations will stop and the connection
464 * will be dropped</i>.
465 * <P>
466 * Calling this method overrides any previous setting made by
467 * this method or {@link #setWantClientAuth(boolean)}.
468 *
469 * @param need set to true if client authentication is required,
470 * or false if no client authentication is desired.
471 * @see #getNeedClientAuth()
472 * @see #setWantClientAuth(boolean)
473 * @see #getWantClientAuth()
474 * @see #setUseClientMode(boolean)
475 */
476 public abstract void setNeedClientAuth(boolean need);
477
478
479 /**
480 * Returns true if the socket will <i>require</i> client authentication.
481 * This option is only useful to sockets in the server mode.
482 *
483 * @return true if client authentication is required,
484 * or false if no client authentication is desired.
485 * @see #setNeedClientAuth(boolean)
486 * @see #setWantClientAuth(boolean)
487 * @see #getWantClientAuth()
488 * @see #setUseClientMode(boolean)
489 */
490 public abstract boolean getNeedClientAuth();
491
492
493 /**
494 * Configures the socket to <i>request</i> client authentication.
495 * This option is only useful for sockets in the server mode.
496 * <P>
497 * A socket's client authentication setting is one of the following:
498 * <ul>
499 * <li> client authentication required
500 * <li> client authentication requested
501 * <li> no client authentication desired
502 * </ul>
503 * <P>
504 * Unlike {@link #setNeedClientAuth(boolean)}, if this option is set and
505 * the client chooses not to provide authentication information
506 * about itself, <i>the negotiations will continue</i>.
507 * <P>
508 * Calling this method overrides any previous setting made by
509 * this method or {@link #setNeedClientAuth(boolean)}.
510 *
511 * @param want set to true if client authentication is requested,
512 * or false if no client authentication is desired.
513 * @see #getWantClientAuth()
514 * @see #setNeedClientAuth(boolean)
515 * @see #getNeedClientAuth()
516 * @see #setUseClientMode(boolean)
517 */
518 public abstract void setWantClientAuth(boolean want);
519
520
521 /**
522 * Returns true if the socket will <i>request</i> client authentication.
523 * This option is only useful for sockets in the server mode.
524 *
525 * @return true if client authentication is requested,
526 * or false if no client authentication is desired.
527 * @see #setNeedClientAuth(boolean)
528 * @see #getNeedClientAuth()
529 * @see #setWantClientAuth(boolean)
530 * @see #setUseClientMode(boolean)
531 */
532 public abstract boolean getWantClientAuth();
533
534
535 /**
536 * Controls whether new SSL sessions may be established by this socket.
537 * If session creations are not allowed, and there are no
538 * existing sessions to resume, there will be no successful
539 * handshaking.
540 *
541 * @param flag true indicates that sessions may be created; this
542 * is the default. false indicates that an existing session
543 * must be resumed
544 * @see #getEnableSessionCreation()
545 */
546 public abstract void setEnableSessionCreation(boolean flag);
547
548
549 /**
550 * Returns true if new SSL sessions may be established by this socket.
551 *
552 * @return true indicates that sessions may be created; this
553 * is the default. false indicates that an existing session
554 * must be resumed
555 * @see #setEnableSessionCreation(boolean)
556 */
557 public abstract boolean getEnableSessionCreation();
558
559 /**
560 * Returns the SSLParameters in effect for this SSLSocket.
561 * The ciphersuites and protocols of the returned SSLParameters
562 * are always non-null.
563 *
564 * @return the SSLParameters in effect for this SSLSocket.
565 * @since 1.6
566 */
567 public SSLParameters getSSLParameters() {
568 SSLParameters params = new SSLParameters();
569 params.setCipherSuites(getEnabledCipherSuites());
570 params.setProtocols(getEnabledProtocols());
571 if (getNeedClientAuth()) {
572 params.setNeedClientAuth(true);
573 } else if (getWantClientAuth()) {
574 params.setWantClientAuth(true);
575 }
576 return params;
577 }
578
579 /**
580 * Applies SSLParameters to this socket.
581 *
582 * <p>This means:
583 * <ul>
584 * <li>if <code>params.getCipherSuites()</code> is non-null,
585 * <code>setEnabledCipherSuites()</code> is called with that value
586 * <li>if <code>params.getProtocols()</code> is non-null,
587 * <code>setEnabledProtocols()</code> is called with that value
588 * <li>if <code>params.getNeedClientAuth()</code> or
589 * <code>params.getWantClientAuth()</code> return <code>true</code>,
590 * <code>setNeedClientAuth(true)</code> and
591 * <code>setWantClientAuth(true)</code> are called, respectively;
592 * otherwise <code>setWantClientAuth(false)</code> is called.
593 * </ul>
594 *
595 * @param params the parameters
596 * @throws IllegalArgumentException if the setEnabledCipherSuites() or
597 * the setEnabledProtocols() call fails
598 * @since 1.6
599 */
600 public void setSSLParameters(SSLParameters params) {
601 String[] s;
602 s = params.getCipherSuites();
603 if (s != null) {
604 setEnabledCipherSuites(s);
605 }
606 s = params.getProtocols();
607 if (s != null) {
608 setEnabledProtocols(s);
609 }
610 if (params.getNeedClientAuth()) {
611 setNeedClientAuth(true);
612 } else if (params.getWantClientAuth()) {
613 setWantClientAuth(true);
614 } else {
615 setWantClientAuth(false);
616 }
617 }
618
619 }
Save This Page