1 /* 2 * Copyright (c) 1997, 2012, 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 */ SSLServerSocket()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 */ SSLServerSocket(int port)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 */ SSLServerSocket(int port, int backlog)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 */ SSLServerSocket(int port, int backlog, InetAddress address)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 */ getEnabledCipherSuites()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 */ setEnabledCipherSuites(String suites [])229 public abstract void setEnabledCipherSuites(String suites []); 230 231 232 // Android-changed: Added warnings about misuse 233 /** 234 * Returns the names of the cipher suites which could be enabled for use 235 * on an SSL connection. 236 * <P> 237 * Normally, only a subset of these will actually 238 * be enabled by default, since this list may include cipher suites which 239 * do not meet quality of service requirements for those defaults. Such 240 * cipher suites are useful in specialized applications. 241 * 242 * <p class="caution">Applications should not blindly enable all supported 243 * cipher suites. The supported cipher suites can include signaling cipher suite 244 * values that can cause connection problems if enabled inappropriately. 245 * 246 * <p>The proper way to use this method is to either check if a specific cipher 247 * suite is supported via {@code Arrays.asList(getSupportedCipherSuites()).contains(...)} 248 * or to filter a desired list of cipher suites to only the supported ones via 249 * {@code desiredSuiteSet.retainAll(Arrays.asList(getSupportedCipherSuites()))}. 250 * 251 * @return an array of cipher suite names 252 * @see #getEnabledCipherSuites() 253 * @see #setEnabledCipherSuites(String []) 254 */ getSupportedCipherSuites()255 public abstract String [] getSupportedCipherSuites(); 256 257 258 /** 259 * Returns the names of the protocols which could be enabled for use. 260 * 261 * @return an array of protocol names supported 262 * @see #getEnabledProtocols() 263 * @see #setEnabledProtocols(String []) 264 */ getSupportedProtocols()265 public abstract String [] getSupportedProtocols(); 266 267 268 /** 269 * Returns the names of the protocols which are currently 270 * enabled for use by the newly accepted connections. 271 * 272 * @return an array of protocol names 273 * @see #getSupportedProtocols() 274 * @see #setEnabledProtocols(String []) 275 */ getEnabledProtocols()276 public abstract String [] getEnabledProtocols(); 277 278 279 // Android-added: Added paragraph about contiguous protocols. 280 /** 281 * Controls which particular protocols are enabled for use by 282 * accepted connections. 283 * <P> 284 * The protocols must have been listed by 285 * getSupportedProtocols() as being supported. 286 * Following a successful call to this method, only protocols listed 287 * in the <code>protocols</code> parameter are enabled for use. 288 * <p> 289 * Because of the way the protocol version is negotiated, connections 290 * will only be able to use a member of the lowest set of contiguous 291 * enabled protocol versions. For example, enabling TLSv1.2 and TLSv1 292 * will result in connections only being able to use TLSv1. 293 * <P> 294 * <code>SSLSocket</code>s returned from <code>accept()</code> 295 * inherit this setting. 296 * 297 * @param protocols Names of all the protocols to enable. 298 * @exception IllegalArgumentException when one or more of 299 * the protocols named by the parameter is not supported or 300 * when the protocols parameter is null. 301 * @see #getEnabledProtocols() 302 * @see #getSupportedProtocols() 303 */ setEnabledProtocols(String protocols[])304 public abstract void setEnabledProtocols(String protocols[]); 305 306 307 /** 308 * Controls whether <code>accept</code>ed server-mode 309 * <code>SSLSockets</code> will be initially configured to 310 * <i>require</i> client authentication. 311 * <P> 312 * A socket's client authentication setting is one of the following: 313 * <ul> 314 * <li> client authentication required 315 * <li> client authentication requested 316 * <li> no client authentication desired 317 * </ul> 318 * <P> 319 * Unlike {@link #setWantClientAuth(boolean)}, if the accepted 320 * socket's option is set and the client chooses not to provide 321 * authentication information about itself, <i>the negotiations 322 * will stop and the connection will be dropped</i>. 323 * <P> 324 * Calling this method overrides any previous setting made by 325 * this method or {@link #setWantClientAuth(boolean)}. 326 * <P> 327 * The initial inherited setting may be overridden by calling 328 * {@link SSLSocket#setNeedClientAuth(boolean)} or 329 * {@link SSLSocket#setWantClientAuth(boolean)}. 330 * 331 * @param need set to true if client authentication is required, 332 * or false if no client authentication is desired. 333 * @see #getNeedClientAuth() 334 * @see #setWantClientAuth(boolean) 335 * @see #getWantClientAuth() 336 * @see #setUseClientMode(boolean) 337 */ setNeedClientAuth(boolean need)338 public abstract void setNeedClientAuth(boolean need); 339 340 341 /** 342 * Returns true if client authentication will be <i>required</i> on 343 * newly <code>accept</code>ed server-mode <code>SSLSocket</code>s. 344 * <P> 345 * The initial inherited setting may be overridden by calling 346 * {@link SSLSocket#setNeedClientAuth(boolean)} or 347 * {@link SSLSocket#setWantClientAuth(boolean)}. 348 * 349 * @return true if client authentication is required, 350 * or false if no client authentication is desired. 351 * @see #setNeedClientAuth(boolean) 352 * @see #setWantClientAuth(boolean) 353 * @see #getWantClientAuth() 354 * @see #setUseClientMode(boolean) 355 */ getNeedClientAuth()356 public abstract boolean getNeedClientAuth(); 357 358 359 /** 360 * Controls whether <code>accept</code>ed server-mode 361 * <code>SSLSockets</code> will be initially configured to 362 * <i>request</i> client authentication. 363 * <P> 364 * A socket's client authentication setting is one of the following: 365 * <ul> 366 * <li> client authentication required 367 * <li> client authentication requested 368 * <li> no client authentication desired 369 * </ul> 370 * <P> 371 * Unlike {@link #setNeedClientAuth(boolean)}, if the accepted 372 * socket's option is set and the client chooses not to provide 373 * authentication information about itself, <i>the negotiations 374 * will continue</i>. 375 * <P> 376 * Calling this method overrides any previous setting made by 377 * this method or {@link #setNeedClientAuth(boolean)}. 378 * <P> 379 * The initial inherited setting may be overridden by calling 380 * {@link SSLSocket#setNeedClientAuth(boolean)} or 381 * {@link SSLSocket#setWantClientAuth(boolean)}. 382 * 383 * @param want set to true if client authentication is requested, 384 * or false if no client authentication is desired. 385 * @see #getWantClientAuth() 386 * @see #setNeedClientAuth(boolean) 387 * @see #getNeedClientAuth() 388 * @see #setUseClientMode(boolean) 389 */ setWantClientAuth(boolean want)390 public abstract void setWantClientAuth(boolean want); 391 392 393 /** 394 * Returns true if client authentication will be <i>requested</i> on 395 * newly accepted server-mode connections. 396 * <P> 397 * The initial inherited setting may be overridden by calling 398 * {@link SSLSocket#setNeedClientAuth(boolean)} or 399 * {@link SSLSocket#setWantClientAuth(boolean)}. 400 * 401 * @return true if client authentication is requested, 402 * or false if no client authentication is desired. 403 * @see #setWantClientAuth(boolean) 404 * @see #setNeedClientAuth(boolean) 405 * @see #getNeedClientAuth() 406 * @see #setUseClientMode(boolean) 407 */ getWantClientAuth()408 public abstract boolean getWantClientAuth(); 409 410 411 /** 412 * Controls whether accepted connections are in the (default) SSL 413 * server mode, or the SSL client mode. 414 * <P> 415 * Servers normally authenticate themselves, and clients are not 416 * required to do so. 417 * <P> 418 * In rare cases, TCP servers 419 * need to act in the SSL client mode on newly accepted 420 * connections. For example, FTP clients acquire server sockets 421 * and listen there for reverse connections from the server. An 422 * FTP client would use an SSLServerSocket in "client" mode to 423 * accept the reverse connection while the FTP server uses an 424 * SSLSocket with "client" mode disabled to initiate the 425 * connection. During the resulting handshake, existing SSL 426 * sessions may be reused. 427 * <P> 428 * <code>SSLSocket</code>s returned from <code>accept()</code> 429 * inherit this setting. 430 * 431 * @param mode true if newly accepted connections should use SSL 432 * client mode. 433 * @see #getUseClientMode() 434 */ setUseClientMode(boolean mode)435 public abstract void setUseClientMode(boolean mode); 436 437 438 /** 439 * Returns true if accepted connections will be in SSL client mode. 440 * 441 * @see #setUseClientMode(boolean) 442 * @return true if the connection should use SSL client mode. 443 */ getUseClientMode()444 public abstract boolean getUseClientMode(); 445 446 447 /** 448 * Controls whether new SSL sessions may be established by the 449 * sockets which are created from this server socket. 450 * <P> 451 * <code>SSLSocket</code>s returned from <code>accept()</code> 452 * inherit this setting. 453 * 454 * @param flag true indicates that sessions may be created; this 455 * is the default. false indicates that an existing session 456 * must be resumed. 457 * @see #getEnableSessionCreation() 458 */ setEnableSessionCreation(boolean flag)459 public abstract void setEnableSessionCreation(boolean flag); 460 461 462 /** 463 * Returns true if new SSL sessions may be established by the 464 * sockets which are created from this server socket. 465 * 466 * @return true indicates that sessions may be created; this 467 * is the default. false indicates that an existing 468 * session must be resumed 469 * @see #setEnableSessionCreation(boolean) 470 */ getEnableSessionCreation()471 public abstract boolean getEnableSessionCreation(); 472 473 /** 474 * Returns the SSLParameters in effect for newly accepted connections. 475 * The ciphersuites and protocols of the returned SSLParameters 476 * are always non-null. 477 * 478 * @return the SSLParameters in effect for newly accepted connections 479 * 480 * @see #setSSLParameters(SSLParameters) 481 * 482 * @since 1.7 483 */ getSSLParameters()484 public SSLParameters getSSLParameters() { 485 SSLParameters parameters = new SSLParameters(); 486 487 parameters.setCipherSuites(getEnabledCipherSuites()); 488 parameters.setProtocols(getEnabledProtocols()); 489 if (getNeedClientAuth()) { 490 parameters.setNeedClientAuth(true); 491 } else if (getWantClientAuth()) { 492 parameters.setWantClientAuth(true); 493 } 494 495 return parameters; 496 } 497 498 /** 499 * Applies SSLParameters to newly accepted connections. 500 * 501 * <p>This means: 502 * <ul> 503 * <li>If {@code params.getCipherSuites()} is non-null, 504 * {@code setEnabledCipherSuites()} is called with that value.</li> 505 * <li>If {@code params.getProtocols()} is non-null, 506 * {@code setEnabledProtocols()} is called with that value.</li> 507 * <li>If {@code params.getNeedClientAuth()} or 508 * {@code params.getWantClientAuth()} return {@code true}, 509 * {@code setNeedClientAuth(true)} and 510 * {@code setWantClientAuth(true)} are called, respectively; 511 * otherwise {@code setWantClientAuth(false)} is called.</li> 512 * <li>If {@code params.getServerNames()} is non-null, the socket will 513 * configure its server names with that value.</li> 514 * <li>If {@code params.getSNIMatchers()} is non-null, the socket will 515 * configure its SNI matchers with that value.</li> 516 * </ul> 517 * 518 * @param params the parameters 519 * @throws IllegalArgumentException if the setEnabledCipherSuites() or 520 * the setEnabledProtocols() call fails 521 * 522 * @see #getSSLParameters() 523 * 524 * @since 1.7 525 */ setSSLParameters(SSLParameters params)526 public void setSSLParameters(SSLParameters params) { 527 String[] s; 528 s = params.getCipherSuites(); 529 if (s != null) { 530 setEnabledCipherSuites(s); 531 } 532 533 s = params.getProtocols(); 534 if (s != null) { 535 setEnabledProtocols(s); 536 } 537 538 if (params.getNeedClientAuth()) { 539 setNeedClientAuth(true); 540 } else if (params.getWantClientAuth()) { 541 setWantClientAuth(true); 542 } else { 543 setWantClientAuth(false); 544 } 545 } 546 547 // Android-added: Make toString explicit that this is an SSLServerSocket (http://b/6602228) 548 @Override toString()549 public String toString() { 550 return "SSL" + super.toString(); 551 } 552 553 } 554