org.eclipse.californium.scandium.dtls

Class DTLSSession

java.lang.Object

org.eclipse.californium.scandium.dtls.DTLSSession

All Implemented Interfaces:

Destroyable

public final class DTLSSession
extends Object
implements Destroyable

Represents a DTLS session between two peers. Keeps track of the current and pending read/write states, the current epoch and sequence number, etc.

Field Summary

Fields

Modifier and Type	Field and Description
static int	DTLS_HEADER_LENGTH The payload length of all headers around a DTLS handshake message payload.
static int	HEADER_LENGTH Deprecated. use DTLS_HEADER_LENGTH and RecordLayer.getMaxDatagramSize(boolean) instead.

Constructor Summary

Constructors

Constructor and Description
DTLSSession(InetSocketAddress peerAddress) Creates a session using default values for all fields.
DTLSSession(InetSocketAddress peerAddress, long initialSequenceNo) Creates a new session initialized with a given sequence number.
DTLSSession(InetSocketAddress peerAddress, long initialSequenceNo, long creationTime) Creates a new session initialized with a given sequence number.
DTLSSession(SessionId id, InetSocketAddress peerAddress, SessionTicket ticket, long initialSequenceNo) Creates a new session based on a given set of crypto params of another session that is to be resumed.

Method Summary

Methods

Modifier and Type	Method and Description
void	destroy()
CipherSuite	getCipherSuite() Gets the cipher and MAC algorithm to be used for this session.
org.eclipse.californium.elements.DtlsEndpointContext	getConnectionReadContext()
org.eclipse.californium.elements.DtlsEndpointContext	getConnectionWriteContext()
long	getCreationTime() System time of session creation in milliseconds.
int	getEffectiveFragmentLimit() Gets effective fragment limit.
String	getHostName() Gets the (virtual) host name for the server that this session has been established for.
String	getLastHandshakeTime() System time tag of last handshake.
int	getMaxCiphertextExpansion() Get maximum expansion of cipher suite.
int	getMaxFragmentLength() Gets the maximum amount of unencrypted payload data that can be sent to this session's peer in a single DTLS record created under this session's current write state.
HandshakeParameter	getParameter() Return the handshake parameter, if set available.
InetSocketAddress	getPeer() Gets the IP address and socket of this session's peer.
Principal	getPeerIdentity() Gets the authenticated peer's identity.
ConnectionId	getReadConnectionId() Get connection id for inbound records.
int	getReadEpoch() Gets this session's current read epoch.
String	getReadStateCipher() Gets the name of the current read state's cipher suite.
Integer	getRecordSizeLimit() Gets the negotiated record size limit
InetSocketAddress	getRouter() Get router address.
long	getSequenceNumber() Gets the smallest unused sequence number for outbound records for the current epoch.
long	getSequenceNumber(int epoch) Gets the smallest unused sequence number for outbound records for a given epoch.
ServerNames	getServerNames() Gets the server names for the server that this session has been established for.
SessionId	getSessionIdentifier() Gets this session's identifier.
SessionTicket	getSessionTicket() Get a session ticket representing this session's current connection state.
SignatureAndHashAlgorithm	getSignatureAndHashAlgorithm() Gets the negotiated signature and hash algorithm to be used to sign the server key exchange message.
Mac	getThreadLocalClusterReadMac()
Mac	getThreadLocalClusterWriteMac()
ConnectionId	getWriteConnectionId() Get connection id for outbound records.
int	getWriteEpoch() Gets this session's current write epoch.
String	getWriteStateCipher() Gets the name of the current write state's cipher suite.
boolean	isDestroyed()
boolean	isMarkedAsClosed() Session is marked as close.
boolean	isRecordProcessable(long epoch, long sequenceNo, boolean useWindowOnly) Deprecated. use isRecordProcessable(long, long, int) instead
boolean	isRecordProcessable(long epoch, long sequenceNo, int useExtendedWindow) Checks whether a given record can be processed within the context of this session.
boolean	isSniSupported() Checks whether the peer (the server) supports the Server Name Indication extension.
void	markCloseNotiy(int epoch, long sequenceNo) Mark as closed.
boolean	markRecordAsRead(long epoch, long sequenceNo) Marks a record as having been received so that it can be detected as a duplicate if it is received again, e.g.
void	setHostName(String hostname) Set the (virtual) host name for the server that this session has been established for.
void	setParameterAvailable() Set parameter available.
void	setPeer(InetSocketAddress peer)
void	setRouter(InetSocketAddress router) Set router address.
void	setServerNames(ServerNames serverNames) Set the server names for the server that this session has been established for.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DTLS_HEADER_LENGTH

public static final int DTLS_HEADER_LENGTH

The payload length of all headers around a DTLS handshake message payload.

1. 12 bytes DTLS message header
2. 13 bytes DTLS record header

25 bytes in total.

Since:

2.5

See Also:

Constant Field Values

HEADER_LENGTH

@Deprecated
public static final int HEADER_LENGTH

Deprecated. use DTLS_HEADER_LENGTH and RecordLayer.getMaxDatagramSize(boolean) instead.

The overall length of all headers around a DTLS handshake message payload.

1. 12 bytes DTLS message header
2. 13 bytes DTLS record header
3. 8 bytes UDP header
4. 20 bytes IP header (Ipv4)
5. 36 bytes optional IP options

89 bytes in total (including 36 bytes optional).

See Also:

Constant Field Values

Constructor Detail

DTLSSession

public DTLSSession(InetSocketAddress peerAddress)

Creates a session using default values for all fields.

Parameters:

peerAddress - the remote address

DTLSSession

public DTLSSession(SessionId id,
           InetSocketAddress peerAddress,
           SessionTicket ticket,
           long initialSequenceNo)

Creates a new session based on a given set of crypto params of another session that is to be resumed.

The newly created session will have its pending state initialized with the given crypto params so that it can be used during the abbreviated handshake used to resume the session.

Parameters:

id - The identifier of the session to be resumed.

peerAddress - The IP address and port of the client that wants to resume the session.

ticket - The crypto params to use for the abbreviated handshake

initialSequenceNo - The initial record sequence number to start from in epoch 0. When starting a new handshake with a client that has successfully exchanged a cookie with the server, the sequence number to use in the SERVER_HELLO record MUST be the same as the one from the successfully validated CLIENT_HELLO record (see section 4.2.1 of RFC 6347 (DTLS 1.2) for details)

DTLSSession

public DTLSSession(InetSocketAddress peerAddress,
           long initialSequenceNo)

Creates a new session initialized with a given sequence number.

Parameters:

peerAddress - the IP address and port of the peer this session is established with

initialSequenceNo - the initial record sequence number to start from in epoch 0. When starting a new handshake with a client that has successfully exchanged a cookie with the server, the sequence number to use in the SERVER_HELLO record MUST be the same as the one from the successfully validated CLIENT_HELLO record (see section 4.2.1 of RFC 6347 (DTLS 1.2) for details)

DTLSSession

public DTLSSession(InetSocketAddress peerAddress,
           long initialSequenceNo,
           long creationTime)

Creates a new session initialized with a given sequence number.

Parameters:

peerAddress - the IP address and port of the peer this session is established with

initialSequenceNo - the initial record sequence number to start from in epoch 0. When starting a new handshake with a client that has successfully exchanged a cookie with the server, the sequence number to use in the SERVER_HELLO record MUST be the same as the one from the successfully validated CLIENT_HELLO record (see section 4.2.1 of RFC 6347 (DTLS 1.2) for details)

creationTime - creation time of session. Maybe from previous session on resumption.

Method Detail

destroy

public void destroy()
             throws DestroyFailedException

Specified by:

destroy in interface Destroyable

Throws:

DestroyFailedException

isDestroyed

public boolean isDestroyed()

Specified by:

isDestroyed in interface Destroyable

getSessionIdentifier

public SessionId getSessionIdentifier()

Gets this session's identifier.

Returns:

the identifier or null if this session does not have an identifier (yet).

getWriteConnectionId

public ConnectionId getWriteConnectionId()

Get connection id for outbound records.

Returns:

connection id for outbound records. null, if connection id is not used by other peer

getReadConnectionId

public ConnectionId getReadConnectionId()

Get connection id for inbound records.

Returns:

connection id for inbound records. null, if connection id is not used for other peer

Since:

2.5

getThreadLocalClusterWriteMac

public Mac getThreadLocalClusterWriteMac()

getThreadLocalClusterReadMac

public Mac getThreadLocalClusterReadMac()

getCreationTime

public long getCreationTime()

System time of session creation in milliseconds.

Returns:

session creation system time in milliseconds

See Also:

System.currentTimeMillis()

getLastHandshakeTime

public String getLastHandshakeTime()

System time tag of last handshake.

Returns:

system time in milliseconds as string of the last handshake

getHostName

public String getHostName()

Gets the (virtual) host name for the server that this session has been established for.

Returns:

the host name or null if this session has not been established for a virtual host.

See Also:

getServerNames()

setHostName

public void setHostName(String hostname)

Set the (virtual) host name for the server that this session has been established for.

Sets the setServerNames(ServerNames) accordingly.

Parameters:

hostname - the virtual host name at the peer (may be null).

getServerNames

public ServerNames getServerNames()

Gets the server names for the server that this session has been established for.

Returns:

server names, or null, if not used.

See Also:

getHostName()

setServerNames

public void setServerNames(ServerNames serverNames)

Set the server names for the server that this session has been established for.

Sets the setHostName(String) accordingly.

Parameters:

serverNames - the server names (may be null).

isSniSupported

public boolean isSniSupported()

Checks whether the peer (the server) supports the Server Name Indication extension.

Returns:

true if the server has included an empty SNI extension in its SERVER_HELLO message during handshake.

getConnectionWriteContext

public org.eclipse.californium.elements.DtlsEndpointContext getConnectionWriteContext()

getConnectionReadContext

public org.eclipse.californium.elements.DtlsEndpointContext getConnectionReadContext()

getCipherSuite

public CipherSuite getCipherSuite()

Gets the cipher and MAC algorithm to be used for this session.

The value returned is part of the pending connection state which has been negotiated with the peer. This means that it is not in effect until the pending state becomes the current state using one of the setReadState(DTLSConnectionState) or setWriteState(DTLSConnectionState) methods.

Returns:

the algorithms to be used

getWriteEpoch

public int getWriteEpoch()

Gets this session's current write epoch.

Returns:

The epoch.

getReadEpoch

public int getReadEpoch()

Gets this session's current read epoch.

Returns:

The epoch.

getSequenceNumber

public long getSequenceNumber()

Gets the smallest unused sequence number for outbound records for the current epoch.

Returns:

the next sequence number

Throws:

IllegalStateException - if the maximum sequence number for the epoch has been reached (2^48 - 1)

getSequenceNumber

public long getSequenceNumber(int epoch)

Gets the smallest unused sequence number for outbound records for a given epoch.

Parameters:

epoch - the epoch for which to get the sequence number

Returns:

the next sequence number

Throws:

IllegalStateException - if the maximum sequence number for the epoch has been reached (2^48 - 1)

getReadStateCipher

public String getReadStateCipher()

Gets the name of the current read state's cipher suite.

Returns:

the name.

getWriteStateCipher

public String getWriteStateCipher()

Gets the name of the current write state's cipher suite.

Returns:

the name.

setParameterAvailable

public void setParameterAvailable()

Set parameter available. Enables getParameter() to return the handshake parameter.

getParameter

public HandshakeParameter getParameter()

Return the handshake parameter, if set available.

Returns:

the handshake parameter, or null, if setParameterAvailable() wasn't called before.

getMaxCiphertextExpansion

public int getMaxCiphertextExpansion()

Get maximum expansion of cipher suite.

Returns:

maximum expansion of cipher suite.

Since:

2.4

See Also:

CipherSuite.getMaxCiphertextExpansion()

getMaxFragmentLength

public int getMaxFragmentLength()

Gets the maximum amount of unencrypted payload data that can be sent to this session's peer in a single DTLS record created under this session's current write state.

The value of this property serves as an upper boundary for the DTLSPlaintext.length field defined in DTLS 1.2 spec, Section 4.3.1. This means that an application can assume that any message containing at most as many bytes as indicated by this method, will be delivered to the peer in a single unfragmented IP datagram.

Returns:

the maximum length in bytes

getRecordSizeLimit

public Integer getRecordSizeLimit()

Gets the negotiated record size limit

Returns:

negotiated record size limit, or null, if not negotiated

Since:

2.4

getEffectiveFragmentLimit

public int getEffectiveFragmentLimit()

Gets effective fragment limit. Either recordSizeLimit, if received, or maxFragmentLength.

Returns:

effective fragment limit

Since:

2.4

getSignatureAndHashAlgorithm

public SignatureAndHashAlgorithm getSignatureAndHashAlgorithm()

Gets the negotiated signature and hash algorithm to be used to sign the server key exchange message.

Returns:

negotiated signature and hash algorithm

Since:

2.3

getPeer

public InetSocketAddress getPeer()

Gets the IP address and socket of this session's peer.

Returns:

The peer's address.

setPeer

public void setPeer(InetSocketAddress peer)

getRouter

public InetSocketAddress getRouter()

Get router address.

Returns:

router address. null, if no router is used.

Since:

2.5

setRouter

public void setRouter(InetSocketAddress router)

Set router address.

Parameters:

router - router address

Since:

2.5

getPeerIdentity

public Principal getPeerIdentity()

Gets the authenticated peer's identity.

Returns:

the identity or null if the peer has not been authenticated

isRecordProcessable

@Deprecated
public boolean isRecordProcessable(long epoch,
                                     long sequenceNo,
                                     boolean useWindowOnly)

Deprecated. use isRecordProcessable(long, long, int) instead

Checks whether a given record can be processed within the context of this session. This is the case if

• the record is from the same epoch as session's current read epoch
• the record has not been received before
• if marked as closed, the record's sequence number is not after the close notify's sequence number

Parameters:

epoch - the record's epoch

sequenceNo - the record's sequence number

useWindowOnly - true use only message window for filter. For message too old for the message window true is returned.

Returns:

true if the record satisfies the conditions above

Since:

2.3 support marked as closed

isRecordProcessable

public boolean isRecordProcessable(long epoch,
                          long sequenceNo,
                          int useExtendedWindow)

Checks whether a given record can be processed within the context of this session. This is the case if

• the record is from the same epoch as session's current read epoch
• the record has not been received before
• if marked as closed, the record's sequence number is not after the close notify's sequence number

Parameters:

epoch - the record's epoch

sequenceNo - the record's sequence number

useExtendedWindow - this value will be subtracted from to lower receive window boundary. A value of -1 will set that calculated value to 0. Messages between lower receive window boundary and that calculated value will pass the filter, for other messages the filter is applied.

Returns:

true if the record satisfies the conditions above

Since:

2.4

markRecordAsRead

public boolean markRecordAsRead(long epoch,
                       long sequenceNo)

Marks a record as having been received so that it can be detected as a duplicate if it is received again, e.g. if a client re-transmits the record because it runs into a timeout. The record is marked as received only, if it belongs to this session's current read epoch as indicated by getReadEpoch().

Parameters:

epoch - the record's epoch

sequenceNo - the record's sequence number

Returns:

true, if the epoch/sequenceNo is newer than the current newest. false, if not.

isMarkedAsClosed

public boolean isMarkedAsClosed()

Session is marked as close.

Returns:

true, if marked as closed, false, otherwise.

Since:

2.3

markCloseNotiy

public void markCloseNotiy(int epoch,
                  long sequenceNo)

Mark as closed. If a session is marked as closed, no records should be sent and no received newer records should be processed.

Parameters:

epoch - epoch of close notify

sequenceNo - sequence number of close notify

Since:

2.3

See Also:

isMarkedAsClosed()

getSessionTicket

public SessionTicket getSessionTicket()

Get a session ticket representing this session's current connection state.

Returns:

The ticket. Or null, if the session id is empty and doesn't support resumption.

Throws:

IllegalStateException - if this session does not have its current connection state set yet.