SSLSocket


1   /*
2    * @(#)SSLSocket.java   1.13 04/06/01
3    *
4    * Copyright (c) 2004 Sun Microsystems, Inc. All Rights Reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL.  Use is subject to license terms.
6    */
7     
8   /*
9    * NOTE:
10   * Because of various external restrictions (i.e. US export
11   * regulations, etc.), the actual source code can not be provided
12   * at this time. This file represents the skeleton of the source
13   * file, so that javadocs of the API can be created.
14   */
15  
16  package javax.net.ssl;
17  
18  import java.net.*;
19  
20  import java.io.IOException;
21  import java.util.Enumeration;
22  import java.util.Vector;
23  
24  /** 
25   * This class extends <code>Socket</code>s and provides secure
26   * socket using protocols such as the "Secure
27   * Sockets Layer" (SSL) or IETF "Transport Layer Security" (TLS) protocols.
28   * <P>
29   * Such sockets are normal stream sockets, but they
30   * add a layer of security protections over the underlying network transport
31   * protocol, such as TCP.  Those protections include: <UL>
32   *
33   *  <LI> <em>Integrity Protection</em>.  SSL protects against
34   *  modification of messages by an active wiretapper.
35   *
36   *  <LI> <em>Authentication</em>.  In most modes, SSL provides
37   *  peer authentication.  Servers are usually authenticated,
38   *  and clients may be authenticated as requested by servers.
39   *
40   *  <LI> <em>Confidentiality (Privacy Protection)</em>.  In most
41   *  modes, SSL encrypts data being sent between client and server.
42   *  This protects the confidentiality of data, so that passive
43   *  wiretappers won't see sensitive data such as financial
44   *  information or personal information of many kinds.
45   *
46   *  </UL>
47   *
48   * <P>These kinds of protection are specified by a "cipher suite", which
49   * is a combination of cryptographic algorithms used by a given SSL connection.
50   * During the negotiation process, the two endpoints must agree on
51   * a ciphersuite that is available in both environments.
52   * If there is no such suite in common, no SSL connection can
53   * be established, and no data can be exchanged.
54   *
55   * <P> The cipher suite used is established by a negotiation process
56   * called "handshaking".  The goal of this
57   * process is to create or rejoin a "session", which may protect many
58   * connections over time.  After handshaking has completed, you can access
59   * session attributes by using the <em>getSession</em> method.
60   * The initial handshake on this connection can be initiated in
61   * one of three ways: <UL>
62   *
63   *      <LI> calling <code>startHandshake</code> which explicitly
64   *      begins handshakes, or
65   *      <LI> any attempt to read or write application data on
66   *      this socket causes an implicit handshake, or
67   *      <LI> a call to <code>getSession</code> tries to set up a session
68   *      if there is no currently valid session, and
69   *      an implicit handshake is done.
70   * </UL>
71   *
72   * <P>If handshaking fails for any reason, the <code>SSLSocket</code>
73   * is closed, and no futher communications can be done.
74   *
75   * <P>There are two groups of cipher suites which you will need to know
76   * about when managing cipher suites: <UL>
77   *
78   *  <LI> <em>Supported</em> cipher suites:  all the suites which are
79   *  supported by the SSL implementation.  This list is reported
80   *  using <em>getSupportedCipherSuites</em>.
81   *
82   *  <LI> <em>Enabled</em> cipher suites, which may be fewer
83   *  than the full set of supported suites.  This group is
84   *  set using the <em>setEnabledCipherSuites</em> method, and
85   *  queried using the <em>getEnabledCipherSuites</em> method.
86   *  Initially, a default set of cipher suites will be enabled on
87   *      a new socket that represents the minimum suggested configuration.
88   *
89   *  </UL>
90   *
91   * <P> Implementation defaults require that only cipher
92   * suites which authenticate servers and provide confidentiality
93   * be enabled by default.
94   * Only if both sides explicitly agree to unauthenticated and/or
95   * non-private (unencrypted) communications will such a ciphersuite be
96   * selected.
97   *
98   * <P>When <code>SSLSocket</code>s are first created, no handshaking
99   * is done so that applications may first set their communication
100  * preferences:  what cipher suites to use, whether the socket should be
101  * in client or server mode, etc.
102  * However, security is always provided by the time that application data
103  * is sent over the connection.
104  *
105  * <P> You may register to receive event notification of handshake
106  * completion.  This involves
107  * the use of two additional classes.  <em>HandshakeCompletedEvent</em>
108  * objects are passed to <em>HandshakeCompletedListener</em> instances,
109  * which are registered by users of this API.
110  *
111  * <code>SSLSocket</code>s are created by <code>SSLSocketFactory</code>s,
112  * or by <code>accept</code>ing a connection from a
113  * <code>SSLServerSocket</code>.
114  *
115  * <P>A SSL socket must choose to operate in the client or server mode.
116  * This will determine who begins the handshaking process, as well
117  * as which messages should be sent by each party.  Each
118  * connection must have one client and one server, or handshaking
119  * will not progress properly.  Once the initial handshaking has started, a
120  * socket can not switch between client and server modes, even when
121  * performing renegotiations.
122  *
123  * @see java.net.Socket
124  * @see SSLServerSocket
125  * @see SSLSocketFactory
126  *
127  * @since 1.4
128  * @version 1.28
129  * @author David Brownell
130  */
131 public abstract class SSLSocket extends Socket
132 {
133 
134     /** 
135      * Used only by subclasses.
136      * Constructs an uninitialized, unconnected TCP socket.
137      */
138     protected SSLSocket() { }
139 
140     /** 
141      * Used only by subclasses.
142      * Constructs a TCP connection to a named host at a specified port.
143      * This acts as the SSL client.
144      *
145      * @param host name of the host with which to connect
146      * @param port number of the server's port
147      * @throws IOException if an I/O error occurs when creating the socket
148      * @throws UnknownHostException if the host is not known
149      */
150     protected SSLSocket(String host, int port)
151         throws IOException, UnknownHostException
152     { }
153 
154     /** 
155      * Used only by subclasses.
156      * Constructs a TCP connection to a server at a specified address
157      * and port.  This acts as the SSL client.
158      *
159      * @param address the server's host
160      * @param port its port
161      * @throws IOException if an I/O error occurs when creating the socket
162      */
163     protected SSLSocket(InetAddress address, int port) throws IOException { }
164 
165     /** 
166      * Used only by subclasses.
167      * Constructs an SSL connection to a named host at a specified port,
168      * binding the client side of the connection a given address and port.
169      * This acts as the SSL client.
170      *
171      * @param host name of the host with which to connect
172      * @param port number of the server's port
173      * @param clientAddress the client's host
174      * @param clientPort number of the client's port
175      * @throws IOException if an I/O error occurs when creating the socket
176      * @throws UnknownHostException if the host is not known
177      */
178     protected SSLSocket(String host, int port, InetAddress clientAddress, int
179         clientPort) throws IOException, UnknownHostException
180     { }
181 
182     /** 
183      * Used only by subclasses.
184      * Constructs an SSL connection to a server at a specified address
185      * and TCP port, binding the client side of the connection a given
186      * address and port.  This acts as the SSL client.
187      *
188      * @param address the server's host
189      * @param port its port
190      * @param clientAddress the client's host
191      * @param clientPort number of the client's port
192      * @throws IOException if an I/O error occurs when creating the socket
193      */
194     protected SSLSocket(InetAddress address, int port, InetAddress
195         clientAddress, int clientPort) throws IOException
196     { }
197 
198     /** 
199      * Returns the names of the cipher suites which could be enabled for use
200      * on this connection.  Normally, only a subset of these will actually
201      * be enabled by default, since this list may include cipher suites which
202      * do not meet quality of service requirements for those defaults.  Such
203      * cipher suites might be useful in specialized applications.
204      *
205      * @return an array of cipher suite names
206      * @see #getEnabledCipherSuites()
207      * @see #setEnabledCipherSuites(String [])
208      */
209     public abstract String[] getSupportedCipherSuites();
210 
211     /** 
212      * Returns the names of the SSL cipher suites which are currently
213      * enabled for use on this connection.  When an SSLSocket is first
214      * created, all enabled cipher suites support a minimum quality of
215      * service.  Thus, in some environments this value might be empty.
216      * <P>
217      * Even if a suite has been enabled, it might never be used.  (For
218      * example, the peer does not support it, the requisite certificates
219      * (and private keys) for the suite are not available, or an
220      * anonymous suite is enabled but authentication is required.
221      *
222      * @return an array of cipher suite names
223      * @see #getSupportedCipherSuites()
224      * @see #setEnabledCipherSuites(String [])
225      */
226     public abstract String[] getEnabledCipherSuites();
227 
228     /** 
229      * Sets the cipher suites enabled for use on this connection.
230      * <P>
231      * Each cipher suite in the <code>suites</code> parameter must have
232      * been listed by getSupportedCipherSuites(), or the method will
233      * fail.  Following a successful call to this method, only suites
234      * listed in the <code>suites</code> parameter are enabled for use.
235      * <P>
236      * See {@link #getEnabledCipherSuites()} for more information
237      * on why a specific ciphersuite may never be used on a connection.
238      *
239      * @param suites Names of all the cipher suites to enable
240      * @throws IllegalArgumentException when one or more of the ciphers
241      *      named by the parameter is not supported, or when the
242      *      parameter is null.
243      * @see #getSupportedCipherSuites()
244      * @see #getEnabledCipherSuites()
245      */
246     public abstract void setEnabledCipherSuites(String[] suites);
247 
248     /** 
249      * Returns the names of the protocols which could be enabled for use
250      * on an SSL connection.
251      *
252      * @return an array of protocols supported
253      */
254     public abstract String[] getSupportedProtocols();
255 
256     /** 
257      * Returns the names of the protocol versions which are currently
258      * enabled for use on this connection.
259      * @see #setEnabledProtocols(String [])
260      * @return an array of protocols
261      */
262     public abstract String[] getEnabledProtocols();
263 
264     /** 
265      * Sets the protocol versions enabled for use on this connection.
266      * <P>
267      * The protocols must have been listed by
268      * <code>getSupportedProtocols()</code> as being supported.
269      * Following a successful call to this method, only protocols listed
270      * in the <code>protocols</code> parameter are enabled for use.
271      *
272      * @param protocols Names of all the protocols to enable.
273      * @throws IllegalArgumentException when one or more of
274      *        the protocols named by the parameter is not supported or
275      *        when the protocols parameter is null.
276      * @see #getEnabledProtocols()
277      */
278     public abstract void setEnabledProtocols(String[] protocols);
279 
280     /** 
281      * Returns the SSL Session in use by this connection.  These can
282      * be long lived, and frequently correspond to an entire login session
283      * for some user.  The session specifies a particular cipher suite
284      * which is being actively used by all connections in that session,
285      * as well as the identities of the session's client and server.
286      * <P>
287      * This method will initiate the initial handshake if
288      * necessary and then block until the handshake has been
289      * established.
290      * <P>
291      * If an error occurs during the initial handshake, this method
292      * returns an invalid session object which reports an invalid
293      * cipher suite of "SSL_NULL_WITH_NULL_NULL".
294      *
295      * @return the <code>SSLSession</code>
296      */
297     public abstract SSLSession getSession();
298 
299     /** 
300      * Registers an event listener to receive notifications that an
301      * SSL handshake has completed on this connection.
302      *
303      * @param listener the HandShake Completed event listener
304      * @see #startHandshake()
305      * @see #removeHandshakeCompletedListener(HandshakeCompletedListener)
306      * @throws IllegalArgumentException if the argument is null.
307      */
308     public abstract void
309         addHandshakeCompletedListener(HandshakeCompletedListener listener);
310 
311     /** 
312      * Removes a previously registered handshake completion listener.
313      *
314      * @param listener the HandShake Completed event listener
315      * @throws IllegalArgumentException if the listener is not registered,
316      * or the argument is null.
317      * @see #addHandshakeCompletedListener(HandshakeCompletedListener)
318      */
319     public abstract void
320         removeHandshakeCompletedListener(HandshakeCompletedListener listener);
321 
322     /** 
323      * Starts an SSL handshake on this connection.  Common reasons include
324      * a need to use new encryption keys, to change cipher suites, or to
325      * initiate a new session.  To force complete reauthentication, the
326      * current session could be invalidated before starting this handshake.
327      *
328      * <P> If data has already been sent on the connection, it continues
329      * to flow during this handshake.  When the handshake completes, this
330      * will be signaled with an event.
331      *
332      * This method is synchronous for the initial handshake on a connection
333      * and returns when the negotiated handshake is complete. Some
334      * protocols may not support multiple handshakes on an existing socket
335      * and may throw an IOException.
336      *
337      * @throws IOException on a network level error
338      * @see #addHandshakeCompletedListener(HandshakeCompletedListener)
339      */
340     public abstract void startHandshake() throws IOException;
341 
342     /** 
343      * Configures the socket to use client (or server) mode when
344      * handshaking.
345      * <P>
346      * This method must be called before any handshaking occurs.
347      * Once handshaking has begun, the mode can not be reset for the
348      * life of this socket.
349      * <P>
350      * Servers normally authenticate themselves, and clients
351      * are not required to do so.
352      *
353      * @param mode true if the socket should start its handshaking
354      *      in "client" mode
355      * @throws IllegalArgumentException if a mode change is attempted
356      *      after the initial handshake has begun.
357      * @see #getUseClientMode()
358      */
359     public abstract void setUseClientMode(boolean mode);
360 
361     /** 
362      * Returns true if the socket is set to use client mode when
363      * handshaking.
364      *
365      * @return true if the socket should do handshaking
366      *      in "client" mode
367      * @see #setUseClientMode(boolean)
368      */
369     public abstract boolean getUseClientMode();
370 
371     /** 
372      * Configures the socket to <i>require</i> client authentication.  This
373      * option is only useful for sockets in the server mode.
374      * <P>
375      * A socket's client authentication setting is one of the following:
376      * <ul>
377      * <li> client authentication required
378      * <li> client authentication requested
379      * <li> no client authentication desired
380      * </ul>
381      * <P>
382      * Unlike {@link #setWantClientAuth(boolean)}, if this option is set and
383      * the client chooses not to provide authentication information
384      * about itself, <i>the negotiations will stop and the connection
385      * will be dropped</i>.
386      * <P>
387      * Calling this method overrides any previous setting made by
388      * this method or {@link #setWantClientAuth(boolean)}.
389      *
390      * @param   need set to true if client authentication is required,
391      *      or false if no client authentication is desired.
392      * @see #getNeedClientAuth()
393      * @see #setWantClientAuth(boolean)
394      * @see #getWantClientAuth()
395      * @see #setUseClientMode(boolean)
396      */
397     public abstract void setNeedClientAuth(boolean need);
398 
399     /** 
400      * Returns true if the socket will <i>require</i> client authentication.
401      * This option is only useful to sockets in the server mode.
402      *
403      * @return  true if client authentication is required,
404      *      or false if no client authentication is desired.
405      * @see #setNeedClientAuth(boolean)
406      * @see #setWantClientAuth(boolean)
407      * @see #getWantClientAuth()
408      * @see #setUseClientMode(boolean)
409      */
410     public abstract boolean getNeedClientAuth();
411 
412     /** 
413      * Configures the socket to <i>request</i> client authentication.
414      * This option is only useful for sockets in the server mode.
415      * <P>
416      * A socket's client authentication setting is one of the following:
417      * <ul>
418      * <li> client authentication required
419      * <li> client authentication requested
420      * <li> no client authentication desired
421      * </ul>
422      * <P>
423      * Unlike {@link #setNeedClientAuth(boolean)}, if this option is set and
424      * the client chooses not to provide authentication information
425      * about itself, <i>the negotiations will continue</i>.
426      * <P>
427      * Calling this method overrides any previous setting made by
428      * this method or {@link #setNeedClientAuth(boolean)}.
429      *
430      * @param   want set to true if client authentication is requested,
431      *      or false if no client authentication is desired.
432      * @see #getWantClientAuth()
433      * @see #setNeedClientAuth(boolean)
434      * @see #getNeedClientAuth()
435      * @see #setUseClientMode(boolean)
436      */
437     public abstract void setWantClientAuth(boolean want);
438 
439     /** 
440      * Returns true if the socket will <i>request</i> client authentication.
441      * This option is only useful for sockets in the server mode.
442      *
443      * @return  true if client authentication is requested,
444      *      or false if no client authentication is desired.
445      * @see #setNeedClientAuth(boolean)
446      * @see #getNeedClientAuth()
447      * @see #setWantClientAuth(boolean)
448      * @see #setUseClientMode(boolean)
449      */
450     public abstract boolean getWantClientAuth();
451 
452     /** 
453      * Controls whether new SSL sessions may be established by this socket.
454      * If session creations are not allowed, and there are no
455      * existing sessions to resume, there will be no successful
456      * handshaking.
457      *
458      * @param flag true indicates that sessions may be created; this
459      *      is the default.  false indicates that an existing session
460      *      must be resumed
461      * @see #getEnableSessionCreation()
462      */
463     public abstract void setEnableSessionCreation(boolean flag);
464 
465     /** 
466      * Returns true if new SSL sessions may be established by this socket.
467      *
468      * @return true indicates that sessions may be created; this
469      *      is the default.  false indicates that an existing session
470      *      must be resumed
471      * @see #setEnableSessionCreation(boolean)
472      */
473     public abstract boolean getEnableSessionCreation();
474 }
475
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Java Books Remove Frame
Popular Tags