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