Please note that the contents of this offline web site may be out of date. To access the most recent documentation visit the online version .
Note that links that point to online resources are green in color and will open in a new window.
We would love it if you could give us feedback about this material by filling this form (You have to be online to fill it)
Android APIs
public abstract class

SSLEngine

extends Object
java.lang.Object
   ↳ javax.net.ssl.SSLEngine

Class Overview

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+

Cipher suites

Cipher suite Supported (API Levels) Enabled by default (API Levels)
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_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA 9+ 9-19
SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA 9+ 9+
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+
SSL_DHE_RSA_WITH_DES_CBC_SHA 9+ 9-19
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+
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+
SSL_RSA_WITH_RC4_128_SHA 9+ 9+
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+
TLS_DH_anon_WITH_AES_256_CBC_SHA 9+
TLS_DH_anon_WITH_DES_CBC_SHA 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_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+ 9+
TLS_DHE_DSS_WITH_AES_256_CBC_SHA 9+ 20+
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_256_CBC_SHA 9+ 20+
TLS_DHE_RSA_WITH_DES_CBC_SHA 1-8 1-8
TLS_NULL_WITH_NULL_NULL 1-8
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_256_CBC_SHA 9+ 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

Summary

Protected Constructors
SSLEngine ()
Creates a new SSLEngine instance.
SSLEngine ( String host, int port)
Creates a new SSLEngine instance with the specified host and port.
Public Methods
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 boolean getEnableSessionCreation ()
Returns whether new SSL sessions may be established by this engine.
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 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.
SSLParameters getSSLParameters ()
Returns a new SSLParameters based on this SSLSocket's current cipher suites, protocols, and client authentication settings.
abstract SSLSession getSession ()
Returns the SSL session for this engine instance.
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 setEnableSessionCreation (boolean flag)
Sets whether new SSL sessions may be established by this engine instance.
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 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.
abstract SSLEngineResult unwrap ( ByteBuffer src, ByteBuffer[] dsts, int offset, int length)
Decodes the incoming network data buffer into application data buffers.
SSLEngineResult unwrap ( ByteBuffer src, ByteBuffer[] dsts)
Decodes the incoming network data buffer into the 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.
[Expand]
Inherited Methods
From class java.lang.Object

Protected Constructors

protected SSLEngine ()

Added in API level 1

Creates a new SSLEngine instance.

protected SSLEngine ( String host, int port)

Added in API level 1

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

Parameters
host the name of the host.
port the port of the host.

Public Methods

public abstract void beginHandshake ()

Added in API level 1

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

public abstract void closeInbound ()

Added in API level 1

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.

public abstract void closeOutbound ()

Added in API level 1

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

public abstract Runnable getDelegatedTask ()

Added in API level 1

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.

public abstract boolean getEnableSessionCreation ()

Added in API level 1

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.

public abstract String[] getEnabledCipherSuites ()

Added in API level 1

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.

public abstract String[] getEnabledProtocols ()

Added in API level 1

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

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

public abstract SSLEngineResult.HandshakeStatus getHandshakeStatus ()

Added in API level 1

Returns the status of the handshake of this engine instance.

Returns
  • the status of the handshake of this engine instance.

public abstract boolean getNeedClientAuth ()

Added in API level 1

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.

public String getPeerHost ()

Added in API level 1

Returns the name of the peer host.

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

public int getPeerPort ()

Added in API level 1

Returns the port number of the peer host.

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

public SSLParameters getSSLParameters ()

Added in API level 9

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

public abstract SSLSession getSession ()

Added in API level 1

Returns the SSL session for this engine instance.

Returns
  • the SSL session for this engine instance.

public abstract String[] getSupportedCipherSuites ()

Added in API level 1

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.

public abstract String[] getSupportedProtocols ()

Added in API level 1

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.

public abstract boolean getUseClientMode ()

Added in API level 1

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.

public abstract boolean getWantClientAuth ()

Added in API level 1

Returns whether this engine will request client authentication.

Returns
  • true if client authentication will be requested, false otherwise.

public abstract boolean isInboundDone ()

Added in API level 1

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.

public abstract boolean isOutboundDone ()

Added in API level 1

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.

public abstract void setEnableSessionCreation (boolean flag)

Added in API level 1

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.

public abstract void setEnabledCipherSuites ( String[] suites)

Added in API level 1

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 .

public abstract void setEnabledProtocols ( String[] protocols)

Added in API level 1

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 .

public abstract void setNeedClientAuth (boolean need)

Added in API level 1

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.

public void setSSLParameters ( SSLParameters p)

Added in API level 9

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.

public abstract void setUseClientMode (boolean mode)

Added in API level 1

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.

public abstract void setWantClientAuth (boolean want)

Added in API level 1

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.

public SSLEngineResult unwrap ( ByteBuffer src, ByteBuffer dst)

Added in API level 1

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

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

Added in API level 1

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

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

Added in API level 1

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

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

Added in API level 1

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

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

Added in API level 1

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

public SSLEngineResult wrap ( ByteBuffer src, ByteBuffer dst)

Added in API level 1

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