1 /*
2 * Copyright (c) 1997, 2010, Oracle and/or its affiliates. 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. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * 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 is the requested maximum number of
112 * pending connections on the socket. Its exact semantics are implementation
113 * specific. In particular, an implementation may impose a maximum length
114 * or may choose to ignore the parameter altogther. The value provided
115 * should be greater than <code>0</code>. If it is less than or equal to
116 * <code>0</code>, then an implementation specific default will be used.
117 * <P>
118 * If there is a security manager, its <code>checkListen</code>
119 * method is called with the <code>port</code> argument as its
120 * argument to ensure the operation is allowed. This could result
121 * in a SecurityException.
122 *
123 * @param port the port on which to listen
124 * @param backlog requested maximum length of the queue of incoming
125 * connections.
126 * @throws IOException if an I/O error occurs when creating the socket
127 * @throws SecurityException if a security manager exists and its
128 * <code>checkListen</code> method doesn't allow the operation.
129 * @throws IllegalArgumentException if the port parameter is outside the
130 * specified range of valid port values, which is between 0 and
131 * 65535, inclusive.
132 * @see SecurityManager#checkListen
133 */
134 protected SSLServerSocket(int port, int backlog)
135 throws IOException
136 { super(port, backlog); }
137
138
139 /**
140 * Used only by subclasses.
141 * <P>
142 * Create a TCP server socket on a port, using the default
143 * authentication context and a specified backlog of connections
144 * as well as a particular specified network interface. This
145 * constructor is used on multihomed hosts, such as those used
146 * for firewalls or as routers, to control through which interface
147 * a network service is provided.
148 * <P>
149 * If there is a security manager, its <code>checkListen</code>
150 * method is called with the <code>port</code> argument as its
151 * argument to ensure the operation is allowed. This could result
152 * in a SecurityException.
153 * <P>
154 * A port number of <code>0</code> creates a socket on any free port.
155 * <P>
156 * The <code>backlog</code> argument is the requested maximum number of
157 * pending connections on the socket. Its exact semantics are implementation
158 * specific. In particular, an implementation may impose a maximum length
159 * or may choose to ignore the parameter altogther. The value provided
160 * should be greater than <code>0</code>. If it is less than or equal to
161 * <code>0</code>, then an implementation specific default will be used.
162 * <P>
163 * If <i>address</i> is null, it will default accepting connections
164 * on any/all local addresses.
165 *
166 * @param port the port on which to listen
167 * @param backlog requested maximum length of the queue of incoming
168 * connections.
169 * @param address the address of the network interface through
170 * which connections will be accepted
171 * @throws IOException if an I/O error occurs when creating the socket
172 * @throws SecurityException if a security manager exists and its
173 * <code>checkListen</code> method doesn't allow the operation.
174 * @throws IllegalArgumentException if the port parameter is outside the
175 * specified range of valid port values, which is between 0 and
176 * 65535, inclusive.
177 * @see SecurityManager#checkListen
178 */
179 protected SSLServerSocket(int port, int backlog, InetAddress address)
180 throws IOException
181 { super(port, backlog, address); }
182
183
184
185 /**
186 * Returns the list of cipher suites which are currently enabled
187 * for use by newly accepted connections.
188 * <P>
189 * If this list has not been explicitly modified, a system-provided
190 * default guarantees a minimum quality of service in all enabled
191 * cipher suites.
192 * <P>
193 * There are several reasons why an enabled cipher suite might
194 * not actually be used. For example: the server socket might
195 * not have appropriate private keys available to it or the cipher
196 * suite might be anonymous, precluding the use of client authentication,
197 * while the server socket has been told to require that sort of
198 * authentication.
199 *
200 * @return an array of cipher suites enabled
201 * @see #getSupportedCipherSuites()
202 * @see #setEnabledCipherSuites(String [])
203 */
204 public abstract String [] getEnabledCipherSuites();
205
206
207 /**
208 * Sets the cipher suites enabled for use by accepted connections.
209 * <P>
210 * The cipher suites must have been listed by getSupportedCipherSuites()
211 * as being supported. Following a successful call to this method,
212 * only suites listed in the <code>suites</code> parameter are enabled
213 * for use.
214 * <P>
215 * Suites that require authentication information which is not available
216 * in this ServerSocket's authentication context will not be used
217 * in any case, even if they are enabled.
218 * <P>
219 * <code>SSLSocket</code>s returned from <code>accept()</code>
220 * inherit this setting.
221 *
222 * @param suites Names of all the cipher suites to enable
223 * @exception IllegalArgumentException when one or more of ciphers
224 * named by the parameter is not supported, or when
225 * the parameter is null.
226 * @see #getSupportedCipherSuites()
227 * @see #getEnabledCipherSuites()
228 */
229 public abstract void setEnabledCipherSuites(String suites []);
230
231
232 /**
233 * Returns the names of the cipher suites which could be enabled for use
234 * on an SSL connection.
235 * <P>
236 * Normally, only a subset of these will actually
237 * be enabled by default, since this list may include cipher suites which
238 * do not meet quality of service requirements for those defaults. Such
239 * cipher suites are useful in specialized applications.
240 *
241 * @return an array of cipher suite names
242 * @see #getEnabledCipherSuites()
243 * @see #setEnabledCipherSuites(String [])
244 */
245 public abstract String [] getSupportedCipherSuites();
246
247
248 /**
249 * Returns the names of the protocols which could be enabled for use.
250 *
251 * @return an array of protocol names supported
252 * @see #getEnabledProtocols()
253 * @see #setEnabledProtocols(String [])
254 */
255 public abstract String [] getSupportedProtocols();
256
257
258 /**
259 * Returns the names of the protocols which are currently
260 * enabled for use by the newly accepted connections.
261 *
262 * @return an array of protocol names
263 * @see #getSupportedProtocols()
264 * @see #setEnabledProtocols(String [])
265 */
266 public abstract String [] getEnabledProtocols();
267
268
269 /**
270 * Controls which particular protocols are enabled for use by
271 * accepted connections.
272 * <P>
273 * The protocols must have been listed by
274 * getSupportedProtocols() as being supported.
275 * Following a successful call to this method, only protocols listed
276 * in the <code>protocols</code> parameter are enabled for use.
277 * <P>
278 * <code>SSLSocket</code>s returned from <code>accept()</code>
279 * inherit this setting.
280 *
281 * @param protocols Names of all the protocols to enable.
282 * @exception IllegalArgumentException when one or more of
283 * the protocols named by the parameter is not supported or
284 * when the protocols parameter is null.
285 * @see #getEnabledProtocols()
286 * @see #getSupportedProtocols()
287 */
288 public abstract void setEnabledProtocols(String protocols[]);
289
290
291 /**
292 * Controls whether <code>accept</code>ed server-mode
293 * <code>SSLSockets</code> will be initially configured to
294 * <i>require</i> client authentication.
295 * <P>
296 * A socket's client authentication setting is one of the following:
297 * <ul>
298 * <li> client authentication required
299 * <li> client authentication requested
300 * <li> no client authentication desired
301 * </ul>
302 * <P>
303 * Unlike {@link #setWantClientAuth(boolean)}, if the accepted
304 * socket's option is set and the client chooses not to provide
305 * authentication information about itself, <i>the negotiations
306 * will stop and the connection will be dropped</i>.
307 * <P>
308 * Calling this method overrides any previous setting made by
309 * this method or {@link #setWantClientAuth(boolean)}.
310 * <P>
311 * The initial inherited setting may be overridden by calling
312 * {@link SSLSocket#setNeedClientAuth(boolean)} or
313 * {@link SSLSocket#setWantClientAuth(boolean)}.
314 *
315 * @param need set to true if client authentication is required,
316 * or false if no client authentication is desired.
317 * @see #getNeedClientAuth()
318 * @see #setWantClientAuth(boolean)
319 * @see #getWantClientAuth()
320 * @see #setUseClientMode(boolean)
321 */
322 public abstract void setNeedClientAuth(boolean need);
323
324
325 /**
326 * Returns true if client authentication will be <i>required</i> on
327 * newly <code>accept</code>ed server-mode <code>SSLSocket</code>s.
328 * <P>
329 * The initial inherited setting may be overridden by calling
330 * {@link SSLSocket#setNeedClientAuth(boolean)} or
331 * {@link SSLSocket#setWantClientAuth(boolean)}.
332 *
333 * @return true if client authentication is required,
334 * or false if no client authentication is desired.
335 * @see #setNeedClientAuth(boolean)
336 * @see #setWantClientAuth(boolean)
337 * @see #getWantClientAuth()
338 * @see #setUseClientMode(boolean)
339 */
340 public abstract boolean getNeedClientAuth();
341
342
343 /**
344 * Controls whether <code>accept</code>ed server-mode
345 * <code>SSLSockets</code> will be initially configured to
346 * <i>request</i> client authentication.
347 * <P>
348 * A socket's client authentication setting is one of the following:
349 * <ul>
350 * <li> client authentication required
351 * <li> client authentication requested
352 * <li> no client authentication desired
353 * </ul>
354 * <P>
355 * Unlike {@link #setNeedClientAuth(boolean)}, if the accepted
356 * socket's option is set and the client chooses not to provide
357 * authentication information about itself, <i>the negotiations
358 * will continue</i>.
359 * <P>
360 * Calling this method overrides any previous setting made by
361 * this method or {@link #setNeedClientAuth(boolean)}.
362 * <P>
363 * The initial inherited setting may be overridden by calling
364 * {@link SSLSocket#setNeedClientAuth(boolean)} or
365 * {@link SSLSocket#setWantClientAuth(boolean)}.
366 *
367 * @param want set to true if client authentication is requested,
368 * or false if no client authentication is desired.
369 * @see #getWantClientAuth()
370 * @see #setNeedClientAuth(boolean)
371 * @see #getNeedClientAuth()
372 * @see #setUseClientMode(boolean)
373 */
374 public abstract void setWantClientAuth(boolean want);
375
376
377 /**
378 * Returns true if client authentication will be <i>requested</i> on
379 * newly accepted server-mode connections.
380 * <P>
381 * The initial inherited setting may be overridden by calling
382 * {@link SSLSocket#setNeedClientAuth(boolean)} or
383 * {@link SSLSocket#setWantClientAuth(boolean)}.
384 *
385 * @return true if client authentication is requested,
386 * or false if no client authentication is desired.
387 * @see #setWantClientAuth(boolean)
388 * @see #setNeedClientAuth(boolean)
389 * @see #getNeedClientAuth()
390 * @see #setUseClientMode(boolean)
391 */
392 public abstract boolean getWantClientAuth();
393
394
395 /**
396 * Controls whether accepted connections are in the (default) SSL
397 * server mode, or the SSL client mode.
398 * <P>
399 * Servers normally authenticate themselves, and clients are not
400 * required to do so.
401 * <P>
402 * In rare cases, TCP servers
403 * need to act in the SSL client mode on newly accepted
404 * connections. For example, FTP clients acquire server sockets
405 * and listen there for reverse connections from the server. An
406 * FTP client would use an SSLServerSocket in "client" mode to
407 * accept the reverse connection while the FTP server uses an
408 * SSLSocket with "client" mode disabled to initiate the
409 * connection. During the resulting handshake, existing SSL
410 * sessions may be reused.
411 * <P>
412 * <code>SSLSocket</code>s returned from <code>accept()</code>
413 * inherit this setting.
414 *
415 * @param mode true if newly accepted connections should use SSL
416 * client mode.
417 * @see #getUseClientMode()
418 */
419 public abstract void setUseClientMode(boolean mode);
420
421
422 /**
423 * Returns true if accepted connections will be in SSL client mode.
424 *
425 * @see #setUseClientMode(boolean)
426 * @return true if the connection should use SSL client mode.
427 */
428 public abstract boolean getUseClientMode();
429
430
431 /**
432 * Controls whether new SSL sessions may be established by the
433 * sockets which are created from this server socket.
434 * <P>
435 * <code>SSLSocket</code>s returned from <code>accept()</code>
436 * inherit this setting.
437 *
438 * @param flag true indicates that sessions may be created; this
439 * is the default. false indicates that an existing session
440 * must be resumed.
441 * @see #getEnableSessionCreation()
442 */
443 public abstract void setEnableSessionCreation(boolean flag);
444
445
446 /**
447 * Returns true if new SSL sessions may be established by the
448 * sockets which are created from this server socket.
449 *
450 * @return true indicates that sessions may be created; this
451 * is the default. false indicates that an existing
452 * session must be resumed
453 * @see #setEnableSessionCreation(boolean)
454 */
455 public abstract boolean getEnableSessionCreation();
456
457 /**
458 * Returns the SSLParameters in effect for newly accepted connections.
459 * The ciphersuites and protocols of the returned SSLParameters
460 * are always non-null.
461 *
462 * @return the SSLParameters in effect for newly accepted connections
463 *
464 * @see #setSSLParameters(SSLParameters)
465 *
466 * @since 1.7
467 */
468 public SSLParameters getSSLParameters() {
469 SSLParameters parameters = new SSLParameters();
470
471 parameters.setCipherSuites(getEnabledCipherSuites());
472 parameters.setProtocols(getEnabledProtocols());
473 if (getNeedClientAuth()) {
474 parameters.setNeedClientAuth(true);
475 } else if (getWantClientAuth()) {
476 parameters.setWantClientAuth(true);
477 }
478
479 return parameters;
480 }
481
482 /**
483 * Applies SSLParameters to newly accepted connections.
484 *
485 * <p>This means:
486 * <ul>
487 * <li>if <code>params.getCipherSuites()</code> is non-null,
488 * <code>setEnabledCipherSuites()</code> is called with that value
489 * <li>if <code>params.getProtocols()</code> is non-null,
490 * <code>setEnabledProtocols()</code> is called with that value
491 * <li>if <code>params.getNeedClientAuth()</code> or
492 * <code>params.getWantClientAuth()</code> return <code>true</code>,
493 * <code>setNeedClientAuth(true)</code> and
494 * <code>setWantClientAuth(true)</code> are called, respectively;
495 * otherwise <code>setWantClientAuth(false)</code> is called.
496 * </ul>
497 *
498 * @param params the parameters
499 * @throws IllegalArgumentException if the setEnabledCipherSuites() or
500 * the setEnabledProtocols() call fails
501 *
502 * @see #getSSLParameters()
503 *
504 * @since 1.7
505 */
506 public void setSSLParameters(SSLParameters params) {
507 String[] s;
508 s = params.getCipherSuites();
509 if (s != null) {
510 setEnabledCipherSuites(s);
511 }
512
513 s = params.getProtocols();
514 if (s != null) {
515 setEnabledProtocols(s);
516 }
517
518 if (params.getNeedClientAuth()) {
519 setNeedClientAuth(true);
520 } else if (params.getWantClientAuth()) {
521 setWantClientAuth(true);
522 } else {
523 setWantClientAuth(false);
524 }
525 }
526
527 }