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