SSLSocket

public abstract class SSLSocket extends Socket

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 futher 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+ 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–22
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–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+ 9–19
SSL_RSA_WITH_RC4_128_SHA 9+ 9–23
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–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+
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_CHACHA20_POLY1305_SHA256 24+ 24+
TLS_ECDHE_ECDSA_WITH_NULL_SHA 11–22
TLS_ECDHE_ECDSA_WITH_RC4_128_SHA 11+ 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+
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–22
TLS_ECDHE_RSA_WITH_RC4_128_SHA 11+ 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+
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_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 24+ 24+
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+ 1–19
RC4-SHA SSL_RSA_WITH_RC4_128_SHA 1+ 1–23

Protected Constructor Summary

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.