ddn.net.dtls.client13

DTLS 1.3 client handshake state machine (RFC 9147).

Drives the DTLS 1.3 client handshake as a resumable state machine. Adapts the TLS 1.3 handshake for datagram transports with:

DTLS record framing (13-byte header)
DTLS handshake framing (12-byte header with message_seq)
Flight-based retransmission with exponential backoff
DTLS 1.3 key schedule with "dtls13" label prefix
Encrypted handshake messages after ServerHello

Uses Tls13KeySchedule for cryptographic key derivation, DtlsTranscriptHash for transcript hashing, and Dtls13ClientKeySchedule for the "dtls13" HKDF label prefix.

var DTLS_1_3_RECORD_VERSION

class Dtls13Client Dtls13ClientKeySchedule

Types 2

classDtls13ClientKeySchedule : Tls13KeySchedule

DTLS 1.3 key schedule with "dtls13" HKDF label prefix.

Overrides hkdfExpandLabel to use "dtls13" instead of "tls13 " per RFC 9147 §5.

Fields

private HKDF hkdf13_

private size_t hashLen13_

Methods

void setCipherSuite(ushort cipherSuite)Reconfigures the hash algorithm based on the negotiated cipher suite.

ubyte[] hkdfExpandLabel(const(ubyte)[]  secret,  string label,
          const(ubyte)[]  context,  size_t length)

HKDF-Expand-Label with "dtls13" prefix for DTLS 1.3.

Constructors

this()Constructs a DTLS 1.3 key schedule.

classDtls13Client

DTLS 1.3 client handshake engine.

Drives the client side of a DTLS 1.3 handshake over a datagram transport. Uses flight-based retransmission with exponential backoff and supports the HelloRetryRequest cookie exchange.

Call handshake() repeatedly until it returns TlsProgress.DONE. Between calls, wait for socket readiness as indicated by the return value.

Fields

private DtlsTransport transport_

private DtlsTimerSink timer_

private DatagramEndpoint serverAddr_

private Dtls13ClientPhase phase_

private ushort messageSeq_

private ushort epoch_

private ulong recordSeq_

private SecureRandom rng_

private DtlsFlight pendingFlight_

private int retryCount_

private ubyte[32] clientRandom_

private ubyte[32] serverRandom_

private ubyte[] sharedSecret_

private ubyte[] receivedCookie_

private X25519PrivateKey ecdhePrivate_

private NamedGroup selectedGroup_

private string serverName_

private DtlsVersion minVersion_

private DtlsVersion maxVersion_

private string[] alpnProtocols_

private SrtpProfile[] srtpProfiles_

private string negotiatedAlpn_

private CipherSuiteId negotiatedCipher_

private DtlsVersion negotiatedVersion_

private SrtpProfile negotiatedSrtpProfile_

private bool cidEnabled_

private ubyte localCidLength_

private DtlsConnectionId localCid_

private DtlsConnectionId peerCid_

private bool cidNegotiated_

private Dtls13ClientKeySchedule keySchedule_

private DtlsTranscriptHash transcript_

private ubyte[] appTrafficHash_Transcript hash through the server Finished (RFC 8446 §7.1: application traffic secrets bind here, before the client Finished enters the transcript).

private TlsAead writeAead_

private TlsAead readAead_

private X509Certificate[] peerX509Certs_

private TlsCertificateChain peerCerts_

private TlsVerifyMode verifyMode_

private DtlsVerifyCallback verifyCallback_

private NativeTlsTrustStore trustStore_

private DtlsFragmentBuffer reassembly_

private ubyte[65536] recvBuffer_

private ubyte[] pendingDatagram_

private DtlsSessionInfo resumptionSession_

private bool resumptionAttempt_

private bool resumptionAccepted_

private TlsAead earlyDataAead_

private bool earlyDataSent_

private ulong earlyDataRecordSeq_

private ubyte[] chBody_

Methods

void setMinVersion(DtlsVersion ver) @safe pure nothrow @nogcSets the minimum DTLS version.

void setMaxVersion(DtlsVersion ver) @safe pure nothrow @nogcSets the maximum DTLS version.

void setAlpnProtocols(string[] protocols) @safe pure nothrowSets the ALPN protocols.

void setSrtpProfiles(SrtpProfile[] profiles) @safe pure nothrowSets the DTLS-SRTP profiles to negotiate (RFC 5764).

void setCidConfig(bool enabled, ubyte cidLength = DtlsCidConstants.DEFAULT_CID_LENGTH) @safe pure nothrow @nogcEnables Connection ID and sets the local CID length.

DtlsConnectionId localCid() @property @safe pure nothrow @nogcReturns: The local Connection ID (set after negotiation).

DtlsConnectionId peerCid() @property @safe pure nothrow @nogcReturns: The peer's Connection ID (set after ServerHello).

bool cidNegotiated() @property const @safe pure nothrow @nogcReturns: true if CID was negotiated.

void setResumptionSession(scope ref const DtlsSessionInfo session) @safe pure nothrowSets the session to resume.

bool resumptionAccepted() @property const @safe pure nothrow @nogcReturns: true if resumption was attempted and accepted.

bool resumptionAttempt() @property const @safe pure nothrow @nogcReturns: true if a resumption attempt will be made.

bool earlyDataSent() @property const @safe pure nothrow @nogcReturns: true if early data has been sent.

void initEarlyDataKeys()Initializes early traffic keys for 0-RTT.

size_t writeEarlyData(const(ubyte)[] data)Writes early data (0-RTT) to the server.

void setVerifyMode(TlsVerifyMode mode) @safe pure nothrow @nogcSets the certificate verification mode.

void setVerifyCallback(DtlsVerifyCallback callback) @safe pure nothrowSets a custom certificate verification callback.

void setTrustStore(NativeTlsTrustStore trustStore) @safe pure nothrowSets the trust store for certificate chain validation.

TlsProgress handshake() @trustedPerforms or continues the DTLS 1.3 client handshake.

ubyte[] buildClientHello(const(ubyte)[] cookie)Builds a DTLS 1.3 ClientHello handshake message.

bool processServerHello(const(ubyte)[] datagram)Process a datagram containing a ServerHello.

void parseServerHello(const(ubyte)[] body)Parse a ServerHello message body.

void processServerHelloExtensions(const(ubyte)[] extData)Process extensions from a ServerHello.

bool processHelloRetry(const(ubyte)[] datagram)Process a datagram that may contain a HelloRetryRequest.

const(ubyte)[] extractHelloRetryCookie(const(ubyte)[] body)Extract the cookie from a HelloRetryRequest body.

bool processEncryptedFlight(const(ubyte)[] datagram)Process an encrypted flight of handshake messages.

ubyte[] decryptRecordPayload(const(ubyte)[] payload, DtlsRecordHeader header)Decrypt a record payload using the read AEAD.

bool processHandshakePayload(const(ubyte)[] payload)Process a handshake payload from an encrypted record.

bool dispatchHandshakeType(HandshakeType msgType, const(ubyte)[] body)Dispatch a complete handshake message to the appropriate handler.

void processEncryptedExtensions(const(ubyte)[] body)Process an EncryptedExtensions message body.

void processCertificate(const(ubyte)[] body)Process a Certificate message body.

private void verifyPeerCertificates()Verify the peer's certificate chain against the trust store.

void processCertificateVerify(const(ubyte)[] body)Process a CertificateVerify message body.

void performKeyExchange(NamedGroup group, const(ubyte)[] peerPubKey)Perform ECDHE key exchange.

void deriveHandshakeKeys()Derives handshake traffic keys from the shared secret.

void deriveAppKeys()Derives application traffic keys.

size_t cipherKeyLength(CipherSuiteId cs) static @safe pure nothrow @nogcReturns the AEAD key length for the given cipher suite.

void processServerFinished(const(ubyte)[] body)Process a server Finished message body.

ubyte[] buildClientFinished()Builds and encrypts a client Finished message.

ubyte[] wrapHandshakeMessage(HandshakeType msgType, const(ubyte)[] body)Wraps a handshake message body in a DTLS handshake header.

ubyte[] wrapInRecord(ContentType contentType, const(ubyte)[] payload)Wraps a handshake message in a DTLS record.

ubyte[] buildDtlsRecord(ContentType contentType, const(ubyte)[] payload)Builds a complete DTLS record with 13-byte header.

ubyte[] encryptRecord(ContentType contentType, const(ubyte)[] plaintext)Encrypts a record payload using the current write AEAD.

const(ubyte)[] receiveDatagram()Receive a single datagram from the transport.

void feedDatagram(const(ubyte)[] data) @trustedFeed a received datagram for processing.

void sendDatagram(const(ubyte)[] data)Send a datagram via the transport.

void sendFlight(ubyte[][] records)Send a flight of records as one or more datagrams.

void scheduleRetransmit()Schedule retransmission timer for the current flight.

void retransmitFlight()Retransmit the pending flight.

Dtls13ClientPhase phase() @property const @safe pure nothrow @nogcReturns: The current handshake phase.

CipherSuiteId negotiatedCipher() @property const @safe pure nothrow @nogcReturns: The negotiated cipher suite.

DtlsVersion negotiatedVersion() @property const @safe pure nothrow @nogcReturns: The negotiated DTLS version.

string alpnProtocol() @property const @safe pure nothrowReturns: The negotiated ALPN protocol.

TlsCertificateChain peerCertificates() @propertyReturns: The peer's certificate chain.

ushort epoch() @property const @safe pure nothrow @nogcReturns: The current epoch.

SrtpProfile negotiatedSrtpProfile() @property const @safe pure nothrow @nogcReturns: The negotiated DTLS-SRTP profile (`SrtpProfile.init` when SRTP was not negotiated).

ubyte[] srtpMasterSecret() @property @trusted

ubyte[] srtpClientRandom() @property @safe pure nothrow @nogc

ubyte[] srtpServerRandom() @property @safe pure nothrow @nogc

TlsAead writeAead() @propertyReturns: The write AEAD cipher (after key derivation).

TlsAead readAead() @propertyReturns: The read AEAD cipher (after key derivation).

Constructors

this(DtlsTransport transport,  DtlsTimerSink timer,
          DatagramEndpoint serverAddr,  string serverName)

Constructs a DTLS 1.3 client handshake engine.

Variables 1

enumvarDTLS_1_3_RECORD_VERSION = [0xFE, 0xFD]

DTLS 1.3 record version used on the wire.

DTLS 1.3 uses the same record layer version as DTLS 1.2 (0xFEFD) for backwards compatibility per RFC 9147.