KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > net > ssl > 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
Popular Tags