APIdia Launch Partner
Top Description Inners Fields Constructors Methods
javax.net.ssl

public Class SSLEngineResult

extends Object
Class Inheritance
Imports
java.nio.ByteBuffer
An encapsulation of the result state produced by SSLEngine I/O calls.

A SSLEngine provides a means for establishing secure communication sessions between two peers. SSLEngine operations typically consume bytes from an input buffer and produce bytes in an output buffer. This class provides operational result values describing the state of the SSLEngine, including indications of what operations are needed to finish an ongoing handshake. Lastly, it reports the number of bytes consumed and produced as a result of this operation.

Author
Brad R. Wetmore
Since
1.5
See Also
SSLEngine, SSLEngine#wrap(ByteBuffer, ByteBuffer), SSLEngine#unwrap(ByteBuffer, ByteBuffer)

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static enum
SSLEngineResult.HandshakeStatus

An SSLEngineResult enum describing the current handshaking state of this SSLEngine.

public static enum
SSLEngineResult.Status

An SSLEngineResult enum describing the overall result of the SSLEngine operation.

Field Summary

Modifier and TypeField and Description
private final int
bytesConsumed

private final int
bytesProduced

private final SSLEngineResult.HandshakeStatus
handshakeStatus

private final long
sequenceNumber

private final SSLEngineResult.Status
status

Constructor Summary

AccessConstructor and Description
public
SSLEngineResult(SSLEngineResult.Status
the return value of the operation.
status, SSLEngineResult.HandshakeStatus
the current handshaking status.
handshakeStatus, int
the number of bytes consumed from the source ByteBuffer
bytesConsumed, int
the number of bytes placed into the destination ByteBuffer
bytesProduced)

Initializes a new instance of this class.

public
SSLEngineResult(SSLEngineResult.Status
the return value of the operation.
status, SSLEngineResult.HandshakeStatus
the current handshaking status.
handshakeStatus, int
the number of bytes consumed from the source ByteBuffer
bytesConsumed, int
the number of bytes placed into the destination ByteBuffer
bytesProduced, long
the sequence number (unsigned long) of the produced or consumed SSL/TLS/DTLS record, or -1L if no record produced or consumed
sequenceNumber)

Initializes a new instance of this class.

Method Summary

Modifier and TypeMethod and Description
public final int

Returns:

the number of bytes consumed.
bytesConsumed()

Returns the number of bytes consumed from the input buffer.

public final int

Returns:

the number of bytes produced
bytesProduced()

Returns the number of bytes written to the output buffer.

public final SSLEngineResult.HandshakeStatus

Returns:

the handshake status
getHandshakeStatus()

Gets the handshake status of this SSLEngine operation.

public final SSLEngineResult.Status

Returns:

the return value
getStatus()

Gets the return value of this SSLEngine operation.

public final long

Returns:

the sequence number of the produced or consumed SSL/TLS/DTLS record; or -1L if no record is produced or consumed, or this operation is not supported by the underlying provider
sequenceNumber()

Returns the sequence number of the produced or consumed SSL/TLS/DTLS record (optional operation).

public String
toString()

Overrides java.lang.Object.toString.

Returns a String representation of this object.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAllwaitwaitwait

Field Detail

bytesConsumedback to summary
private final int bytesConsumed
bytesProducedback to summary
private final int bytesProduced
handshakeStatusback to summary
private final SSLEngineResult.HandshakeStatus handshakeStatus
sequenceNumberback to summary
private final long sequenceNumber
statusback to summary
private final SSLEngineResult.Status status

Constructor Detail

SSLEngineResultback to summary
public SSLEngineResult(SSLEngineResult.Status status, SSLEngineResult.HandshakeStatus handshakeStatus, int bytesConsumed, int bytesProduced)

Initializes a new instance of this class.

Parameters
status:SSLEngineResult.Status

the return value of the operation.

handshakeStatus:SSLEngineResult.HandshakeStatus

the current handshaking status.

bytesConsumed:int

the number of bytes consumed from the source ByteBuffer

bytesProduced:int

the number of bytes placed into the destination ByteBuffer

Exceptions
IllegalArgumentException:
if the status or handshakeStatus arguments are null, or if bytesConsumed or bytesProduced is negative.
SSLEngineResultback to summary
public SSLEngineResult(SSLEngineResult.Status status, SSLEngineResult.HandshakeStatus handshakeStatus, int bytesConsumed, int bytesProduced, long sequenceNumber)

Initializes a new instance of this class.

Parameters
status:SSLEngineResult.Status

the return value of the operation.

handshakeStatus:SSLEngineResult.HandshakeStatus

the current handshaking status.

bytesConsumed:int

the number of bytes consumed from the source ByteBuffer

bytesProduced:int

the number of bytes placed into the destination ByteBuffer

sequenceNumber:long

the sequence number (unsigned long) of the produced or consumed SSL/TLS/DTLS record, or -1L if no record produced or consumed

Exceptions
IllegalArgumentException:
if the status or handshakeStatus arguments are null, or if bytesConsumed or bytesProduced is negative
Since
9

Method Detail

bytesConsumedback to summary
public final int bytesConsumed()

Returns the number of bytes consumed from the input buffer.

Returns:int

the number of bytes consumed.

bytesProducedback to summary
public final int bytesProduced()

Returns the number of bytes written to the output buffer.

Returns:int

the number of bytes produced

getHandshakeStatusback to summary
public final SSLEngineResult.HandshakeStatus getHandshakeStatus()

Gets the handshake status of this SSLEngine operation.

Returns:SSLEngineResult.HandshakeStatus

the handshake status

getStatusback to summary
public final SSLEngineResult.Status getStatus()

Gets the return value of this SSLEngine operation.

Returns:SSLEngineResult.Status

the return value

sequenceNumberback to summary
public final long sequenceNumber()

Returns the sequence number of the produced or consumed SSL/TLS/DTLS record (optional operation).

API Note

Note that sequence number is an unsigned long and cannot exceed -1L. It is desired to use the unsigned long comparing mode for comparison of unsigned long values (see also Long.compareUnsigned()).

For DTLS protocols, the first 16 bits of the sequence number is a counter value (epoch) that is incremented on every cipher state change. The remaining 48 bits on the right side of the sequence number represents the sequence of the record, which is maintained separately for each epoch.

Implementation Note

It is recommended that providers should never allow the sequence number incremented to -1L. If the sequence number is close to wrapping, renegotiate should be requested, otherwise the connection should be closed immediately. This should be carried on automatically by the underlying implementation.

Returns:long

the sequence number of the produced or consumed SSL/TLS/DTLS record; or -1L if no record is produced or consumed, or this operation is not supported by the underlying provider

Since
9
See Also
java.lang.Long#compareUnsigned(long, long)
toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Returns a String representation of this object.

Annotations
@Override
javax.net.ssl back to summary

public final Enum SSLEngineResult.HandshakeStatus

extends Enum<SSLEngineResult.HandshakeStatus>
Class Inheritance
An SSLEngineResult enum describing the current handshaking state of this SSLEngine.
Author
Brad R. Wetmore
Since
1.5

Field Summary

Modifier and TypeField and Description
public static final SSLEngineResult.HandshakeStatus
FINISHED

The SSLEngine has just finished handshaking.

public static final SSLEngineResult.HandshakeStatus
NEED_TASK

The SSLEngine needs the results of one (or more) delegated tasks before handshaking can continue.

public static final SSLEngineResult.HandshakeStatus
NEED_UNWRAP

The SSLEngine needs to receive data from the remote side before handshaking can continue.

public static final SSLEngineResult.HandshakeStatus
NEED_UNWRAP_AGAIN

The SSLEngine needs to unwrap before handshaking can continue.

public static final SSLEngineResult.HandshakeStatus
NEED_WRAP

The SSLEngine must send data to the remote side before handshaking can continue, so SSLEngine.wrap() should be called.

public static final SSLEngineResult.HandshakeStatus
NOT_HANDSHAKING

The SSLEngine is not currently handshaking.

Constructor Summary

AccessConstructor and Description
private
HandshakeStatus()

Method Summary

Modifier and TypeMethod and Description
public static SSLEngineResult.HandshakeStatus
valueOf(String name)

public static SSLEngineResult.HandshakeStatus[]
values()

Inherited from java.lang.Enum:
clonecompareTodescribeConstableequalsfinalizegetDeclaringClasshashCodenameordinaltoStringvalueOf

Field Detail

FINISHEDback to summary
public static final SSLEngineResult.HandshakeStatus FINISHED

The SSLEngine has just finished handshaking.

This value is only generated by a call to SSLEngine.wrap()/unwrap() when that call finishes a handshake. It is never generated by SSLEngine.getHandshakeStatus().

See Also
SSLEngine#wrap(ByteBuffer, ByteBuffer), SSLEngine#unwrap(ByteBuffer, ByteBuffer), SSLEngine#getHandshakeStatus()
NEED_TASKback to summary
public static final SSLEngineResult.HandshakeStatus NEED_TASK

The SSLEngine needs the results of one (or more) delegated tasks before handshaking can continue.

See Also
SSLEngine#getDelegatedTask()
NEED_UNWRAPback to summary
public static final SSLEngineResult.HandshakeStatus NEED_UNWRAP

The SSLEngine needs to receive data from the remote side before handshaking can continue.

NEED_UNWRAP_AGAINback to summary
public static final SSLEngineResult.HandshakeStatus NEED_UNWRAP_AGAIN

The SSLEngine needs to unwrap before handshaking can continue.

This value is used to indicate that not-yet-interpreted data has been previously received from the remote side, and does not need to be received again.

This handshake status only applies to DTLS.

Since
9
NEED_WRAPback to summary
public static final SSLEngineResult.HandshakeStatus NEED_WRAP

The SSLEngine must send data to the remote side before handshaking can continue, so SSLEngine.wrap() should be called.

See Also
SSLEngine#wrap(ByteBuffer, ByteBuffer)
NOT_HANDSHAKINGback to summary
public static final SSLEngineResult.HandshakeStatus NOT_HANDSHAKING

The SSLEngine is not currently handshaking.

Constructor Detail

HandshakeStatusback to summary
private HandshakeStatus()

Method Detail

valueOfback to summary
public static SSLEngineResult.HandshakeStatus valueOf(String name)
valuesback to summary
public static SSLEngineResult.HandshakeStatus[] values()
javax.net.ssl back to summary

public final Enum SSLEngineResult.Status

extends Enum<SSLEngineResult.Status>
Class Inheritance
An SSLEngineResult enum describing the overall result of the SSLEngine operation. The Status value does not reflect the state of a SSLEngine handshake currently in progress. The SSLEngineResult's HandshakeStatus should be consulted for that information.
Author
Brad R. Wetmore
Since
1.5

Field Summary

Modifier and TypeField and Description
public static final SSLEngineResult.Status
BUFFER_OVERFLOW

The SSLEngine was not able to process the operation because there are not enough bytes available in the destination buffer to hold the result.

public static final SSLEngineResult.Status
BUFFER_UNDERFLOW

The SSLEngine was not able to unwrap the incoming data because there were not enough source bytes available to make a complete packet.

public static final SSLEngineResult.Status
CLOSED

The operation just closed this side of the SSLEngine, or the operation could not be completed because it was already closed.

public static final SSLEngineResult.Status
OK

The SSLEngine completed the operation, and is available to process similar calls.

Constructor Summary

AccessConstructor and Description
private
Status()

Method Summary

Modifier and TypeMethod and Description
public static SSLEngineResult.Status
valueOf(String name)

public static SSLEngineResult.Status[]
values()

Inherited from java.lang.Enum:
clonecompareTodescribeConstableequalsfinalizegetDeclaringClasshashCodenameordinaltoStringvalueOf

Field Detail

BUFFER_OVERFLOWback to summary
public static final SSLEngineResult.Status BUFFER_OVERFLOW

The SSLEngine was not able to process the operation because there are not enough bytes available in the destination buffer to hold the result.

Repeat the call once more bytes are available.

See Also
SSLSession#getPacketBufferSize(), SSLSession#getApplicationBufferSize()
BUFFER_UNDERFLOWback to summary
public static final SSLEngineResult.Status BUFFER_UNDERFLOW

The SSLEngine was not able to unwrap the incoming data because there were not enough source bytes available to make a complete packet.

Repeat the call once more bytes are available.

CLOSEDback to summary
public static final SSLEngineResult.Status CLOSED

The operation just closed this side of the SSLEngine, or the operation could not be completed because it was already closed.

OKback to summary
public static final SSLEngineResult.Status OK

The SSLEngine completed the operation, and is available to process similar calls.

Constructor Detail

Statusback to summary
private Status()

Method Detail

valueOfback to summary
public static SSLEngineResult.Status valueOf(String name)
valuesback to summary
public static SSLEngineResult.Status[] values()