Sockets and provides secure
* socket 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:
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:
startHandshake which explicitly
* begins handshakes, or
* 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:
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 SSLSockets are 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.
*
* SSLSockets are created by SSLSocketFactorys,
* 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. * *
{@code SSLSocket} instances obtained from default {@link SSLSocketFactory}, * {@link SSLServerSocketFactory}, and {@link SSLContext} are configured as follows: * * * *
Client socket: *
| Protocol | *Supported (API Levels) | *Enabled by default (API Levels) | *
|---|---|---|
| SSLv3 | *1–25 | *1–22 | *
| TLSv1 | *1+ | *1+ | *
| TLSv1.1 | *16+ | *20+ | *
| TLSv1.2 | *16+ | *20+ | *
| TLSv1.3 | *29+ | *29+ | *
Server socket: *
| Protocol | *Supported (API Levels) | *Enabled by default (API Levels) | *
|---|---|---|
| SSLv3 | *1–25 | *1–22 | *
| TLSv1 | *1+ | *1+ | *
| TLSv1.1 | *16+ | *16+ | *
| TLSv1.2 | *16+ | *16+ | *
| TLSv1.3 | *29+ | *29+ | *
Methods that operate with cipher suite names (for example, * {@link #getSupportedCipherSuites() getSupportedCipherSuites}, * {@link #setEnabledCipherSuites(String[]) setEnabledCipherSuites}) have used * standard names for cipher suites since API Level 9, as listed in the table * below. Prior to API Level 9, non-standard (OpenSSL) names had been used (see * the table following this table). *
| Cipher suite | *Supported (API Levels) | *Enabled by default (API Levels) | *
|---|---|---|
| SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA | *9-22 | *9-19 | *
| SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA | *9-22 | *9-19 | *
| SSL_DHE_DSS_WITH_DES_CBC_SHA | *9-22 | *9-19 | *
| SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA | *9-22 | *9-19 | *
| SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA | *9-22 | *9-19 | *
| SSL_DHE_RSA_WITH_DES_CBC_SHA | *9-22 | *9-19 | *
| SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA | *9-22 | ** |
| SSL_DH_anon_EXPORT_WITH_RC4_40_MD5 | *9-22 | ** |
| SSL_DH_anon_WITH_3DES_EDE_CBC_SHA | *9-22 | ** |
| SSL_DH_anon_WITH_DES_CBC_SHA | *9-22 | ** |
| SSL_DH_anon_WITH_RC4_128_MD5 | *9-22 | ** |
| SSL_RSA_EXPORT_WITH_DES40_CBC_SHA | *9-22 | *9-19 | *
| SSL_RSA_EXPORT_WITH_RC4_40_MD5 | *9-22 | *9-19 | *
| SSL_RSA_WITH_3DES_EDE_CBC_SHA | *9+ | *9-19 | *
| SSL_RSA_WITH_DES_CBC_SHA | *9-22 | *9-19 | *
| SSL_RSA_WITH_NULL_MD5 | *9-22 | ** |
| SSL_RSA_WITH_NULL_SHA | *9-22 | ** |
| SSL_RSA_WITH_RC4_128_MD5 | *9-25 | *9-19 | *
| SSL_RSA_WITH_RC4_128_SHA | *9-25 | *9-23 | *
| TLS_AES_128_GCM_SHA256 | *29+ | *29+ | *
| TLS_AES_256_GCM_SHA384 | *29+ | *29+ | *
| TLS_CHACHA20_POLY1305_SHA256 | *29+ | *29+ | *
| TLS_DHE_DSS_WITH_AES_128_CBC_SHA | *9-22 | *9-22 | *
| TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 | *20-22 | ** |
| TLS_DHE_DSS_WITH_AES_128_GCM_SHA256 | *20-22 | ** |
| TLS_DHE_DSS_WITH_AES_256_CBC_SHA | *9-22 | *11-22 | *
| TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 | *20-22 | ** |
| TLS_DHE_DSS_WITH_AES_256_GCM_SHA384 | *20-22 | ** |
| TLS_DHE_RSA_WITH_AES_128_CBC_SHA | *9-25 | *9-25 | *
| TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 | *20-25 | ** |
| TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 | *20-25 | *20-25 | *
| TLS_DHE_RSA_WITH_AES_256_CBC_SHA | *9-25 | *11-25 | *
| TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 | *20-25 | ** |
| TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 | *20-25 | *20-25 | *
| TLS_DH_anon_WITH_AES_128_CBC_SHA | *9-22 | ** |
| TLS_DH_anon_WITH_AES_128_CBC_SHA256 | *20-22 | ** |
| TLS_DH_anon_WITH_AES_128_GCM_SHA256 | *20-22 | ** |
| TLS_DH_anon_WITH_AES_256_CBC_SHA | *9-22 | ** |
| TLS_DH_anon_WITH_AES_256_CBC_SHA256 | *20-22 | ** |
| TLS_DH_anon_WITH_AES_256_GCM_SHA384 | *20-22 | ** |
| TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA | *11-22 | *11-19 | *
| TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA | *11+ | *11+ | *
| TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 | *20-28 | ** |
| TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 | *20+ | *20+ | *
| TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA | *11+ | *11+ | *
| TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 | *20-28 | ** |
| TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 | *20+ | *20+ | *
| TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 | *24+ | *24+ | *
| TLS_ECDHE_ECDSA_WITH_NULL_SHA | *11-22 | ** |
| TLS_ECDHE_ECDSA_WITH_RC4_128_SHA | *11-25 | *11-23 | *
| TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA | *21+ | *21+ | *
| TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA | *21+ | *21+ | *
| TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256 | *24+ | *24+ | *
| TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA | *11-22 | *11-19 | *
| TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA | *11+ | *11+ | *
| TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 | *20-28 | ** |
| TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 | *20+ | *20+ | *
| TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA | *11+ | *11+ | *
| TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 | *20-28 | ** |
| TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 | *20+ | *20+ | *
| TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 | *24+ | *24+ | *
| TLS_ECDHE_RSA_WITH_NULL_SHA | *11-22 | ** |
| TLS_ECDHE_RSA_WITH_RC4_128_SHA | *11-25 | *11-23 | *
| TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA | *11-22 | *11-19 | *
| TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA | *11-22 | *11-19 | *
| TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 | *20-22 | ** |
| TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 | *20-22 | ** |
| TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA | *11-22 | *11-19 | *
| TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 | *20-22 | ** |
| TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384 | *20-22 | ** |
| TLS_ECDH_ECDSA_WITH_NULL_SHA | *11-22 | ** |
| TLS_ECDH_ECDSA_WITH_RC4_128_SHA | *11-22 | *11-19 | *
| TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA | *11-22 | *11-19 | *
| TLS_ECDH_RSA_WITH_AES_128_CBC_SHA | *11-22 | *11-19 | *
| TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 | *20-22 | ** |
| TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 | *20-22 | ** |
| TLS_ECDH_RSA_WITH_AES_256_CBC_SHA | *11-22 | *11-19 | *
| TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 | *20-22 | ** |
| TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 | *20-22 | ** |
| TLS_ECDH_RSA_WITH_NULL_SHA | *11-22 | ** |
| TLS_ECDH_RSA_WITH_RC4_128_SHA | *11-22 | *11-19 | *
| TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA | *11-22 | ** |
| TLS_ECDH_anon_WITH_AES_128_CBC_SHA | *11-22 | ** |
| TLS_ECDH_anon_WITH_AES_256_CBC_SHA | *11-22 | ** |
| TLS_ECDH_anon_WITH_NULL_SHA | *11-22 | ** |
| TLS_ECDH_anon_WITH_RC4_128_SHA | *11-22 | ** |
| TLS_EMPTY_RENEGOTIATION_INFO_SCSV | *11+ | *11+ | *
| TLS_FALLBACK_SCSV | *21+ | ** |
| TLS_PSK_WITH_3DES_EDE_CBC_SHA | *21-22 | ** |
| TLS_PSK_WITH_AES_128_CBC_SHA | *21+ | *21+ | *
| TLS_PSK_WITH_AES_256_CBC_SHA | *21+ | *21+ | *
| TLS_PSK_WITH_RC4_128_SHA | *21-25 | ** |
| TLS_RSA_WITH_AES_128_CBC_SHA | *9+ | *9+ | *
| TLS_RSA_WITH_AES_128_CBC_SHA256 | *20-28 | ** |
| TLS_RSA_WITH_AES_128_GCM_SHA256 | *20+ | *20+ | *
| TLS_RSA_WITH_AES_256_CBC_SHA | *9+ | *11+ | *
| TLS_RSA_WITH_AES_256_CBC_SHA256 | *20-28 | ** |
| TLS_RSA_WITH_AES_256_GCM_SHA384 | *20+ | *20+ | *
| TLS_RSA_WITH_NULL_SHA256 | *20-22 | ** |
NOTE: PSK cipher suites are enabled by default only if the {@code SSLContext} through * which the socket was created has been initialized with a {@code PSKKeyManager}. * *
API Levels 1 to 8 use OpenSSL names for cipher suites. The table below * lists these OpenSSL names and their corresponding standard names used in API * Levels 9 and newer. *
| OpenSSL cipher suite | *Standard cipher suite | *Supported (API Levels) | *Enabled by default (API Levels) | *
|---|---|---|---|
| AES128-SHA | *TLS_RSA_WITH_AES_128_CBC_SHA | *1+ | *1+ | *
| AES256-SHA | *TLS_RSA_WITH_AES_256_CBC_SHA | *1+ | *1–8, 11+ | *
| DES-CBC-MD5 | *SSL_CK_DES_64_CBC_WITH_MD5 | *1–8 | *1–8 | *
| DES-CBC-SHA | *SSL_RSA_WITH_DES_CBC_SHA | *1–22 | *1–19 | *
| DES-CBC3-MD5 | *SSL_CK_DES_192_EDE3_CBC_WITH_MD5 | *1–8 | *1–8 | *
| DES-CBC3-SHA | *SSL_RSA_WITH_3DES_EDE_CBC_SHA | *1+ | *1–19 | *
| DHE-DSS-AES128-SHA | *TLS_DHE_DSS_WITH_AES_128_CBC_SHA | *1–22 | *1–22 | *
| DHE-DSS-AES256-SHA | *TLS_DHE_DSS_WITH_AES_256_CBC_SHA | *1–22 | *1–8, 11–22 | *
| DHE-RSA-AES128-SHA | *TLS_DHE_RSA_WITH_AES_128_CBC_SHA | *1+ | *1+ | *
| DHE-RSA-AES256-SHA | *TLS_DHE_RSA_WITH_AES_256_CBC_SHA | *1+ | *1–8, 11+ | *
| EDH-DSS-DES-CBC-SHA | *SSL_DHE_DSS_WITH_DES_CBC_SHA | *1–22 | *1–19 | *
| EDH-DSS-DES-CBC3-SHA | *SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA | *1–22 | *1–19 | *
| EDH-RSA-DES-CBC-SHA | *SSL_DHE_RSA_WITH_DES_CBC_SHA | *1–22 | *1–19 | *
| EDH-RSA-DES-CBC3-SHA | *SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA | *1–22 | *1–19 | *
| EXP-DES-CBC-SHA | *SSL_RSA_EXPORT_WITH_DES40_CBC_SHA | *1–22 | *1–19 | *
| EXP-EDH-DSS-DES-CBC-SHA | *SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA | *1–22 | *1–19 | *
| EXP-EDH-RSA-DES-CBC-SHA | *SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA | *1–22 | *1–19 | *
| EXP-RC2-CBC-MD5 | *SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5 | *1–8 | *1–8 | *
| EXP-RC4-MD5 | *SSL_RSA_EXPORT_WITH_RC4_40_MD5 | *1–22 | *1–19 | *
| RC2-CBC-MD5 | *SSL_CK_RC2_128_CBC_WITH_MD5 | *1–8 | *1–8 | *
| RC4-MD5 | *SSL_RSA_WITH_RC4_128_MD5 | *1–25 | *1–19 | *
| RC4-SHA | *SSL_RSA_WITH_RC4_128_SHA | *1–25 | *1–23 | *
* 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.
*
* @param host name of the host with which to connect, or
* null 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
* checkConnect 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.
*
* @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
* checkConnect 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 address 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.
*
* @param host name of the host with which to connect, or
* null for the loopback address.
* @param port number of the server's port
* @param clientAddress the client's address the socket is bound to, or
* null for the anyLocal address.
* @param 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
* @throws SecurityException if a security manager exists and its
* checkConnect 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.
*
* @param address the server's host
* @param port its port
* @param clientAddress the client's address the socket is bound to, or
* null for the anyLocal address.
* @param 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
* @throws SecurityException if a security manager exists and its
* checkConnect 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 address is null.
* @see SecurityManager#checkConnect
*/
protected SSLSocket(InetAddress address, int port,
InetAddress clientAddress, int clientPort)
throws IOException
{ super(address, port, clientAddress, clientPort); }
// Android-changed: Added warnings about misuse
/**
* 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.
*
*
Applications should not blindly enable all supported * cipher suites. The supported cipher suites can include signaling cipher suite * values that can cause connection problems if enabled inappropriately. * *
The proper way to use this method is to either check if a specific cipher * suite is supported via {@code Arrays.asList(getSupportedCipherSuites()).contains(...)} * or to filter a desired list of cipher suites to only the supported ones via * {@code desiredSuiteSet.retainAll(Arrays.asList(getSupportedCipherSuites()))}. * * @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. *
* Even if a suite has been enabled, it might never be used. (For * example, the peer does not support it, the requisite certificates * (and private keys) for the suite are not available, or an * anonymous suite is enabled but authentication is required. * * @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.
*
* 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. * * @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. * @see #setEnabledProtocols(String []) * @return an array of protocols */ public abstract String [] getEnabledProtocols(); // Android-added: Added paragraph about contiguous protocols. /** * 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.
*
* Because of the way the protocol version is negotiated, connections * will only be able to use a member of the lowest set of contiguous * enabled protocol versions. For example, enabling TLSv1.2 and TLSv1 * will result in connections only being able to use TLSv1. * * @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".
*
* @return the SSLSession
*/
public abstract SSLSession getSession();
/**
* Returns the {@code 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 {@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 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 {@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. *
* 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. * * @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. * * @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 #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. * * @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. * * @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: *
* Unlike {@link #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 {@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. * * @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: *
* Unlike {@link #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 {@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. * * @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. * * @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. * * @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. * * @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 supported by the underlying SSL/TLS implementation, * application name negotiation mechanisms such as RFC 7301 , 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 {@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 handshake. * The function overrides any values supplied using * {@link SSLParameters#setApplicationProtocols * SSLParameters.setApplicationProtocols} and it supports the following * type parameters: *
** * For example, the following call registers a callback function that * examines the TLS handshake parameters and selects an application protocol * name: **
*- {@code SSLSocket} *
- The function's first argument allows the current {@code SSLSocket} * to be inspected, including the handshake session and configuration * settings. *
- {@code List
} * - The function's second argument lists the application protocol names * advertised by the TLS peer. *
- {@code 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 {@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.) *
{@code
* serverSocket.setHandshakeApplicationProtocolSelector(
* (serverSocket, clientProtocols) -> {
* SSLSession session = serverSocket.getHandshakeSession();
* return chooseApplicationProtocol(
* serverSocket,
* clientProtocols,
* session.getProtocol(),
* session.getCipherSuite());
* });
* }
*
* @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