IT. Expert System.

Direct Known Subclasses:

MySSLContextSpi.tmpSSLEngine, MySSLContextSpi.tmpSSLEngine, SSLEngineImpl

public abstract class SSLEngine
extends Object

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

  Methods

  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