javax.net.ssl

Class SSLEngine

java.lang.Object

javax.net.ssl.SSLEngine

Direct Known Subclasses:

OpenSSLEngineImpl

public abstract class SSLEngine
extends Object

The abstract implementation of secure communications using SSL, TLS, or other protocols. It includes the setup, handshake, and encrypt/decrypt functionality needed to create a secure connection.

Default configuration

SSLEngine instances obtained from default SSLContext are configured as follows:

Protocols

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

Cipher suites

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_EXPORT_WITH_DES40_CBC_SHA	1–8	1–8
TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA	1–8	1–8
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	20–22
TLS_DHE_DSS_WITH_AES_256_CBC_SHA256	20–22
TLS_DHE_DSS_WITH_AES_256_GCM_SHA384	20–22
TLS_DHE_DSS_WITH_DES_CBC_SHA	1–8	1–8
TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA	1–8	1–8
TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA	1–8	1–8
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+	20+
TLS_DHE_RSA_WITH_AES_256_CBC_SHA256	20+
TLS_DHE_RSA_WITH_AES_256_GCM_SHA384	20+	20+
TLS_DHE_RSA_WITH_DES_CBC_SHA	1–8	1–8
TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA	1–8
TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA	1–8
TLS_DH_DSS_WITH_DES_CBC_SHA	1–8
TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA	1–8
TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA	1–8
TLS_DH_RSA_WITH_DES_CBC_SHA	1–8
TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA	1–8
TLS_DH_anon_WITH_3DES_EDE_CBC_SHA	1–8
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_DH_anon_WITH_DES_CBC_SHA	1–8
TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA	20–22
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA	20+	20+
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	20+	20+
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	20–22
TLS_ECDHE_ECDSA_WITH_RC4_128_SHA	20+	20+
TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA	20–22
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA	20+	20+
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	20+	20+
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	20–22
TLS_ECDHE_RSA_WITH_RC4_128_SHA	20+	20+
TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA	20–22
TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA	20–22
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	20–22
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	20–22
TLS_ECDH_ECDSA_WITH_RC4_128_SHA	20–22
TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA	20–22
TLS_ECDH_RSA_WITH_AES_128_CBC_SHA	20–22
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	20–22
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	20–22
TLS_ECDH_RSA_WITH_RC4_128_SHA	20–22
TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA	20–22
TLS_ECDH_anon_WITH_AES_128_CBC_SHA	20–22
TLS_ECDH_anon_WITH_AES_256_CBC_SHA	20–22
TLS_ECDH_anon_WITH_NULL_SHA	20–22
TLS_ECDH_anon_WITH_RC4_128_SHA	20–22
TLS_EMPTY_RENEGOTIATION_INFO_SCSV	20+	20+
TLS_FALLBACK_SCSV	21+
TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA	21+	21+
TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA	21+	21+
TLS_NULL_WITH_NULL_NULL	1–8
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_EXPORT_WITH_DES40_CBC_SHA	1–8	1–8
TLS_RSA_WITH_3DES_EDE_CBC_SHA	1–8	1–8
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+	20+
TLS_RSA_WITH_AES_256_CBC_SHA256	20+
TLS_RSA_WITH_AES_256_GCM_SHA384	20+	20+
TLS_RSA_WITH_DES_CBC_SHA	1–8	1–8
TLS_RSA_WITH_NULL_MD5	1–8
TLS_RSA_WITH_NULL_SHA	1–8
TLS_RSA_WITH_NULL_SHA256	20–22

NOTE: PSK cipher suites are enabled by default only if the SSLContext through which the engine was created has been initialized with a PSKKeyManager.

Since:

1.5

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	SSLEngine() Creates a new SSLEngine instance.
protected	SSLEngine(String host, int port) Creates a new SSLEngine instance with the specified host and port.

Method Summary

Modifier and Type	Method and Description
abstract void	beginHandshake() Initiates a handshake on this engine.
abstract void	closeInbound() Notifies this engine instance that no more inbound network data will be sent to this engine.
abstract void	closeOutbound() Notifies this engine instance that no more outbound application data will be sent to this engine.
abstract Runnable	getDelegatedTask() Returns a delegate task for this engine instance.
abstract String[]	getEnabledCipherSuites() Returns the SSL cipher suite names that are enabled in this engine instance.
abstract String[]	getEnabledProtocols() Returns the protocol version names that are enabled in this engine instance.
abstract boolean	getEnableSessionCreation() Returns whether new SSL sessions may be established by this engine.
abstract SSLEngineResult.HandshakeStatus	getHandshakeStatus() Returns the status of the handshake of this engine instance.
abstract boolean	getNeedClientAuth() Returns whether this engine instance will require client authentication.
String	getPeerHost() Returns the name of the peer host.
int	getPeerPort() Returns the port number of the peer host.
abstract SSLSession	getSession() Returns the SSL session for this engine instance.
SSLParameters	getSSLParameters() Returns a new SSLParameters based on this SSLSocket's current cipher suites, protocols, and client authentication settings.
abstract String[]	getSupportedCipherSuites() Returns the SSL cipher suite names that are supported by this engine.
abstract String[]	getSupportedProtocols() Returns the protocol names that are supported by this engine.
abstract boolean	getUseClientMode() Returns whether this engine is set to act in client mode when handshaking.
abstract boolean	getWantClientAuth() Returns whether this engine will request client authentication.
abstract boolean	isInboundDone() Returns whether no more inbound data will be accepted by this engine.
abstract boolean	isOutboundDone() Returns whether no more outbound data will be produced by this engine.
abstract void	setEnabledCipherSuites(String[] suites) Sets the SSL cipher suite names that should be enabled in this engine instance.
abstract void	setEnabledProtocols(String[] protocols) Sets the protocol version names that should be enabled in this engine instance.
abstract void	setEnableSessionCreation(boolean flag) Sets whether new SSL sessions may be established by this engine instance.
abstract void	setNeedClientAuth(boolean need) Sets whether this engine must 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 engine should act in client (or server) mode when handshaking.
abstract void	setWantClientAuth(boolean want) Sets whether this engine should request client authentication.
SSLEngineResult	unwrap(ByteBuffer src, ByteBuffer dst) Decodes the incoming network data buffer into the application data buffer.
SSLEngineResult	unwrap(ByteBuffer src, ByteBuffer[] dsts) Decodes the incoming network data buffer into the application data buffers.
abstract SSLEngineResult	unwrap(ByteBuffer src, ByteBuffer[] dsts, int offset, int length) Decodes the incoming network data buffer into application data buffers.
SSLEngineResult	wrap(ByteBuffer[] srcs, ByteBuffer dst) Encodes the outgoing application data buffers into the network data buffer.
abstract SSLEngineResult	wrap(ByteBuffer[] srcs, int offset, int length, ByteBuffer dst) Encodes the outgoing application data buffers into the network data buffer.
SSLEngineResult	wrap(ByteBuffer src, ByteBuffer dst) Encodes the outgoing application data buffer into the network data buffer.

Methods inherited from class java.lang.Object

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

Constructor Detail

SSLEngine

protected SSLEngine()

Creates a new SSLEngine instance.

SSLEngine

protected SSLEngine(String host,
                    int port)

Creates a new SSLEngine instance with the specified host and port.

Parameters:

host - the name of the host.

port - the port of the host.

Method Detail

getPeerHost

public String getPeerHost()

Returns the name of the peer host.

Returns:

the name of the peer host, or null if none is available.

getPeerPort

public int getPeerPort()

Returns the port number of the peer host.

Returns:

the port number of the peer host, or -1 is none is available.

beginHandshake

public abstract void beginHandshake()
                             throws SSLException

Initiates a handshake on this engine.

Calling this method is not needed for the initial handshake: it will be called by wrap or unwrap if the initial handshake has not been started yet.

Throws:

SSLException - if starting the handshake fails.

IllegalStateException - if the engine does not have all the needed settings (e.g. client/server mode not set).

closeInbound

public abstract void closeInbound()
                           throws SSLException

Notifies this engine instance that no more inbound network data will be sent to this engine.

Throws:

SSLException - if this engine did not receive a needed protocol specific close notification message from the peer.

closeOutbound

public abstract void closeOutbound()

Notifies this engine instance that no more outbound application data will be sent to this engine.

getDelegatedTask

public abstract Runnable getDelegatedTask()

Returns a delegate task for this engine instance. Some engine operations may require the results of blocking or long running operations, and the SSLEngineResult instances returned by this engine may indicate that a delegated task result is needed. In this case the run method of the returned Runnable delegated task must be called.

Returns:

a delegate task, or null if none are available.

getEnabledCipherSuites

public abstract String[] getEnabledCipherSuites()

Returns the SSL cipher suite names that are enabled in this engine instance.

Returns:

the SSL cipher suite names that are enabled in this engine instance.

getEnabledProtocols

public abstract String[] getEnabledProtocols()

Returns the protocol version names that are enabled in this engine instance.

Returns:

the protocol version names that are enabled in this engine instance.

getEnableSessionCreation

public abstract boolean getEnableSessionCreation()

Returns whether new SSL sessions may be established by this engine.

Returns:

true if new session may be established, false if existing sessions must be reused.

getHandshakeStatus

public abstract SSLEngineResult.HandshakeStatus getHandshakeStatus()

Returns the status of the handshake of this engine instance.

Returns:

the status of the handshake of this engine instance.

getNeedClientAuth

public abstract boolean getNeedClientAuth()

Returns whether this engine instance will require client authentication.

Returns:

true if this engine will require client authentication, false if no client authentication is needed.

getSession

public abstract SSLSession getSession()

Returns the SSL session for this engine instance.

Returns:

the SSL session for this engine instance.

getSupportedCipherSuites

public abstract String[] getSupportedCipherSuites()

Returns the SSL cipher suite names that are supported by this engine. These cipher suites can be enabled using setEnabledCipherSuites(String[]).

Returns:

the SSL cipher suite names that are supported by this engine.

getSupportedProtocols

public abstract String[] getSupportedProtocols()

Returns the protocol names that are supported by this engine. These protocols can be enables using setEnabledProtocols(String[]).

Returns:

the protocol names that are supported by this engine.

getUseClientMode

public abstract boolean getUseClientMode()

Returns whether this engine is set to act in client mode when handshaking.

Returns:

true if the engine is set to do handshaking in client mode.

getWantClientAuth

public abstract boolean getWantClientAuth()

Returns whether this engine will request client authentication.

Returns:

true if client authentication will be requested, false otherwise.

isInboundDone

public abstract boolean isInboundDone()

Returns whether no more inbound data will be accepted by this engine.

Returns:

true if no more inbound data will be accepted by this engine, false otherwise.

isOutboundDone

public abstract boolean isOutboundDone()

Returns whether no more outbound data will be produced by this engine.

Returns:

true if no more outbound data will be producted by this engine, otherwise false.

setEnabledCipherSuites

public abstract void setEnabledCipherSuites(String[] suites)

Sets the SSL cipher suite names that should be enabled in this engine instance. Only cipher suites listed by getSupportedCipherSuites() are allowed.

Parameters:

suites - the SSL cipher suite names to be enabled.

Throws:

IllegalArgumentException - if one of the specified cipher suites is not supported, or if suites is null.

setEnabledProtocols

public abstract void setEnabledProtocols(String[] protocols)

Sets the protocol version names that should be enabled in this engine instance. Only protocols listed by getSupportedProtocols() are allowed.

Parameters:

protocols - the protocol version names to be enabled.

Throws:

IllegalArgumentException - if one of the protocol version names is not supported, or if protocols is null.

setEnableSessionCreation

public abstract void setEnableSessionCreation(boolean flag)

Sets whether new SSL sessions may be established by this engine instance.

Parameters:

flag - true if new SSL sessions may be established, false if existing SSL sessions must be reused.

setNeedClientAuth

public abstract void setNeedClientAuth(boolean need)

Sets whether this engine must require client authentication. The client authentication is one of:

• authentication required
• authentication requested
• no authentication needed

This method overrides the setting of setWantClientAuth(boolean).

Parameters:

need - true if client authentication is required, false if no authentication is needed.

setUseClientMode

public abstract void setUseClientMode(boolean mode)

Sets whether this engine should act in client (or server) mode when handshaking.

Parameters:

mode - true if this engine should act in client mode, false if not.

Throws:

IllegalArgumentException - if this method is called after starting the initial handshake.

setWantClientAuth

public abstract void setWantClientAuth(boolean want)

Sets whether this engine should request client authentication. The client authentication is one of the following:

• authentication required
• authentication requested
• no authentication needed

This method overrides the setting of setNeedClientAuth(boolean).

Parameters:

want - true if client authentication should be requested, false if no authentication is needed.

unwrap

public abstract SSLEngineResult unwrap(ByteBuffer src,
                                       ByteBuffer[] dsts,
                                       int offset,
                                       int length)
                                throws SSLException

Decodes the incoming network data buffer into application data buffers. If a handshake has not been started yet, it will automatically be started.

Parameters:

src - the buffer with incoming network data

dsts - the array of destination buffers for incoming application data.

offset - the offset in the array of destination buffers to which data is to be transferred.

length - the maximum number of destination buffers to be used.

Returns:

the result object of this operation.

Throws:

SSLException - if a problem occurred while processing the data.

IndexOutOfBoundsException - if length is greater than dsts.length - offset.

ReadOnlyBufferException - if one of the destination buffers is read-only.

IllegalArgumentException - if src, dsts, or one of the entries in dsts is null.

IllegalStateException - if the engine does not have all the needed settings (e.g. client/server mode not set).

wrap

public abstract SSLEngineResult wrap(ByteBuffer[] srcs,
                                     int offset,
                                     int length,
                                     ByteBuffer dst)
                              throws SSLException

Encodes the outgoing application data buffers into the network data buffer. If a handshake has not been started yet, it will automatically be started.

Parameters:

srcs - the array of source buffers of outgoing application data.

offset - the offset in the array of source buffers from which data is to be retrieved.

length - the maximum number of source buffers to be used.

dst - the destination buffer for network data.

Returns:

the result object of this operation.

Throws:

SSLException - if a problem occurred while processing the data.

IndexOutOfBoundsException - if length is greater than srcs.length - offset.

ReadOnlyBufferException - if the destination buffer is readonly.

IllegalArgumentException - if srcs, dst, or one the entries in srcs is null.

IllegalStateException - if the engine does not have all the needed settings (e.g. client/server mode not set).

unwrap

public SSLEngineResult unwrap(ByteBuffer src,
                              ByteBuffer dst)
                       throws SSLException

Decodes the incoming network data buffer into the application data buffer. If a handshake has not been started yet, it will automatically be started.

Parameters:

src - the buffer with incoming network data

dst - the destination buffer for incoming application data.

Returns:

the result object of this operation.

Throws:

SSLException - if a problem occurred while processing the data.

ReadOnlyBufferException - if one of the destination buffers is read-only.

IllegalArgumentException - if src or dst is null.

IllegalStateException - if the engine does not have all the needed settings (e.g. client/server mode not set).

unwrap

public SSLEngineResult unwrap(ByteBuffer src,
                              ByteBuffer[] dsts)
                       throws SSLException

Decodes the incoming network data buffer into the application data buffers. If a handshake has not been started yet, it will automatically be started.

Parameters:

src - the buffer with incoming network data

dsts - the array of destination buffers for incoming application data.

Returns:

the result object of this operation.

Throws:

SSLException - if a problem occurred while processing the data.

ReadOnlyBufferException - if one of the destination buffers is read-only.

IllegalArgumentException - if src or dsts is null.

IllegalStateException - if the engine does not have all the needed settings (e.g. client/server mode not set).

wrap

public SSLEngineResult wrap(ByteBuffer[] srcs,
                            ByteBuffer dst)
                     throws SSLException

Encodes the outgoing application data buffers into the network data buffer. If a handshake has not been started yet, it will automatically be started.

Parameters:

srcs - the array of source buffers of outgoing application data.

dst - the destination buffer for network data.

Returns:

the result object of this operation.

Throws:

SSLException - if a problem occurred while processing the data.

ReadOnlyBufferException - if the destination buffer is readonly.

IllegalArgumentException - if srcs or dst is null.

IllegalStateException - if the engine does not have all the needed settings (e.g. client/server mode not set).

wrap

public SSLEngineResult wrap(ByteBuffer src,
                            ByteBuffer dst)
                     throws SSLException

Encodes the outgoing application data buffer into the network data buffer. If a handshake has not been started yet, it will automatically be started.

Parameters:

src - the source buffers of outgoing application data.

dst - the destination buffer for network data.

Returns:

the result object of this operation.

Throws:

SSLException - if a problem occurred while processing the data.

ReadOnlyBufferException - if the destination buffer is readonly.

IllegalArgumentException - if src or dst is null.

IllegalStateException - if the engine does not have all the needed settings (e.g. client/server mode not set).

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 SSLEngine'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 SSLEngine, otherwise both are set to false.

Since:

1.6