Skip to content

Most visited

Recently visited

navigation
Added in API level 1

SSLSocket

public abstract class SSLSocket
extends Socket

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

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–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+
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_NULL_SHA 11–22
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–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+
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_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+

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.

Inherited methods

From class java.net.Socket
From class java.lang.Object
From interface java.io.Closeable
From interface java.lang.AutoCloseable

Protected constructors

SSLSocket

Added in API level 1
SSLSocket ()

Only to be used by subclasses.

Creates a TCP socket.

SSLSocket

Added in API level 1
SSLSocket (String host, 
                int port)

Only to be used by subclasses.

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

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

SSLSocket

Added in API level 1
SSLSocket (InetAddress address, 
                int port)

Only to be used by subclasses.

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

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

SSLSocket

Added in API level 1
SSLSocket (String host, 
                int port, 
                InetAddress clientAddress, 
                int clientPort)

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 String: the host name to connect to.
port int: the port number to connect to.
clientAddress InetAddress: the client address to bind to
clientPort int: the client port number to bind to.
Throws
IOException if creating the socket fails.
UnknownHostException if the specified host is not known.

SSLSocket

Added in API level 1
SSLSocket (InetAddress address, 
                int port, 
                InetAddress clientAddress, 
                int clientPort)

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 InetAddress: the address to connect to.
port int: the port number to connect to.
clientAddress InetAddress: the client address to bind to.
clientPort int: the client port number to bind to.
Throws
IOException if creating the socket fails.

Public methods

addHandshakeCompletedListener

Added in API level 1
void addHandshakeCompletedListener (HandshakeCompletedListener listener)

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

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

getEnableSessionCreation

Added in API level 1
boolean getEnableSessionCreation ()

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

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

getEnabledCipherSuites

Added in API level 1
String[] getEnabledCipherSuites ()

Returns the names of the enabled cipher suites.

Returns
String[]

getEnabledProtocols

Added in API level 1
String[] getEnabledProtocols ()

Returns the names of the enabled protocols.

Returns
String[]

getNeedClientAuth

Added in API level 1
boolean getNeedClientAuth ()

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

Returns
boolean

getSSLParameters

Added in API level 9
SSLParameters getSSLParameters ()

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

Returns
SSLParameters

getSession

Added in API level 1
SSLSession getSession ()

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
SSLSession the session object.

getSupportedCipherSuites

Added in API level 1
String[] getSupportedCipherSuites ()

Returns the names of the supported cipher suites.

Returns
String[]

getSupportedProtocols

Added in API level 1
String[] getSupportedProtocols ()

Returns the names of the supported protocols.

Returns
String[]

getUseClientMode

Added in API level 1
boolean getUseClientMode ()

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

Returns
boolean

getWantClientAuth

Added in API level 1
boolean getWantClientAuth ()

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

Returns
boolean

removeHandshakeCompletedListener

Added in API level 1
void removeHandshakeCompletedListener (HandshakeCompletedListener listener)

Removes the specified handshake completion listener.

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

setEnableSessionCreation

Added in API level 1
void setEnableSessionCreation (boolean flag)

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 boolean: true if new sessions may be created.

setEnabledCipherSuites

Added in API level 1
void setEnabledCipherSuites (String[] suites)

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

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

setEnabledProtocols

Added in API level 1
void setEnabledProtocols (String[] protocols)

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

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

setNeedClientAuth

Added in API level 1
void setNeedClientAuth (boolean need)

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

Parameters
need boolean

setSSLParameters

Added in API level 9
void setSSLParameters (SSLParameters p)

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.

Parameters
p SSLParameters

setUseClientMode

Added in API level 1
void setUseClientMode (boolean mode)

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

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

setWantClientAuth

Added in API level 1
void setWantClientAuth (boolean want)

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

Parameters
want boolean

shutdownInput

Added in API level 1
void shutdownInput ()

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

Throws
IOException

shutdownOutput

Added in API level 1
void shutdownOutput ()

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

Throws
IOException

startHandshake

Added in API level 1
void startHandshake ()

Starts a new SSL handshake on this connection.

Throws
IOException if an error occurs.
This site uses cookies to store your preferences for site-specific language and display options.

Hooray!

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.