java.lang.Object | ||
↳ | java.net.Socket | |
↳ | javax.net.ssl.SSLSocket |
The extension of Socket
providing secure protocols like SSL (Secure
Sockets Layer) or TLS (Transport Layer Security).
SSLSocket
instances obtained from default SSLSocketFactory
,
SSLServerSocketFactory
, and SSLContext
are configured as follows:
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+ |
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+ | 9-19 |
SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA | 9+ | 9-19 |
SSL_DHE_DSS_WITH_DES_CBC_SHA | 9+ | 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+ | 9+ |
TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 | 20+ | |
TLS_DHE_DSS_WITH_AES_128_GCM_SHA256 | 20+ | |
TLS_DHE_DSS_WITH_AES_256_CBC_SHA | 9+ | 11+ |
TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 | 20+ | |
TLS_DHE_DSS_WITH_AES_256_GCM_SHA384 | 20+ | |
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_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_EMPTY_RENEGOTIATION_INFO_SCSV | 11+ | 11+ |
TLS_ECDH_anon_WITH_RC4_128_SHA | 11+ | |
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+ |
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+ | 1+ |
DHE-DSS-AES256-SHA | TLS_DHE_DSS_WITH_AES_256_CBC_SHA | 1+ | 1-8, 11+ |
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+ | 1-19 |
EDH-DSS-DES-CBC3-SHA | SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA | 1+ | 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+ | 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+ |
Protected Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Only to be used by subclasses.
| |||||||||||
Only to be used by subclasses.
| |||||||||||
Only to be used by subclasses.
| |||||||||||
Only to be used by subclasses.
| |||||||||||
Only to be used by subclasses.
|
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Registers the specified listener to receive notification on completion of
a handshake on this connection.
| |||||||||||
Returns whether new SSL sessions may be created by this socket or if
existing sessions must be reused.
| |||||||||||
Returns the names of the enabled cipher suites.
| |||||||||||
Returns the names of the enabled protocols.
| |||||||||||
Returns true if the server socket should require client authentication.
| |||||||||||
Returns a new SSLParameters based on this SSLSocket's current
cipher suites, protocols, and client authentication settings.
| |||||||||||
Returns the
SSLSession for this connection. | |||||||||||
Returns the names of the supported cipher suites.
| |||||||||||
Returns the names of the supported protocols.
| |||||||||||
Returns true if this connection will act in client mode when handshaking.
| |||||||||||
Returns true if the server should request client authentication.
| |||||||||||
Removes the specified handshake completion listener.
| |||||||||||
Sets whether new SSL sessions may be created by this socket or if
existing sessions must be reused.
| |||||||||||
Sets the names of the cipher suites to be enabled.
| |||||||||||
Sets the names of the protocols to be enabled.
| |||||||||||
Sets whether the server should require client authentication.
| |||||||||||
Sets various SSL handshake parameters based on the SSLParameter
argument.
| |||||||||||
Sets whether this connection should act in client mode when handshaking.
| |||||||||||
Sets whether the server should request client authentication.
| |||||||||||
Unsupported for SSL because reading from an SSL socket may require
writing to the network.
| |||||||||||
Unsupported for SSL because writing to an SSL socket may require reading
from the network.
| |||||||||||
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
|
Only to be used by subclasses.
Creates a TCP socket connection to the specified host at the specified port.
host | the host name to connect to. |
---|---|
port | the port number to connect to. |
IOException | if creating the socket fails. |
---|---|
UnknownHostException | if the specified host is not known. |
Only to be used by subclasses.
Creates a TCP socket connection to the specified address at the specified port.
address | the address to connect to. |
---|---|
port | the port number to connect to. |
IOException | if creating the socket fails. |
---|
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.
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. |
IOException | if creating the socket fails. |
---|---|
UnknownHostException | if the specified host is not known. |
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.
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. |
IOException | if creating the socket fails. |
---|
Registers the specified listener to receive notification on completion of a handshake on this connection.
listener | the listener to register. |
---|
IllegalArgumentException | if listener is null .
|
---|
Returns whether new SSL sessions may be created by this socket or if existing sessions must be reused.
true
if new sessions may be created, otherwise
false
.
Returns the names of the enabled cipher suites.
Returns the names of the enabled protocols.
Returns true if the server socket should require client authentication.
This does not apply to sockets in client
mode
.
Returns a new SSLParameters based on this SSLSocket's current cipher suites, protocols, and client authentication settings.
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 names of the supported cipher suites.
Returns the names of the supported protocols.
Returns true if this connection will act in client mode when handshaking.
Returns true if the server should request client authentication. This
does not apply to sockets in client mode
.
Removes the specified handshake completion listener.
listener | the listener to remove. |
---|
IllegalArgumentException | if the specified listener is not registered or null .
|
---|
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.
flag | true if new sessions may be created.
|
---|
Sets the names of the cipher suites to be enabled.
Only cipher suites returned by getSupportedCipherSuites()
are
allowed.
suites | the names of the to be enabled cipher suites. |
---|
IllegalArgumentException | if one of the cipher suite names is not supported. |
---|
Sets the names of the protocols to be enabled. Only
protocols returned by getSupportedProtocols()
are allowed.
protocols | the names of the to be enabled protocols. |
---|
IllegalArgumentException | if one of the protocols is not supported. |
---|
Sets whether the server should require client authentication. This
does not apply to sockets in client mode
.
Client authentication is one of the following:
setWantClientAuth(boolean)
.
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.
Sets whether this connection should act in client mode when handshaking.
mode | true if this connection should act in client mode,
false if not.
|
---|
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:
setNeedClientAuth(boolean)
.
Unsupported for SSL because reading from an SSL socket may require writing to the network.
IOException |
---|
Unsupported for SSL because writing to an SSL socket may require reading from the network.
IOException |
---|
Starts a new SSL handshake on this connection.
IOException | if an error occurs. |
---|