Package javax.net.ssl

Class SSLEngine

java.lang.Object
javax.net.ssl.SSLEngine
Direct Known Subclasses:
SSLEngineImpl
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.
Since:
1.5

  • Constructor Details

    • 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 Details

    • 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