1 /* 2 * Copyright (c) 1997, 2017, 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.IOException; 30 import java.net.*; 31 import java.util.List; 32 import java.util.function.BiFunction; 33 34 /** 35 * This class extends <code>Socket</code> and provides secure 36 * sockets using protocols such as the "Secure 37 * Sockets Layer" (SSL) or IETF "Transport Layer Security" (TLS) protocols. 38 * <P> 39 * Such sockets are normal stream sockets, but they 40 * add a layer of security protections over the underlying network transport 41 * protocol, such as TCP. Those protections include: <UL> 42 * 43 * <LI> <em>Integrity Protection</em>. SSL protects against 44 * modification of messages by an active wiretapper. 45 * 46 * <LI> <em>Authentication</em>. In most modes, SSL provides 47 * peer authentication. Servers are usually authenticated, 48 * and clients may be authenticated as requested by servers. 49 * 50 * <LI> <em>Confidentiality (Privacy Protection)</em>. In most 51 * modes, SSL encrypts data being sent between client and server. 52 * This protects the confidentiality of data, so that passive 53 * wiretappers won't see sensitive data such as financial 54 * information or personal information of many kinds. 55 * 56 * </UL> 57 * 58 * <P>These kinds of protection are specified by a "cipher suite", which 59 * is a combination of cryptographic algorithms used by a given SSL connection. 60 * During the negotiation process, the two endpoints must agree on 61 * a ciphersuite that is available in both environments. 62 * If there is no such suite in common, no SSL connection can 63 * be established, and no data can be exchanged. 64 * 65 * <P> The cipher suite used is established by a negotiation process 66 * called "handshaking". The goal of this 67 * process is to create or rejoin a "session", which may protect many 68 * connections over time. After handshaking has completed, you can access 69 * session attributes by using the <em>getSession</em> method. 70 * The initial handshake on this connection can be initiated in 71 * one of three ways: <UL> 72 * 73 * <LI> calling <code>startHandshake</code> which explicitly 74 * begins handshakes, or 75 * <LI> any attempt to read or write application data on 76 * this socket causes an implicit handshake, or 77 * <LI> a call to <code>getSession</code> tries to set up a session 78 * if there is no currently valid session, and 79 * an implicit handshake is done. 80 * </UL> 81 * 82 * <P>If handshaking fails for any reason, the <code>SSLSocket</code> 83 * is closed, and no further communications can be done. 84 * 85 * <P>There are two groups of cipher suites which you will need to know 86 * about when managing cipher suites: <UL> 87 * 88 * <LI> <em>Supported</em> cipher suites: all the suites which are 89 * supported by the SSL implementation. This list is reported 90 * using <em>getSupportedCipherSuites</em>. 91 * 92 * <LI> <em>Enabled</em> cipher suites, which may be fewer 93 * than the full set of supported suites. This group is 94 * set using the <em>setEnabledCipherSuites</em> method, and 95 * queried using the <em>getEnabledCipherSuites</em> method. 96 * Initially, a default set of cipher suites will be enabled on 97 * a new socket that represents the minimum suggested configuration. 98 * 99 * </UL> 100 * 101 * <P> Implementation defaults require that only cipher 102 * suites which authenticate servers and provide confidentiality 103 * be enabled by default. 104 * Only if both sides explicitly agree to unauthenticated and/or 105 * non-private (unencrypted) communications will such a ciphersuite be 106 * selected. 107 * 108 * <P>When an <code>SSLSocket</code> is first created, no handshaking 109 * is done so that applications may first set their communication 110 * preferences: what cipher suites to use, whether the socket should be 111 * in client or server mode, etc. 112 * However, security is always provided by the time that application data 113 * is sent over the connection. 114 * 115 * <P> You may register to receive event notification of handshake 116 * completion. This involves 117 * the use of two additional classes. <em>HandshakeCompletedEvent</em> 118 * objects are passed to <em>HandshakeCompletedListener</em> instances, 119 * which are registered by users of this API. 120 * 121 * An <code>SSLSocket</code> is created by <code>SSLSocketFactory</code>, 122 * or by <code>accept</code>ing a connection from a 123 * <code>SSLServerSocket</code>. 124 * 125 * <P>A SSL socket must choose to operate in the client or server mode. 126 * This will determine who begins the handshaking process, as well 127 * as which messages should be sent by each party. Each 128 * connection must have one client and one server, or handshaking 129 * will not progress properly. Once the initial handshaking has started, a 130 * socket can not switch between client and server modes, even when 131 * performing renegotiations. 132 * 133 * @see java.net.Socket 134 * @see SSLServerSocket 135 * @see SSLSocketFactory 136 * 137 * @since 1.4 138 * @author David Brownell 139 */ 140 public abstract class SSLSocket extends Socket 141 { 142 /** 143 * Used only by subclasses. 144 * Constructs an uninitialized, unconnected TCP socket. 145 */ 146 protected SSLSocket() 147 { super(); } 148 149 150 /** 151 * Used only by subclasses. 152 * Constructs a TCP connection to a named host at a specified port. 153 * This acts as the SSL client. 154 * <p> 155 * If there is a security manager, its <code>checkConnect</code> 156 * method is called with the host address and <code>port</code> 157 * as its arguments. This could result in a SecurityException. 158 * 159 * @param host name of the host with which to connect, or 160 * <code>null</code> for the loopback address. 161 * @param port number of the server's port 162 * @throws IOException if an I/O error occurs when creating the socket 163 * @throws SecurityException if a security manager exists and its 164 * <code>checkConnect</code> method doesn't allow the operation. 165 * @throws UnknownHostException if the host is not known 166 * @throws IllegalArgumentException if the port parameter is outside the 167 * specified range of valid port values, which is between 0 and 168 * 65535, inclusive. 169 * @see SecurityManager#checkConnect 170 */ 171 protected SSLSocket(String host, int port) 172 throws IOException, UnknownHostException 173 { super(host, port); } 174 175 176 /** 177 * Used only by subclasses. 178 * Constructs a TCP connection to a server at a specified address 179 * and port. This acts as the SSL client. 180 * <p> 181 * If there is a security manager, its <code>checkConnect</code> 182 * method is called with the host address and <code>port</code> 183 * as its arguments. This could result in a SecurityException. 184 * 185 * @param address the server's host 186 * @param port its port 187 * @throws IOException if an I/O error occurs when creating the socket 188 * @throws SecurityException if a security manager exists and its 189 * <code>checkConnect</code> method doesn't allow the operation. 190 * @throws IllegalArgumentException if the port parameter is outside the 191 * specified range of valid port values, which is between 0 and 192 * 65535, inclusive. 193 * @throws NullPointerException if <code>address</code> is null. 194 * @see SecurityManager#checkConnect 195 */ 196 protected SSLSocket(InetAddress address, int port) 197 throws IOException 198 { super(address, port); } 199 200 201 /** 202 * Used only by subclasses. 203 * Constructs an SSL connection to a named host at a specified port, 204 * binding the client side of the connection a given address and port. 205 * This acts as the SSL client. 206 * <p> 207 * If there is a security manager, its <code>checkConnect</code> 208 * method is called with the host address and <code>port</code> 209 * as its arguments. This could result in a SecurityException. 210 * 211 * @param host name of the host with which to connect, or 212 * <code>null</code> for the loopback address. 213 * @param port number of the server's port 214 * @param clientAddress the client's address the socket is bound to, or 215 * <code>null</code> for the <code>anyLocal</code> address. 216 * @param clientPort the client's port the socket is bound to, or 217 * <code>zero</code> for a system selected free port. 218 * @throws IOException if an I/O error occurs when creating the socket 219 * @throws SecurityException if a security manager exists and its 220 * <code>checkConnect</code> method doesn't allow the operation. 221 * @throws UnknownHostException if the host is not known 222 * @throws IllegalArgumentException if the port parameter or clientPort 223 * parameter is outside the specified range of valid port values, 224 * which is between 0 and 65535, inclusive. 225 * @see SecurityManager#checkConnect 226 */ 227 protected SSLSocket(String host, int port, 228 InetAddress clientAddress, int clientPort) 229 throws IOException, UnknownHostException 230 { super(host, port, clientAddress, clientPort); } 231 232 233 /** 234 * Used only by subclasses. 235 * Constructs an SSL connection to a server at a specified address 236 * and TCP port, binding the client side of the connection a given 237 * address and port. This acts as the SSL client. 238 * <p> 239 * If there is a security manager, its <code>checkConnect</code> 240 * method is called with the host address and <code>port</code> 241 * as its arguments. This could result in a SecurityException. 242 * 243 * @param address the server's host 244 * @param port its port 245 * @param clientAddress the client's address the socket is bound to, or 246 * <code>null</code> for the <code>anyLocal</code> address. 247 * @param clientPort the client's port the socket is bound to, or 248 * <code>zero</code> for a system selected free port. 249 * @throws IOException if an I/O error occurs when creating the socket 250 * @throws SecurityException if a security manager exists and its 251 * <code>checkConnect</code> method doesn't allow the operation. 252 * @throws IllegalArgumentException if the port parameter or clientPort 253 * parameter is outside the specified range of valid port values, 254 * which is between 0 and 65535, inclusive. 255 * @throws NullPointerException if <code>address</code> is null. 256 * @see SecurityManager#checkConnect 257 */ 258 protected SSLSocket(InetAddress address, int port, 259 InetAddress clientAddress, int clientPort) 260 throws IOException 261 { super(address, port, clientAddress, clientPort); } 262 263 264 /** 265 * Returns the names of the cipher suites which could be enabled for use 266 * on this connection. Normally, only a subset of these will actually 267 * be enabled by default, since this list may include cipher suites which 268 * do not meet quality of service requirements for those defaults. Such 269 * cipher suites might be useful in specialized applications. 270 * <P> 271 * The returned array includes cipher suites from the list of standard 272 * cipher suite names in the <a href= 273 * "{@docRoot}/../specs/security/standard-names.html#jsse-cipher-suite-names"> 274 * JSSE Cipher Suite Names</a> section of the Java Cryptography 275 * Architecture Standard Algorithm Name Documentation, and may also 276 * include other cipher suites that the provider supports. 277 * 278 * @return an array of cipher suite names 279 * @see #getEnabledCipherSuites() 280 * @see #setEnabledCipherSuites(String []) 281 */ 282 public abstract String [] getSupportedCipherSuites(); 283 284 285 /** 286 * Returns the names of the SSL cipher suites which are currently 287 * enabled for use on this connection. When an SSLSocket is first 288 * created, all enabled cipher suites support a minimum quality of 289 * service. Thus, in some environments this value might be empty. 290 * <P> 291 * Note that even if a suite is enabled, it may never be used. This 292 * can occur if the peer does not support it, or its use is restricted, 293 * or the requisite certificates (and private keys) for the suite are 294 * not available, or an anonymous suite is enabled but authentication 295 * is required. 296 * <P> 297 * The returned array includes cipher suites from the list of standard 298 * cipher suite names in the <a href= 299 * "{@docRoot}/../specs/security/standard-names.html#jsse-cipher-suite-names"> 300 * JSSE Cipher Suite Names</a> section of the Java Cryptography 301 * Architecture Standard Algorithm Name Documentation, and may also 302 * include other cipher suites that the provider supports. 303 * 304 * @return an array of cipher suite names 305 * @see #getSupportedCipherSuites() 306 * @see #setEnabledCipherSuites(String []) 307 */ 308 public abstract String [] getEnabledCipherSuites(); 309 310 311 /** 312 * Sets the cipher suites enabled for use on this connection. 313 * <P> 314 * Each cipher suite in the <code>suites</code> parameter must have 315 * been listed by getSupportedCipherSuites(), or the method will 316 * fail. Following a successful call to this method, only suites 317 * listed in the <code>suites</code> parameter are enabled for use. 318 * <P> 319 * Note that the standard list of cipher suite names may be found in the 320 * <a href= 321 * "{@docRoot}/../specs/security/standard-names.html#jsse-cipher-suite-names"> 322 * JSSE Cipher Suite Names</a> section of the Java Cryptography 323 * Architecture Standard Algorithm Name Documentation. Providers 324 * may support cipher suite names not found in this list or might not 325 * use the recommended name for a certain cipher suite. 326 * <P> 327 * See {@link #getEnabledCipherSuites()} for more information 328 * on why a specific ciphersuite may never be used on a connection. 329 * 330 * @param suites Names of all the cipher suites to enable 331 * @throws IllegalArgumentException when one or more of the ciphers 332 * named by the parameter is not supported, or when the 333 * parameter is null. 334 * @see #getSupportedCipherSuites() 335 * @see #getEnabledCipherSuites() 336 */ 337 public abstract void setEnabledCipherSuites(String suites []); 338 339 340 /** 341 * Returns the names of the protocols which could be enabled for use 342 * on an SSL connection. 343 * 344 * @return an array of protocols supported 345 */ 346 public abstract String [] getSupportedProtocols(); 347 348 349 /** 350 * Returns the names of the protocol versions which are currently 351 * enabled for use on this connection. 352 * <P> 353 * Note that even if a protocol is enabled, it may never be used. 354 * This can occur if the peer does not support the protocol, or its 355 * use is restricted, or there are no enabled cipher suites supported 356 * by the protocol. 357 * 358 * @see #setEnabledProtocols(String []) 359 * @return an array of protocols 360 */ 361 public abstract String [] getEnabledProtocols(); 362 363 364 /** 365 * Sets the protocol versions enabled for use on this connection. 366 * <P> 367 * The protocols must have been listed by 368 * <code>getSupportedProtocols()</code> as being supported. 369 * Following a successful call to this method, only protocols listed 370 * in the <code>protocols</code> parameter are enabled for use. 371 * 372 * @param protocols Names of all the protocols to enable. 373 * @throws IllegalArgumentException when one or more of 374 * the protocols named by the parameter is not supported or 375 * when the protocols parameter is null. 376 * @see #getEnabledProtocols() 377 */ 378 public abstract void setEnabledProtocols(String protocols[]); 379 380 381 /** 382 * Returns the SSL Session in use by this connection. These can 383 * be long lived, and frequently correspond to an entire login session 384 * for some user. The session specifies a particular cipher suite 385 * which is being actively used by all connections in that session, 386 * as well as the identities of the session's client and server. 387 * <P> 388 * This method will initiate the initial handshake if 389 * necessary and then block until the handshake has been 390 * established. 391 * <P> 392 * If an error occurs during the initial handshake, this method 393 * returns an invalid session object which reports an invalid 394 * cipher suite of "SSL_NULL_WITH_NULL_NULL". 395 * 396 * @return the <code>SSLSession</code> 397 */ 398 public abstract SSLSession getSession(); 399 400 401 /** 402 * Returns the {@code SSLSession} being constructed during a SSL/TLS 403 * handshake. 404 * <p> 405 * TLS protocols may negotiate parameters that are needed when using 406 * an instance of this class, but before the {@code SSLSession} has 407 * been completely initialized and made available via {@code getSession}. 408 * For example, the list of valid signature algorithms may restrict 409 * the type of certificates that can used during TrustManager 410 * decisions, or the maximum TLS fragment packet sizes can be 411 * resized to better support the network environment. 412 * <p> 413 * This method provides early access to the {@code SSLSession} being 414 * constructed. Depending on how far the handshake has progressed, 415 * some data may not yet be available for use. For example, if a 416 * remote server will be sending a Certificate chain, but that chain 417 * has yet not been processed, the {@code getPeerCertificates} 418 * method of {@code SSLSession} will throw a 419 * SSLPeerUnverifiedException. Once that chain has been processed, 420 * {@code getPeerCertificates} will return the proper value. 421 * <p> 422 * Unlike {@link #getSession()}, this method does not initiate the 423 * initial handshake and does not block until handshaking is 424 * complete. 425 * 426 * @see SSLEngine 427 * @see SSLSession 428 * @see ExtendedSSLSession 429 * @see X509ExtendedKeyManager 430 * @see X509ExtendedTrustManager 431 * 432 * @return null if this instance is not currently handshaking, or 433 * if the current handshake has not progressed far enough to 434 * create a basic SSLSession. Otherwise, this method returns the 435 * {@code SSLSession} currently being negotiated. 436 * @throws UnsupportedOperationException if the underlying provider 437 * does not implement the operation. 438 * 439 * @since 1.7 440 */ 441 public SSLSession getHandshakeSession() { 442 throw new UnsupportedOperationException(); 443 } 444 445 446 /** 447 * Registers an event listener to receive notifications that an 448 * SSL handshake has completed on this connection. 449 * 450 * @param listener the HandShake Completed event listener 451 * @see #startHandshake() 452 * @see #removeHandshakeCompletedListener(HandshakeCompletedListener) 453 * @throws IllegalArgumentException if the argument is null. 454 */ 455 public abstract void addHandshakeCompletedListener( 456 HandshakeCompletedListener listener); 457 458 459 /** 460 * Removes a previously registered handshake completion listener. 461 * 462 * @param listener the HandShake Completed event listener 463 * @throws IllegalArgumentException if the listener is not registered, 464 * or the argument is null. 465 * @see #addHandshakeCompletedListener(HandshakeCompletedListener) 466 */ 467 public abstract void removeHandshakeCompletedListener( 468 HandshakeCompletedListener listener); 469 470 471 /** 472 * Starts an SSL handshake on this connection. Common reasons include 473 * a need to use new encryption keys, to change cipher suites, or to 474 * initiate a new session. To force complete reauthentication, the 475 * current session could be invalidated before starting this handshake. 476 * 477 * <P> If data has already been sent on the connection, it continues 478 * to flow during this handshake. When the handshake completes, this 479 * will be signaled with an event. 480 * 481 * This method is synchronous for the initial handshake on a connection 482 * and returns when the negotiated handshake is complete. Some 483 * protocols may not support multiple handshakes on an existing socket 484 * and may throw an IOException. 485 * 486 * @throws IOException on a network level error 487 * @see #addHandshakeCompletedListener(HandshakeCompletedListener) 488 */ 489 public abstract void startHandshake() throws IOException; 490 491 492 /** 493 * Configures the socket to use client (or server) mode when 494 * handshaking. 495 * <P> 496 * This method must be called before any handshaking occurs. 497 * Once handshaking has begun, the mode can not be reset for the 498 * life of this socket. 499 * <P> 500 * Servers normally authenticate themselves, and clients 501 * are not required to do so. 502 * 503 * @param mode true if the socket should start its handshaking 504 * in "client" mode 505 * @throws IllegalArgumentException if a mode change is attempted 506 * after the initial handshake has begun. 507 * @see #getUseClientMode() 508 */ 509 public abstract void setUseClientMode(boolean mode); 510 511 512 /** 513 * Returns true if the socket is set to use client mode when 514 * handshaking. 515 * 516 * @return true if the socket should do handshaking 517 * in "client" mode 518 * @see #setUseClientMode(boolean) 519 */ 520 public abstract boolean getUseClientMode(); 521 522 523 /** 524 * Configures the socket to <i>require</i> client authentication. This 525 * option is only useful for sockets in the server mode. 526 * <P> 527 * A socket's client authentication setting is one of the following: 528 * <ul> 529 * <li> client authentication required 530 * <li> client authentication requested 531 * <li> no client authentication desired 532 * </ul> 533 * <P> 534 * Unlike {@link #setWantClientAuth(boolean)}, if this option is set and 535 * the client chooses not to provide authentication information 536 * about itself, <i>the negotiations will stop and the connection 537 * will be dropped</i>. 538 * <P> 539 * Calling this method overrides any previous setting made by 540 * this method or {@link #setWantClientAuth(boolean)}. 541 * 542 * @param need set to true if client authentication is required, 543 * or false if no client authentication is desired. 544 * @see #getNeedClientAuth() 545 * @see #setWantClientAuth(boolean) 546 * @see #getWantClientAuth() 547 * @see #setUseClientMode(boolean) 548 */ 549 public abstract void setNeedClientAuth(boolean need); 550 551 552 /** 553 * Returns true if the socket will <i>require</i> client authentication. 554 * This option is only useful to sockets in the server mode. 555 * 556 * @return true if client authentication is required, 557 * or false if no client authentication is desired. 558 * @see #setNeedClientAuth(boolean) 559 * @see #setWantClientAuth(boolean) 560 * @see #getWantClientAuth() 561 * @see #setUseClientMode(boolean) 562 */ 563 public abstract boolean getNeedClientAuth(); 564 565 566 /** 567 * Configures the socket to <i>request</i> client authentication. 568 * This option is only useful for sockets in the server mode. 569 * <P> 570 * A socket's client authentication setting is one of the following: 571 * <ul> 572 * <li> client authentication required 573 * <li> client authentication requested 574 * <li> no client authentication desired 575 * </ul> 576 * <P> 577 * Unlike {@link #setNeedClientAuth(boolean)}, if this option is set and 578 * the client chooses not to provide authentication information 579 * about itself, <i>the negotiations will continue</i>. 580 * <P> 581 * Calling this method overrides any previous setting made by 582 * this method or {@link #setNeedClientAuth(boolean)}. 583 * 584 * @param want set to true if client authentication is requested, 585 * or false if no client authentication is desired. 586 * @see #getWantClientAuth() 587 * @see #setNeedClientAuth(boolean) 588 * @see #getNeedClientAuth() 589 * @see #setUseClientMode(boolean) 590 */ 591 public abstract void setWantClientAuth(boolean want); 592 593 594 /** 595 * Returns true if the socket will <i>request</i> client authentication. 596 * This option is only useful for sockets in the server mode. 597 * 598 * @return true if client authentication is requested, 599 * or false if no client authentication is desired. 600 * @see #setNeedClientAuth(boolean) 601 * @see #getNeedClientAuth() 602 * @see #setWantClientAuth(boolean) 603 * @see #setUseClientMode(boolean) 604 */ 605 public abstract boolean getWantClientAuth(); 606 607 608 /** 609 * Controls whether new SSL sessions may be established by this socket. 610 * If session creations are not allowed, and there are no 611 * existing sessions to resume, there will be no successful 612 * handshaking. 613 * 614 * @param flag true indicates that sessions may be created; this 615 * is the default. false indicates that an existing session 616 * must be resumed 617 * @see #getEnableSessionCreation() 618 */ 619 public abstract void setEnableSessionCreation(boolean flag); 620 621 622 /** 623 * Returns true if new SSL sessions may be established by this socket. 624 * 625 * @return true indicates that sessions may be created; this 626 * is the default. false indicates that an existing session 627 * must be resumed 628 * @see #setEnableSessionCreation(boolean) 629 */ 630 public abstract boolean getEnableSessionCreation(); 631 632 /** 633 * Returns the SSLParameters in effect for this SSLSocket. 634 * The ciphersuites and protocols of the returned SSLParameters 635 * are always non-null. 636 * 637 * @return the SSLParameters in effect for this SSLSocket. 638 * @since 1.6 639 */ 640 public SSLParameters getSSLParameters() { 641 SSLParameters params = new SSLParameters(); 642 params.setCipherSuites(getEnabledCipherSuites()); 643 params.setProtocols(getEnabledProtocols()); 644 if (getNeedClientAuth()) { 645 params.setNeedClientAuth(true); 646 } else if (getWantClientAuth()) { 647 params.setWantClientAuth(true); 648 } 649 return params; 650 } 651 652 /** 653 * Applies SSLParameters to this socket. 654 * 655 * <p>This means: 656 * <ul> 657 * <li>If {@code params.getCipherSuites()} is non-null, 658 * {@code setEnabledCipherSuites()} is called with that value.</li> 659 * <li>If {@code params.getProtocols()} is non-null, 660 * {@code setEnabledProtocols()} is called with that value.</li> 661 * <li>If {@code params.getNeedClientAuth()} or 662 * {@code params.getWantClientAuth()} return {@code true}, 663 * {@code setNeedClientAuth(true)} and 664 * {@code setWantClientAuth(true)} are called, respectively; 665 * otherwise {@code setWantClientAuth(false)} is called.</li> 666 * <li>If {@code params.getServerNames()} is non-null, the socket will 667 * configure its server names with that value.</li> 668 * <li>If {@code params.getSNIMatchers()} is non-null, the socket will 669 * configure its SNI matchers with that value.</li> 670 * </ul> 671 * 672 * @param params the parameters 673 * @throws IllegalArgumentException if the setEnabledCipherSuites() or 674 * the setEnabledProtocols() call fails 675 * @since 1.6 676 */ 677 public void setSSLParameters(SSLParameters params) { 678 String[] s; 679 s = params.getCipherSuites(); 680 if (s != null) { 681 setEnabledCipherSuites(s); 682 } 683 s = params.getProtocols(); 684 if (s != null) { 685 setEnabledProtocols(s); 686 } 687 if (params.getNeedClientAuth()) { 688 setNeedClientAuth(true); 689 } else if (params.getWantClientAuth()) { 690 setWantClientAuth(true); 691 } else { 692 setWantClientAuth(false); 693 } 694 } 695 696 /** 697 * Returns the most recent application protocol value negotiated for this 698 * connection. 699 * <p> 700 * If supported by the underlying SSL/TLS/DTLS implementation, 701 * application name negotiation mechanisms such as <a 702 * href="http://www.ietf.org/rfc/rfc7301.txt"> RFC 7301 </a>, the 703 * Application-Layer Protocol Negotiation (ALPN), can negotiate 704 * application-level values between peers. 705 * 706 * @implSpec 707 * The implementation in this class throws 708 * {@code UnsupportedOperationException} and performs no other action. 709 * 710 * @return null if it has not yet been determined if application 711 * protocols might be used for this connection, an empty 712 * {@code String} if application protocols values will not 713 * be used, or a non-empty application protocol {@code String} 714 * if a value was successfully negotiated. 715 * @throws UnsupportedOperationException if the underlying provider 716 * does not implement the operation. 717 * @since 9 718 */ 719 public String getApplicationProtocol() { 720 throw new UnsupportedOperationException(); 721 } 722 723 /** 724 * Returns the application protocol value negotiated on a SSL/TLS 725 * handshake currently in progress. 726 * <p> 727 * Like {@link #getHandshakeSession()}, 728 * a connection may be in the middle of a handshake. The 729 * application protocol may or may not yet be available. 730 * 731 * @implSpec 732 * The implementation in this class throws 733 * {@code UnsupportedOperationException} and performs no other action. 734 * 735 * @return null if it has not yet been determined if application 736 * protocols might be used for this handshake, an empty 737 * {@code String} if application protocols values will not 738 * be used, or a non-empty application protocol {@code String} 739 * if a value was successfully negotiated. 740 * @throws UnsupportedOperationException if the underlying provider 741 * does not implement the operation. 742 * @since 9 743 */ 744 public String getHandshakeApplicationProtocol() { 745 throw new UnsupportedOperationException(); 746 } 747 748 749 /** 750 * Registers a callback function that selects an application protocol 751 * value for a SSL/TLS/DTLS handshake. 752 * The function overrides any values supplied using 753 * {@link SSLParameters#setApplicationProtocols 754 * SSLParameters.setApplicationProtocols} and it supports the following 755 * type parameters: 756 * <blockquote> 757 * <dl> 758 * <dt> {@code SSLSocket} 759 * <dd> The function's first argument allows the current {@code SSLSocket} 760 * to be inspected, including the handshake session and configuration 761 * settings. 762 * <dt> {@code List<String>} 763 * <dd> The function's second argument lists the application protocol names 764 * advertised by the TLS peer. 765 * <dt> {@code String} 766 * <dd> The function's result is an application protocol name, or null to 767 * indicate that none of the advertised names are acceptable. 768 * If the return value is an empty {@code String} then application 769 * protocol indications will not be used. 770 * If the return value is null (no value chosen) or is a value that 771 * was not advertised by the peer, the underlying protocol will 772 * determine what action to take. (For example, ALPN will send a 773 * "no_application_protocol" alert and terminate the connection.) 774 * </dl> 775 * </blockquote> 776 * 777 * For example, the following call registers a callback function that 778 * examines the TLS handshake parameters and selects an application protocol 779 * name: 780 * <pre>{@code 781 * serverSocket.setHandshakeApplicationProtocolSelector( 782 * (serverSocket, clientProtocols) -> { 783 * SSLSession session = serverSocket.getHandshakeSession(); 784 * return chooseApplicationProtocol( 785 * serverSocket, 786 * clientProtocols, 787 * session.getProtocol(), 788 * session.getCipherSuite()); 789 * }); 790 * }</pre> 791 * 792 * @apiNote 793 * This method should be called by TLS server applications before the TLS 794 * handshake begins. Also, this {@code SSLSocket} should be configured with 795 * parameters that are compatible with the application protocol selected by 796 * the callback function. For example, enabling a poor choice of cipher 797 * suites could result in no suitable application protocol. 798 * See {@link SSLParameters}. 799 * 800 * @implSpec 801 * The implementation in this class throws 802 * {@code UnsupportedOperationException} and performs no other action. 803 * 804 * @param selector the callback function, or null to de-register. 805 * @throws UnsupportedOperationException if the underlying provider 806 * does not implement the operation. 807 * @since 9 808 */ 809 public void setHandshakeApplicationProtocolSelector( 810 BiFunction<SSLSocket, List<String>, String> selector) { 811 throw new UnsupportedOperationException(); 812 } 813 814 /** 815 * Retrieves the callback function that selects an application protocol 816 * value during a SSL/TLS/DTLS handshake. 817 * See {@link #setHandshakeApplicationProtocolSelector 818 * setHandshakeApplicationProtocolSelector} 819 * for the function's type parameters. 820 * 821 * @implSpec 822 * The implementation in this class throws 823 * {@code UnsupportedOperationException} and performs no other action. 824 * 825 * @return the callback function, or null if none has been set. 826 * @throws UnsupportedOperationException if the underlying provider 827 * does not implement the operation. 828 * @since 9 829 */ 830 public BiFunction<SSLSocket, List<String>, String> 831 getHandshakeApplicationProtocolSelector() { 832 throw new UnsupportedOperationException(); 833 } 834 }