ddn.net.dtls.engine

DTLS engine for client and server roles.

Provides the main DtlsEngine class that manages DTLS connections over a datagram transport. Supports both client and server modes, multiple concurrent peers, and configurable timeouts.

The engine handles:

DTLS handshake state machine
Peer connection tracking
Retransmission timers
Idle peer pruning
MTU configuration

class NativeDtlsEngine

Types 1

classNativeDtlsEngine : DtlsEngine

Main DTLS engine for client and server roles.

The engine manages DTLS connections over a single datagram socket. In server mode, it can handle multiple peers simultaneously. In client mode, it connects to a single server.

Thread safety: NOT thread-safe. All calls must be serialized.

Example (client):

auto engine = new NativeDtlsEngine(transport, timer, "example.com");
engine.setMinVersion(DtlsVersion.DTLS_1_2);
while (engine.handshake() != TlsProgress.DONE) {
  // poll and handle I/O
}

Example (server):

auto engine = new NativeDtlsEngine(transport, timer);
engine.setCertificateChain(certs);
engine.setPrivateKey(key);
// Process incoming datagrams in event loop

Fields

private ubyte[2] DTLS_RECORD_VERSION

DtlsTransport transport_

DtlsTimerSink timer_

bool isServer_

string serverName_

DatagramEndpoint serverAddr_

Dtls12Client client12_

Dtls13Client client13_

bool handshakeStarted_

bool useDtls13_

DtlsPeerState[DatagramEndpoint] peers_

size_t maxPeers_

size_t maxHandshakingPeers_

Duration handshakeTimeout_

Duration idleTimeout_

void delegate(DatagramEndpoint, DtlsEvictReason) @safe onPeerEvicted_

DtlsVersion minVersion_

DtlsVersion maxVersion_

size_t mtu_

string[] alpnProtocols_

const(ubyte)[][] certChainDer_

string privateKeyPem_

NativeTlsTrustStore trustStore_

TlsVerifyMode verifyMode_

DtlsVerifyCallback verifyCallback_

ubyte[] cookieSecret_

DtlsPmtudEngine pmtudEngine_

PmtudPeerState[DatagramEndpoint] pmtudStates_

DtlsMtuChangedCallback onMtuChanged_

DtlsCidManager cidManager_

DtlsPeerMigratedCallback onPeerMigrated_

SrtpProfile[] srtpProfiles_

bool sessionResumptionEnabled_

Duration sessionTicketLifetime_

size_t maxEarlyDataSize_

EarlyDataReplayProtection earlyDataReplayMode_

Duration earlyDataTimeWindow_

DtlsSessionCallback onSessionTicket_

DtlsEarlyDataCallback onEarlyData_

DtlsSessionInfo resumeSession_

bool hasResumeSession_

DtlsTicketKeyManager ticketKeyMgr_

DtlsReplayCache replayCache_

Methods

DtlsCidManager cidManager() @safe pure nothrow @nogcReturns: The CID manager (package-internal access for NativeDtlsPeer).

void setCertificateChain(const(ubyte[])[] derCerts) @safeSet the certificate chain for authentication.

void setPrivateKey(string pemKey) @safe pure nothrowSet the private key for authentication.

void setMinVersion(DtlsVersion ver) @safe pure nothrow @nogcSet the minimum DTLS version to accept.

void setMaxVersion(DtlsVersion ver) @safe pure nothrow @nogcSet the maximum DTLS version to offer.

void setMtu(size_t mtu) @safe pure nothrow @nogcSet the path MTU for datagram fragmentation.

void setAlpnProtocols(string[] protocols) @safe pure nothrowSet the ALPN protocol list.

void setTrustStore(TlsTrustStore trustStore) @safeSets the trust store for certificate verification.

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

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

void setServerAddress(DatagramEndpoint addr) @safe pure nothrow @nogcSets the target server address for client mode.

TlsProgress handshake() @safePerform or continue the DTLS handshake.

TlsProgress processDatagram(const(ubyte)[] data, DatagramEndpoint from) @safeProcess an incoming datagram.

TlsProgress checkTimers() @safeCheck and fire any pending retransmission timers.

TlsProgress flush() @safeFlush any pending outgoing data.

void enablePmtuDiscovery(bool enable) @safe

size_t getEffectiveMtu(DatagramEndpoint peer) @safe

void setOnMtuChanged(DtlsMtuChangedCallback callback) @safe

void enableConnectionId(bool enable) @safe

void setConnectionIdLength(ubyte length) @safe

void setOnPeerMigrated(DtlsPeerMigratedCallback callback) @safe

void enableSessionResumption(bool enable) @safe

void setSessionTicketLifetime(Duration lifetime) @safe

void setMaxEarlyDataSize(size_t bytes) @safe

void setEarlyDataReplayProtection(EarlyDataReplayProtection mode) @safe

void setEarlyDataTimeWindow(Duration window) @safe

void setOnSessionTicket(DtlsSessionCallback callback) @safe

void setOnEarlyData(DtlsEarlyDataCallback callback) @safe

void resumeWithSession(scope ref const DtlsSessionInfo session) @safe

void setSrtpProfiles(const(SrtpProfile[]) profiles) @safe

DtlsPeer getPeer(DatagramEndpoint addr) @safeGet a peer by address.

DtlsPeer[] peers() @safeGet all active peers.

void setHandshakeTimeout(Duration timeout) @safe pure nothrow @nogcSet the handshake timeout.

void setIdleTimeout(Duration timeout) @safe pure nothrow @nogcSet the idle timeout.

void setMaxPeers(size_t limit) @safe pure nothrow @nogcSet the maximum number of peers.

void setMaxHandshakingPeers(size_t limit) @safe pure nothrow @nogcSet the maximum number of peers in handshake state.

size_t peerCount() const @safe pure nothrow @nogcGet the current number of peers.

void evictPeer(DatagramEndpoint addr) @safeEvict a peer by address.

size_t pruneIdlePeers(Duration idleTimeout) @safePrune idle peers.

void setOnPeerEvicted(DtlsEvictCallback callback) @safe pure nothrow @nogcSet the peer eviction callback.

TlsResult readFromPeer(DtlsPeerState state, ubyte[] buffer) @safeRead decrypted data from a peer.

TlsResult writeToPeer(DtlsPeerState state, const(ubyte)[] data) @safeWrite data to a peer.

TlsProgress shutdownPeer(DtlsPeerState state) @safeShutdown a peer connection.

DtlsVersion negotiatedVersion(const DtlsPeerState state) const @safeGet the negotiated DTLS version for a peer.

string cipherSuite(const DtlsPeerState state) const @safeGet the negotiated cipher suite for a peer.

string alpnProtocol(const DtlsPeerState state) const @safeGet the negotiated ALPN protocol for a peer.

bool isPeerConnected(const DtlsPeerState state) const @safeCheck if a peer's handshake is complete.

TlsCertificateChain peerCertificates(DtlsPeerState state) @safeGet the peer's certificate chain.

bool isServer() @property const @safe pure nothrow @nogcCheck if this is a server engine.

string serverName() @property const @safe pure nothrow @nogcGet the server name (SNI) for client engines.

size_t mtu() @property const @safe pure nothrow @nogcGet the configured MTU.

DtlsVersion minVersion() @property const @safe pure nothrow @nogcGet the minimum DTLS version.

DtlsVersion maxVersion() @property const @safe pure nothrow @nogcGet the maximum DTLS version.

DtlsTransport transport() @property @safe pure nothrow @nogcGet the transport.

private

ubyte[] encryptAppData(DtlsPeerState state,  TlsAead aead,
          const(ubyte)[]  plaintext)

Encrypt application data into a DTLS record.

private

ubyte[] encryptAppData12(DtlsPeerState state,  TlsAead aead,
          const(ubyte)[]  plaintext)

Encrypt application data using DTLS 1.2 format (explicit nonce).

private

ubyte[] encryptAppData13(DtlsPeerState state,  TlsAead aead,
          const(ubyte)[]  plaintext)

Encrypt application data using DTLS 1.3 format (XOR nonce).

private

ubyte[] decryptAppDataRecord(DtlsPeerState state,
          const(ubyte)[]  payload,  DtlsRecordHeader header)

Decrypt an APPLICATION_DATA record payload.

private

ubyte[] decryptAppData12(TlsAead aead,  const(ubyte)[]  payload,
          DtlsRecordHeader header)

Decrypt a DTLS 1.2 APPLICATION_DATA record (explicit nonce).

private

ubyte[] decryptAppData13(TlsAead aead,  const(ubyte)[]  payload,
          DtlsRecordHeader header)

Decrypt a DTLS 1.3 APPLICATION_DATA record (XOR nonce).

private

ubyte[] buildDtlsRecord(ContentType type,  ushort  epoch,
          ulong  seq,  const(ubyte)[]  payload)

@safe pure nothrowBuild a complete DTLS record with the given parameters.

TlsProgress sendAlert(DtlsPeerState state,  AlertLevel level,
          AlertDescription description)

@safeBuild and send a DTLS alert record to a peer.

private

ubyte[] encryptAlertRecord(DtlsPeerState state,  TlsAead aead,
          const(ubyte)[]  alertPayload)

Encrypt an alert record payload using the peer's write AEAD.

private

TlsProgress processAppDataDatagram(DtlsPeerState state,
          DatagramEndpoint from,  const(ubyte)[]  data)

@safeProcess a datagram containing APPLICATION_DATA for a connected peer.

private

void handleAlertRecord(DtlsPeerState state,
          ref  DtlsRecord rec)

@safeHandle a received ALERT record for a connected peer.

private string cipherSuiteName(CipherSuiteId id) @safe pure nothrow Converts a CipherSuiteId to its IANA name string. Params: id = The cipher suite identifier. Returns: * The IANA cipher suite name.

Constructors

this(DtlsTransport transport, DtlsTimerSink timer, string serverName)Create a client engine.

this(DtlsTransport transport, DtlsTimerSink timer)Create a server engine.