Package javax.net.ssl

Class SSLSocket

java.lang.Object

java.net.Socket

javax.net.ssl.SSLSocket

All Implemented Interfaces:

Closeable, AutoCloseable

Direct Known Subclasses:

OpenSSLSocketImpl

public abstract class SSLSocket
extends Socket

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–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+

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	SSLSocket()	Only to be used by subclasses.
protected	SSLSocket(String host, int port)	Only to be used by subclasses.
protected	SSLSocket(String host, int port, InetAddress clientAddress, int clientPort)	Only to be used by subclasses.
protected	SSLSocket(InetAddress address, int port)	Only to be used by subclasses.
protected	SSLSocket(InetAddress address, int port, InetAddress clientAddress, int clientPort)	Only to be used by subclasses.

Method Summary

Modifier and Type	Method	Description
abstract void	addHandshakeCompletedListener(HandshakeCompletedListener listener)	Registers the specified listener to receive notification on completion of a handshake on this connection.
abstract String[]	getEnabledCipherSuites()	Returns the names of the enabled cipher suites.
abstract String[]	getEnabledProtocols()	Returns the names of the enabled protocols.
abstract boolean	getEnableSessionCreation()	Returns whether new SSL sessions may be created by this socket or if existing sessions must be reused.
abstract boolean	getNeedClientAuth()	Returns true if the server socket should require client authentication.
abstract SSLSession	getSession()	Returns the SSLSession for this connection.
SSLParameters	getSSLParameters()	Returns a new SSLParameters based on this SSLSocket's current cipher suites, protocols, and client authentication settings.
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	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	setEnableSessionCreation(boolean flag)	Sets whether new SSL sessions may be created by this socket or if existing sessions must be reused.
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.

Methods inherited from class java.net.Socket

bind, close, connect, connect, getChannel, getFileDescriptor$, getInetAddress, getInputStream, getKeepAlive, getLocalAddress, getLocalPort, getLocalSocketAddress, getOOBInline, getOutputStream, getPort, getReceiveBufferSize, getRemoteSocketAddress, getReuseAddress, getReusePort, getSendBufferSize, getSoLinger, getSoTimeout, getTcpNoDelay, getTrafficClass, isBound, isClosed, isConnected, isInputShutdown, isOutputShutdown, onBind, onClose, onConnect, sendUrgentData, setKeepAlive, setOOBInline, setPerformancePreferences, setReceiveBufferSize, setReuseAddress, setReusePort, setSendBufferSize, setSocketImplFactory, setSoLinger, setSoTimeout, setTcpNoDelay, setTrafficClass, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SSLSocket

protected SSLSocket()

Only to be used by subclasses.

Creates a TCP socket.

SSLSocket

protected SSLSocket(String host,
                    int port)
             throws IOException,
                    UnknownHostException

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.

SSLSocket

protected SSLSocket(InetAddress address,
                    int port)
             throws IOException

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.

SSLSocket

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

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.

SSLSocket

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

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.

Method Detail

shutdownInput

public void shutdownInput()
                   throws IOException

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

Overrides:

shutdownInput in class Socket

Throws:

IOException - if an error occurs while closing the socket input stream.

SocketException - if the input stream is already closed.

shutdownOutput

public void shutdownOutput()
                    throws IOException

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

Overrides:

shutdownOutput in class Socket

Throws:

IOException - if an error occurs while closing the socket output stream.

SocketException - if the output stream is already closed.

getSupportedCipherSuites

public abstract String[] getSupportedCipherSuites()

Returns the names of the supported cipher suites.

getEnabledCipherSuites

public abstract String[] getEnabledCipherSuites()

Returns the names of the enabled cipher suites.

setEnabledCipherSuites

public abstract void setEnabledCipherSuites(String[] suites)

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.

getSupportedProtocols

public abstract String[] getSupportedProtocols()

Returns the names of the supported protocols.

getEnabledProtocols

public abstract String[] getEnabledProtocols()

Returns the names of the enabled protocols.

setEnabledProtocols

public abstract void setEnabledProtocols(String[] protocols)

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.

getSession

public abstract 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:

the session object.

addHandshakeCompletedListener

public abstract void addHandshakeCompletedListener(HandshakeCompletedListener listener)

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.

removeHandshakeCompletedListener

public abstract void removeHandshakeCompletedListener(HandshakeCompletedListener listener)

Removes the specified handshake completion listener.

Parameters:

listener - the listener to remove.

Throws:

IllegalArgumentException - if the specified listener is not registered or null.

startHandshake

public abstract void startHandshake()
                             throws IOException

Starts a new SSL handshake on this connection.

Throws:

IOException - if an error occurs.

setUseClientMode

public abstract void setUseClientMode(boolean mode)

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.

getUseClientMode

public abstract boolean getUseClientMode()

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

setNeedClientAuth

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

setWantClientAuth

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

getNeedClientAuth

public abstract boolean getNeedClientAuth()

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

getWantClientAuth

public abstract boolean getWantClientAuth()

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

setEnableSessionCreation

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

getEnableSessionCreation

public abstract boolean getEnableSessionCreation()

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.

getSSLParameters

public SSLParameters getSSLParameters()

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

Since:

1.6

setSSLParameters

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

Since:

1.6