Android APIs
public abstract class

SSLSocket

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

Class Overview

The extension of Socket providing secure protocols like SSL (Secure Sockets Layer) or TLS (Transport Layer Security).

Default configuration

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+ 1+
TLSv1 1+ 1+
TLSv1.1 16+ 20+
TLSv1.2 16+ 20+

Server socket:

Protocol Supported (API Levels) Enabled by default (API Levels)
SSLv3 1+ 1+
TLSv1 1+ 1+
TLSv1.1 16+ 16+
TLSv1.2 16+ 16+

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+ 9-19
SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA 9+ 9-19
SSL_DHE_RSA_WITH_DES_CBC_SHA 9+ 9-19
SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA 9+
SSL_DH_anon_EXPORT_WITH_RC4_40_MD5 9+
SSL_DH_anon_WITH_3DES_EDE_CBC_SHA 9+
SSL_DH_anon_WITH_DES_CBC_SHA 9+
SSL_DH_anon_WITH_RC4_128_MD5 9+
SSL_RSA_EXPORT_WITH_DES40_CBC_SHA 9+ 9-19
SSL_RSA_EXPORT_WITH_RC4_40_MD5 9+ 9-19
SSL_RSA_WITH_3DES_EDE_CBC_SHA 9+ 9-19
SSL_RSA_WITH_DES_CBC_SHA 9+ 9-19
SSL_RSA_WITH_NULL_MD5 9+
SSL_RSA_WITH_NULL_SHA 9+
SSL_RSA_WITH_RC4_128_MD5 9+ 9-19
SSL_RSA_WITH_RC4_128_SHA 9+ 9+
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+ 9+
TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 20+
TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 20+ 20+
TLS_DHE_RSA_WITH_AES_256_CBC_SHA 9+ 11+
TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 20+
TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 20+ 20+
TLS_DH_anon_WITH_AES_128_CBC_SHA 9+
TLS_DH_anon_WITH_AES_128_CBC_SHA256 20+
TLS_DH_anon_WITH_AES_128_GCM_SHA256 20+
TLS_DH_anon_WITH_AES_256_CBC_SHA 9+
TLS_DH_anon_WITH_AES_256_CBC_SHA256 20+
TLS_DH_anon_WITH_AES_256_GCM_SHA384 20+
TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA 11+ 11-19
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA 11+ 11+
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 20+
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+
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 20+ 20+
TLS_ECDHE_ECDSA_WITH_NULL_SHA 11+
TLS_ECDHE_ECDSA_WITH_RC4_128_SHA 11+ 11+
TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA 21+ 21+
TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA 21+ 21+
TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA 11+ 11-19
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA 11+ 11+
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 20+
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+
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 20+ 20+
TLS_ECDHE_RSA_WITH_NULL_SHA 11+
TLS_ECDHE_RSA_WITH_RC4_128_SHA 11+ 11+
TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA 11+ 11-19
TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA 11+ 11-19
TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 20+
TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 20+
TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA 11+ 11-19
TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 20+
TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384 20+
TLS_ECDH_ECDSA_WITH_NULL_SHA 11+
TLS_ECDH_ECDSA_WITH_RC4_128_SHA 11+ 11-19
TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA 11+ 11-19
TLS_ECDH_RSA_WITH_AES_128_CBC_SHA 11+ 11-19
TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 20+
TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 20+
TLS_ECDH_RSA_WITH_AES_256_CBC_SHA 11+ 11-19
TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 20+
TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 20+
TLS_ECDH_RSA_WITH_NULL_SHA 11+
TLS_ECDH_RSA_WITH_RC4_128_SHA 11+ 11-19
TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA 11+
TLS_ECDH_anon_WITH_AES_128_CBC_SHA 11+
TLS_ECDH_anon_WITH_AES_256_CBC_SHA 11+
TLS_ECDH_anon_WITH_NULL_SHA 11+
TLS_ECDH_anon_WITH_RC4_128_SHA 11+
TLS_EMPTY_RENEGOTIATION_INFO_SCSV 11+ 11+
TLS_FALLBACK_SCSV 21+
TLS_PSK_WITH_3DES_EDE_CBC_SHA 21+
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+
TLS_RSA_WITH_AES_128_CBC_SHA 9+ 9+
TLS_RSA_WITH_AES_128_CBC_SHA256 20+
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+
TLS_RSA_WITH_AES_256_GCM_SHA384 20+ 20+
TLS_RSA_WITH_NULL_SHA256 20+

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+ 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+ 1-19
EDH-RSA-DES-CBC3-SHA SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA 1+ 1-19
EXP-DES-CBC-SHA SSL_RSA_EXPORT_WITH_DES40_CBC_SHA 1+ 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+ 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+ 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+ 1-19
RC4-SHA SSL_RSA_WITH_RC4_128_SHA 1+ 1+

Summary

Protected Constructors
SSLSocket()
Only to be used by subclasses.
SSLSocket(String host, int port)
Only to be used by subclasses.
SSLSocket(InetAddress address, int port)
Only to be used by subclasses.
SSLSocket(String host, int port, InetAddress clientAddress, int clientPort)
Only to be used by subclasses.
SSLSocket(InetAddress address, int port, InetAddress clientAddress, int clientPort)
Only to be used by subclasses.
Public Methods
abstract void addHandshakeCompletedListener(HandshakeCompletedListener listener)
Registers the specified listener to receive notification on completion of a handshake on this connection.
abstract boolean getEnableSessionCreation()
Returns whether new SSL sessions may be created by this socket or if existing sessions must be reused.
abstract String[] getEnabledCipherSuites()
Returns the names of the enabled cipher suites.
abstract String[] getEnabledProtocols()
Returns the names of the enabled protocols.
abstract boolean getNeedClientAuth()
Returns true if the server socket should require client authentication.
SSLParameters getSSLParameters()
Returns a new SSLParameters based on this SSLSocket's current cipher suites, protocols, and client authentication settings.
abstract SSLSession getSession()
Returns the SSLSession for this connection.
abstract String[] getSupportedCipherSuites()
Returns the names of the supported cipher suites.
abstract String[] getSupportedProtocols()
Returns the names of the supported protocols.
abstract boolean getUseClientMode()
Returns true if this connection will act in client mode when handshaking.
abstract boolean getWantClientAuth()
Returns true if the server should request client authentication.
abstract void removeHandshakeCompletedListener(HandshakeCompletedListener listener)
Removes the specified handshake completion listener.
abstract void setEnableSessionCreation(boolean flag)
Sets whether new SSL sessions may be created by this socket or if existing sessions must be reused.
abstract void setEnabledCipherSuites(String[] suites)
Sets the names of the cipher suites to be enabled.
abstract void setEnabledProtocols(String[] protocols)
Sets the names of the protocols to be enabled.
abstract void setNeedClientAuth(boolean need)
Sets whether the server should require client authentication.
void setSSLParameters(SSLParameters p)
Sets various SSL handshake parameters based on the SSLParameter argument.
abstract void setUseClientMode(boolean mode)
Sets whether this connection should act in client mode when handshaking.
abstract void setWantClientAuth(boolean want)
Sets whether the server should request client authentication.
void shutdownInput()
Unsupported for SSL because reading from an SSL socket may require writing to the network.
void shutdownOutput()
Unsupported for SSL because writing to an SSL socket may require reading from the network.
abstract void startHandshake()
Starts a new SSL handshake on this connection.
[Expand]
Inherited Methods
From class java.net.Socket
From class java.lang.Object
From interface java.io.Closeable
From interface java.lang.AutoCloseable

Protected Constructors

protected SSLSocket ()

Added in API level 1

Only to be used by subclasses.

Creates a TCP socket.

protected SSLSocket (String host, int port)

Added in API level 1

Only to be used by subclasses.

Creates a TCP socket connection to the specified host at the specified port.

Parameters
host the host name to connect to.
port the port number to connect to.
Throws
IOException if creating the socket fails.
UnknownHostException if the specified host is not known.

protected SSLSocket (InetAddress address, int port)

Added in API level 1

Only to be used by subclasses.

Creates a TCP socket connection to the specified address at the specified port.

Parameters
address the address to connect to.
port the port number to connect to.
Throws
IOException if creating the socket fails.

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

Added in API level 1

Only to be used by subclasses.

Creates a TCP socket connection to the specified host at the specified port with the client side bound to the specified address and port.

Parameters
host the host name to connect to.
port the port number to connect to.
clientAddress the client address to bind to
clientPort the client port number to bind to.
Throws
IOException if creating the socket fails.
UnknownHostException if the specified host is not known.

protected SSLSocket (InetAddress address, int port, InetAddress clientAddress, int clientPort)

Added in API level 1

Only to be used by subclasses.

Creates a TCP socket connection to the specified address at the specified port with the client side bound to the specified address and port.

Parameters
address the address to connect to.
port the port number to connect to.
clientAddress the client address to bind to.
clientPort the client port number to bind to.
Throws
IOException if creating the socket fails.

Public Methods

public abstract void addHandshakeCompletedListener (HandshakeCompletedListener listener)

Added in API level 1

Registers the specified listener to receive notification on completion of a handshake on this connection.

Parameters
listener the listener to register.
Throws
IllegalArgumentException if listener is null.

public abstract boolean getEnableSessionCreation ()

Added in API level 1

Returns whether new SSL sessions may be created by this socket or if existing sessions must be reused.

Returns
  • true if new sessions may be created, otherwise false.

public abstract String[] getEnabledCipherSuites ()

Added in API level 1

Returns the names of the enabled cipher suites.

public abstract String[] getEnabledProtocols ()

Added in API level 1

Returns the names of the enabled protocols.

public abstract boolean getNeedClientAuth ()

Added in API level 1

Returns true if the server socket should require client authentication. This does not apply to sockets in client mode.

public SSLParameters getSSLParameters ()

Added in API level 9

Returns a new SSLParameters based on this SSLSocket's current cipher suites, protocols, and client authentication settings.

public abstract SSLSession getSession ()

Added in API level 1

Returns the SSLSession for this connection. If necessary, a handshake will be initiated, in which case this method will block until the handshake has been established. If the handshake fails, an invalid session object will be returned.

Returns
  • the session object.

public abstract String[] getSupportedCipherSuites ()

Added in API level 1

Returns the names of the supported cipher suites.

public abstract String[] getSupportedProtocols ()

Added in API level 1

Returns the names of the supported protocols.

public abstract boolean getUseClientMode ()

Added in API level 1

Returns true if this connection will act in client mode when handshaking.

public abstract boolean getWantClientAuth ()

Added in API level 1

Returns true if the server should request client authentication. This does not apply to sockets in client mode.

public abstract void removeHandshakeCompletedListener (HandshakeCompletedListener listener)

Added in API level 1

Removes the specified handshake completion listener.

Parameters
listener the listener to remove.
Throws
IllegalArgumentException if the specified listener is not registered or null.

public abstract void setEnableSessionCreation (boolean flag)

Added in API level 1

Sets whether new SSL sessions may be created by this socket or if existing sessions must be reused. If flag is false and there are no sessions to resume, handshaking will fail.

Parameters
flag true if new sessions may be created.

public abstract void setEnabledCipherSuites (String[] suites)

Added in API level 1

Sets the names of the cipher suites to be enabled. Only cipher suites returned by getSupportedCipherSuites() are allowed.

Parameters
suites the names of the to be enabled cipher suites.
Throws
IllegalArgumentException if one of the cipher suite names is not supported.

public abstract void setEnabledProtocols (String[] protocols)

Added in API level 1

Sets the names of the protocols to be enabled. Only protocols returned by getSupportedProtocols() are allowed.

Parameters
protocols the names of the to be enabled protocols.
Throws
IllegalArgumentException if one of the protocols is not supported.

public abstract void setNeedClientAuth (boolean need)

Added in API level 1

Sets whether the server should require client authentication. This does not apply to sockets in client mode. Client authentication is one of the following:

  • authentication required
  • authentication requested
  • no authentication needed
This method overrides the setting of setWantClientAuth(boolean).

public void setSSLParameters (SSLParameters p)

Added in API level 9

Sets various SSL handshake parameters based on the SSLParameter argument. Specifically, sets the SSLSocket's enabled cipher suites if the parameter's cipher suites are non-null. Similarly sets the enabled protocols. If the parameters specify the want or need for client authentication, those requirements are set on the SSLSocket, otherwise both are set to false.

public abstract void setUseClientMode (boolean mode)

Added in API level 1

Sets whether this connection should act in client mode when handshaking.

Parameters
mode true if this connection should act in client mode, false if not.

public abstract void setWantClientAuth (boolean want)

Added in API level 1

Sets whether the server should request client authentication. Unlike setNeedClientAuth(boolean) this won't stop the negotiation if the client doesn't authenticate. This does not apply to sockets in client mode.The client authentication is one of:

  • authentication required
  • authentication requested
  • no authentication needed
This method overrides the setting of setNeedClientAuth(boolean).

public void shutdownInput ()

Added in API level 1

Unsupported for SSL because reading from an SSL socket may require writing to the network.

Throws
IOException

public void shutdownOutput ()

Added in API level 1

Unsupported for SSL because writing to an SSL socket may require reading from the network.

Throws
IOException

public abstract void startHandshake ()

Added in API level 1

Starts a new SSL handshake on this connection.

Throws
IOException if an error occurs.