org.eclipse.californium.scandium.dtls

Class Record

java.lang.Object

org.eclipse.californium.scandium.dtls.Record

public class Record
extends Object

An object representation of the DTLS Record layer data structure(s).

The Datagram Transport Layer Security specification defines a set of data structures at the Record layer containing the data to be exchanged with peers.

This class is used to transform these data structures from their binary encoding as received from the network interface to their object representation and vice versa.

Field Summary

Fields

Modifier and Type	Field and Description
static int	CID_LENGTH_BITS
static int	CONTENT_TYPE_BITS
static int	EPOCH_BITS
static int	LENGTH_BITS
static int	RECORD_HEADER_BITS
static int	RECORD_HEADER_BYTES Bytes for dtls record header.
static int	SEQUENCE_NUMBER_BITS
static int	VERSION_BITS

Constructor Summary

Constructors

Constructor and Description
Record(ContentType type, int epoch, long sequenceNumber, DTLSMessage fragment, DTLSSession session, boolean cid, int pad) Creates an outbound record containing a DTLSMessage as its payload.
Record(ContentType type, ProtocolVersion version, long sequenceNumber, DTLSMessage fragment, InetSocketAddress peerAddress) Creates an outbound record representing a DTLSMessage as its payload.

Method Summary

Methods

Modifier and Type	Method and Description
void	applySession(DTLSSession session) Apply session for incoming records and decrypt fragment.
static List<Record>	fromByteArray(byte[] byteArray, InetSocketAddress peerAddress, ConnectionIdGenerator cidGenerator, long receiveNanos) Deprecated. use fromReader(DatagramReader, InetSocketAddress, InetSocketAddress, ConnectionIdGenerator, long) instead.
static List<Record>	fromReader(org.eclipse.californium.elements.util.DatagramReader reader, InetSocketAddress peerAddress, InetSocketAddress router, ConnectionIdGenerator cidGenerator, long receiveNanos) Parses a sequence of DTLSCiphertext structures into Record instances.
protected byte[]	generateAdditionalData(int length) See RFC 5246:
protected byte[]	generateExplicitNonce() Generates the explicit part of the nonce to be used with the AEAD Cipher.
ConnectionId	getConnectionId() Get connection id.
int	getEpoch()
DTLSMessage	getFragment() Gets the object representation of this record's DTLSPlaintext.fragment.
byte[]	getFragmentBytes() Get fragment payload as byte array.
int	getFragmentLength() Gets the length of the fragment contained in this record in bytes.
InetSocketAddress	getPeerAddress() Get peer address.
long	getReceiveNanos() Get uptime nanoseconds receiving this record.
InetSocketAddress	getRouter() Get router address.
long	getSequenceNumber()
ContentType	getType()
ProtocolVersion	getVersion()
boolean	isDecoded() Check, if record is decoded.
boolean	isFollowUpRecord() Get follow-up-record marker for received record.
boolean	isNewClientHello() Check, if record is CLIENT_HELLO of epoch 0.
static ConnectionId	readConnectionIdFromReader(org.eclipse.californium.elements.util.DatagramReader reader, ConnectionIdGenerator cidGenerator) Read the connection id.
int	size()
byte[]	toByteArray() Encodes this record into its corresponding DTLSCiphertext structure.
String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

CONTENT_TYPE_BITS

public static final int CONTENT_TYPE_BITS

See Also:

Constant Field Values

VERSION_BITS

public static final int VERSION_BITS

See Also:

Constant Field Values

EPOCH_BITS

public static final int EPOCH_BITS

See Also:

Constant Field Values

SEQUENCE_NUMBER_BITS

public static final int SEQUENCE_NUMBER_BITS

See Also:

Constant Field Values

LENGTH_BITS

public static final int LENGTH_BITS

See Also:

Constant Field Values

CID_LENGTH_BITS

public static final int CID_LENGTH_BITS

See Also:

Constant Field Values

RECORD_HEADER_BITS

public static final int RECORD_HEADER_BITS

See Also:

Constant Field Values

RECORD_HEADER_BYTES

public static final int RECORD_HEADER_BYTES

Bytes for dtls record header.

Since:

2.4

See Also:

Constant Field Values

Constructor Detail

Record

public Record(ContentType type,
      int epoch,
      long sequenceNumber,
      DTLSMessage fragment,
      DTLSSession session,
      boolean cid,
      int pad)
       throws GeneralSecurityException

Creates an outbound record containing a DTLSMessage as its payload. The given fragment is encoded into its binary representation and encrypted according to the given session's current write state. In order to create a Record containing an un-encrypted fragment, use the Record(ContentType, ProtocolVersion, long, DTLSMessage, InetSocketAddress) constructor.

Parameters:

type - the type of the record's payload. The new record type ContentType.TLS12_CID is not supported directly. Provide the inner type and true for the parameter cid

epoch - the epoch

sequenceNumber - the 48-bit sequence number

fragment - the payload

session - the session to determine the current write state from

cid - if true use write connection id from provided session. Otherwise use null as connection id

pad - if cid is enabled, pad could be used to add that number of zero-bytes as padding to the payload to obfuscate the payload length.

Throws:

IllegalArgumentException - if the given sequence number is longer than 48 bits or less than 0, the given epoch is less than 0, the provided type is not supported or the fragment could not be converted into bytes. Or the provided session doesn't have a peer address.

NullPointerException - if the given type, fragment or session is null.

GeneralSecurityException - if the message could not be encrypted, e.g. because the JVM does not support the negotiated cipher suite's cipher algorithm

Record

public Record(ContentType type,
      ProtocolVersion version,
      long sequenceNumber,
      DTLSMessage fragment,
      InetSocketAddress peerAddress)

Creates an outbound record representing a DTLSMessage as its payload. The payload will be sent un-encrypted using epoch 0.

Parameters:

type - the type of the record's payload. The new record type ContentType.TLS12_CID is not supported.

version - the version

sequenceNumber - the 48-bit sequence number

fragment - the payload to send

peerAddress - the IP address and port of the peer this record should be sent to

Throws:

IllegalArgumentException - if the given sequence number is longer than 48 bits or less than 0, the given epoch is less than 0, or the fragment could not be converted into bytes.

NullPointerException - if the given type, fragment or peer address is null.

Method Detail

toByteArray

public byte[] toByteArray()

Encodes this record into its corresponding DTLSCiphertext structure.

Returns:

a byte array containing the DTLSCiphertext structure

size

public int size()

fromByteArray

@Deprecated
public static List<Record> fromByteArray(byte[] byteArray,
                                    InetSocketAddress peerAddress,
                                    ConnectionIdGenerator cidGenerator,
                                    long receiveNanos)

Deprecated. use fromReader(DatagramReader, InetSocketAddress, InetSocketAddress, ConnectionIdGenerator, long) instead.

Parses a sequence of DTLSCiphertext structures into Record instances. The binary representation is expected to comply with the DTLSCiphertext structure defined in RFC6347, Section 4.3.1.

Parameters:

byteArray - the raw binary representation containing one or more DTLSCiphertext structures

peerAddress - the IP address and port of the peer from which the bytes have been received

cidGenerator - the connection id generator. May be null.

receiveNanos - uptime nanoseconds of receiving this record

Returns:

the Record instances

Throws:

NullPointerException - if either one of the byte array or peer address is null

fromReader

public static List<Record> fromReader(org.eclipse.californium.elements.util.DatagramReader reader,
                      InetSocketAddress peerAddress,
                      InetSocketAddress router,
                      ConnectionIdGenerator cidGenerator,
                      long receiveNanos)

Parses a sequence of DTLSCiphertext structures into Record instances. The binary representation is expected to comply with the DTLSCiphertext structure defined in RFC6347, Section 4.3.1.

Parameters:

reader - a reader with the raw binary representation containing one or more DTLSCiphertext structures

peerAddress - the IP address and port of the peer from which the bytes have been received

router - router address, null, if not used.

cidGenerator - the connection id generator. May be null.

receiveNanos - uptime nanoseconds of receiving this record

Returns:

the Record instances

Throws:

NullPointerException - if either one of the reader or peer address is null

Since:

2.4

readConnectionIdFromReader

public static ConnectionId readConnectionIdFromReader(org.eclipse.californium.elements.util.DatagramReader reader,
                                      ConnectionIdGenerator cidGenerator)

Read the connection id.

Parameters:

reader - reader with the raw received record.

cidGenerator - cid generator.

Returns:

connection, or null, if not available.

Throws:

NullPointerException - if either reader or cid generator is null.

IllegalArgumentException - if the cid generator doesn't use cid or the record is too short.

Since:

2.5

generateExplicitNonce

protected byte[] generateExplicitNonce()

Generates the explicit part of the nonce to be used with the AEAD Cipher. RFC6655, Section 3 encourages the use of the session's 16bit epoch value concatenated with a monotonically increasing 48bit sequence number as the explicit nonce.

Returns:

the 64-bit explicit nonce constructed from the epoch and sequence number

generateAdditionalData

protected byte[] generateAdditionalData(int length)

See RFC 5246:

 additional_data = seq_num + TLSCompressed.type +
                   TLSCompressed.version + TLSCompressed.length;
 

where "+" denotes concatenation. For the new tls_cid record, currently defined in Draft dtls-connection-id this is extended by the conneciton id:

 additional_data = seq_num + TLSCompressed.type + TLSCompressed.version + 
                   connection_id + connection_id_length + TLSCompressed.length;
 

with the connection_id_length encoded in one uint8 byte.

Parameters:

length - length of the data to be authenticated

Returns:

the additional authentication data.

isFollowUpRecord

public boolean isFollowUpRecord()

Get follow-up-record marker for received record.

Returns:

true, if record follows up an other record in the same datagram, false, otherwise.

Since:

2.4

isNewClientHello

public boolean isNewClientHello()

Check, if record is CLIENT_HELLO of epoch 0. This is important to detect a new association according RFC6347, section 4.2.8.

Returns:

true, if record contains CLIENT_HELLO of epoch 0, false otherwise.

isDecoded

public boolean isDecoded()

Check, if record is decoded.

Returns:

true, if records is decode, false, otherwise.

Since:

2.4

getType

public ContentType getType()

getVersion

public ProtocolVersion getVersion()

getEpoch

public int getEpoch()

getSequenceNumber

public long getSequenceNumber()

getFragmentLength

public int getFragmentLength()

Gets the length of the fragment contained in this record in bytes.

The overall length of this record's DTLSCiphertext representation is thus Record.length + 13 (DTLS record headers) bytes.

Returns:

the fragment length excluding record headers

applySession

public void applySession(DTLSSession session)
                  throws GeneralSecurityException,
                         HandshakeException

Apply session for incoming records and decrypt fragment.

Parameters:

session - session to apply. If null is provided, DTLSConnectionState.NULL is used for de-cryption.

Throws:

GeneralSecurityException - if de-cryption fails, e.g. because the JVM does not support the negotiated cipher algorithm, or decoding of the inner plain text of ContentType.TLS12_CID fails.

HandshakeException - if the TLSPlaintext.fragment could not be parsed into a valid handshake message

IllegalArgumentException - if session was already applied.

getPeerAddress

public InetSocketAddress getPeerAddress()

Get peer address.

Returns:

peer address

getRouter

public InetSocketAddress getRouter()

Get router address.

Returns:

router address. null, if no router is used.

getConnectionId

public ConnectionId getConnectionId()

Get connection id.

Returns:

connection id

getReceiveNanos

public long getReceiveNanos()

Get uptime nanoseconds receiving this record.

Returns:

uptime nanoseconds, or 0, if records wasn't received.

getFragmentBytes

public byte[] getFragmentBytes()

Get fragment payload as byte array.

Returns:

fragments byte array.

getFragment

public DTLSMessage getFragment()

Gets the object representation of this record's DTLSPlaintext.fragment. For incoming records, the fragment is only available after the session of the epoch is applySession(DTLSSession).

Returns:

the plaintext fragment

Throws:

IllegalStateException - if plaint-text fragment is not available

toString

public String toString()

Overrides:

toString in class Object