SSLServerSocket


1   /*
2    * @(#)SSLServerSocket.java 1.14 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.io.*;
19  import java.net.*;
20  
21  /** 
22   * This class extends <code>ServerSocket</code>s and
23   * provides secure server sockets using protocols such as the Secure
24   * Sockets Layer (SSL) or Transport Layer Security (TLS) protocols.
25   * <P>
26   * Instances of this class are generally created using a
27   * <code>SSLServerSocketFactory</code>.  The primary function
28   * of <code>SSLServerSocket</code>s
29   * is to create <code>SSLSocket</code>s by <code>accept</code>ing
30   * connections.
31   * <P>
32   * <code>SSLServerSocket</code>s contain several pieces of state data
33   * which are inherited by the <code>SSLSocket</code> at
34   * socket creation.  These include the enabled cipher
35   * suites and protocols, whether client
36   * authentication is necessary, and whether created sockets should
37   * begin handshaking in client or server mode.  The state
38   * inherited by the created <code>SSLSocket</code> can be
39   * overriden by calling the appropriate methods.
40   *
41   * @see java.net.ServerSocket
42   * @see SSLSocket
43   *
44   * @since 1.4
45   * @version 1.25
46   * @author David Brownell
47   */
48  public abstract class SSLServerSocket extends ServerSocket
49  {
50  
51      /** 
52       * Used only by subclasses.
53       * <P>
54       * Create an unbound TCP server socket using the default authentication
55       * context.
56       *
57       * @throws IOException if an I/O error occurs when creating the socket
58       */
59      protected SSLServerSocket() throws IOException { }
60  
61      /** 
62       * Used only by subclasses.
63       * <P>
64       * Create a TCP server socket on a port, using the default
65       * authentication context.  The connection backlog defaults to
66       * fifty connections queued up before the system starts to
67       * reject new connection requests.
68       *
69       * @param port the port on which to listen
70       * @throws IOException if an I/O error occurs when creating the socket
71       */
72      protected SSLServerSocket(int port) throws IOException { }
73  
74      /** 
75       * Used only by subclasses.
76       * <P>
77       * Create a TCP server socket on a port, using the default
78       * authentication context and a specified backlog of connections.
79       *
80       * @param port the port on which to listen
81       * @param backlog how many connections may be pending before
82       *      the system should start rejecting new requests
83       * @throws IOException if an I/O error occurs when creating the socket
84       */
85      protected SSLServerSocket(int port, int backlog) throws IOException { }
86  
87      /** 
88       * Used only by subclasses.
89       * <P>
90       * Create a TCP server socket on a port, using the default
91       * authentication context and a specified backlog of connections
92       * as well as a particular specified network interface.  This
93       * constructor is used on multihomed hosts, such as those used
94       * for firewalls or as routers, to control through which interface
95       * a network service is provided.
96       *
97       * @param port the port on which to listen
98       * @param backlog how many connections may be pending before
99       *      the system should start rejecting new requests
100      * @param address the address of the network interface through
101      *      which connections will be accepted
102      * @throws IOException if an I/O error occurs when creating the socket
103      */
104     protected SSLServerSocket(int port, int backlog, InetAddress address)
105         throws IOException
106     { }
107 
108     /** 
109      * Returns the list of cipher suites which are currently enabled
110      * for use by newly accepted connections.
111      * <P>
112      * If this list has not been explicitly modified, a system-provided
113      * default guarantees a minimum quality of service in all enabled
114      * cipher suites.
115      * <P>
116      * There are several reasons why an enabled cipher suite might
117      * not actually be used.  For example:  the server socket might
118      * not have appropriate private keys available to it or the cipher
119      * suite might be anonymous, precluding the use of client authentication,
120      * while the server socket has been told to require that sort of
121      * authentication.
122      *
123      * @return an array of cipher suites enabled
124      * @see #getSupportedCipherSuites()
125      * @see #setEnabledCipherSuites(String [])
126      */
127     public abstract String[] getEnabledCipherSuites();
128 
129     /** 
130      * Sets the cipher suites enabled for use by accepted connections.
131      * <P>
132      * The cipher suites must have been listed by getSupportedCipherSuites()
133      * as being supported.  Following a successful call to this method,
134      * only suites listed in the <code>suites</code> parameter are enabled
135      * for use.
136      * <P>
137      * Suites that require authentication information which is not available
138      * in this ServerSocket's authentication context will not be used
139      * in any case, even if they are enabled.
140      * <P>
141      * <code>SSLSocket</code>s returned from <code>accept()</code>
142      * inherit this setting.
143      *
144      * @param suites Names of all the cipher suites to enable
145      * @exception IllegalArgumentException when one or more of ciphers
146      *      named by the parameter is not supported, or when
147      *      the parameter is null.
148      * @see #getSupportedCipherSuites()
149      * @see #getEnabledCipherSuites()
150      */
151     public abstract void setEnabledCipherSuites(String[] suites);
152 
153     /** 
154      * Returns the names of the cipher suites which could be enabled for use
155      * on an SSL connection.
156      * <P>
157      * Normally, only a subset of these will actually
158      * be enabled by default, since this list may include cipher suites which
159      * do not meet quality of service requirements for those defaults.  Such
160      * cipher suites are useful in specialized applications.
161      *
162      * @return an array of cipher suite names
163      * @see #getEnabledCipherSuites()
164      * @see #setEnabledCipherSuites(String [])
165      */
166     public abstract String[] getSupportedCipherSuites();
167 
168     /** 
169      * Returns the names of the protocols which could be enabled for use.
170      *
171      * @return an array of protocol names supported
172      * @see #getEnabledProtocols()
173      * @see #setEnabledProtocols(String [])
174      */
175     public abstract String[] getSupportedProtocols();
176 
177     /** 
178      * Returns the names of the protocols which are currently
179      * enabled for use by the newly accepted connections.
180      *
181      * @return an array of protocol names
182      * @see #getSupportedProtocols()
183      * @see #setEnabledProtocols(String [])
184      */
185     public abstract String[] getEnabledProtocols();
186 
187     /** 
188      * Controls which particular protocols are enabled for use by
189      * accepted connections.
190      * <P>
191      * The protocols must have been listed by
192      * getSupportedProtocols() as being supported.
193      * Following a successful call to this method, only protocols listed
194      * in the <code>protocols</code> parameter are enabled for use.
195      * <P>
196      * <code>SSLSocket</code>s returned from <code>accept()</code>
197      * inherit this setting.
198      *
199      * @param protocols Names of all the protocols to enable.
200      * @exception IllegalArgumentException when one or more of
201      *        the protocols named by the parameter is not supported or
202      *        when the protocols parameter is null.
203      * @see #getEnabledProtocols()
204      * @see #getSupportedProtocols()
205      */
206     public abstract void setEnabledProtocols(String[] protocols);
207 
208     /** 
209      * Controls whether <code>accept</code>ed server-mode
210      * <code>SSLSockets</code> will be initially configured to
211      * <i>require</i> client authentication.
212      * <P>
213      * A socket's client authentication setting is one of the following:
214      * <ul>
215      * <li> client authentication required
216      * <li> client authentication requested
217      * <li> no client authentication desired
218      * </ul>
219      * <P>
220      * Unlike {@link #setWantClientAuth(boolean)}, if the accepted
221      * socket's option is set and the client chooses not to provide
222      * authentication information about itself, <i>the negotiations
223      * will stop and the connection will be dropped</i>.
224      * <P>
225      * Calling this method overrides any previous setting made by
226      * this method or {@link #setWantClientAuth(boolean)}.
227      * <P>
228      * The initial inherited setting may be overridden by calling
229      * {@link SSLSocket#setNeedClientAuth(boolean)} or
230      * {@link SSLSocket#setWantClientAuth(boolean)}.
231      *
232      * @param   need set to true if client authentication is required,
233      *      or false if no client authentication is desired.
234      * @see #getNeedClientAuth()
235      * @see #setWantClientAuth(boolean)
236      * @see #getWantClientAuth()
237      * @see #setUseClientMode(boolean)
238      */
239     public abstract void setNeedClientAuth(boolean need);
240 
241     /** 
242      * Returns true if client authentication will be <i>required</i> on
243      * newly <code>accept</code>ed server-mode <code>SSLSocket</code>s.
244      * <P>
245      * The initial inherited setting may be overridden by calling
246      * {@link SSLSocket#setNeedClientAuth(boolean)} or
247      * {@link SSLSocket#setWantClientAuth(boolean)}.
248      *
249      * @return  true if client authentication is required,
250      *      or false if no client authentication is desired.
251      * @see #setNeedClientAuth(boolean)
252      * @see #setWantClientAuth(boolean)
253      * @see #getWantClientAuth()
254      * @see #setUseClientMode(boolean)
255      */
256     public abstract boolean getNeedClientAuth();
257 
258     /** 
259      * Controls whether <code>accept</code>ed server-mode
260      * <code>SSLSockets</code> will be initially configured to
261      * <i>request</i> client authentication.
262      * <P>
263      * A socket's client authentication setting is one of the following:
264      * <ul>
265      * <li> client authentication required
266      * <li> client authentication requested
267      * <li> no client authentication desired
268      * </ul>
269      * <P>
270      * Unlike {@link #setNeedClientAuth(boolean)}, if the accepted
271      * socket's option is set and the client chooses not to provide
272      * authentication information about itself, <i>the negotiations
273      * will continue</i>.
274      * <P>
275      * Calling this method overrides any previous setting made by
276      * this method or {@link #setNeedClientAuth(boolean)}.
277      * <P>
278      * The initial inherited setting may be overridden by calling
279      * {@link SSLSocket#setNeedClientAuth(boolean)} or
280      * {@link SSLSocket#setWantClientAuth(boolean)}.
281      *
282      * @param   want set to true if client authentication is requested,
283      *      or false if no client authentication is desired.
284      * @see #getWantClientAuth()
285      * @see #setNeedClientAuth(boolean)
286      * @see #getNeedClientAuth()
287      * @see #setUseClientMode(boolean)
288      */
289     public abstract void setWantClientAuth(boolean want);
290 
291     /** 
292      * Returns true if client authentication will be <i>requested</i> on
293      * newly accepted server-mode connections.
294      * <P>
295      * The initial inherited setting may be overridden by calling
296      * {@link SSLSocket#setNeedClientAuth(boolean)} or
297      * {@link SSLSocket#setWantClientAuth(boolean)}.
298      *
299      * @return  true if client authentication is requested,
300      *      or false if no client authentication is desired.
301      * @see #setWantClientAuth(boolean)
302      * @see #setNeedClientAuth(boolean)
303      * @see #getNeedClientAuth()
304      * @see #setUseClientMode(boolean)
305      */
306     public abstract boolean getWantClientAuth();
307 
308     /** 
309      * Controls whether accepted connections are in the (default) SSL
310      * server mode, or the SSL client mode.
311      * <P>
312      * Servers normally authenticate themselves, and clients are not
313      * required to do so.
314      * <P>
315      * In rare cases, TCP servers
316      * need to act in the SSL client mode on newly accepted
317      * connections. For example, FTP clients acquire server sockets
318      * and listen there for reverse connections from the server. An
319      * FTP client would use an SSLServerSocket in "client" mode to
320      * accept the reverse connection while the FTP server uses an
321      * SSLSocket with "client" mode disabled to initiate the
322      * connection. During the resulting handshake, existing SSL
323      * sessions may be reused.
324      * <P>
325      * <code>SSLSocket</code>s returned from <code>accept()</code>
326      * inherit this setting.
327      *
328      * @param mode true if newly accepted connections should use SSL
329      *      client mode.
330      * @see #getUseClientMode()
331      */
332     public abstract void setUseClientMode(boolean mode);
333 
334     /** 
335      * Returns true if accepted connections will be in SSL client mode.
336      *
337      * @see #setUseClientMode(boolean)
338      * @return true if the connection should use SSL client mode.
339      */
340     public abstract boolean getUseClientMode();
341 
342     /** 
343      * Controls whether new SSL sessions may be established by the
344      * sockets which are created from this server socket.
345      * <P>
346      * <code>SSLSocket</code>s returned from <code>accept()</code>
347      * inherit this setting.
348      *
349      * @param flag true indicates that sessions may be created; this
350      *      is the default. false indicates that an existing session
351      *      must be resumed.
352      * @see #getEnableSessionCreation()
353      */
354     public abstract void setEnableSessionCreation(boolean flag);
355 
356     /** 
357      * Returns true if new SSL sessions may be established by the
358      * sockets which are created from this server socket.
359      *
360      * @return true indicates that sessions may be created; this
361      *      is the default.  false indicates that an existing
362      *      session must be resumed.
363      * @see #setEnableSessionCreation(boolean)
364      */
365     public abstract boolean getEnableSessionCreation();
366 }
367
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Java Books Remove Frame
Popular Tags