ddn.net.dtls.types

DTLS protocol constants and types.

Defines DTLS-specific record headers, handshake headers, version constants, state machine phases, and helper functions for RFC 6347 (DTLS 1.2) and RFC 9147 (DTLS 1.3).

var DTLS_HANDSHAKE_HEADER_SIZE DTLS_RECORD_HEADER_SIZE
enum Dtls12ClientPhase Dtls12ServerPhase Dtls13ClientPhase Dtls13Label Dtls13ServerPhase
struct DtlsHandshakeHeader DtlsRecordHeader
fn readSeq48 readUint24 writeSeq48 writeUint24

Types 7

structDtlsRecordHeader

DTLS record layer header.

The DTLS record header is 13 bytes on the wire:

  • ContentType (1 byte)
  • Protocol version (2 bytes)
  • Epoch (2 bytes)
  • Sequence number (6 bytes, 48-bit)
  • Length (2 bytes)
Fields
ContentType typeContent type of the record.
ubyte[2] protocolVersionProtocol version (2 bytes, big-endian on wire).
ushort epochEpoch number for key material.
ulong sequenceNumber48-bit sequence number (stored as ulong, only low 48 bits used).
ushort lengthLength of the record payload in bytes.
Methods
Nullable!DtlsRecordHeader parse(const(ubyte)[] data) @safe pure nothrow @nogcParses a DTLS record header from wire format.
ubyte[DTLS_RECORD_HEADER_SIZE] serialize() const @safe pure nothrow @nogcSerializes the DTLS record header to wire format.
structDtlsHandshakeHeader

DTLS handshake message header.

The DTLS handshake header is 12 bytes on the wire:

  • HandshakeType (1 byte)
  • Total message length (3 bytes, 24-bit)
  • Message sequence (2 bytes)
  • Fragment offset (3 bytes, 24-bit)
  • Fragment length (3 bytes, 24-bit)
Fields
HandshakeType msgTypeType of handshake message.
ubyte[3] lengthTotal length of the handshake message (24-bit, stored as ubyte[3]).
ushort messageSeqMessage sequence number for ordering across fragments.
ubyte[3] fragmentOffsetOffset of this fragment within the complete message (24-bit).
ubyte[3] fragmentLengthLength of this fragment (24-bit).
Methods
uint totalLength() const @safe pure nothrow @nogcGets the total message length as a uint.
uint fragOffset() const @safe pure nothrow @nogcGets the fragment offset as a uint.
uint fragLength() const @safe pure nothrow @nogcGets the fragment length as a uint.
Nullable!DtlsHandshakeHeader parse(const(ubyte)[] data) @safe pure nothrow @nogcParses a DTLS handshake header from wire format.
ubyte[DTLS_HANDSHAKE_HEADER_SIZE] serialize() const @safe pure nothrow @nogcSerializes the DTLS handshake header to wire format.
DtlsHandshakeHeader create( HandshakeType msgType, uint totalLen, ushort msgSeq, uint fragOff, uint fragLen ) @safe pure nothrow @nogcCreates a handshake header with the given parameters.
enumDtls12ClientPhase

DTLS 1.2 client handshake state machine phases.

Tracks the progress of a DTLS 1.2 handshake from the client's perspective.

NOT_STARTEDHandshake not yet started.
SEND_CLIENT_HELLOSending initial ClientHello.
WAIT_CLIENT_HELLO_ACKWaiting for acknowledgment of ClientHello.
RECV_HELLO_VERIFYReceived HelloVerifyRequest, need to retry with cookie.
SEND_CLIENT_HELLO_RETRYSending ClientHello with cookie.
WAIT_RETRY_ACKWaiting for acknowledgment of retried ClientHello.
RECV_SERVER_HELLOReceiving ServerHello.
RECV_CERTIFICATEReceiving server Certificate.
RECV_SERVER_KEY_EXCHANGEReceiving ServerKeyExchange.
RECV_CERTIFICATE_REQUESTReceiving CertificateRequest (optional).
RECV_SERVER_HELLO_DONEReceiving ServerHelloDone.
SEND_CLIENT_CERTIFICATESending client Certificate (if requested).
SEND_CLIENT_KEY_EXCHANGESending ClientKeyExchange.
SEND_CERTIFICATE_VERIFYSending CertificateVerify (if client cert sent).
SEND_CHANGE_CIPHER_SPECSending ChangeCipherSpec.
SEND_CLIENT_FINISHEDSending client Finished.
WAIT_FINISHED_ACKWaiting for acknowledgment of Finished.
RECV_CHANGE_CIPHER_SPECReceiving server ChangeCipherSpec.
RECV_SERVER_FINISHEDReceiving server Finished.
DONEHandshake complete.
enumDtls12ServerPhase

DTLS 1.2 server handshake state machine phases.

Tracks the progress of a DTLS 1.2 handshake from the server's perspective.

NOT_STARTEDHandshake not yet started.
RECV_CLIENT_HELLOWaiting for initial ClientHello.
SEND_HELLO_VERIFYSending HelloVerifyRequest (cookie exchange).
WAIT_HELLO_VERIFY_ACKWaiting for HelloVerifyRequest acknowledgment.
RECV_CLIENT_HELLO_RETRYReceiving ClientHello with cookie.
SEND_SERVER_HELLOSending ServerHello.
SEND_CERTIFICATESending server Certificate.
SEND_SERVER_KEY_EXCHANGESending ServerKeyExchange.
SEND_CERTIFICATE_REQUESTSending CertificateRequest (optional).
SEND_SERVER_HELLO_DONESending ServerHelloDone.
WAIT_SERVER_FLIGHT_ACKWaiting for server flight acknowledgment.
RECV_CLIENT_CERTIFICATEReceiving client Certificate (if requested).
RECV_CLIENT_KEY_EXCHANGEReceiving ClientKeyExchange.
RECV_CERTIFICATE_VERIFYReceiving CertificateVerify (if client cert received).
RECV_CHANGE_CIPHER_SPECReceiving client ChangeCipherSpec.
RECV_CLIENT_FINISHEDReceiving client Finished.
SEND_CHANGE_CIPHER_SPECSending server ChangeCipherSpec.
SEND_SERVER_FINISHEDSending server Finished.
WAIT_SERVER_FINISHED_ACKWaiting for server Finished acknowledgment.
DONEHandshake complete.
enumDtls13ClientPhase

DTLS 1.3 client handshake state machine phases.

Tracks the progress of a DTLS 1.3 handshake from the client's perspective. DTLS 1.3 (RFC 9147) is closer to TLS 1.3 but with DTLS-specific framing.

NOT_STARTEDHandshake not yet started.
SEND_CLIENT_HELLOSending initial ClientHello.
WAIT_CLIENT_HELLO_ACKWaiting for acknowledgment of ClientHello.
RECV_HELLO_RETRYReceived HelloRetryRequest, need to retry with cookie.
SEND_CLIENT_HELLO_RETRYSending ClientHello with cookie.
WAIT_RETRY_ACKWaiting for acknowledgment of retried ClientHello.
RECV_SERVER_HELLOReceiving ServerHello.
DERIVE_HANDSHAKE_KEYSDeriving handshake traffic keys.
RECV_ENCRYPTED_EXTENSIONSReceiving EncryptedExtensions.
RECV_CERTIFICATEReceiving server Certificate.
RECV_CERTIFICATE_VERIFYReceiving CertificateVerify.
RECV_SERVER_FINISHEDReceiving server Finished.
SEND_CLIENT_FINISHEDSending client Finished.
WAIT_FINISHED_ACKWaiting for Finished acknowledgment.
DERIVE_APP_KEYSDeriving application traffic keys.
DONEHandshake complete.
enumDtls13ServerPhase

DTLS 1.3 server handshake state machine phases.

Tracks the progress of a DTLS 1.3 handshake from the server's perspective.

NOT_STARTEDHandshake not yet started.
RECV_CLIENT_HELLOWaiting for initial ClientHello.
SEND_HELLO_RETRYSending HelloRetryRequest (cookie exchange).
WAIT_HELLO_RETRY_ACKWaiting for HelloRetryRequest acknowledgment.
RECV_CLIENT_HELLO_RETRYReceiving ClientHello with cookie.
SEND_SERVER_HELLOSending ServerHello.
SEND_ENCRYPTED_EXTENSIONSSending EncryptedExtensions.
SEND_CERTIFICATESending server Certificate.
SEND_CERTIFICATE_VERIFYSending CertificateVerify.
SEND_SERVER_FINISHEDSending server Finished.
WAIT_SERVER_FLIGHT_ACKWaiting for server flight acknowledgment.
RECV_CLIENT_FINISHEDReceiving client Finished.
DERIVE_APP_KEYSDeriving application traffic keys.
DONEHandshake complete.
enumDtls13Label : string

DTLS 1.3 HKDF label strings (RFC 9147 §5).

DTLS 1.3 uses different HKDF labels than TLS 1.3, prefixed with "dtls13" instead of "tls13".

CLIENT_HANDSHAKE_TRAFFIC = "dtls13 c hs traffic"Client handshake traffic secret label.
SERVER_HANDSHAKE_TRAFFIC = "dtls13 s hs traffic"Server handshake traffic secret label.
CLIENT_APPLICATION_TRAFFIC = "dtls13 c ap traffic"Client application traffic secret label.
SERVER_APPLICATION_TRAFFIC = "dtls13 s ap traffic"Server application traffic secret label.
EXPORTER_MASTER = "dtls13 exp master"Exporter master secret label.
RESUMPTION = "dtls13 res master"Resumption master secret label.
DERIVED = "dtls13 derived"Derived secret label.
FINISHED = "dtls13 finished"Finished key label.

Functions 4

fnuint readUint24(const(ubyte)[] data) @safe pure nothrow @nogcReads a 24-bit unsigned integer from 3 bytes (big-endian).
fnvoid writeUint24(ubyte[] data, uint value) @safe pure nothrow @nogcWrites a 24-bit unsigned integer to 3 bytes (big-endian).
fnulong readSeq48(const(ubyte)[] data) @safe pure nothrow @nogcReads a 48-bit sequence number from 6 bytes (big-endian).
fnvoid writeSeq48(ubyte[] data, ulong seq) @safe pure nothrow @nogcWrites a 48-bit sequence number to 6 bytes (big-endian).

Variables 2

enumvarDTLS_RECORD_HEADER_SIZE = 13

Size of the DTLS record header in bytes.

enumvarDTLS_HANDSHAKE_HEADER_SIZE = 12

Size of the DTLS handshake header in bytes.