Package javax.net.ssl

Class 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 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