Added in API level 1

Summary: Protected Ctors | Methods | Inherited Methods

SSLSocket

public abstract class SSLSocket
extends Socket

java.lang.Object
↳	java.net.Socket
	↳	javax.net.ssl.SSLSocket

---

This class extends 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:

• 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 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.

Default configuration for different Android versions

SSLSocket instances obtained from default SSLSocketFactory, SSLServerSocketFactory, and SSLContext are configured as follows:

Protocols

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+

Cipher suites

Methods that operate with cipher suite names (for example, getSupportedCipherSuites, 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 SSLContext through which the socket was created has been initialized with a 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

See also:

• Socket
• SSLServerSocket
• SSLSocketFactory

Summary

Protected constructors
SSLSocket() Used only by subclasses.
SSLSocket(String host, int port) Used only by subclasses.
SSLSocket(InetAddress address, int port) Used only by subclasses.
SSLSocket(String host, int port, InetAddress clientAddress, int clientPort) Used only by subclasses.
SSLSocket(InetAddress address, int port, InetAddress clientAddress, int clientPort) Used only by subclasses.

Public methods
abstract void	addHandshakeCompletedListener(HandshakeCompletedListener listener) Registers an event listener to receive notifications that an SSL handshake has completed on this connection.
String	getApplicationProtocol() Returns the most recent application protocol value negotiated for this connection.
abstract boolean	getEnableSessionCreation() Returns true if new SSL sessions may be established by this socket.
abstract String[]	getEnabledCipherSuites() Returns the names of the SSL cipher suites which are currently enabled for use on this connection.
abstract String[]	getEnabledProtocols() Returns the names of the protocol versions which are currently enabled for use on this connection.
String	getHandshakeApplicationProtocol() Returns the application protocol value negotiated on a SSL/TLS handshake currently in progress.
BiFunction<SSLSocket, List<String>, String>	getHandshakeApplicationProtocolSelector() Retrieves the callback function that selects an application protocol value during a SSL/TLS handshake.
SSLSession	getHandshakeSession() Returns the SSLSession being constructed during a SSL/TLS handshake.
abstract boolean	getNeedClientAuth() Returns true if the socket will require client authentication.
SSLParameters	getSSLParameters() Returns the SSLParameters in effect for this SSLSocket.
abstract SSLSession	getSession() Returns the SSL Session in use by this connection.
abstract String[]	getSupportedCipherSuites() Returns the names of the cipher suites which could be enabled for use on this connection.
abstract String[]	getSupportedProtocols() Returns the names of the protocols which could be enabled for use on an SSL connection.
abstract boolean	getUseClientMode() Returns true if the socket is set to use client mode when handshaking.
abstract boolean	getWantClientAuth() Returns true if the socket will request client authentication.
abstract void	removeHandshakeCompletedListener(HandshakeCompletedListener listener) Removes a previously registered handshake completion listener.
abstract void	setEnableSessionCreation(boolean flag) Controls whether new SSL sessions may be established by this socket.
abstract void	setEnabledCipherSuites(String[] suites) Sets the cipher suites enabled for use on this connection.
abstract void	setEnabledProtocols(String[] protocols) Sets the protocol versions enabled for use on this connection.
void	setHandshakeApplicationProtocolSelector(BiFunction<SSLSocket, List<String>, String> selector) Registers a callback function that selects an application protocol value for a SSL/TLS handshake.
abstract void	setNeedClientAuth(boolean need) Configures the socket to require client authentication.
void	setSSLParameters(SSLParameters params) Applies SSLParameters to this socket.
abstract void	setUseClientMode(boolean mode) Configures the socket to use client (or server) mode when handshaking.
abstract void	setWantClientAuth(boolean want) Configures the socket to request client authentication.
abstract void	startHandshake() Starts an SSL handshake on this connection.
String	toString() Converts this socket to a String.

Inherited methods
From class java.net.Socket void bind(SocketAddress bindpoint) Binds the socket to a local address. void close() Closes this socket. void connect(SocketAddress endpoint, int timeout) Connects this socket to the server with a specified timeout value. void connect(SocketAddress endpoint) Connects this socket to the server. SocketChannel getChannel() Returns the unique SocketChannel object associated with this socket, if any. InetAddress getInetAddress() Returns the address to which the socket is connected. InputStream getInputStream() Returns an input stream for this socket. boolean getKeepAlive() Tests if SO_KEEPALIVE is enabled. InetAddress getLocalAddress() Gets the local address to which the socket is bound. int getLocalPort() Returns the local port number to which this socket is bound. SocketAddress getLocalSocketAddress() Returns the address of the endpoint this socket is bound to. boolean getOOBInline() Tests if SO_OOBINLINE is enabled. <T> T getOption(SocketOption<T> name) Returns the value of a socket option. OutputStream getOutputStream() Returns an output stream for this socket. int getPort() Returns the remote port number to which this socket is connected. int getReceiveBufferSize() Gets the value of the SO_RCVBUF option for this Socket, that is the buffer size used by the platform for input on this Socket. SocketAddress getRemoteSocketAddress() Returns the address of the endpoint this socket is connected to, or null if it is unconnected. boolean getReuseAddress() Tests if SO_REUSEADDR is enabled. int getSendBufferSize() Get value of the SO_SNDBUF option for this Socket, that is the buffer size used by the platform for output on this Socket. int getSoLinger() Returns setting for SO_LINGER. int getSoTimeout() Returns setting for SO_TIMEOUT. boolean getTcpNoDelay() Tests if TCP_NODELAY is enabled. int getTrafficClass() Gets traffic class or type-of-service in the IP header for packets sent from this Socket As the underlying network implementation may ignore the traffic class or type-of-service set using setTrafficClass(int) this method may return a different value than was previously set using the setTrafficClass(int) method on this Socket. boolean isBound() Returns the binding state of the socket. boolean isClosed() Returns the closed state of the socket. boolean isConnected() Returns the connection state of the socket. boolean isInputShutdown() Returns whether the read-half of the socket connection is closed. boolean isOutputShutdown() Returns whether the write-half of the socket connection is closed. void sendUrgentData(int data) Send one byte of urgent data on the socket. void setKeepAlive(boolean on) Enable/disable SO_KEEPALIVE. void setOOBInline(boolean on) Enable/disable SO_OOBINLINE (receipt of TCP urgent data) By default, this option is disabled and TCP urgent data received on a socket is silently discarded. <T> Socket setOption(SocketOption<T> name, T value) Sets the value of a socket option. void setPerformancePreferences(int connectionTime, int latency, int bandwidth) Sets performance preferences for this socket. void setReceiveBufferSize(int size) Sets the SO_RCVBUF option to the specified value for this Socket. void setReuseAddress(boolean on) Enable/disable the SO_REUSEADDR socket option. void setSendBufferSize(int size) Sets the SO_SNDBUF option to the specified value for this Socket. void setSoLinger(boolean on, int linger) Enable/disable SO_LINGER with the specified linger time in seconds. void setSoTimeout(int timeout) Enable/disable SO_TIMEOUT with the specified timeout, in milliseconds. static void setSocketImplFactory(SocketImplFactory fac) Sets the client socket implementation factory for the application. void setTcpNoDelay(boolean on) Enable/disable TCP_NODELAY (disable/enable Nagle's algorithm). void setTrafficClass(int tc) Sets traffic class or type-of-service octet in the IP header for packets sent from this Socket. void shutdownInput() Places the input stream for this socket at "end of stream". void shutdownOutput() Disables the output stream for this socket. Set<SocketOption<?>> supportedOptions() Returns a set of the socket options supported by this socket. String toString() Converts this socket to a String.
From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. final Class<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long timeoutMillis, int nanos) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait(long timeoutMillis) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait() Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
From interface java.io.Closeable abstract void close() Closes this stream and releases any system resources associated with it.
From interface java.lang.AutoCloseable abstract void close() Closes this resource, relinquishing any underlying resources.

Protected constructors

SSLSocket

Added in API level 1

protected SSLSocket ()

Used only by subclasses. Constructs an uninitialized, unconnected TCP socket.

SSLSocket

Added in API level 1

protected SSLSocket (String host, 
                int port)

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.

Parameters
host	String: name of the host with which to connect, or null for the loopback address.
port	int: 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(String, int)

SSLSocket

Added in API level 1

protected SSLSocket (InetAddress address, 
                int 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.

Parameters
address	InetAddress: the server's host
port	int: 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(String, int)

SSLSocket

Added in API level 1

protected SSLSocket (String host, 
                int port, 
                InetAddress clientAddress, 
                int clientPort)

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.

Parameters
host	String: name of the host with which to connect, or null for the loopback address.
port	int: number of the server's port
clientAddress	InetAddress: the client's address the socket is bound to, or null for the anyLocal address.
clientPort	int: 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(String, int)

SSLSocket

Added in API level 1

protected SSLSocket (InetAddress address, 
                int port, 
                InetAddress clientAddress, 
                int 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.

Parameters
address	InetAddress: the server's host
port	int: its port
clientAddress	InetAddress: the client's address the socket is bound to, or null for the anyLocal address.
clientPort	int: 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(String, int)

Public methods

addHandshakeCompletedListener

Added in API level 1

public abstract void addHandshakeCompletedListener (HandshakeCompletedListener listener)

Registers an event listener to receive notifications that an SSL handshake has completed on this connection.

Parameters
listener	HandshakeCompletedListener: the HandShake Completed event listener

Throws
IllegalArgumentException	if the argument is null.

See also:

• startHandshake()
• removeHandshakeCompletedListener(HandshakeCompletedListener)

getApplicationProtocol

Added in API level 29

public String getApplicationProtocol ()

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

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.

Implementation Requirements:

• The implementation in this class throws UnsupportedOperationException and performs no other action.

Returns
String	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.

Throws
UnsupportedOperationException	if the underlying provider does not implement the operation.

getEnableSessionCreation

Added in API level 1

public abstract boolean getEnableSessionCreation ()

Returns true if new SSL sessions may be established by this socket.

Returns
boolean	true indicates that sessions may be created; this is the default. false indicates that an existing session must be resumed

See also:

• setEnableSessionCreation(boolean)

getEnabledCipherSuites

Added in API level 1

public abstract String[] getEnabledCipherSuites ()

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.

Returns
String[]	an array of cipher suite names

See also:

• getSupportedCipherSuites()
• setEnabledCipherSuites(String[])

getEnabledProtocols

Added in API level 1

public abstract String[] getEnabledProtocols ()

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

Returns
String[]	an array of protocols

See also:

• setEnabledProtocols(String[])

getHandshakeApplicationProtocol

Added in API level 29

public String getHandshakeApplicationProtocol ()

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.

Implementation Requirements:

• The implementation in this class throws UnsupportedOperationException and performs no other action.

Returns
String	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.

Throws
UnsupportedOperationException	if the underlying provider does not implement the operation.

getHandshakeApplicationProtocolSelector

Added in API level 29

public BiFunction<SSLSocket, List<String>, String> getHandshakeApplicationProtocolSelector ()

Retrieves the callback function that selects an application protocol value during a SSL/TLS handshake. See setHandshakeApplicationProtocolSelector for the function's type parameters.

Implementation Requirements:

• The implementation in this class throws UnsupportedOperationException and performs no other action.

Returns
BiFunction<SSLSocket, List<String>, String>	the callback function, or null if none has been set.

Throws
UnsupportedOperationException	if the underlying provider does not implement the operation.

getHandshakeSession

Added in API level 24

public SSLSession getHandshakeSession ()

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 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.

Returns
SSLSession	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.

Throws
UnsupportedOperationException	if the underlying provider does not implement the operation.

See also:

• SSLEngine
• SSLSession
• ExtendedSSLSession
• X509ExtendedKeyManager
• X509ExtendedTrustManager

getNeedClientAuth

Added in API level 1

public abstract boolean getNeedClientAuth ()

Returns true if the socket will require client authentication. This option is only useful to sockets in the server mode.

Returns
boolean	true if client authentication is required, or false if no client authentication is desired.

See also:

• setNeedClientAuth(boolean)
• setWantClientAuth(boolean)
• getWantClientAuth()
• setUseClientMode(boolean)

getSSLParameters

Added in API level 9

public SSLParameters getSSLParameters ()

Returns the SSLParameters in effect for this SSLSocket. The ciphersuites and protocols of the returned SSLParameters are always non-null.

Returns
SSLParameters	the SSLParameters in effect for this SSLSocket.

getSession

Added in API level 1

public abstract SSLSession getSession ()

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
SSLSession	the SSLSession

getSupportedCipherSuites

Added in API level 1

public abstract String[] getSupportedCipherSuites ()

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 Arrays.asList(getSupportedCipherSuites()).contains(...) or to filter a desired list of cipher suites to only the supported ones via desiredSuiteSet.retainAll(Arrays.asList(getSupportedCipherSuites())).

Returns
String[]	an array of cipher suite names

See also:

• getEnabledCipherSuites()
• setEnabledCipherSuites(String[])

getSupportedProtocols

Added in API level 1

public abstract String[] getSupportedProtocols ()

Returns the names of the protocols which could be enabled for use on an SSL connection.

Returns
String[]	an array of protocols supported

getUseClientMode

Added in API level 1

public abstract boolean getUseClientMode ()

Returns true if the socket is set to use client mode when handshaking.

Returns
boolean	true if the socket should do handshaking in "client" mode

See also:

• setUseClientMode(boolean)

getWantClientAuth

Added in API level 1

public abstract boolean getWantClientAuth ()

Returns true if the socket will request client authentication. This option is only useful for sockets in the server mode.

Returns
boolean	true if client authentication is requested, or false if no client authentication is desired.

See also:

• setNeedClientAuth(boolean)
• getNeedClientAuth()
• setWantClientAuth(boolean)
• setUseClientMode(boolean)

removeHandshakeCompletedListener

Added in API level 1

public abstract void removeHandshakeCompletedListener (HandshakeCompletedListener listener)

Removes a previously registered handshake completion listener.

Parameters
listener	HandshakeCompletedListener: the HandShake Completed event listener

Throws
IllegalArgumentException	if the listener is not registered, or the argument is null.

See also:

• addHandshakeCompletedListener(HandshakeCompletedListener)

setEnableSessionCreation

Added in API level 1

public abstract void setEnableSessionCreation (boolean flag)

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.

Parameters
flag	boolean: true indicates that sessions may be created; this is the default. false indicates that an existing session must be resumed

See also:

• getEnableSessionCreation()

setEnabledCipherSuites

Added in API level 1

public abstract void setEnabledCipherSuites (String[] suites)

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 getEnabledCipherSuites() for more information on why a specific ciphersuite may never be used on a connection.

Parameters
suites	String: 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()

setEnabledProtocols

Added in API level 1

public abstract void setEnabledProtocols (String[] 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.

Parameters
protocols	String: 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()

setHandshakeApplicationProtocolSelector

Added in API level 29

public void setHandshakeApplicationProtocolSelector (BiFunction<SSLSocket, List<String>, String> selector)

Registers a callback function that selects an application protocol value for a SSL/TLS 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());
         });
 

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.

Parameters
selector	BiFunction: the callback function, or null to de-register.

Throws
UnsupportedOperationException	if the underlying provider does not implement the operation.

setNeedClientAuth

Added in API level 1

public abstract void setNeedClientAuth (boolean need)

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).

Parameters
need	boolean: set to true if client authentication is required, or false if no client authentication is desired.

See also:

• getNeedClientAuth()
• setWantClientAuth(boolean)
• getWantClientAuth()
• setUseClientMode(boolean)

setSSLParameters

Added in API level 9

public void setSSLParameters (SSLParameters 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.

Parameters
params	SSLParameters: the parameters

Throws
IllegalArgumentException	if the setEnabledCipherSuites() or the setEnabledProtocols() call fails

setUseClientMode

Added in API level 1

public abstract void setUseClientMode (boolean mode)

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.

Parameters
mode	boolean: 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()

setWantClientAuth

Added in API level 1

public abstract void setWantClientAuth (boolean want)

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).

Parameters
want	boolean: set to true if client authentication is requested, or false if no client authentication is desired.

See also:

• getWantClientAuth()
• setNeedClientAuth(boolean)
• getNeedClientAuth()
• setUseClientMode(boolean)

startHandshake

Added in API level 1

public abstract void startHandshake ()

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)

toString

Added in API level 1

public String toString ()

Converts this socket to a String.

Returns
String	a string representation of this socket.