/*
 * Copyright (c) 1997, 2018, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */


package javax.net.ssl;

import java.io.IOException;
import java.net.*;
import java.util.List;
import java.util.function.BiFunction;

This class extends Socket and provides secure
sockets using protocols such as the "Secure
Sockets Layer" (SSL) or IETF "Transport Layer Security" (TLS) protocols.

Such sockets are normal stream sockets, but they
add a layer of security protections over the underlying network transport
protocol, such as TCP.  Those protections include: 

     
 Integrity Protection.  SSL protects against
     modification of messages by an active wiretapper.
     
 Authentication.  In most modes, SSL provides
     peer authentication.  Servers are usually authenticated,
     and clients may be authenticated as requested by servers.
     
 Confidentiality (Privacy Protection).  In most
     modes, SSL encrypts data being sent between client and server.
     This protects the confidentiality of data, so that passive
     wiretappers won't see sensitive data such as financial
     information or personal information of many kinds.
     
These kinds of protection are specified by a "cipher suite", which
is a combination of cryptographic algorithms used by a given SSL connection.
During the negotiation process, the two endpoints must agree on
a ciphersuite that is available in both environments.
If there is no such suite in common, no SSL connection can
be established, and no data can be exchanged.
 The cipher suite used is established by a negotiation process
called "handshaking".  The goal of this
process is to create or rejoin a "session", which may protect many
connections over time.  After handshaking has completed, you can access
session attributes by using the getSession method.
The initial handshake on this connection can be initiated in
one of three ways: 

     
 calling startHandshake which explicitly
             begins handshakes, or
     
 any attempt to read or write application data on
             this socket causes an implicit handshake, or
     
 a call to getSession tries to set up a session
             if there is no currently valid session, and
             an implicit handshake is done.

If handshaking fails for any reason, the SSLSocket
is closed, and no further communications can be done.
There are two groups of cipher suites which you will need to know
about when managing cipher suites: 

     
 Supported cipher suites:  all the suites which are
     supported by the SSL implementation.  This list is reported
     using getSupportedCipherSuites.
     
 Enabled cipher suites, which may be fewer
     than the full set of supported suites.  This group is
     set using the setEnabledCipherSuites method, and
     queried using the getEnabledCipherSuites method.
     Initially, a default set of cipher suites will be enabled on
     a new socket that represents the minimum suggested configuration.
     
 Implementation defaults require that only cipher
suites which authenticate servers and provide confidentiality
be enabled by default.
Only if both sides explicitly agree to unauthenticated and/or
non-private (unencrypted) communications will such a ciphersuite be
selected.
When an SSLSocket is first created, no handshaking
is done so that applications may first set their communication
preferences:  what cipher suites to use, whether the socket should be
in client or server mode, etc.
However, security is always provided by the time that application data
is sent over the connection.
 You may register to receive event notification of handshake
completion.  This involves
the use of two additional classes.  HandshakeCompletedEvent
objects are passed to HandshakeCompletedListener instances,
which are registered by users of this API.
An SSLSocket is created by SSLSocketFactory,
or by accepting a connection from a
SSLServerSocket.
A SSL socket must choose to operate in the client or server mode.
This will determine who begins the handshaking process, as well
as which messages should be sent by each party.  Each
connection must have one client and one server, or handshaking
will not progress properly.  Once the initial handshaking has started, a
socket can not switch between client and server modes, even when
performing renegotiations.
Author:
David Brownell
See Also:
Socket
SSLServerSocket
SSLSocketFactory
API Note:
 When the connection is no longer needed, the client and server applications should each close both sides of their respective connection. For SSLSocket objects, for example, an application can call Socket.shutdownOutput() or OutputStream.close() for output strean close and call Socket.shutdownInput() or InputStream.close() for input stream close. Note that in some cases, closing the input stream may depend on the peer's output stream being closed first. If the connection is not closed in an orderly manner (for example Socket.shutdownInput() is called before the peer's write closure notification has been received), exceptions may be raised to indicate that an error has occurred. Once an SSLSocket is closed, it is not reusable: a new SSLSocket must be created.
Since:
1.4/**
 * This class extends <code>Socket</code> and provides secure
 * sockets using protocols such as the "Secure
 * Sockets Layer" (SSL) or IETF "Transport Layer Security" (TLS) protocols.
 * <P>
 * Such sockets are normal stream sockets, but they
 * add a layer of security protections over the underlying network transport
 * protocol, such as TCP.  Those protections include: <UL>
 *
 *      <LI> <em>Integrity Protection</em>.  SSL protects against
 *      modification of messages by an active wiretapper.
 *
 *      <LI> <em>Authentication</em>.  In most modes, SSL provides
 *      peer authentication.  Servers are usually authenticated,
 *      and clients may be authenticated as requested by servers.
 *
 *      <LI> <em>Confidentiality (Privacy Protection)</em>.  In most
 *      modes, SSL encrypts data being sent between client and server.
 *      This protects the confidentiality of data, so that passive
 *      wiretappers won't see sensitive data such as financial
 *      information or personal information of many kinds.
 *
 *      </UL>
 *
 * <P>These kinds of protection are specified by a "cipher suite", which
 * is a combination of cryptographic algorithms used by a given SSL connection.
 * During the negotiation process, the two endpoints must agree on
 * a ciphersuite that is available in both environments.
 * If there is no such suite in common, no SSL connection can
 * be established, and no data can be exchanged.
 *
 * <P> The cipher suite used is established by a negotiation process
 * called "handshaking".  The goal of this
 * process is to create or rejoin a "session", which may protect many
 * connections over time.  After handshaking has completed, you can access
 * session attributes by using the <em>getSession</em> method.
 * The initial handshake on this connection can be initiated in
 * one of three ways: <UL>
 *
 *      <LI> calling <code>startHandshake</code> which explicitly
 *              begins handshakes, or
 *      <LI> any attempt to read or write application data on
 *              this socket causes an implicit handshake, or
 *      <LI> a call to <code>getSession</code> tries to set up a session
 *              if there is no currently valid session, and
 *              an implicit handshake is done.
 * </UL>
 *
 * <P>If handshaking fails for any reason, the <code>SSLSocket</code>
 * is closed, and no further communications can be done.
 *
 * <P>There are two groups of cipher suites which you will need to know
 * about when managing cipher suites: <UL>
 *
 *      <LI> <em>Supported</em> cipher suites:  all the suites which are
 *      supported by the SSL implementation.  This list is reported
 *      using <em>getSupportedCipherSuites</em>.
 *
 *      <LI> <em>Enabled</em> cipher suites, which may be fewer
 *      than the full set of supported suites.  This group is
 *      set using the <em>setEnabledCipherSuites</em> method, and
 *      queried using the <em>getEnabledCipherSuites</em> method.
 *      Initially, a default set of cipher suites will be enabled on
 *      a new socket that represents the minimum suggested configuration.
 *
 *      </UL>
 *
 * <P> Implementation defaults require that only cipher
 * suites which authenticate servers and provide confidentiality
 * be enabled by default.
 * Only if both sides explicitly agree to unauthenticated and/or
 * non-private (unencrypted) communications will such a ciphersuite be
 * selected.
 *
 * <P>When an <code>SSLSocket</code> is first created, no handshaking
 * is done so that applications may first set their communication
 * preferences:  what cipher suites to use, whether the socket should be
 * in client or server mode, etc.
 * However, security is always provided by the time that application data
 * is sent over the connection.
 *
 * <P> You may register to receive event notification of handshake
 * completion.  This involves
 * the use of two additional classes.  <em>HandshakeCompletedEvent</em>
 * objects are passed to <em>HandshakeCompletedListener</em> instances,
 * which are registered by users of this API.
 *
 * An <code>SSLSocket</code> is created by <code>SSLSocketFactory</code>,
 * or by <code>accept</code>ing a connection from a
 * <code>SSLServerSocket</code>.
 *
 * <P>A SSL socket must choose to operate in the client or server mode.
 * This will determine who begins the handshaking process, as well
 * as which messages should be sent by each party.  Each
 * connection must have one client and one server, or handshaking
 * will not progress properly.  Once the initial handshaking has started, a
 * socket can not switch between client and server modes, even when
 * performing renegotiations.
 *
 * @apiNote
 * When the connection is no longer needed, the client and server
 * applications should each close both sides of their respective connection.
 * For {@code SSLSocket} objects, for example, an application can call
 * {@link Socket#shutdownOutput()} or {@link java.io.OutputStream#close()}
 * for output strean close and call {@link Socket#shutdownInput()} or
 * {@link java.io.InputStream#close()} for input stream close.  Note that
 * in some cases, closing the input stream may depend on the peer's output
 * stream being closed first.  If the connection is not closed in an orderly
 * manner (for example {@link Socket#shutdownInput()} is called before the
 * peer's write closure notification has been received), exceptions may
 * be raised to indicate that an error has occurred.  Once an
 * {@code SSLSocket} is closed, it is not reusable: a new {@code SSLSocket}
 * must be created.
 *
 * @see java.net.Socket
 * @see SSLServerSocket
 * @see SSLSocketFactory
 *
 * @since 1.4
 * @author David Brownell
 */
public abstract class SSLSocket extends Socket
{
    
Used only by subclasses.
Constructs an uninitialized, unconnected TCP socket.
/**
     * Used only by subclasses.
     * Constructs an uninitialized, unconnected TCP socket.
     */
    protected SSLSocket()
        { super(); }


    
Used only by subclasses.
Constructs a TCP connection to a named host at a specified port.
This acts as the SSL client.

If there is a security manager, its checkConnect
method is called with the host address and port
as its arguments. This could result in a SecurityException.
Params:
host – name of the host with which to connect, or
       null for the loopback address.
port – number of the server's port
Throws:
IOException – if an I/O error occurs when creating the socket
SecurityException – if a security manager exists and its
        checkConnect method doesn't allow the operation.
UnknownHostException – if the host is not known
IllegalArgumentException – if the port parameter is outside the
        specified range of valid port values, which is between 0 and
        65535, inclusive.
See Also:
SecurityManager.checkConnect/**
     * Used only by subclasses.
     * Constructs a TCP connection to a named host at a specified port.
     * This acts as the SSL client.
     * <p>
     * If there is a security manager, its <code>checkConnect</code>
     * method is called with the host address and <code>port</code>
     * as its arguments. This could result in a SecurityException.
     *
     * @param host name of the host with which to connect, or
     *        <code>null</code> for the loopback address.
     * @param port number of the server's port
     * @throws IOException if an I/O error occurs when creating the socket
     * @throws SecurityException if a security manager exists and its
     *         <code>checkConnect</code> method doesn't allow the operation.
     * @throws UnknownHostException if the host is not known
     * @throws IllegalArgumentException if the port parameter is outside the
     *         specified range of valid port values, which is between 0 and
     *         65535, inclusive.
     * @see SecurityManager#checkConnect
     */
    protected SSLSocket(String host, int port)
    throws IOException, UnknownHostException
        { super(host, port); }


    
Used only by subclasses.
Constructs a TCP connection to a server at a specified address
and port.  This acts as the SSL client.

If there is a security manager, its checkConnect
method is called with the host address and port
as its arguments. This could result in a SecurityException.
Params:
address – the server's host
port – its port
Throws:
IOException – if an I/O error occurs when creating the socket
SecurityException – if a security manager exists and its
        checkConnect method doesn't allow the operation.
IllegalArgumentException – if the port parameter is outside the
        specified range of valid port values, which is between 0 and
        65535, inclusive.
NullPointerException – if address is null.
See Also:
SecurityManager.checkConnect/**
     * Used only by subclasses.
     * Constructs a TCP connection to a server at a specified address
     * and port.  This acts as the SSL client.
     * <p>
     * If there is a security manager, its <code>checkConnect</code>
     * method is called with the host address and <code>port</code>
     * as its arguments. This could result in a SecurityException.
     *
     * @param address the server's host
     * @param port its port
     * @throws IOException if an I/O error occurs when creating the socket
     * @throws SecurityException if a security manager exists and its
     *         <code>checkConnect</code> method doesn't allow the operation.
     * @throws IllegalArgumentException if the port parameter is outside the
     *         specified range of valid port values, which is between 0 and
     *         65535, inclusive.
     * @throws NullPointerException if <code>address</code> is null.
     * @see SecurityManager#checkConnect
     */
    protected SSLSocket(InetAddress address, int port)
    throws IOException
        { super(address, port); }


    
Used only by subclasses.
Constructs an SSL connection to a named host at a specified port,
binding the client side of the connection a given address and port.
This acts as the SSL client.

If there is a security manager, its checkConnect
method is called with the host address and port
as its arguments. This could result in a SecurityException.
Params:
host – name of the host with which to connect, or
       null for the loopback address.
port – number of the server's port
clientAddress – the client's address the socket is bound to, or
       null for the anyLocal address.
clientPort – the client's port the socket is bound to, or
       zero for a system selected free port.
Throws:
IOException – if an I/O error occurs when creating the socket
SecurityException – if a security manager exists and its
        checkConnect method doesn't allow the operation.
UnknownHostException – if the host is not known
IllegalArgumentException – if the port parameter or clientPort
        parameter is outside the specified range of valid port values,
        which is between 0 and 65535, inclusive.
See Also:
SecurityManager.checkConnect/**
     * Used only by subclasses.
     * Constructs an SSL connection to a named host at a specified port,
     * binding the client side of the connection a given address and port.
     * This acts as the SSL client.
     * <p>
     * If there is a security manager, its <code>checkConnect</code>
     * method is called with the host address and <code>port</code>
     * as its arguments. This could result in a SecurityException.
     *
     * @param host name of the host with which to connect, or
     *        <code>null</code> for the loopback address.
     * @param port number of the server's port
     * @param clientAddress the client's address the socket is bound to, or
     *        <code>null</code> for the <code>anyLocal</code> address.
     * @param clientPort the client's port the socket is bound to, or
     *        <code>zero</code> for a system selected free port.
     * @throws IOException if an I/O error occurs when creating the socket
     * @throws SecurityException if a security manager exists and its
     *         <code>checkConnect</code> method doesn't allow the operation.
     * @throws UnknownHostException if the host is not known
     * @throws IllegalArgumentException if the port parameter or clientPort
     *         parameter is outside the specified range of valid port values,
     *         which is between 0 and 65535, inclusive.
     * @see SecurityManager#checkConnect
     */
    protected SSLSocket(String host, int port,
        InetAddress clientAddress, int clientPort)
    throws IOException, UnknownHostException
        { super(host, port, clientAddress, clientPort); }


    
Used only by subclasses.
Constructs an SSL connection to a server at a specified address
and TCP port, binding the client side of the connection a given
address and port.  This acts as the SSL client.

If there is a security manager, its checkConnect
method is called with the host address and port
as its arguments. This could result in a SecurityException.
Params:
address – the server's host
port – its port
clientAddress – the client's address the socket is bound to, or
       null for the anyLocal address.
clientPort – the client's port the socket is bound to, or
       zero for a system selected free port.
Throws:
IOException – if an I/O error occurs when creating the socket
SecurityException – if a security manager exists and its
        checkConnect method doesn't allow the operation.
IllegalArgumentException – if the port parameter or clientPort
        parameter is outside the specified range of valid port values,
        which is between 0 and 65535, inclusive.
NullPointerException – if address is null.
See Also:
SecurityManager.checkConnect/**
     * Used only by subclasses.
     * Constructs an SSL connection to a server at a specified address
     * and TCP port, binding the client side of the connection a given
     * address and port.  This acts as the SSL client.
     * <p>
     * If there is a security manager, its <code>checkConnect</code>
     * method is called with the host address and <code>port</code>
     * as its arguments. This could result in a SecurityException.
     *
     * @param address the server's host
     * @param port its port
     * @param clientAddress the client's address the socket is bound to, or
     *        <code>null</code> for the <code>anyLocal</code> address.
     * @param clientPort the client's port the socket is bound to, or
     *        <code>zero</code> for a system selected free port.
     * @throws IOException if an I/O error occurs when creating the socket
     * @throws SecurityException if a security manager exists and its
     *         <code>checkConnect</code> method doesn't allow the operation.
     * @throws IllegalArgumentException if the port parameter or clientPort
     *         parameter is outside the specified range of valid port values,
     *         which is between 0 and 65535, inclusive.
     * @throws NullPointerException if <code>address</code> is null.
     * @see SecurityManager#checkConnect
     */
    protected SSLSocket(InetAddress address, int port,
        InetAddress clientAddress, int clientPort)
    throws IOException
        { super(address, port, clientAddress, clientPort); }


    
Returns the names of the cipher suites which could be enabled for use
on this connection.  Normally, only a subset of these will actually
be enabled by default, since this list may include cipher suites which
do not meet quality of service requirements for those defaults.  Such
cipher suites might be useful in specialized applications.

The returned array includes cipher suites from the list of standard
cipher suite names in the 
JSSE Cipher Suite Names section of the Java Cryptography
Architecture Standard Algorithm Name Documentation, and may also
include other cipher suites that the provider supports.
See Also:
getEnabledCipherSuites()
setEnabledCipherSuites(String[])
Returns:
an array of cipher suite names/**
     * Returns the names of the cipher suites which could be enabled for use
     * on this connection.  Normally, only a subset of these will actually
     * be enabled by default, since this list may include cipher suites which
     * do not meet quality of service requirements for those defaults.  Such
     * cipher suites might be useful in specialized applications.
     * <P>
     * The returned array includes cipher suites from the list of standard
     * cipher suite names in the <a href=
     * "{@docRoot}/../specs/security/standard-names.html#jsse-cipher-suite-names">
     * JSSE Cipher Suite Names</a> section of the Java Cryptography
     * Architecture Standard Algorithm Name Documentation, and may also
     * include other cipher suites that the provider supports.
     *
     * @return an array of cipher suite names
     * @see #getEnabledCipherSuites()
     * @see #setEnabledCipherSuites(String [])
     */
    public abstract String [] getSupportedCipherSuites();


    
Returns the names of the SSL cipher suites which are currently
enabled for use on this connection.  When an SSLSocket is first
created, all enabled cipher suites support a minimum quality of
service.  Thus, in some environments this value might be empty.

Note that even if a suite is enabled, it may never be used. This
can occur if the peer does not support it, or its use is restricted,
or the requisite certificates (and private keys) for the suite are
not available, or an anonymous suite is enabled but authentication
is required.

The returned array includes cipher suites from the list of standard
cipher suite names in the 
JSSE Cipher Suite Names section of the Java Cryptography
Architecture Standard Algorithm Name Documentation, and may also
include other cipher suites that the provider supports.
See Also:
getSupportedCipherSuites()
setEnabledCipherSuites(String[])
Returns:
an array of cipher suite names/**
     * Returns the names of the SSL cipher suites which are currently
     * enabled for use on this connection.  When an SSLSocket is first
     * created, all enabled cipher suites support a minimum quality of
     * service.  Thus, in some environments this value might be empty.
     * <P>
     * Note that even if a suite is enabled, it may never be used. This
     * can occur if the peer does not support it, or its use is restricted,
     * or the requisite certificates (and private keys) for the suite are
     * not available, or an anonymous suite is enabled but authentication
     * is required.
     * <P>
     * The returned array includes cipher suites from the list of standard
     * cipher suite names in the <a href=
     * "{@docRoot}/../specs/security/standard-names.html#jsse-cipher-suite-names">
     * JSSE Cipher Suite Names</a> section of the Java Cryptography
     * Architecture Standard Algorithm Name Documentation, and may also
     * include other cipher suites that the provider supports.
     *
     * @return an array of cipher suite names
     * @see #getSupportedCipherSuites()
     * @see #setEnabledCipherSuites(String [])
     */
    public abstract String [] getEnabledCipherSuites();


    
Sets the cipher suites enabled for use on this connection.

Each cipher suite in the suites parameter must have
been listed by getSupportedCipherSuites(), or the method will
fail.  Following a successful call to this method, only suites
listed in the suites parameter are enabled for use.

Note that the standard list of cipher suite names may be found in the

JSSE Cipher Suite Names section of the Java Cryptography
Architecture Standard Algorithm Name Documentation.  Providers
may support cipher suite names not found in this list or might not
use the recommended name for a certain cipher suite.
 See getEnabledCipherSuites() for more information on why a specific ciphersuite may never be used on a connection. 
Params:
suites – Names of all the cipher suites to enable
Throws:
IllegalArgumentException – when one or more of the ciphers
         named by the parameter is not supported, or when the
         parameter is null.
See Also:
getSupportedCipherSuites()
getEnabledCipherSuites()/**
     * Sets the cipher suites enabled for use on this connection.
     * <P>
     * Each cipher suite in the <code>suites</code> parameter must have
     * been listed by getSupportedCipherSuites(), or the method will
     * fail.  Following a successful call to this method, only suites
     * listed in the <code>suites</code> parameter are enabled for use.
     * <P>
     * Note that the standard list of cipher suite names may be found in the
     * <a href=
     * "{@docRoot}/../specs/security/standard-names.html#jsse-cipher-suite-names">
     * JSSE Cipher Suite Names</a> section of the Java Cryptography
     * Architecture Standard Algorithm Name Documentation.  Providers
     * may support cipher suite names not found in this list or might not
     * use the recommended name for a certain cipher suite.
     * <P>
     * See {@link #getEnabledCipherSuites()} for more information
     * on why a specific ciphersuite may never be used on a connection.
     *
     * @param suites Names of all the cipher suites to enable
     * @throws IllegalArgumentException when one or more of the ciphers
     *          named by the parameter is not supported, or when the
     *          parameter is null.
     * @see #getSupportedCipherSuites()
     * @see #getEnabledCipherSuites()
     */
    public abstract void setEnabledCipherSuites(String suites []);


    
Returns the names of the protocols which could be enabled for use
on an SSL connection.
Returns:
an array of protocols supported/**
     * Returns the names of the protocols which could be enabled for use
     * on an SSL connection.
     *
     * @return an array of protocols supported
     */
    public abstract String [] getSupportedProtocols();


    
Returns the names of the protocol versions which are currently
enabled for use on this connection.

Note that even if a protocol is enabled, it may never be used.
This can occur if the peer does not support the protocol, or its
use is restricted, or there are no enabled cipher suites supported
by the protocol.
See Also:
setEnabledProtocols(String[])
Returns:
an array of protocols/**
     * Returns the names of the protocol versions which are currently
     * enabled for use on this connection.
     * <P>
     * Note that even if a protocol is enabled, it may never be used.
     * This can occur if the peer does not support the protocol, or its
     * use is restricted, or there are no enabled cipher suites supported
     * by the protocol.
     *
     * @see #setEnabledProtocols(String [])
     * @return an array of protocols
     */
    public abstract String [] getEnabledProtocols();


    
Sets the protocol versions enabled for use on this connection.

The protocols must have been listed by
getSupportedProtocols() as being supported.
Following a successful call to this method, only protocols listed
in the protocols parameter are enabled for use.
Params:
protocols – Names of all the protocols to enable.
Throws:
IllegalArgumentException – when one or more of
           the protocols named by the parameter is not supported or
           when the protocols parameter is null.
See Also:
getEnabledProtocols()/**
     * Sets the protocol versions enabled for use on this connection.
     * <P>
     * The protocols must have been listed by
     * <code>getSupportedProtocols()</code> as being supported.
     * Following a successful call to this method, only protocols listed
     * in the <code>protocols</code> parameter are enabled for use.
     *
     * @param protocols Names of all the protocols to enable.
     * @throws IllegalArgumentException when one or more of
     *            the protocols named by the parameter is not supported or
     *            when the protocols parameter is null.
     * @see #getEnabledProtocols()
     */
    public abstract void setEnabledProtocols(String protocols[]);


    
Returns the SSL Session in use by this connection.  These can
be long lived, and frequently correspond to an entire login session
for some user.  The session specifies a particular cipher suite
which is being actively used by all connections in that session,
as well as the identities of the session's client and server.

This method will initiate the initial handshake if
necessary and then block until the handshake has been
established.

If an error occurs during the initial handshake, this method
returns an invalid session object which reports an invalid
cipher suite of "SSL_NULL_WITH_NULL_NULL".
Returns:
the SSLSession/**
     * Returns the SSL Session in use by this connection.  These can
     * be long lived, and frequently correspond to an entire login session
     * for some user.  The session specifies a particular cipher suite
     * which is being actively used by all connections in that session,
     * as well as the identities of the session's client and server.
     * <P>
     * This method will initiate the initial handshake if
     * necessary and then block until the handshake has been
     * established.
     * <P>
     * If an error occurs during the initial handshake, this method
     * returns an invalid session object which reports an invalid
     * cipher suite of "SSL_NULL_WITH_NULL_NULL".
     *
     * @return the <code>SSLSession</code>
     */
    public abstract SSLSession getSession();


    
Returns the SSLSession being constructed during a SSL/TLS handshake. 
 TLS protocols may negotiate parameters that are needed when using an instance of this class, but before the SSLSession has been completely initialized and made available via getSession. For example, the list of valid signature algorithms may restrict the type of certificates that can be used during TrustManager decisions, or the maximum TLS fragment packet sizes can be resized to better support the network environment. 
 This method provides early access to the SSLSession being constructed. Depending on how far the handshake has progressed, some data may not yet be available for use. For example, if a remote server will be sending a Certificate chain, but that chain has yet not been processed, the getPeerCertificates method of SSLSession will throw a SSLPeerUnverifiedException. Once that chain has been processed, getPeerCertificates will return the proper value. 
 Unlike getSession(), this method does not initiate the initial handshake and does not block until handshaking is complete. 
Throws:
UnsupportedOperationException – if the underlying provider
        does not implement the operation.
See Also:
SSLEngine
SSLSession
ExtendedSSLSession
X509ExtendedKeyManager
X509ExtendedTrustManager
Returns:
null if this instance is not currently handshaking, or if the current handshake has not progressed far enough to create a basic SSLSession. Otherwise, this method returns the SSLSession currently being negotiated.
Since:
1.7/**
     * Returns the {@code SSLSession} being constructed during a SSL/TLS
     * handshake.
     * <p>
     * TLS protocols may negotiate parameters that are needed when using
     * an instance of this class, but before the {@code SSLSession} has
     * been completely initialized and made available via {@code getSession}.
     * For example, the list of valid signature algorithms may restrict
     * the type of certificates that can be used during TrustManager
     * decisions, or the maximum TLS fragment packet sizes can be
     * resized to better support the network environment.
     * <p>
     * This method provides early access to the {@code SSLSession} being
     * constructed.  Depending on how far the handshake has progressed,
     * some data may not yet be available for use.  For example, if a
     * remote server will be sending a Certificate chain, but that chain
     * has yet not been processed, the {@code getPeerCertificates}
     * method of {@code SSLSession} will throw a
     * SSLPeerUnverifiedException.  Once that chain has been processed,
     * {@code getPeerCertificates} will return the proper value.
     * <p>
     * Unlike {@link #getSession()}, this method does not initiate the
     * initial handshake and does not block until handshaking is
     * complete.
     *
     * @see SSLEngine
     * @see SSLSession
     * @see ExtendedSSLSession
     * @see X509ExtendedKeyManager
     * @see X509ExtendedTrustManager
     *
     * @return null if this instance is not currently handshaking, or
     *         if the current handshake has not progressed far enough to
     *         create a basic SSLSession.  Otherwise, this method returns the
     *         {@code SSLSession} currently being negotiated.
     * @throws UnsupportedOperationException if the underlying provider
     *         does not implement the operation.
     *
     * @since 1.7
     */
    public SSLSession getHandshakeSession() {
        throw new UnsupportedOperationException();
    }


    
Registers an event listener to receive notifications that an
SSL handshake has completed on this connection.
Params:
listener – the HandShake Completed event listener
Throws:
IllegalArgumentException – if the argument is null.
See Also:
startHandshake()
removeHandshakeCompletedListener(HandshakeCompletedListener)/**
     * Registers an event listener to receive notifications that an
     * SSL handshake has completed on this connection.
     *
     * @param listener the HandShake Completed event listener
     * @see #startHandshake()
     * @see #removeHandshakeCompletedListener(HandshakeCompletedListener)
     * @throws IllegalArgumentException if the argument is null.
     */
    public abstract void addHandshakeCompletedListener(
        HandshakeCompletedListener listener);


    
Removes a previously registered handshake completion listener.
Params:
listener – the HandShake Completed event listener
Throws:
IllegalArgumentException – if the listener is not registered,
or the argument is null.
See Also:
addHandshakeCompletedListener(HandshakeCompletedListener)/**
     * Removes a previously registered handshake completion listener.
     *
     * @param listener the HandShake Completed event listener
     * @throws IllegalArgumentException if the listener is not registered,
     * or the argument is null.
     * @see #addHandshakeCompletedListener(HandshakeCompletedListener)
     */
    public abstract void removeHandshakeCompletedListener(
        HandshakeCompletedListener listener);


    
Starts an SSL handshake on this connection.  Common reasons include
a need to use new encryption keys, to change cipher suites, or to
initiate a new session.  To force complete reauthentication, the
current session could be invalidated before starting this handshake.
 If data has already been sent on the connection, it continues
to flow during this handshake.  When the handshake completes, this
will be signaled with an event.
This method is synchronous for the initial handshake on a connection
and returns when the negotiated handshake is complete. Some
protocols may not support multiple handshakes on an existing socket
and may throw an IOException.
Throws:
IOException – on a network level error
See Also:
addHandshakeCompletedListener(HandshakeCompletedListener)/**
     * Starts an SSL handshake on this connection.  Common reasons include
     * a need to use new encryption keys, to change cipher suites, or to
     * initiate a new session.  To force complete reauthentication, the
     * current session could be invalidated before starting this handshake.
     *
     * <P> If data has already been sent on the connection, it continues
     * to flow during this handshake.  When the handshake completes, this
     * will be signaled with an event.
     *
     * This method is synchronous for the initial handshake on a connection
     * and returns when the negotiated handshake is complete. Some
     * protocols may not support multiple handshakes on an existing socket
     * and may throw an IOException.
     *
     * @throws IOException on a network level error
     * @see #addHandshakeCompletedListener(HandshakeCompletedListener)
     */
    public abstract void startHandshake() throws IOException;


    
Configures the socket to use client (or server) mode when
handshaking.

This method must be called before any handshaking occurs.
Once handshaking has begun, the mode can not be reset for the
life of this socket.

Servers normally authenticate themselves, and clients
are not required to do so.
Params:
mode – true if the socket should start its handshaking
         in "client" mode
Throws:
IllegalArgumentException – if a mode change is attempted
         after the initial handshake has begun.
See Also:
getUseClientMode()/**
     * Configures the socket to use client (or server) mode when
     * handshaking.
     * <P>
     * This method must be called before any handshaking occurs.
     * Once handshaking has begun, the mode can not be reset for the
     * life of this socket.
     * <P>
     * Servers normally authenticate themselves, and clients
     * are not required to do so.
     *
     * @param mode true if the socket should start its handshaking
     *          in "client" mode
     * @throws IllegalArgumentException if a mode change is attempted
     *          after the initial handshake has begun.
     * @see #getUseClientMode()
     */
    public abstract void setUseClientMode(boolean mode);


    
Returns true if the socket is set to use client mode when
handshaking.
See Also:
setUseClientMode(boolean)
Returns:
true if the socket should do handshaking
         in "client" mode/**
     * Returns true if the socket is set to use client mode when
     * handshaking.
     *
     * @return true if the socket should do handshaking
     *          in "client" mode
     * @see #setUseClientMode(boolean)
     */
    public abstract boolean getUseClientMode();


    
Configures the socket to require client authentication.  This
option is only useful for sockets in the server mode.

A socket's client authentication setting is one of the following:

 client authentication required
 client authentication requested
 no client authentication desired

 Unlike setWantClientAuth(boolean), if this option is set and the client chooses not to provide authentication information about itself, the negotiations will stop and the connection
will be dropped.
 Calling this method overrides any previous setting made by this method or setWantClientAuth(boolean). 
Params:
need – set to true if client authentication is required,
         or false if no client authentication is desired.
See Also:
getNeedClientAuth()
setWantClientAuth(boolean)
getWantClientAuth()
setUseClientMode(boolean)/**
     * Configures the socket to <i>require</i> client authentication.  This
     * option is only useful for sockets in the server mode.
     * <P>
     * A socket's client authentication setting is one of the following:
     * <ul>
     * <li> client authentication required
     * <li> client authentication requested
     * <li> no client authentication desired
     * </ul>
     * <P>
     * Unlike {@link #setWantClientAuth(boolean)}, if this option is set and
     * the client chooses not to provide authentication information
     * about itself, <i>the negotiations will stop and the connection
     * will be dropped</i>.
     * <P>
     * Calling this method overrides any previous setting made by
     * this method or {@link #setWantClientAuth(boolean)}.
     *
     * @param   need set to true if client authentication is required,
     *          or false if no client authentication is desired.
     * @see #getNeedClientAuth()
     * @see #setWantClientAuth(boolean)
     * @see #getWantClientAuth()
     * @see #setUseClientMode(boolean)
     */
    public abstract void setNeedClientAuth(boolean need);


    
Returns true if the socket will require client authentication.
This option is only useful to sockets in the server mode.
See Also:
setNeedClientAuth(boolean)
setWantClientAuth(boolean)
getWantClientAuth()
setUseClientMode(boolean)
Returns:
 true if client authentication is required,
         or false if no client authentication is desired./**
     * Returns true if the socket will <i>require</i> client authentication.
     * This option is only useful to sockets in the server mode.
     *
     * @return  true if client authentication is required,
     *          or false if no client authentication is desired.
     * @see #setNeedClientAuth(boolean)
     * @see #setWantClientAuth(boolean)
     * @see #getWantClientAuth()
     * @see #setUseClientMode(boolean)
     */
    public abstract boolean getNeedClientAuth();


    
Configures the socket to request client authentication.
This option is only useful for sockets in the server mode.

A socket's client authentication setting is one of the following:

 client authentication required
 client authentication requested
 no client authentication desired

 Unlike setNeedClientAuth(boolean), if this option is set and the client chooses not to provide authentication information about itself, the negotiations will continue.
 Calling this method overrides any previous setting made by this method or setNeedClientAuth(boolean). 
Params:
want – set to true if client authentication is requested,
         or false if no client authentication is desired.
See Also:
getWantClientAuth()
setNeedClientAuth(boolean)
getNeedClientAuth()
setUseClientMode(boolean)/**
     * Configures the socket to <i>request</i> client authentication.
     * This option is only useful for sockets in the server mode.
     * <P>
     * A socket's client authentication setting is one of the following:
     * <ul>
     * <li> client authentication required
     * <li> client authentication requested
     * <li> no client authentication desired
     * </ul>
     * <P>
     * Unlike {@link #setNeedClientAuth(boolean)}, if this option is set and
     * the client chooses not to provide authentication information
     * about itself, <i>the negotiations will continue</i>.
     * <P>
     * Calling this method overrides any previous setting made by
     * this method or {@link #setNeedClientAuth(boolean)}.
     *
     * @param   want set to true if client authentication is requested,
     *          or false if no client authentication is desired.
     * @see #getWantClientAuth()
     * @see #setNeedClientAuth(boolean)
     * @see #getNeedClientAuth()
     * @see #setUseClientMode(boolean)
     */
    public abstract void setWantClientAuth(boolean want);


    
Returns true if the socket will request client authentication.
This option is only useful for sockets in the server mode.
See Also:
setNeedClientAuth(boolean)
getNeedClientAuth()
setWantClientAuth(boolean)
setUseClientMode(boolean)
Returns:
 true if client authentication is requested,
         or false if no client authentication is desired./**
     * Returns true if the socket will <i>request</i> client authentication.
     * This option is only useful for sockets in the server mode.
     *
     * @return  true if client authentication is requested,
     *          or false if no client authentication is desired.
     * @see #setNeedClientAuth(boolean)
     * @see #getNeedClientAuth()
     * @see #setWantClientAuth(boolean)
     * @see #setUseClientMode(boolean)
     */
    public abstract boolean getWantClientAuth();


    
Controls whether new SSL sessions may be established by this socket.
If session creations are not allowed, and there are no
existing sessions to resume, there will be no successful
handshaking.
Params:
flag – true indicates that sessions may be created; this
         is the default.  false indicates that an existing session
         must be resumed
See Also:
getEnableSessionCreation()/**
     * Controls whether new SSL sessions may be established by this socket.
     * If session creations are not allowed, and there are no
     * existing sessions to resume, there will be no successful
     * handshaking.
     *
     * @param flag true indicates that sessions may be created; this
     *          is the default.  false indicates that an existing session
     *          must be resumed
     * @see #getEnableSessionCreation()
     */
    public abstract void setEnableSessionCreation(boolean flag);


    
Returns true if new SSL sessions may be established by this socket.
See Also:
setEnableSessionCreation(boolean)
Returns:
true indicates that sessions may be created; this
         is the default.  false indicates that an existing session
         must be resumed/**
     * Returns true if new SSL sessions may be established by this socket.
     *
     * @return true indicates that sessions may be created; this
     *          is the default.  false indicates that an existing session
     *          must be resumed
     * @see #setEnableSessionCreation(boolean)
     */
    public abstract boolean getEnableSessionCreation();

    
Returns the SSLParameters in effect for this SSLSocket.
The ciphersuites and protocols of the returned SSLParameters
are always non-null.
Returns:
the SSLParameters in effect for this SSLSocket.
Since:
1.6/**
     * Returns the SSLParameters in effect for this SSLSocket.
     * The ciphersuites and protocols of the returned SSLParameters
     * are always non-null.
     *
     * @return the SSLParameters in effect for this SSLSocket.
     * @since 1.6
     */
    public SSLParameters getSSLParameters() {
        SSLParameters params = new SSLParameters();
        params.setCipherSuites(getEnabledCipherSuites());
        params.setProtocols(getEnabledProtocols());
        if (getNeedClientAuth()) {
            params.setNeedClientAuth(true);
        } else if (getWantClientAuth()) {
            params.setWantClientAuth(true);
        }
        return params;
    }

    
Applies SSLParameters to this socket.
This means:

If params.getCipherSuites() is non-null, setEnabledCipherSuites() is called with that value.
If params.getProtocols() is non-null, setEnabledProtocols() is called with that value.
If params.getNeedClientAuth() or params.getWantClientAuth() return true, setNeedClientAuth(true) and setWantClientAuth(true) are called, respectively; otherwise setWantClientAuth(false) is called.
If params.getServerNames() is non-null, the socket will configure its server names with that value.
If params.getSNIMatchers() is non-null, the socket will configure its SNI matchers with that value.

Params:
params – the parameters
Throws:
IllegalArgumentException – if the setEnabledCipherSuites() or
   the setEnabledProtocols() call fails
Since:
1.6/**
     * Applies SSLParameters to this socket.
     *
     * <p>This means:
     * <ul>
     * <li>If {@code params.getCipherSuites()} is non-null,
     *   {@code setEnabledCipherSuites()} is called with that value.</li>
     * <li>If {@code params.getProtocols()} is non-null,
     *   {@code setEnabledProtocols()} is called with that value.</li>
     * <li>If {@code params.getNeedClientAuth()} or
     *   {@code params.getWantClientAuth()} return {@code true},
     *   {@code setNeedClientAuth(true)} and
     *   {@code setWantClientAuth(true)} are called, respectively;
     *   otherwise {@code setWantClientAuth(false)} is called.</li>
     * <li>If {@code params.getServerNames()} is non-null, the socket will
     *   configure its server names with that value.</li>
     * <li>If {@code params.getSNIMatchers()} is non-null, the socket will
     *   configure its SNI matchers with that value.</li>
     * </ul>
     *
     * @param params the parameters
     * @throws IllegalArgumentException if the setEnabledCipherSuites() or
     *    the setEnabledProtocols() call fails
     * @since 1.6
     */
    public void setSSLParameters(SSLParameters params) {
        String[] s;
        s = params.getCipherSuites();
        if (s != null) {
            setEnabledCipherSuites(s);
        }
        s = params.getProtocols();
        if (s != null) {
            setEnabledProtocols(s);
        }
        if (params.getNeedClientAuth()) {
            setNeedClientAuth(true);
        } else if (params.getWantClientAuth()) {
            setWantClientAuth(true);
        } else {
            setWantClientAuth(false);
        }
    }

    
Returns the most recent application protocol value negotiated for this
connection.

If supported by the underlying SSL/TLS/DTLS implementation,
application name negotiation mechanisms such as  RFC 7301 , the
Application-Layer Protocol Negotiation (ALPN), can negotiate
application-level values between peers.
Throws:
UnsupportedOperationException – if the underlying provider
        does not implement the operation.
Implementation Requirements:
 The implementation in this class throws UnsupportedOperationException and performs no other action.
Returns:
null if it has not yet been determined if application protocols might be used for this connection, an empty String if application protocols values will not be used, or a non-empty application protocol String if a value was successfully negotiated.
Since:
9/**
     * Returns the most recent application protocol value negotiated for this
     * connection.
     * <p>
     * If supported by the underlying SSL/TLS/DTLS implementation,
     * application name negotiation mechanisms such as <a
     * href="http://www.ietf.org/rfc/rfc7301.txt"> RFC 7301 </a>, the
     * Application-Layer Protocol Negotiation (ALPN), can negotiate
     * application-level values between peers.
     *
     * @implSpec
     * The implementation in this class throws
     * {@code UnsupportedOperationException} and performs no other action.
     *
     * @return null if it has not yet been determined if application
     *         protocols might be used for this connection, an empty
     *         {@code String} if application protocols values will not
     *         be used, or a non-empty application protocol {@code String}
     *         if a value was successfully negotiated.
     * @throws UnsupportedOperationException if the underlying provider
     *         does not implement the operation.
     * @since 9
     */
    public String getApplicationProtocol() {
        throw new UnsupportedOperationException();
    }

    
Returns the application protocol value negotiated on a SSL/TLS
handshake currently in progress.
 Like getHandshakeSession(), a connection may be in the middle of a handshake. The application protocol may or may not yet be available. 
Throws:
UnsupportedOperationException – if the underlying provider
        does not implement the operation.
Implementation Requirements:
 The implementation in this class throws UnsupportedOperationException and performs no other action.
Returns:
null if it has not yet been determined if application protocols might be used for this handshake, an empty String if application protocols values will not be used, or a non-empty application protocol String if a value was successfully negotiated.
Since:
9/**
     * Returns the application protocol value negotiated on a SSL/TLS
     * handshake currently in progress.
     * <p>
     * Like {@link #getHandshakeSession()},
     * a connection may be in the middle of a handshake. The
     * application protocol may or may not yet be available.
     *
     * @implSpec
     * The implementation in this class throws
     * {@code UnsupportedOperationException} and performs no other action.
     *
     * @return null if it has not yet been determined if application
     *         protocols might be used for this handshake, an empty
     *         {@code String} if application protocols values will not
     *         be used, or a non-empty application protocol {@code String}
     *         if a value was successfully negotiated.
     * @throws UnsupportedOperationException if the underlying provider
     *         does not implement the operation.
     * @since 9
     */
    public String getHandshakeApplicationProtocol() {
        throw new UnsupportedOperationException();
    }


    
Registers a callback function that selects an application protocol value for a SSL/TLS/DTLS handshake. The function overrides any values supplied using 
SSLParameters.setApplicationProtocols and it supports the following type parameters: 


 SSLSocket 
 The function's first argument allows the current SSLSocket to be inspected, including the handshake session and configuration settings. 
 List<String> 
 The function's second argument lists the application protocol names
     advertised by the TLS peer.
 String 
 The function's result is an application protocol name, or null to indicate that none of the advertised names are acceptable. If the return value is an empty String then application protocol indications will not be used. If the return value is null (no value chosen) or is a value that was not advertised by the peer, the underlying protocol will determine what action to take. (For example, ALPN will send a "no_application_protocol" alert and terminate the connection.) 

For example, the following call registers a callback function that
examines the TLS handshake parameters and selects an application protocol
name:

    serverSocket.setHandshakeApplicationProtocolSelector(
        (serverSocket, clientProtocols) -> {
            SSLSession session = serverSocket.getHandshakeSession();
            return chooseApplicationProtocol(
                serverSocket,
                clientProtocols,
                session.getProtocol(),
                session.getCipherSuite());
        });

Params:
selector – the callback function, or null to de-register.
Throws:
UnsupportedOperationException – if the underlying provider
        does not implement the operation.
API Note:
 This method should be called by TLS server applications before the TLS handshake begins. Also, this SSLSocket should be configured with parameters that are compatible with the application protocol selected by the callback function. For example, enabling a poor choice of cipher suites could result in no suitable application protocol. See SSLParameters.
Implementation Requirements:
 The implementation in this class throws UnsupportedOperationException and performs no other action.
Since:
9/**
     * Registers a callback function that selects an application protocol
     * value for a SSL/TLS/DTLS handshake.
     * The function overrides any values supplied using
     * {@link SSLParameters#setApplicationProtocols
     * SSLParameters.setApplicationProtocols} and it supports the following
     * type parameters:
     * <blockquote>
     * <dl>
     * <dt> {@code SSLSocket}
     * <dd> The function's first argument allows the current {@code SSLSocket}
     *      to be inspected, including the handshake session and configuration
     *      settings.
     * <dt> {@code List<String>}
     * <dd> The function's second argument lists the application protocol names
     *      advertised by the TLS peer.
     * <dt> {@code String}
     * <dd> The function's result is an application protocol name, or null to
     *      indicate that none of the advertised names are acceptable.
     *      If the return value is an empty {@code String} then application
     *      protocol indications will not be used.
     *      If the return value is null (no value chosen) or is a value that
     *      was not advertised by the peer, the underlying protocol will
     *      determine what action to take. (For example, ALPN will send a
     *      "no_application_protocol" alert and terminate the connection.)
     * </dl>
     * </blockquote>
     *
     * For example, the following call registers a callback function that
     * examines the TLS handshake parameters and selects an application protocol
     * name:
     * <pre>{@code
     *     serverSocket.setHandshakeApplicationProtocolSelector(
     *         (serverSocket, clientProtocols) -> {
     *             SSLSession session = serverSocket.getHandshakeSession();
     *             return chooseApplicationProtocol(
     *                 serverSocket,
     *                 clientProtocols,
     *                 session.getProtocol(),
     *                 session.getCipherSuite());
     *         });
     * }</pre>
     *
     * @apiNote
     * This method should be called by TLS server applications before the TLS
     * handshake begins. Also, this {@code SSLSocket} should be configured with
     * parameters that are compatible with the application protocol selected by
     * the callback function. For example, enabling a poor choice of cipher
     * suites could result in no suitable application protocol.
     * See {@link SSLParameters}.
     *
     * @implSpec
     * The implementation in this class throws
     * {@code UnsupportedOperationException} and performs no other action.
     *
     * @param selector the callback function, or null to de-register.
     * @throws UnsupportedOperationException if the underlying provider
     *         does not implement the operation.
     * @since 9
     */
    public void setHandshakeApplicationProtocolSelector(
            BiFunction<SSLSocket, List<String>, String> selector) {
        throw new UnsupportedOperationException();
    }

    
Retrieves the callback function that selects an application protocol value during a SSL/TLS/DTLS handshake. See 
setHandshakeApplicationProtocolSelector for the function's type parameters. 
Throws:
UnsupportedOperationException – if the underlying provider
        does not implement the operation.
Implementation Requirements:
 The implementation in this class throws UnsupportedOperationException and performs no other action.
Returns:
the callback function, or null if none has been set.
Since:
9/**
     * Retrieves the callback function that selects an application protocol
     * value during a SSL/TLS/DTLS handshake.
     * See {@link #setHandshakeApplicationProtocolSelector
     * setHandshakeApplicationProtocolSelector}
     * for the function's type parameters.
     *
     * @implSpec
     * The implementation in this class throws
     * {@code UnsupportedOperationException} and performs no other action.
     *
     * @return the callback function, or null if none has been set.
     * @throws UnsupportedOperationException if the underlying provider
     *         does not implement the operation.
     * @since 9
     */
    public BiFunction<SSLSocket, List<String>, String>
            getHandshakeApplicationProtocolSelector() {
        throw new UnsupportedOperationException();
    }
}