1 /*
2 * Copyright (c) 1997, 2018, 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> 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 an
39 * <code>SSLServerSocketFactory</code>. The primary function
40 * of an <code>SSLServerSocket</code>
41 * is to create <code>SSLSocket</code>s by <code>accept</code>ing
42 * connections.
43 * <P>
44 * An <code>SSLServerSocket</code> contains 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 * overridden 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 * Note that even if a suite is enabled, it may never be used. This
194 * can occur if the peer does not support it, or its use is restricted,
195 * or the requisite certificates (and private keys) for the suite are
196 * not available, or an anonymous suite is enabled but authentication
197 * is required.
198 * <P>
199 * The returned array includes cipher suites from the list of standard
200 * cipher suite names in the <a href=
201 * "{@docRoot}/../specs/security/standard-names.html#jsse-cipher-suite-names">
202 * JSSE Cipher Suite Names</a> section of the Java Cryptography
203 * Architecture Standard Algorithm Name Documentation, and may also
204 * include other cipher suites that the provider supports.
205 *
206 * @return an array of cipher suites enabled
207 * @see #getSupportedCipherSuites()
208 * @see #setEnabledCipherSuites(String [])
209 */
210 public abstract String [] getEnabledCipherSuites();
211
212
213 /**
214 * Sets the cipher suites enabled for use by accepted connections.
215 * <P>
216 * The cipher suites must have been listed by getSupportedCipherSuites()
217 * as being supported. Following a successful call to this method,
218 * only suites listed in the <code>suites</code> parameter are enabled
219 * for use.
220 * <P>
221 * Suites that require authentication information which is not available
222 * in this ServerSocket's authentication context will not be used
223 * in any case, even if they are enabled.
224 * <P>
225 * Note that the standard list of cipher suite names may be found in the
226 * <a href=
227 * "{@docRoot}/../specs/security/standard-names.html#jsse-cipher-suite-names">
228 * JSSE Cipher Suite Names</a> section of the Java Cryptography
229 * Architecture Standard Algorithm Name Documentation. Providers
230 * may support cipher suite names not found in this list or might not
231 * use the recommended name for a certain cipher suite.
232 * <P>
233 * <code>SSLSocket</code>s returned from <code>accept()</code>
234 * inherit this setting.
235 *
236 * @param suites Names of all the cipher suites to enable
237 * @exception IllegalArgumentException when one or more of ciphers
238 * named by the parameter is not supported, or when
239 * the parameter is null.
240 * @see #getSupportedCipherSuites()
241 * @see #getEnabledCipherSuites()
242 */
243 public abstract void setEnabledCipherSuites(String[] suites);
244
245
246 /**
247 * Returns the names of the cipher suites which could be enabled for use
248 * on an SSL connection.
249 * <P>
250 * Normally, only a subset of these will actually
251 * be enabled by default, since this list may include cipher suites which
252 * do not meet quality of service requirements for those defaults. Such
253 * cipher suites are useful in specialized applications.
254 * <P>
255 * The returned array includes cipher suites from the list of standard
256 * cipher suite names in the <a href=
257 * "{@docRoot}/../specs/security/standard-names.html#jsse-cipher-suite-names">
258 * JSSE Cipher Suite Names</a> section of the Java Cryptography
259 * Architecture Standard Algorithm Name Documentation, and may also
260 * include other cipher suites that the provider supports.
261 *
262 * @return an array of cipher suite names
263 * @see #getEnabledCipherSuites()
264 * @see #setEnabledCipherSuites(String [])
265 */
266 public abstract String [] getSupportedCipherSuites();
267
268
269 /**
270 * Returns the names of the protocols which could be enabled for use.
271 *
272 * @return an array of protocol names supported
273 * @see #getEnabledProtocols()
274 * @see #setEnabledProtocols(String [])
275 */
276 public abstract String [] getSupportedProtocols();
277
278
279 /**
280 * Returns the names of the protocols which are currently
281 * enabled for use by the newly accepted connections.
282 * <P>
283 * Note that even if a protocol is enabled, it may never be used.
284 * This can occur if the peer does not support the protocol, or its
285 * use is restricted, or there are no enabled cipher suites supported
286 * by the protocol.
287 *
288 * @return an array of protocol names
289 * @see #getSupportedProtocols()
290 * @see #setEnabledProtocols(String [])
291 */
292 public abstract String [] getEnabledProtocols();
293
294
295 /**
296 * Controls which particular protocols are enabled for use by
297 * accepted connections.
298 * <P>
299 * The protocols must have been listed by
300 * getSupportedProtocols() as being supported.
301 * Following a successful call to this method, only protocols listed
302 * in the <code>protocols</code> parameter are enabled for use.
303 * <P>
304 * <code>SSLSocket</code>s returned from <code>accept()</code>
305 * inherit this setting.
306 *
307 * @param protocols Names of all the protocols to enable.
308 * @exception IllegalArgumentException when one or more of
309 * the protocols named by the parameter is not supported or
310 * when the protocols parameter is null.
311 * @see #getEnabledProtocols()
312 * @see #getSupportedProtocols()
313 */
314 public abstract void setEnabledProtocols(String[] protocols);
315
316
317 /**
318 * Controls whether <code>accept</code>ed server-mode
319 * <code>SSLSockets</code> will be initially configured to
320 * <i>require</i> client authentication.
321 * <P>
322 * A socket's client authentication setting is one of the following:
323 * <ul>
324 * <li> client authentication required
325 * <li> client authentication requested
326 * <li> no client authentication desired
327 * </ul>
328 * <P>
329 * Unlike {@link #setWantClientAuth(boolean)}, if the accepted
330 * socket's option is set and the client chooses not to provide
331 * authentication information about itself, <i>the negotiations
332 * will stop and the connection will be dropped</i>.
333 * <P>
334 * Calling this method overrides any previous setting made by
335 * this method or {@link #setWantClientAuth(boolean)}.
336 * <P>
337 * The initial inherited setting may be overridden by calling
338 * {@link SSLSocket#setNeedClientAuth(boolean)} or
339 * {@link SSLSocket#setWantClientAuth(boolean)}.
340 *
341 * @param need set to true if client authentication is required,
342 * or false if no client authentication is desired.
343 * @see #getNeedClientAuth()
344 * @see #setWantClientAuth(boolean)
345 * @see #getWantClientAuth()
346 * @see #setUseClientMode(boolean)
347 */
348 public abstract void setNeedClientAuth(boolean need);
349
350
351 /**
352 * Returns true if client authentication will be <i>required</i> on
353 * newly <code>accept</code>ed server-mode <code>SSLSocket</code>s.
354 * <P>
355 * The initial inherited setting may be overridden by calling
356 * {@link SSLSocket#setNeedClientAuth(boolean)} or
357 * {@link SSLSocket#setWantClientAuth(boolean)}.
358 *
359 * @return true if client authentication is required,
360 * or false if no client authentication is desired.
361 * @see #setNeedClientAuth(boolean)
362 * @see #setWantClientAuth(boolean)
363 * @see #getWantClientAuth()
364 * @see #setUseClientMode(boolean)
365 */
366 public abstract boolean getNeedClientAuth();
367
368
369 /**
370 * Controls whether <code>accept</code>ed server-mode
371 * <code>SSLSockets</code> will be initially configured to
372 * <i>request</i> client authentication.
373 * <P>
374 * A socket's client authentication setting is one of the following:
375 * <ul>
376 * <li> client authentication required
377 * <li> client authentication requested
378 * <li> no client authentication desired
379 * </ul>
380 * <P>
381 * Unlike {@link #setNeedClientAuth(boolean)}, if the accepted
382 * socket's option is set and the client chooses not to provide
383 * authentication information about itself, <i>the negotiations
384 * will continue</i>.
385 * <P>
386 * Calling this method overrides any previous setting made by
387 * this method or {@link #setNeedClientAuth(boolean)}.
388 * <P>
389 * The initial inherited setting may be overridden by calling
390 * {@link SSLSocket#setNeedClientAuth(boolean)} or
391 * {@link SSLSocket#setWantClientAuth(boolean)}.
392 *
393 * @param want set to true if client authentication is requested,
394 * or false if no client authentication is desired.
395 * @see #getWantClientAuth()
396 * @see #setNeedClientAuth(boolean)
397 * @see #getNeedClientAuth()
398 * @see #setUseClientMode(boolean)
399 */
400 public abstract void setWantClientAuth(boolean want);
401
402
403 /**
404 * Returns true if client authentication will be <i>requested</i> on
405 * newly accepted server-mode connections.
406 * <P>
407 * The initial inherited setting may be overridden by calling
408 * {@link SSLSocket#setNeedClientAuth(boolean)} or
409 * {@link SSLSocket#setWantClientAuth(boolean)}.
410 *
411 * @return true if client authentication is requested,
412 * or false if no client authentication is desired.
413 * @see #setWantClientAuth(boolean)
414 * @see #setNeedClientAuth(boolean)
415 * @see #getNeedClientAuth()
416 * @see #setUseClientMode(boolean)
417 */
418 public abstract boolean getWantClientAuth();
419
420
421 /**
422 * Controls whether accepted connections are in the (default) SSL
423 * server mode, or the SSL client mode.
424 * <P>
425 * Servers normally authenticate themselves, and clients are not
426 * required to do so.
427 * <P>
428 * In rare cases, TCP servers
429 * need to act in the SSL client mode on newly accepted
430 * connections. For example, FTP clients acquire server sockets
431 * and listen there for reverse connections from the server. An
432 * FTP client would use an SSLServerSocket in "client" mode to
433 * accept the reverse connection while the FTP server uses an
434 * SSLSocket with "client" mode disabled to initiate the
435 * connection. During the resulting handshake, existing SSL
436 * sessions may be reused.
437 * <P>
438 * <code>SSLSocket</code>s returned from <code>accept()</code>
439 * inherit this setting.
440 *
441 * @param mode true if newly accepted connections should use SSL
442 * client mode.
443 * @see #getUseClientMode()
444 */
445 public abstract void setUseClientMode(boolean mode);
446
447
448 /**
449 * Returns true if accepted connections will be in SSL client mode.
450 *
451 * @see #setUseClientMode(boolean)
452 * @return true if the connection should use SSL client mode.
453 */
454 public abstract boolean getUseClientMode();
455
456
457 /**
458 * Controls whether new SSL sessions may be established by the
459 * sockets which are created from this server socket.
460 * <P>
461 * <code>SSLSocket</code>s returned from <code>accept()</code>
462 * inherit this setting.
463 *
464 * @param flag true indicates that sessions may be created; this
465 * is the default. false indicates that an existing session
466 * must be resumed.
467 * @see #getEnableSessionCreation()
468 */
469 public abstract void setEnableSessionCreation(boolean flag);
470
471
472 /**
473 * Returns true if new SSL sessions may be established by the
474 * sockets which are created from this server socket.
475 *
476 * @return true indicates that sessions may be created; this
477 * is the default. false indicates that an existing
478 * session must be resumed
479 * @see #setEnableSessionCreation(boolean)
480 */
481 public abstract boolean getEnableSessionCreation();
482
483 /**
484 * Returns the SSLParameters in effect for newly accepted connections.
485 * The ciphersuites and protocols of the returned SSLParameters
486 * are always non-null.
487 *
488 * @return the SSLParameters in effect for newly accepted connections
489 *
490 * @see #setSSLParameters(SSLParameters)
491 *
492 * @since 1.7
493 */
494 public SSLParameters getSSLParameters() {
495 SSLParameters parameters = new SSLParameters();
496
497 parameters.setCipherSuites(getEnabledCipherSuites());
498 parameters.setProtocols(getEnabledProtocols());
499 if (getNeedClientAuth()) {
500 parameters.setNeedClientAuth(true);
501 } else if (getWantClientAuth()) {
502 parameters.setWantClientAuth(true);
503 }
504
505 return parameters;
506 }
507
508 /**
509 * Applies SSLParameters to newly accepted connections.
510 *
511 * <p>This means:
512 * <ul>
513 * <li>If {@code params.getCipherSuites()} is non-null,
514 * {@code setEnabledCipherSuites()} is called with that value.</li>
515 * <li>If {@code params.getProtocols()} is non-null,
516 * {@code setEnabledProtocols()} is called with that value.</li>
517 * <li>If {@code params.getNeedClientAuth()} or
518 * {@code params.getWantClientAuth()} return {@code true},
519 * {@code setNeedClientAuth(true)} and
520 * {@code setWantClientAuth(true)} are called, respectively;
521 * otherwise {@code setWantClientAuth(false)} is called.</li>
522 * <li>If {@code params.getServerNames()} is non-null, the socket will
523 * configure its server names with that value.</li>
524 * <li>If {@code params.getSNIMatchers()} is non-null, the socket will
525 * configure its SNI matchers with that value.</li>
526 * </ul>
527 *
528 * @param params the parameters
529 * @throws IllegalArgumentException if the setEnabledCipherSuites() or
530 * the setEnabledProtocols() call fails
531 *
532 * @see #getSSLParameters()
533 *
534 * @since 1.7
535 */
536 public void setSSLParameters(SSLParameters params) {
537 String[] s;
538 s = params.getCipherSuites();
539 if (s != null) {
540 setEnabledCipherSuites(s);
541 }
542
543 s = params.getProtocols();
544 if (s != null) {
545 setEnabledProtocols(s);
546 }
547
548 if (params.getNeedClientAuth()) {
549 setNeedClientAuth(true);
550 } else if (params.getWantClientAuth()) {
551 setWantClientAuth(true);
552 } else {
553 setWantClientAuth(false);
554 }
555 }
556
557 }