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 }