DTLS

The node:dtls module provides an implementation of the Datagram Transport Layer Security (DTLS) protocol over UDP. DTLS provides TLS-equivalent security guarantees for datagram-based communication, including confidentiality, integrity, and authentication.

To use this module, it must be enabled at build time with the --experimental-dtls configure flag and at runtime with the --experimental-dtls CLI flag.

node --experimental-dtls app.mjs

import { listen, connect } from 'node:dtls';

const { listen, connect } = require('node:dtls');

When using the Permission Model, the --allow-net flag must be passed to allow DTLS network operations. Without it, calling dtls.connect() or dtls.listen() will throw an ERR_ACCESS_DENIED error.

node --permission --allow-fs-read=* --experimental-dtls index.mjs
Error: Access to this API has been restricted. Use --allow-net to manage permissions.
  code: 'ERR_ACCESS_DENIED',
  permission: 'Net',
}

Creating a DTLSEndpoint instance without connecting or listening is permitted even without --allow-net, since no network I/O occurs until dtls.connect() or dtls.listen() is called.

DTLS is designed for UDP transport and differs from TLS in several key ways:

• No stream guarantees: Messages may arrive out of order or be lost. DTLS preserves datagram semantics.
• One socket, many peers: A single UDP socket can serve multiple DTLS sessions. The DTLSEndpoint manages this multiplexing.
• Cookie exchange: DTLS servers use a stateless cookie mechanism (HelloVerifyRequest) to prevent denial-of-service amplification attacks.
• Retransmission: DTLS handles handshake retransmission internally since UDP does not guarantee delivery.

dtls.listen(callback, options): DTLSEndpoint

Creates a DTLS server bound to the specified address and port. The server uses automatic HMAC-based cookie exchange for DoS protection. See Denial of service.

Binding failures are thrown with the code the operating system gave, as in net and dgram: an address already in use throws an error whose code is 'EADDRINUSE', with errno and syscall set.

import { listen } from 'node:dtls';
import { readFileSync } from 'node:fs';

const endpoint = listen((session) => {
  session.onmessage = (data) => {
    console.log('Received:', data.toString());
    session.send('pong');
  };

  session.onhandshake = (protocol) => {
    console.log('Handshake complete:', protocol);
  };
}, {
  cert: readFileSync('server-cert.pem'),
  key: readFileSync('server-key.pem'),
  port: 4433,
});

console.log('DTLS server listening on', endpoint.address);

dtls.connect(host, port, options?): DTLSSession

Connects to a DTLS server. Returns a DTLSSession whose opened property is a Promise that resolves when the handshake completes.

import { connect } from 'node:dtls';
import { readFileSync } from 'node:fs';

const session = connect('127.0.0.1', 4433, {
  ca: [readFileSync('ca-cert.pem')],
});

await session.opened;
session.send('hello');

session.onmessage = (data) => {
  console.log('Received:', data.toString());
};

dtls.createSecureContext(options?): DTLSSecureContext

Options marked "Servers only" require isServer: true. Passing one to a client context throws ERR_INVALID_ARG_VALUE, rather than being ignored or applied where it can have no effect.

Creates a reusable secure context. Pass it to dtls.listen() or dtls.connect() as secureContext in place of the credential options.

A context holds a parsed certificate and key and, when ca is given, its own certificate store; roughly 28 KiB in total. Building one per connection is therefore expensive in memory rather than in time -- two thousand of them cost about 54 MiB, against 2 MiB when a single context is shared. Clients opening many connections should build the context once.

The peer identity checked during verification is not part of the context. It is bound to each connection from servername (or the host), so one context can be used against different peers and still reject the wrong certificate.

isServer is fixed when the context is created, because it selects the underlying OpenSSL method. Passing a server context to dtls.connect(), or a client context to dtls.listen(), throws.

import { connect, createSecureContext, listen } from 'node:dtls';
import { readFileSync } from 'node:fs';

const serverContext = createSecureContext({
  cert: readFileSync('server-cert.pem'),
  key: readFileSync('server-key.pem'),
  isServer: true,
});

// One context, several endpoints.
const a = listen(onsession, { secureContext: serverContext, port: 5684 });
const b = listen(onsession, { secureContext: serverContext, port: 5685 });

const clientContext = createSecureContext({
  ca: readFileSync('ca-cert.pem'),
});

// One context, many connections, each verified against its own name.
const s1 = connect('192.0.2.1', 5684, {
  secureContext: clientContext,
  servername: 'a.example.com',
});
const s2 = connect('192.0.2.2', 5684, {
  secureContext: clientContext,
  servername: 'b.example.com',
});

An endpoint can serve more than one identity by giving listen() an sni map, or a function. Each key of a map is a host name and each value is either a DTLSSecureContext created with isServer: true, or a plain object of the same options dtls.createSecureContext() takes:

import { createSecureContext, listen } from 'node:dtls';
import { readFileSync } from 'node:fs';

const endpoint = listen(onsession, {
  cert: readFileSync('default-cert.pem'),
  key: readFileSync('default-key.pem'),
  port: 5684,
  sni: {
    'api.example.com': {
      cert: readFileSync('api-cert.pem'),
      key: readFileSync('api-key.pem'),
    },
    'www.example.com': createSecureContext({
      cert: readFileSync('www-cert.pem'),
      key: readFileSync('www-key.pem'),
      isServer: true,
    }),
    '*': {
      cert: readFileSync('default-cert.pem'),
      key: readFileSync('default-key.pem'),
    },
  },
});

The '*' key is the fallback, used when the client's name matches nothing and when the client sends no name at all. Without it, an unmatched name is refused with an unrecognized_name alert rather than falling back to the endpoint's own cert and key; providing an sni map is taken to mean that only the names in it are served. tls.createServer() differs here: its SNICallback falls back to the default identity silently.

Verification follows the selected identity, so an entry carrying its own ca accepts only client certificates issued under it. requestCert and rejectUnauthorized are not per-identity: they belong to the endpoint and apply to every name it serves.

A function may be given instead of a map, for identities that are chosen rather than enumerated:

listen(onsession, {
  port: 5684,
  cert,
  key,
  sni: (servername) => contexts.get(servername),
});

It is called with the name the client asked for, or undefined if the client sent no SNI extension, and returns what a map entry holds: a dtls.createSecureContext() result or the options to build one. Returning nothing declines the name, which is refused exactly as an unmatched map with no '*' entry is, rather than falling back to the endpoint's own certificate.

The function runs during the handshake and must return synchronously, so it cannot consult a database. Returning a prepared context is worth doing: building one from options parses the certificate again on every handshake.

An exception thrown by the function fails that handshake and is reported to the session's error handler, like any other handshake failure. It does not reach the process as an uncaught exception.

The certificate and the cipher list both follow the selected context. Pre-shared keys do not. OpenSSL installs the PSK callbacks on the connection when it is created, before any name is known, and selecting an identity does not replace them, so the keys a server accepts are always the endpoint's own. A psk given on an SNI identity is never consulted, and an identity cannot be served over PSK alone.

sni belongs to the secure context rather than to the endpoint, so it can be given to dtls.createSecureContext() and cannot be combined with a secureContext that already exists. Applying it to a prepared context would reconfigure that context for every endpoint sharing it, and the identities a server serves are part of what its context is.

A connection refused for an unrecognized name still reaches the listen() callback: the session exists once the client's address is validated, which happens before the name is examined. It then fails like any other handshake failure.

Cookie exchange proves a peer can receive at its claimed address, but it does not limit how many sessions that peer may then establish, and each session holds a TLS state machine, two buffers and a timer. maxSessions bounds the total; maxSessionsPerHost is what prevents one peer from taking all of it. A peer refused by either cap is answered with silence rather than an alert, because replying to an address that has not completed cookie exchange would create an amplification vector; a legitimate client retransmits and is admitted once there is room. Refusals are counted by endpointStats.serverRefusedCount.

Deployments serving many clients behind a single NAT may need to raise maxSessionsPerHost.

A handshake that never finishes is abandoned after handshakeTimeout milliseconds, and its session error is DTLS handshake timeout.

OpenSSL already gives up on its own, but only after twelve retransmits on a doubling backoff capped at 60 seconds -- around eight minutes in total. Until then the session holds its place against maxSessions (see Denial of service), so handshakes that are started and abandoned can occupy an endpoint for the cost of starting them. That needs no spoofing: the peer completes the cookie exchange and then simply stops.

The two limits coexist and whichever comes first ends the handshake. The retransmit schedule itself is untouched, deliberately -- compressing it to force earlier failure would cause spurious retransmissions on exactly the lossy links DTLS is meant for.

The timeout covers resumed and PSK handshakes as well, and stops applying once the handshake completes; it is not an idle timeout.

A handshake can stall without either peer being at fault or aware. DTLS discards records it cannot authenticate rather than answering them (RFC 6347 section 4.1.2.1), so a mismatched pre-shared key or a cipher list with nothing in common produces silence rather than an alert. This timeout is what ends those.

DTLS can authenticate with a key both peers already hold instead of a certificate (RFC 4279). This is how it is usually deployed to constrained devices, which frequently have no certificate at all.

A server gives the identities it accepts; a client gives the one it is. No certificate is needed on either side:

import { connect, listen } from 'node:dtls';

const endpoint = listen(onsession, {
  port: 5684,
  psk: { 'device-42': deviceKey },
});

const client = connect('192.0.2.1', 5684, {
  psk: { identity: 'device-42', key: deviceKey },
});

Either side may pass a function instead, for keys that are looked up or derived rather than known up front. A server's is called with the identity the client offered and returns the key, or nothing to refuse it. A client's is called with the server's identity hint, if it sent one, and returns { identity, key }:

listen(onsession, {
  port: 5684,
  psk: (identity) => deriveKey(masterSecret, identity),
});

The callback runs during the handshake and must return synchronously, so it cannot consult a database. Where both are given, the map is checked first and the callback is only reached when the map has no answer -- a configuration using only the map never runs JavaScript inside the handshake.

An exception thrown by the callback fails that handshake and is reported to the session's error handler. It does not reach the process as an uncaught exception.

The default cipher list excludes PSK, so giving psk without ciphers enables the PSK suites. Supplying ciphers disables that and uses exactly what was asked for.

A server keeps the certificate suites as well, since it may serve both kinds of client on one port. A client does not: a client that configured a pre-shared key and no CA wants the key, and leaving the certificate suites enabled would let a server choose one, failing the handshake while verifying a certificate the caller never meant to rely on.

Forward-secret PSK key exchanges are preferred over plain PSK of the same strength. Plain PSK derives its keys from the shared secret alone, so anyone who later learns that key can decrypt traffic they recorded earlier. RSA-PSK is excluded: it needs a certificate and adds no forward secrecy.

CoAP requires TLS_PSK_WITH_AES_128_CCM_8 (RFC 7252), whose 64-bit authentication tag OpenSSL rejects at security level 1 and above. Node.js default is above it, so that suite has to be asked for explicitly and with the security level lowered:

listen(onsession, { port: 5684, psk, ciphers: 'PSK-AES128-CCM8@SECLEVEL=0' });

A wrong key does not produce an error. The identity only names the key, so the handshake proceeds and the two sides derive different secrets; the first record that fails authentication is then discarded rather than answered, since DTLS discards invalid records instead of replying to them (RFC 6347 section 4.1.2.1). Neither peer is told anything and both retransmit.

A cipher list with nothing in common behaves the same way, which is what makes the CCM8 case above present as a stall rather than a rejection. Both are ended by handshakeTimeout, after 60 seconds by default.

An identity the server does not recognise is refused outright, and the client sees the handshake fail.

A resumed handshake skips the server's certificate, which matters more here than it does over TCP: the Certificate flight is fragmented across several datagrams, and losing any one of them costs a retransmission timeout. Measured on loopback, a full handshake has the server send 1850 bytes in 4 packets against 280 bytes in 3 for a resumed one.

A client reads session.session once the session is open and passes it to a later dtls.connect():

import { connect } from 'node:dtls';

const first = connect('192.0.2.1', 5684, { ca, servername: 'device.example' });
await first.opened;
const ticket = first.session;        // Buffer.
await first.close();

const second = connect('192.0.2.1', 5684, {
  ca,
  servername: 'device.example',
  session: ticket,
});
await second.opened;
console.log(second.reused);          // True.

A session that the server will not accept -- expired, or issued by a different endpoint -- is not an error. The handshake simply proceeds in full, and session.reused is false.

The cookie exchange still happens for a resumed handshake, so resumption is not a way around the address validation described under Denial of service.

A session may only be resumed against the identity it was authenticated for -- the servername, or the host when there is none. Reusing it for anything else throws.

This is not a convenience check. A resumed handshake does not re-send or re-verify the peer's certificate; it inherits the authenticated identity of the original session. Replaying a session against a different host would therefore skip verification while appearing to succeed. For the same reason a session that did not come from session.session is rejected outright: nothing records which identity it belongs to, so it cannot be checked.

A session carries the verification result it was established with, so a session established with rejectUnauthorized: false cannot be resumed by a connection that asked for a verified peer. The handshake fails:

import { connect } from 'node:dtls';

// Connected without verifying anything.
const first = connect('192.0.2.1', 5684, { rejectUnauthorized: false });
await first.opened;
console.log(first.authorized);         // False.
const ticket = first.session;
await first.close();

const second = connect('192.0.2.1', 5684, {
  rejectUnauthorized: true,
  session: ticket,
});
await second.opened;                   // Rejects: verification failed.

The host is the same in both, so binding the session to its authenticated identity does not cover this on its own; what differs is whether the caller asked for the peer to be verified. Because a resumed handshake runs no verification of its own, the recorded result is re-checked once it completes, and a session whose peer never verified is refused wherever verification is required. session.authorized and session.authorizationError report the recorded result on a resumed session either way.

The key that encrypts session tickets is generated at random for each context, so by default a ticket is only good for the endpoint that issued it and only until the process restarts. Give every endpoint the same ticketKeys to let tickets be resumed across a restart or a cluster:

import { listen } from 'node:dtls';
import { randomBytes } from 'node:crypto';

const ticketKeys = randomBytes(80);    // Share this between processes.
const endpoint = listen(onsession, { cert, key, port: 5684, ticketKeys });

The length is OpenSSL's: a key name followed by an HMAC key and an AES key. It differs from the 48 bytes tls.createServer() uses, which is a layout node:tls defines for itself. Supplying the wrong length throws and reports the length expected.

Ticket keys are long-lived secrets. Anyone holding them can decrypt tickets and recover the sessions they protect, so treat them as key material and rotate them.

An opaque, reusable bundle of credentials and TLS settings, created by dtls.createSecureContext(). It cannot be constructed directly.

Manages a UDP socket and multiplexes DTLS sessions.

The local address the endpoint is bound to.

The statistics collected for this endpoint. Read only. The stats object is live and updated as data flows through the endpoint.

When true, the endpoint rejects new incoming connections. Can be set to implement backpressure.

endpoint.close(): Promise

Gracefully closes the endpoint. All active sessions are closed with close_notify alerts before the UDP socket is released.

endpoint.destroy(error?): void

Immediately destroys the endpoint without sending close_notify alerts.

endpoint[Symbol.asyncDispose](): void

Equivalent to calling endpoint.close().

A view of the collected statistics for an endpoint.

Datagrams arriving at a listening endpoint that do not match an existing session are screened for the shape of a DTLS ClientHello record before any state is allocated for them. A steadily rising value indicates junk or scan traffic rather than failing clients, which are counted as sessions that never complete.

true if the stats object is still connected to the underlying endpoint. Once the endpoint is destroyed, the stats become a stale snapshot.

Represents a DTLS association with a single remote peer.

session.send(data): number

Send application data to the peer. The data is encrypted by DTLS before being sent over UDP. Can only be called after the handshake completes (session.opened has resolved).

DTLS carries application data in a single record per datagram and does not fragment it, so data must fit in one record. Sending more throws ERR_OUT_OF_RANGE. This limit is independent of the mtu option: a record larger than the path MTU is still sent, and is fragmented by IP.

Throws ERR_INVALID_STATE if the handshake has not completed, or if the session is closed or destroyed.

A successful return means the data was handed to the DTLS layer and written to the socket, not that the peer received it. DTLS runs over UDP, so application data may still be lost in transit.

session.close(): Promise

Initiates a graceful DTLS shutdown by sending a close_notify alert.

session.destroy(error?): void

Immediately destroys the session without sending close_notify.

Rejects if the handshake fails, and also if the session is closed or destroyed before the handshake completes -- in that case with ERR_INVALID_STATE, or with the error passed to session.destroy() if one was given. The promise always settles, so awaiting it cannot hang.

This is the leaf certificate as PEM text and nothing else. For the issuer chain and the parsed fields, use session.peerX509Certificate, whose toString() returns this same PEM. Use session.authorized and session.authorizationError for the verification result rather than parsing either.

An X509Certificate for the peer's leaf certificate. The issuer chain is reachable through its issuerCertificate property, and the parsed fields -- subject, issuer, validFrom, validTo, fingerprint256, serialNumber and the rest -- are properties of that object.

Where tls.TLSSocket.getPeerCertificate() returns a plain dictionary with valid_from, valid_to and a chain walked through issuerCertificate, this returns the same X509Certificate class that tls.TLSSocket.getPeerX509Certificate() does. Call toLegacyObject() on it to get the dictionary form.

The same object is returned on every access once the peer's certificate is available.

Pass it as the session option to a later dtls.connect(). It is bound to the host this connection authenticated against and is refused elsewhere; see Session resumption.

Server sessions return undefined: a server has no identity to bind the value to, and it is the client that carries a session between connections.

Like session.authorized, this reads false once the session is closed.

A peer that presented no certificate at all reports 'UNABLE_TO_GET_ISSUER_CERT', so this can be used to distinguish "no certificate" from "a certificate that failed to verify".

The chain is verified even when rejectUnauthorized is false; the result is simply not enforced. That makes these two properties the way to apply a custom authorization policy:

import { connect } from 'node:dtls';

const session = connect('192.0.2.1', 4433, {
  ca: [caCert],
  servername: 'example.com',
  rejectUnauthorized: false,
});

await session.opened;

if (!session.authorized && session.authorizationError !== 'CERT_HAS_EXPIRED') {
  await session.close();
}

If a server has alpn configured and a client offers only protocols the server does not support, the server sends a fatal no_application_protocol alert and the handshake fails, as required by RFC 7301 section 3.2. A server with no alpn configured declines the extension instead, and the handshake completes with no protocol negotiated.

The statistics collected for this session. Read only. The stats object is live and updated as data flows through the session.

session.exportKeyingMaterial(length, label, context?): Buffer

Exports keying material from the DTLS session, as defined in RFC 5705. This is commonly used with DTLS-SRTP to derive encryption keys for media streams.

Throws ERR_OUT_OF_RANGE if length is outside the accepted range. The upper bound is not imposed by RFC 5705; it exists so that a caller cannot request an arbitrarily large allocation, and is far above what any defined exporter needs (DTLS-SRTP uses 60 bytes).

Set to receive application data from the peer.

Set to receive error notifications.

Set to receive handshake completion notifications.

Set to receive TLS key log lines (for debugging with Wireshark).

session[Symbol.asyncDispose](): void

Equivalent to calling session.close().

A view of the collected statistics for a session.

true if the stats object is still connected to the underlying session. Once the session is destroyed, the stats become a stale snapshot.

DTLS-SRTP is used by WebRTC for media encryption. The DTLS handshake negotiates the SRTP protection profile and provides keying material.

import { listen, connect } from 'node:dtls';
import { readFileSync } from 'node:fs';

// Server with SRTP
const server = listen((session) => {
  session.onhandshake = () => {
    console.log('SRTP profile:', session.srtpProfile);
    const keys = session.exportKeyingMaterial(
      60,
      'EXTRACTOR-dtls_srtp',
    );
    console.log('SRTP keying material:', keys);
  };
}, {
  cert: readFileSync('server-cert.pem'),
  key: readFileSync('server-key.pem'),
  port: 5004,
  srtp: 'SRTP_AES128_CM_SHA1_80:SRTP_AEAD_AES_128_GCM',
});

// Client with SRTP
const session = connect('127.0.0.1', 5004, {
  rejectUnauthorized: false,
  srtp: 'SRTP_AEAD_AES_128_GCM:SRTP_AES128_CM_SHA1_80',
});

await session.opened;
console.log('Negotiated SRTP:', session.srtpProfile);
const keys = session.exportKeyingMaterial(60, 'EXTRACTOR-dtls_srtp');

Since libuv does not currently support path MTU discovery, the DTLS module uses a conservative default MTU of 1200 bytes. This value works across virtually all network paths but may be suboptimal for local networks.

This bounds the UDP payload, not the application payload: a record carries somewhat less once its header and MAC are accounted for. It is fixed when the endpoint is created and cannot be changed afterwards. It does not bound session.send(), which is limited by the DTLS record size instead.

The MTU can be configured via the mtu option:

// For a local network where you know the path MTU
const endpoint = listen(callback, {
  // ...
  mtu: 1400,
});

The minimum allowed MTU is 256 bytes. The maximum is 65535.