public Class ALPNLimitingSSLEngine

Implements abstract javax.net.ssl.SSLEngine.beginHandshake.

Doc from javax.net.ssl.SSLEngine.beginHandshake.

Initiates handshaking (initial or renegotiation) on this SSLEngine.

This method is not needed for the initial handshake, as the wrap() and unwrap() methods will implicitly call this method if handshaking has not already begun.

Note that the peer may also request a session renegotiation with this SSLEngine by sending the appropriate session renegotiate handshake message.

Unlike the SSLSocket#startHandshake() method, this method does not block until handshaking is completed.

To force a complete SSL/TLS/DTLS session renegotiation, the current session should be invalidated prior to calling this method.

Some protocols may not support multiple handshakes on an existing engine and may throw an SSLException.

Annotations

@Override

Exceptions

SSLException:

if a problem was encountered while signaling the SSLEngine to begin a new handshake. See the class description for more information on engine closure.

Implements abstract javax.net.ssl.SSLEngine.closeInbound.

Doc from javax.net.ssl.SSLEngine.closeInbound.

Signals that no more inbound network data will be sent to this SSLEngine.

If the application initiated the closing process by calling closeOutbound(), under some circumstances it is not required that the initiator wait for the peer's corresponding close message. (See section 7.2.1 of the TLS specification (RFC 2246) for more information on waiting for closure alerts.) In such cases, this method need not be called.

But if the application did not initiate the closure process, or if the circumstances above do not apply, this method should be called whenever the end of the SSL/TLS/DTLS data stream is reached. This ensures closure of the inbound side, and checks that the peer followed the SSL/TLS/DTLS close procedure properly, thus detecting possible truncation attacks.

This method is idempotent: if the inbound side has already been closed, this method does not do anything.

wrap() should be called to flush any remaining handshake data.

Annotations

@Override

Exceptions

SSLException:

if this engine has not received the proper SSL/TLS/DTLS close notification message from the peer.

Implements abstract javax.net.ssl.SSLEngine.closeOutbound.

Doc from javax.net.ssl.SSLEngine.closeOutbound.

Signals that no more outbound application data will be sent on this SSLEngine.

This method is idempotent: if the outbound side has already been closed, this method does not do anything.

wrap(ByteBuffer, ByteBuffer) should be called to flush any remaining handshake data.

Annotations

@Override

Implements abstract javax.net.ssl.SSLEngine.getDelegatedTask.

Doc from javax.net.ssl.SSLEngine.getDelegatedTask.

Returns a delegated Runnable task for this SSLEngine.

SSLEngine operations may require the results of operations that block, or may take an extended period of time to complete. This method is used to obtain an outstanding java.lang.Runnable operation (task). Each task must be assigned a thread (possibly the current) to perform the run operation. Once the run method returns, the Runnable object is no longer needed and may be discarded.

Delegated tasks run in the AccessControlContext in place when this object was created.

A call to this method will return each outstanding task exactly once.

Multiple delegated tasks can be run in parallel.

Returns:Runnable

a delegated Runnable task, or null if none are available.

Annotations

@Override

Implements abstract javax.net.ssl.SSLEngine.getEnabledCipherSuites.

Doc from javax.net.ssl.SSLEngine.getEnabledCipherSuites.

Returns the names of the SSL cipher suites which are currently enabled for use on this engine. When an SSLEngine is first created, all enabled cipher suites support a minimum quality of service. Thus, in some environments this value might be empty.

Note that even if a suite is enabled, it may never be used. This can occur if the peer does not support it, or its use is restricted, or the requisite certificates (and private keys) for the suite are not available, or an anonymous suite is enabled but authentication is required.

The returned array includes cipher suites from the list of standard cipher suite names in the JSSE Cipher Suite Names section of the Java Security Standard Algorithm Names Specification, and may also include other cipher suites that the provider supports.

Returns:String[]

an array of cipher suite names

Annotations

@Override

Implements abstract javax.net.ssl.SSLEngine.getEnabledProtocols.

Doc from javax.net.ssl.SSLEngine.getEnabledProtocols.

Returns the names of the protocol versions which are currently enabled for use with this SSLEngine.

Note that even if a protocol is enabled, it may never be used. This can occur if the peer does not support the protocol, or its use is restricted, or there are no enabled cipher suites supported by the protocol.

Returns:String[]

an array of protocols

Annotations

@Override

Implements abstract javax.net.ssl.SSLEngine.getEnableSessionCreation.

Doc from javax.net.ssl.SSLEngine.getEnableSessionCreation.

Returns true if new SSL sessions may be established by this engine.

Returns:boolean

true indicates that sessions may be created; this is the default. false indicates that an existing session must be resumed

Annotations

@Override

Overrides javax.net.ssl.SSLEngine.getHandshakeSession.

Doc from javax.net.ssl.SSLEngine.getHandshakeSession.

Returns the SSLSession being constructed during a SSL/TLS/DTLS handshake.

TLS/DTLS protocols may negotiate parameters that are needed when using an instance of this class, but before the SSLSession has been completely initialized and made available via getSession. For example, the list of valid signature algorithms may restrict the type of certificates that can be used during TrustManager decisions, or the maximum TLS/DTLS fragment packet sizes can be resized to better support the network environment.

This method provides early access to the SSLSession being constructed. Depending on how far the handshake has progressed, some data may not yet be available for use. For example, if a remote server will be sending a Certificate chain, but that chain has yet not been processed, the getPeerCertificates method of SSLSession will throw a SSLPeerUnverifiedException. Once that chain has been processed, getPeerCertificates will return the proper value.

Returns:SSLSession

null if this instance is not currently handshaking, or if the current handshake has not progressed far enough to create a basic SSLSession. Otherwise, this method returns the SSLSession currently being negotiated.

Annotations

@Override

Implements abstract javax.net.ssl.SSLEngine.getHandshakeStatus.

Doc from javax.net.ssl.SSLEngine.getHandshakeStatus.

Returns the current handshake status for this SSLEngine.

Returns:SSLEngineResult.HandshakeStatus

the current SSLEngineResult.HandshakeStatus.

Annotations

@Override

Implements abstract javax.net.ssl.SSLEngine.getNeedClientAuth.

Doc from javax.net.ssl.SSLEngine.getNeedClientAuth.

Returns true if the engine will require client authentication. This option is only useful to engines in the server mode.

Returns:boolean

true if client authentication is required, or false if no client authentication is desired.

Annotations

@Override

Overrides javax.net.ssl.SSLEngine.getPeerHost.

Doc from javax.net.ssl.SSLEngine.getPeerHost.

Returns the host name of the peer.

Note that the value is not authenticated, and should not be relied upon.

Returns:String

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

Annotations

@Override

Overrides javax.net.ssl.SSLEngine.getPeerPort.

Doc from javax.net.ssl.SSLEngine.getPeerPort.

Returns the port number of the peer.

Note that the value is not authenticated, and should not be relied upon.

Returns:int

the port number of the peer, or -1 if nothing is available.

Annotations

@Override

Implements abstract javax.net.ssl.SSLEngine.getSession.

Doc from javax.net.ssl.SSLEngine.getSession.

Returns the SSLSession in use in this SSLEngine.

These can be long-lived, and frequently correspond to an entire login session for some user. The session specifies a particular cipher suite which is being actively used by all connections in that session, as well as the identities of the session's client and server.

Unlike SSLSocket#getSession() this method does not block until handshaking is complete.

Until the initial handshake has completed, this method returns a session object which reports an invalid cipher suite of "SSL_NULL_WITH_NULL_NULL".

Returns:SSLSession

the SSLSession for this SSLEngine

Annotations

@Override

Overrides javax.net.ssl.SSLEngine.getSSLParameters.

Doc from javax.net.ssl.SSLEngine.getSSLParameters.

Returns the SSLParameters in effect for this SSLEngine. The ciphersuites and protocols of the returned SSLParameters are always non-null.

Returns:SSLParameters

the SSLParameters in effect for this SSLEngine.

Annotations

@Override

Implements abstract javax.net.ssl.SSLEngine.getSupportedCipherSuites.

Doc from javax.net.ssl.SSLEngine.getSupportedCipherSuites.

Returns the names of the cipher suites which could be enabled for use on this engine. Normally, only a subset of these will actually be enabled by default, since this list may include cipher suites which do not meet quality of service requirements for those defaults. Such cipher suites might be useful in specialized applications.

The returned array includes cipher suites from the list of standard cipher suite names in the JSSE Cipher Suite Names section of the Java Security Standard Algorithm Names Specification, and may also include other cipher suites that the provider supports.

Returns:String[]

an array of cipher suite names

Annotations

@Override

Implements abstract javax.net.ssl.SSLEngine.getSupportedProtocols.

Doc from javax.net.ssl.SSLEngine.getSupportedProtocols.

Returns the names of the protocols which could be enabled for use with this SSLEngine.

Returns:String[]

an array of protocols supported

Annotations

@Override

Implements abstract javax.net.ssl.SSLEngine.getUseClientMode.

Doc from javax.net.ssl.SSLEngine.getUseClientMode.

Returns true if the engine is set to use client mode when handshaking.

Returns:boolean

true if the engine should do handshaking in "client" mode

Annotations

@Override

Implements abstract javax.net.ssl.SSLEngine.getWantClientAuth.

Doc from javax.net.ssl.SSLEngine.getWantClientAuth.

Returns true if the engine will request client authentication. This option is only useful for engines in the server mode.

Returns:boolean

true if client authentication is requested, or false if no client authentication is desired.

Annotations

@Override

Implements abstract javax.net.ssl.SSLEngine.isInboundDone.

Doc from javax.net.ssl.SSLEngine.isInboundDone.

Returns whether unwrap(ByteBuffer, ByteBuffer) will accept any more inbound data messages.

Returns:boolean

true if the SSLEngine will not consume any more network data (and by implication, will not produce any more application data.)

Annotations

@Override

Implements abstract javax.net.ssl.SSLEngine.isOutboundDone.

Doc from javax.net.ssl.SSLEngine.isOutboundDone.

Returns whether wrap(ByteBuffer, ByteBuffer) will produce any more outbound data messages.

Note that during the closure phase, a SSLEngine may generate handshake closure data that must be sent to the peer. wrap() must be called to generate this data. When this method returns true, no more outbound data will be created.

Returns:boolean

true if the SSLEngine will not produce any more network data

Annotations

@Override

Implements abstract javax.net.ssl.SSLEngine.setEnabledCipherSuites.

Doc from javax.net.ssl.SSLEngine.setEnabledCipherSuites.

Sets the cipher suites enabled for use on this engine.

Each cipher suite in the suites parameter must have been listed by getSupportedCipherSuites(), or the method will fail. Following a successful call to this method, only suites listed in the suites parameter are enabled for use.

Note that the standard list of cipher suite names may be found in the JSSE Cipher Suite Names section of the Java Security Standard Algorithm Names Specification. Providers may support cipher suite names not found in this list or might not use the recommended name for a certain cipher suite.

See getEnabledCipherSuites() for more information on why a specific cipher suite may never be used on an engine.

Parameters

strings:String[]

Names of all the cipher suites to enable

Annotations

@Override

Implements abstract javax.net.ssl.SSLEngine.setEnabledProtocols.

Doc from javax.net.ssl.SSLEngine.setEnabledProtocols.

Set the protocol versions enabled for use on this engine.

The protocols must have been listed by getSupportedProtocols() as being supported. Following a successful call to this method, only protocols listed in the protocols parameter are enabled for use.

Parameters

strings:String[]

Names of all the protocols to enable.

Annotations

@Override

Implements abstract javax.net.ssl.SSLEngine.setEnableSessionCreation.

Doc from javax.net.ssl.SSLEngine.setEnableSessionCreation.

Controls whether new SSL sessions may be established by this engine. If session creations are not allowed, and there are no existing sessions to resume, there will be no successful handshaking.

Parameters

b:boolean

true indicates that sessions may be created; this is the default. false indicates that an existing session must be resumed

Annotations

@Override

Implements abstract javax.net.ssl.SSLEngine.setNeedClientAuth.

Doc from javax.net.ssl.SSLEngine.setNeedClientAuth.

Configures the engine to require client authentication. This option is only useful for engines in the server mode.

An engine's client authentication setting is one of the following:

• client authentication required
• client authentication requested
• no client authentication desired

Unlike setWantClientAuth(boolean), if this option is set and the client chooses not to provide authentication information about itself, the negotiations will stop and the engine will begin its closure procedure.

Calling this method overrides any previous setting made by this method or setWantClientAuth(boolean).

Parameters

b:boolean

set to true if client authentication is required, or false if no client authentication is desired.

Annotations

@Override

Overrides javax.net.ssl.SSLEngine.setSSLParameters.

Doc from javax.net.ssl.SSLEngine.setSSLParameters.

Applies SSLParameters to this engine.

This means:

• If params.getCipherSuites() is non-null, setEnabledCipherSuites() is called with that value.
• If params.getProtocols() is non-null, setEnabledProtocols() is called with that value.
• If params.getNeedClientAuth() or params.getWantClientAuth() return true, setNeedClientAuth(true) and setWantClientAuth(true) are called, respectively; otherwise setWantClientAuth(false) is called.
• If params.getServerNames() is non-null, the engine will configure its server names with that value.
• If params.getSNIMatchers() is non-null, the engine will configure its SNI matchers with that value.

Parameters

sslParameters:SSLParameters

the parameters

Annotations

@Override

Implements abstract javax.net.ssl.SSLEngine.setUseClientMode.

Doc from javax.net.ssl.SSLEngine.setUseClientMode.

Configures the engine to use client (or server) mode when handshaking.

This method must be called before any handshaking occurs. Once handshaking has begun, the mode can not be reset for the life of this engine.

Servers normally authenticate themselves, and clients are not required to do so.

Parameters

b:boolean

true if the engine should start its handshaking in "client" mode

Annotations

@Override

Implements abstract javax.net.ssl.SSLEngine.setWantClientAuth.

Doc from javax.net.ssl.SSLEngine.setWantClientAuth.

Configures the engine to request client authentication. This option is only useful for engines in the server mode.

An engine's client authentication setting is one of the following:

• client authentication required
• client authentication requested
• no client authentication desired

Unlike setNeedClientAuth(boolean), if this option is set and the client chooses not to provide authentication information about itself, the negotiations will continue.

Calling this method overrides any previous setting made by this method or setNeedClientAuth(boolean).

Parameters

b:boolean

set to true if client authentication is requested, or false if no client authentication is desired.

Annotations

@Override

Overrides javax.net.ssl.SSLEngine.unwrap.

Doc from javax.net.ssl.SSLEngine.unwrap.

Attempts to decode SSL/TLS/DTLS network data into a plaintext application data buffer.

An invocation of this method behaves in exactly the same manner as the invocation:

engine.unwrap(src, new ByteBuffer[] { dst }, 0, 1);

Parameters

src:ByteBuffer

a ByteBuffer containing inbound network data.

dst:ByteBuffer

a ByteBuffer to hold inbound application data.

Returns:SSLEngineResult

an SSLEngineResult describing the result of this operation.

Annotations

@Override

Exceptions

SSLException:

A problem was encountered while processing the data that caused the SSLEngine to abort. See the class description for more information on engine closure.

Overrides javax.net.ssl.SSLEngine.unwrap.

Doc from javax.net.ssl.SSLEngine.unwrap.

Attempts to decode SSL/TLS/DTLS network data into a sequence of plaintext application data buffers.

An invocation of this method behaves in exactly the same manner as the invocation:

engine.unwrap(src, dsts, 0, dsts.length);

Parameters

src:ByteBuffer

a ByteBuffer containing inbound network data.

dsts:ByteBuffer[]

an array of ByteBuffers to hold inbound application data.

Returns:SSLEngineResult

an SSLEngineResult describing the result of this operation.

Annotations

@Override

Exceptions

SSLException:

A problem was encountered while processing the data that caused the SSLEngine to abort. See the class description for more information on engine closure.

Implements abstract javax.net.ssl.SSLEngine.unwrap.

Doc from javax.net.ssl.SSLEngine.unwrap.

Attempts to decode SSL/TLS/DTLS network data into a subsequence of plaintext application data buffers. This "scattering" operation decodes, in a single invocation, a sequence of bytes into one or more of a given sequence of buffers. Scattering unwraps are often useful when implementing network protocols or file formats that, for example, group data into segments consisting of one or more fixed-length headers followed by a variable-length body. See java.nio.channels.ScatteringByteChannel for more information on scattering, and java.nio.channels.ScatteringByteChannel#read(ByteBuffer[], int, int) for more information on the subsequence behavior.

Depending on the state of the SSLEngine, this method may consume network data without producing any application data (for example, it may consume handshake data.)

The application is responsible for reliably obtaining the network data from the peer, and for invoking unwrap() on the data in the order it was received. The application must properly synchronize multiple calls to this method.

If this SSLEngine has not yet started its initial handshake, this method will automatically start the handshake.

This method will attempt to consume one complete SSL/TLS/DTLS network packet, but will never consume more than the sum of the bytes remaining in the buffers. Each ByteBuffer's position is updated to reflect the amount of data consumed or produced. The limits remain the same.

The underlying memory used by the src and dsts ByteBuffers must not be the same.

The inbound network buffer, src, may be modified as a result of this call: therefore if the network data packet is required for some secondary purpose, the data should be duplicated before calling this method.

Parameters

byteBuffer:ByteBuffer

a ByteBuffer containing inbound network data.

byteBuffers:ByteBuffer[]

an array of ByteBuffers to hold inbound application data.

i:int

The offset within the buffer array of the first buffer from which bytes are to be transferred; it must be non-negative and no larger than dsts.length.

i1:int

The maximum number of buffers to be accessed; it must be non-negative and no larger than dsts.length - offset.

Returns:SSLEngineResult

an SSLEngineResult describing the result of this operation.

Annotations

@Override

Exceptions

SSLException:

A problem was encountered while processing the data that caused the SSLEngine to abort. See the class description for more information on engine closure.

Overrides javax.net.ssl.SSLEngine.wrap.

Doc from javax.net.ssl.SSLEngine.wrap.

Attempts to encode a buffer of plaintext application data into SSL/TLS/DTLS network data.

An invocation of this method behaves in exactly the same manner as the invocation:

engine.wrap(new ByteBuffer[] { src }, 0, 1, dst);

Parameters

src:ByteBuffer

a ByteBuffer containing outbound application data

dst:ByteBuffer

a ByteBuffer to hold outbound network data

Returns:SSLEngineResult

an SSLEngineResult describing the result of this operation.

Annotations

@Override

Exceptions

SSLException:

A problem was encountered while processing the data that caused the SSLEngine to abort. See the class description for more information on engine closure.

Overrides javax.net.ssl.SSLEngine.wrap.

Doc from javax.net.ssl.SSLEngine.wrap.

Attempts to encode plaintext bytes from a sequence of data buffers into SSL/TLS/DTLS network data.

An invocation of this method behaves in exactly the same manner as the invocation:

engine.wrap(srcs, 0, srcs.length, dst);

Parameters

srcs:ByteBuffer[]

an array of ByteBuffers containing the outbound application data

dst:ByteBuffer

a ByteBuffer to hold outbound network data

Returns:SSLEngineResult

an SSLEngineResult describing the result of this operation.

Annotations

@Override

Exceptions

SSLException:

A problem was encountered while processing the data that caused the SSLEngine to abort. See the class description for more information on engine closure.

Implements abstract javax.net.ssl.SSLEngine.wrap.

Doc from javax.net.ssl.SSLEngine.wrap.

Attempts to encode plaintext bytes from a subsequence of data buffers into SSL/TLS/DTLS network data. This "gathering" operation encodes, in a single invocation, a sequence of bytes from one or more of a given sequence of buffers. Gathering wraps are often useful when implementing network protocols or file formats that, for example, group data into segments consisting of one or more fixed-length headers followed by a variable-length body. See java.nio.channels.GatheringByteChannel for more information on gathering, and java.nio.channels.GatheringByteChannel#write(ByteBuffer[], int, int) for more information on the subsequence behavior.

Depending on the state of the SSLEngine, this method may produce network data without consuming any application data (for example, it may generate handshake data.)

The application is responsible for reliably transporting the network data to the peer, and for ensuring that data created by multiple calls to wrap() is transported in the same order in which it was generated. The application must properly synchronize multiple calls to this method.

If this SSLEngine has not yet started its initial handshake, this method will automatically start the handshake.

This method will attempt to produce SSL/TLS/DTLS records, and will consume as much source data as possible, but will never consume more than the sum of the bytes remaining in each buffer. Each ByteBuffer's position is updated to reflect the amount of data consumed or produced. The limits remain the same.

The underlying memory used by the srcs and dst ByteBuffers must not be the same.

See the class description for more information on engine closure.

Parameters

srcs:ByteBuffer[]

an array of ByteBuffers containing the outbound application data

off:int

The offset within the buffer array of the first buffer from which bytes are to be retrieved; it must be non-negative and no larger than srcs.length

len:int

The maximum number of buffers to be accessed; it must be non-negative and no larger than srcs.length - offset

dst:ByteBuffer

a ByteBuffer to hold outbound network data

Returns:SSLEngineResult

an SSLEngineResult describing the result of this operation.

Annotations

@Override

Exceptions

SSLException:

A problem was encountered while processing the data that caused the SSLEngine to abort. See the class description for more information on engine closure.