The node:dtls module provides an implementation of the Datagram Transport\nLayer Security (DTLS) protocol over UDP. DTLS provides TLS-equivalent\nsecurity guarantees for datagram-based communication, including\nconfidentiality, integrity, and authentication.
To use this module, it must be enabled at build time with the\n--experimental-dtls configure flag and at runtime with the\n--experimental-dtls CLI flag.
node --experimental-dtls app.mjs\nimport { listen, connect } from 'node:dtls';\nconst { listen, connect } = require('node:dtls');\nWhen using the Permission Model, the --allow-net flag must be passed to\nallow DTLS network operations. Without it, calling dtls.connect() or\ndtls.listen() will throw an ERR_ACCESS_DENIED error.
node --permission --allow-fs-read=* --experimental-dtls index.mjs\nError: Access to this API has been restricted. Use --allow-net to manage permissions.\n code: 'ERR_ACCESS_DENIED',\n permission: 'Net',\n}\nCreating a DTLSEndpoint instance without connecting or listening\nis permitted even without --allow-net, since no network I/O occurs until\ndtls.connect() or dtls.listen() is called.
DTLS is designed for UDP transport and differs from TLS in several key ways:
\nDTLSEndpoint manages this multiplexing.An endpoint can serve more than one identity by giving listen() an sni\nmap, or a function. Each key of a map is a host name and each value is either\na\nDTLSSecureContext created with isServer: true, or a plain object of\nthe same options dtls.createSecureContext() takes:
import { createSecureContext, listen } from 'node:dtls';\nimport { readFileSync } from 'node:fs';\n\nconst endpoint = listen(onsession, {\n cert: readFileSync('default-cert.pem'),\n key: readFileSync('default-key.pem'),\n port: 5684,\n sni: {\n 'api.example.com': {\n cert: readFileSync('api-cert.pem'),\n key: readFileSync('api-key.pem'),\n },\n 'www.example.com': createSecureContext({\n cert: readFileSync('www-cert.pem'),\n key: readFileSync('www-key.pem'),\n isServer: true,\n }),\n '*': {\n cert: readFileSync('default-cert.pem'),\n key: readFileSync('default-key.pem'),\n },\n },\n});\nThe '*' key is the fallback, used when the client's name matches nothing and\nwhen the client sends no name at all. Without it, an unmatched name is\nrefused with an unrecognized_name alert rather than falling back to the\nendpoint's own cert and key; providing an sni map is taken to mean that\nonly the names in it are served. tls.createServer() differs here: its\nSNICallback falls back to the default identity silently.
Verification follows the selected identity, so an entry carrying its own ca\naccepts only client certificates issued under it. requestCert and\nrejectUnauthorized are not per-identity: they belong to the endpoint and\napply to every name it serves.
A function may be given instead of a map, for identities that are chosen\nrather than enumerated:
\nlisten(onsession, {\n port: 5684,\n cert,\n key,\n sni: (servername) => contexts.get(servername),\n});\nIt is called with the name the client asked for, or undefined if the client\nsent no SNI extension, and returns what a map entry holds: a\ndtls.createSecureContext() result or the options to build one. Returning\nnothing declines the name, which is refused exactly as an unmatched map with no\n'*' entry is, rather than falling back to the endpoint's own certificate.
The function runs during the handshake and must return synchronously, so it\ncannot consult a database. Returning a prepared context is worth doing:\nbuilding one from options parses the certificate again on every handshake.
\nAn exception thrown by the function fails that handshake and is reported to the\nsession's error handler, like any other handshake failure. It does not reach\nthe process as an uncaught exception.
\nThe certificate and the cipher list both follow the selected context.\nPre-shared keys do not. OpenSSL installs the PSK callbacks on the connection\nwhen it is created, before any name is known, and selecting an identity does\nnot replace them, so the keys a server accepts are always the endpoint's own.\nA psk given on an SNI identity is never consulted, and an identity cannot be\nserved over PSK alone.
sni belongs to the secure context rather than to the endpoint, so it can be\ngiven to dtls.createSecureContext() and cannot be combined with a\nsecureContext that already exists. Applying it to a prepared context would\nreconfigure that context for every endpoint sharing it, and the identities a\nserver serves are part of what its context is.
A connection refused for an unrecognized name still reaches the listen()\ncallback: the session exists once the client's address is validated, which\nhappens before the name is examined. It then fails like any other handshake\nfailure.
Cookie exchange proves a peer can receive at its claimed address, but it does\nnot limit how many sessions that peer may then establish, and each session\nholds a TLS state machine, two buffers and a timer. maxSessions bounds the\ntotal; maxSessionsPerHost is what prevents one peer from taking all of it.\nA peer refused by either cap is answered with silence rather than an alert,\nbecause replying to an address that has not completed cookie exchange would\ncreate an amplification vector; a legitimate client retransmits and is\nadmitted once there is room. Refusals are counted by\nendpointStats.serverRefusedCount.
Deployments serving many clients behind a single NAT may need to raise\nmaxSessionsPerHost.
A handshake that never finishes is abandoned after handshakeTimeout\nmilliseconds, and its session error is DTLS handshake timeout.
OpenSSL already gives up on its own, but only after twelve retransmits on a\ndoubling backoff capped at 60 seconds -- around eight minutes in total. Until\nthen the session holds its place against maxSessions (see\nDenial of service),\nso handshakes that are started and abandoned can occupy an endpoint for the\ncost of starting them. That needs no spoofing: the peer completes the cookie\nexchange and then simply stops.
The two limits coexist and whichever comes first ends the handshake. The\nretransmit schedule itself is untouched, deliberately -- compressing it to\nforce earlier failure would cause spurious retransmissions on exactly the\nlossy links DTLS is meant for.
\nThe timeout covers resumed and PSK handshakes as well, and stops applying once\nthe handshake completes; it is not an idle timeout.
\nA handshake can stall without either peer being at fault or aware.\nDTLS discards records it cannot authenticate rather than answering them\n(RFC 6347 section 4.1.2.1), so a mismatched pre-shared key or a cipher list\nwith nothing in common produces silence rather than an alert. This timeout is\nwhat ends those.
", "displayName": "Handshake timeout" }, { "textRaw": "Pre-shared keys", "name": "pre-shared_keys", "type": "module", "desc": "DTLS can authenticate with a key both peers already hold instead of a\ncertificate (RFC 4279). This is how it is usually deployed to constrained\ndevices, which frequently have no certificate at all.
\nA server gives the identities it accepts; a client gives the one it is. No\ncertificate is needed on either side:
\nimport { connect, listen } from 'node:dtls';\n\nconst endpoint = listen(onsession, {\n port: 5684,\n psk: { 'device-42': deviceKey },\n});\n\nconst client = connect('192.0.2.1', 5684, {\n psk: { identity: 'device-42', key: deviceKey },\n});\nEither side may pass a function instead, for keys that are looked up or\nderived rather than known up front. A server's is called with the identity the\nclient offered and returns the key, or nothing to refuse it. A client's is\ncalled with the server's identity hint, if it sent one, and returns\n{ identity, key }:
listen(onsession, {\n port: 5684,\n psk: (identity) => deriveKey(masterSecret, identity),\n});\nThe callback runs during the handshake and must return synchronously, so it\ncannot consult a database. Where both are given, the map is checked first and\nthe callback is only reached when the map has no answer -- a configuration\nusing only the map never runs JavaScript inside the handshake.
\nAn exception thrown by the callback fails that handshake and is reported to\nthe session's error handler. It does not reach the process as an uncaught\nexception.
", "modules": [ { "textRaw": "Cipher suites", "name": "cipher_suites", "type": "module", "desc": "The default cipher list excludes PSK, so giving psk without ciphers\nenables the PSK suites. Supplying ciphers disables that and uses exactly\nwhat was asked for.
A server keeps the certificate suites as well, since it may serve both kinds\nof client on one port. A client does not: a client that configured a\npre-shared key and no CA wants the key, and leaving the certificate suites\nenabled would let a server choose one, failing the handshake while verifying a\ncertificate the caller never meant to rely on.
\nForward-secret PSK key exchanges are preferred over plain PSK of the same\nstrength. Plain PSK derives its keys from the shared secret alone, so anyone\nwho later learns that key can decrypt traffic they recorded earlier. RSA-PSK\nis excluded: it needs a certificate and adds no forward secrecy.
CoAP requires TLS_PSK_WITH_AES_128_CCM_8 (RFC 7252), whose 64-bit\nauthentication tag OpenSSL rejects at security level 1 and above. Node.js\ndefault is above it, so that suite has to be asked for explicitly and with the\nsecurity level lowered:
listen(onsession, { port: 5684, psk, ciphers: 'PSK-AES128-CCM8@SECLEVEL=0' });\nA wrong key does not produce an error. The identity only names the key, so the\nhandshake proceeds and the two sides derive different secrets; the first\nrecord that fails authentication is then discarded rather than answered, since\nDTLS discards invalid records instead of replying to them (RFC 6347 section\n4.1.2.1). Neither peer is told anything and both retransmit.
\nA cipher list with nothing in common behaves the same way, which is what makes\nthe CCM8 case above present as a stall rather than a rejection. Both are\nended by handshakeTimeout, after 60 seconds by default.
An identity the server does not recognise is refused outright, and the client\nsees the handshake fail.
", "displayName": "Failure modes" } ], "displayName": "Pre-shared keys" }, { "textRaw": "Session resumption", "name": "session_resumption", "type": "module", "desc": "A resumed handshake skips the server's certificate, which matters more here\nthan it does over TCP: the Certificate flight is fragmented across several\ndatagrams, and losing any one of them costs a retransmission timeout. Measured\non loopback, a full handshake has the server send 1850 bytes in 4 packets\nagainst 280 bytes in 3 for a resumed one.
A client reads session.session once the session is open and passes it to\na later dtls.connect():
import { connect } from 'node:dtls';\n\nconst first = connect('192.0.2.1', 5684, { ca, servername: 'device.example' });\nawait first.opened;\nconst ticket = first.session; // Buffer.\nawait first.close();\n\nconst second = connect('192.0.2.1', 5684, {\n ca,\n servername: 'device.example',\n session: ticket,\n});\nawait second.opened;\nconsole.log(second.reused); // True.\nA session that the server will not accept -- expired, or issued by a different\nendpoint -- is not an error. The handshake simply proceeds in full, and\nsession.reused is false.
The cookie exchange still happens for a resumed handshake, so resumption is not\na way around the address validation described under Denial of service.
", "modules": [ { "textRaw": "Binding to the authenticated host", "name": "binding_to_the_authenticated_host", "type": "module", "desc": "A session may only be resumed against the identity it was authenticated for --\nthe servername, or the host when there is none. Reusing it for anything else\nthrows.
This is not a convenience check. A resumed handshake does not re-send or\nre-verify the peer's certificate; it inherits the authenticated identity of the\noriginal session. Replaying a session against a different host would therefore\nskip verification while appearing to succeed. For the same reason a session\nthat did not come from session.session is rejected outright: nothing\nrecords which identity it belongs to, so it cannot be checked.
A session carries the verification result it was established with, so a session\nestablished with rejectUnauthorized: false cannot be resumed by a connection\nthat asked for a verified peer. The handshake fails:
import { connect } from 'node:dtls';\n\n// Connected without verifying anything.\nconst first = connect('192.0.2.1', 5684, { rejectUnauthorized: false });\nawait first.opened;\nconsole.log(first.authorized); // False.\nconst ticket = first.session;\nawait first.close();\n\nconst second = connect('192.0.2.1', 5684, {\n rejectUnauthorized: true,\n session: ticket,\n});\nawait second.opened; // Rejects: verification failed.\nThe host is the same in both, so binding the session to its authenticated\nidentity does not cover this on its own; what differs is whether the caller\nasked for the peer to be verified. Because a resumed handshake runs no\nverification of its own, the recorded result is re-checked once it completes,\nand a session whose peer never verified is refused wherever verification is\nrequired. session.authorized and session.authorizationError report\nthe recorded result on a resumed session either way.
The key that encrypts session tickets is generated at random for each context,\nso by default a ticket is only good for the endpoint that issued it and only\nuntil the process restarts. Give every endpoint the same ticketKeys to let\ntickets be resumed across a restart or a cluster:
import { listen } from 'node:dtls';\nimport { randomBytes } from 'node:crypto';\n\nconst ticketKeys = randomBytes(80); // Share this between processes.\nconst endpoint = listen(onsession, { cert, key, port: 5684, ticketKeys });\nThe length is OpenSSL's: a key name followed by an HMAC key and an AES key. It\ndiffers from the 48 bytes tls.createServer() uses, which is a layout\nnode:tls defines for itself. Supplying the wrong length throws and reports\nthe length expected.
Ticket keys are long-lived secrets. Anyone holding them can decrypt tickets and\nrecover the sessions they protect, so treat them as key material and rotate\nthem.
", "displayName": "Ticket keys" } ], "displayName": "Session resumption" }, { "textRaw": "DTLS-SRTP example", "name": "dtls-srtp_example", "type": "module", "desc": "DTLS-SRTP is used by WebRTC for media encryption. The DTLS handshake\nnegotiates the SRTP protection profile and provides keying material.
\nimport { listen, connect } from 'node:dtls';\nimport { readFileSync } from 'node:fs';\n\n// Server with SRTP\nconst server = listen((session) => {\n session.onhandshake = () => {\n console.log('SRTP profile:', session.srtpProfile);\n const keys = session.exportKeyingMaterial(\n 60,\n 'EXTRACTOR-dtls_srtp',\n );\n console.log('SRTP keying material:', keys);\n };\n}, {\n cert: readFileSync('server-cert.pem'),\n key: readFileSync('server-key.pem'),\n port: 5004,\n srtp: 'SRTP_AES128_CM_SHA1_80:SRTP_AEAD_AES_128_GCM',\n});\n\n// Client with SRTP\nconst session = connect('127.0.0.1', 5004, {\n rejectUnauthorized: false,\n srtp: 'SRTP_AEAD_AES_128_GCM:SRTP_AES128_CM_SHA1_80',\n});\n\nawait session.opened;\nconsole.log('Negotiated SRTP:', session.srtpProfile);\nconst keys = session.exportKeyingMaterial(60, 'EXTRACTOR-dtls_srtp');\nSince libuv does not currently support path MTU discovery, the DTLS module\nuses a conservative default MTU of 1200 bytes. This value works across\nvirtually all network paths but may be suboptimal for local networks.
\nThis bounds the UDP payload, not the application payload: a record carries\nsomewhat less once its header and MAC are accounted for. It is fixed when the\nendpoint is created and cannot be changed afterwards. It does not bound\nsession.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\nconst endpoint = listen(callback, {\n // ...\n mtu: 1400,\n});\nThe minimum allowed MTU is 256 bytes. The maximum is 65535.
", "displayName": "MTU considerations" } ], "methods": [ { "textRaw": "`dtls.listen(callback, options)`", "name": "listen", "type": "method", "meta": { "added": [ "v26.9.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`callback` {Function} Called for each new DTLS session accepted by the server.", "name": "callback", "type": "Function", "desc": "Called for each new DTLS session accepted by the server.", "options": [ { "textRaw": "`session` {DTLSSession} The new session.", "name": "session", "type": "DTLSSession", "desc": "The new session." } ] }, { "textRaw": "`options` {Object}", "name": "options", "type": "Object", "options": [ { "textRaw": "`cert` {string|Buffer} Server certificate in PEM format. **Required.**", "name": "cert", "type": "string|Buffer", "desc": "Server certificate in PEM format. **Required.**" }, { "textRaw": "`key` {string|Buffer} Server private key in PEM format. **Required.**", "name": "key", "type": "string|Buffer", "desc": "Server private key in PEM format. **Required.**" }, { "textRaw": "`secureContext` {DTLSSecureContext} A context from `dtls.createSecureContext()` to use instead of building one from the credential options below. Must have been created with `isServer: true`. Cannot be combined with any option the context already carries.", "name": "secureContext", "type": "DTLSSecureContext", "desc": "A context from `dtls.createSecureContext()` to use instead of building one from the credential options below. Must have been created with `isServer: true`. Cannot be combined with any option the context already carries." }, { "textRaw": "`sni` {Object|Function} Server Name Indication. A map of host names to the identity to serve them with, or a function returning one. Cannot be combined with `secureContext`; set it on the context instead. See Server Name Indication.", "name": "sni", "type": "Object|Function", "desc": "Server Name Indication. A map of host names to the identity to serve them with, or a function returning one. Cannot be combined with `secureContext`; set it on the context instead. See Server Name Indication." }, { "textRaw": "`passphrase` {string} Passphrase to decrypt `key`, if it is encrypted. Ignored when `key` is not encrypted. Unlike `key` and `cert`, this must be a string, matching `tls.createSecureContext()`.", "name": "passphrase", "type": "string", "desc": "Passphrase to decrypt `key`, if it is encrypted. Ignored when `key` is not encrypted. Unlike `key` and `cert`, this must be a string, matching `tls.createSecureContext()`." }, { "textRaw": "`port` {number} Port to bind to. **Required.**", "name": "port", "type": "number", "desc": "Port to bind to. **Required.**" }, { "textRaw": "`host` {string} Address to bind to. **Default:** `'0.0.0.0'`.", "name": "host", "type": "string", "default": "`'0.0.0.0'`", "desc": "Address to bind to." }, { "textRaw": "`ca` {string|Buffer|string}[] | {Buffer}[] CA certificates in PEM format.", "name": "ca", "type": "string|Buffer|string", "desc": "[] | {Buffer}[] CA certificates in PEM format." }, { "textRaw": "`ciphers` {string} OpenSSL cipher list string.", "name": "ciphers", "type": "string", "desc": "OpenSSL cipher list string." }, { "textRaw": "`alpn` {string}[] | {Buffer} ALPN protocol names. Each name must be between 1 and 255 bytes. A `Buffer` must already be in ALPN wire format: one length byte followed by that many bytes, repeated.", "name": "alpn", "type": "string", "desc": "[] | {Buffer} ALPN protocol names. Each name must be between 1 and 255 bytes. A `Buffer` must already be in ALPN wire format: one length byte followed by that many bytes, repeated." }, { "textRaw": "`srtp` {string} Colon-separated SRTP protection profile names (e.g., `'SRTP_AES128_CM_SHA1_80:SRTP_AEAD_AES_128_GCM'`).", "name": "srtp", "type": "string", "desc": "Colon-separated SRTP protection profile names (e.g., `'SRTP_AES128_CM_SHA1_80:SRTP_AEAD_AES_128_GCM'`)." }, { "textRaw": "`requestCert` {boolean} Request a certificate from the client. **Default:** `false`.", "name": "requestCert", "type": "boolean", "default": "`false`", "desc": "Request a certificate from the client." }, { "textRaw": "`rejectUnauthorized` {boolean} Only has an effect together with `requestCert`. When `true`, a client that presents no certificate, or one that does not chain to a trusted CA, is rejected during the handshake and receives a TLS alert. When `false`, the certificate is still requested and verified but the handshake completes regardless, leaving the decision to the application via `session.authorized`. **Default:** `true`.", "name": "rejectUnauthorized", "type": "boolean", "default": "`true`", "desc": "Only has an effect together with `requestCert`. When `true`, a client that presents no certificate, or one that does not chain to a trusted CA, is rejected during the handshake and receives a TLS alert. When `false`, the certificate is still requested and verified but the handshake completes regardless, leaving the decision to the application via `session.authorized`." }, { "textRaw": "`mtu` {number} Maximum size in bytes of a DTLS datagram. **Default:** `1200`.", "name": "mtu", "type": "number", "default": "`1200`", "desc": "Maximum size in bytes of a DTLS datagram." }, { "textRaw": "`handshakeTimeout` {number} Milliseconds a handshake may take before it is abandoned. `0` disables it. **Default:** `60000`. See Handshake timeout.", "name": "handshakeTimeout", "type": "number", "default": "`60000`. See Handshake timeout", "desc": "Milliseconds a handshake may take before it is abandoned. `0` disables it." }, { "textRaw": "`ipv6Only` {boolean} When `true`, an IPv6 endpoint serves IPv6 only. When `false`, binding `'::'` also accepts IPv4 peers, which arrive with mapped addresses such as `'::ffff:203.0.113.1'` -- anything keyed on the peer address, including `maxSessionsPerHost`, sees them in that form. Has no effect on an IPv4 endpoint. **Default:** `false`.", "name": "ipv6Only", "type": "boolean", "default": "`false`", "desc": "When `true`, an IPv6 endpoint serves IPv6 only. When `false`, binding `'::'` also accepts IPv4 peers, which arrive with mapped addresses such as `'::ffff:203.0.113.1'` -- anything keyed on the peer address, including `maxSessionsPerHost`, sees them in that form. Has no effect on an IPv4 endpoint." }, { "textRaw": "`reusePort` {boolean} When `true`, sets `SO_REUSEPORT`, so several processes may bind the same port and the kernel spreads arriving datagrams between them. Every one of them must set it. **Default:** `false`.", "name": "reusePort", "type": "boolean", "default": "`false`", "desc": "When `true`, sets `SO_REUSEPORT`, so several processes may bind the same port and the kernel spreads arriving datagrams between them. Every one of them must set it." }, { "textRaw": "`udpReceiveBufferSize` {number} Size in bytes for the socket's receive buffer (`SO_RCVBUF`). Raising it gives the endpoint room for bursts that the default would drop. The kernel clamps this to its own maximum. **Default:** the system default.", "name": "udpReceiveBufferSize", "type": "number", "default": "the system default", "desc": "Size in bytes for the socket's receive buffer (`SO_RCVBUF`). Raising it gives the endpoint room for bursts that the default would drop. The kernel clamps this to its own maximum." }, { "textRaw": "`udpSendBufferSize` {number} Size in bytes for the socket's send buffer (`SO_SNDBUF`). Clamped as above. **Default:** the system default.", "name": "udpSendBufferSize", "type": "number", "default": "the system default", "desc": "Size in bytes for the socket's send buffer (`SO_SNDBUF`). Clamped as above." }, { "textRaw": "`udpTTL` {number} IP time-to-live for outgoing datagrams, from `1` to `255`. **Default:** the system default.", "name": "udpTTL", "type": "number", "default": "the system default", "desc": "IP time-to-live for outgoing datagrams, from `1` to `255`." }, { "textRaw": "`maxSessions` {number} The maximum number of concurrent sessions the endpoint will hold. Set to `0` for no limit. **Default:** `10000`.", "name": "maxSessions", "type": "number", "default": "`10000`", "desc": "The maximum number of concurrent sessions the endpoint will hold. Set to `0` for no limit." }, { "textRaw": "`maxSessionsPerHost` {number} The maximum number of concurrent sessions from any single source IP address, ignoring port. Set to `0` for no limit. **Default:** `1000`.", "name": "maxSessionsPerHost", "type": "number", "default": "`1000`", "desc": "The maximum number of concurrent sessions from any single source IP address, ignoring port. Set to `0` for no limit." }, { "textRaw": "`sessionIdContext` {string} Opaque identifier scoping resumable sessions to this server, at most 32 bytes. **Default:** a value derived from `process.argv`, as in `tls.createServer()`.", "name": "sessionIdContext", "type": "string", "default": "a value derived from `process.argv`, as in `tls.createServer()`", "desc": "Opaque identifier scoping resumable sessions to this server, at most 32 bytes." } ] } ], "return": { "textRaw": "Returns: {DTLSEndpoint}", "name": "return", "type": "DTLSEndpoint" } } ], "desc": "Creates a DTLS server bound to the specified address and port. The server\nuses automatic HMAC-based cookie exchange for DoS protection. See\nDenial of service.
\nBinding failures are thrown with the code the operating system gave, as in\nnet and dgram: an address already in use throws an error whose code is\n'EADDRINUSE', with errno and syscall set.
import { listen } from 'node:dtls';\nimport { readFileSync } from 'node:fs';\n\nconst endpoint = listen((session) => {\n session.onmessage = (data) => {\n console.log('Received:', data.toString());\n session.send('pong');\n };\n\n session.onhandshake = (protocol) => {\n console.log('Handshake complete:', protocol);\n };\n}, {\n cert: readFileSync('server-cert.pem'),\n key: readFileSync('server-key.pem'),\n port: 4433,\n});\n\nconsole.log('DTLS server listening on', endpoint.address);\nConnects to a DTLS server. Returns a DTLSSession whose opened property\nis a Promise that resolves when the handshake completes.
import { connect } from 'node:dtls';\nimport { readFileSync } from 'node:fs';\n\nconst session = connect('127.0.0.1', 4433, {\n ca: [readFileSync('ca-cert.pem')],\n});\n\nawait session.opened;\nsession.send('hello');\n\nsession.onmessage = (data) => {\n console.log('Received:', data.toString());\n};\nOptions marked \"Servers only\" require isServer: true. Passing one to a\nclient context throws ERR_INVALID_ARG_VALUE, rather than being ignored or\napplied where it can have no effect.
Creates a reusable secure context. Pass it to dtls.listen() or\ndtls.connect() as secureContext in place of the credential options.
A context holds a parsed certificate and key and, when ca is given, its own\ncertificate store; roughly 28 KiB in total. Building one per connection is\ntherefore expensive in memory rather than in time -- two thousand of them cost\nabout 54 MiB, against 2 MiB when a single context is shared. Clients opening\nmany connections should build the context once.
The peer identity checked during verification is not part of the context.\nIt is bound to each connection from servername (or the host), so one context\ncan be used against different peers and still reject the wrong certificate.
isServer is fixed when the context is created, because it selects the\nunderlying OpenSSL method. Passing a server context to dtls.connect(),\nor a client context to dtls.listen(), throws.
import { connect, createSecureContext, listen } from 'node:dtls';\nimport { readFileSync } from 'node:fs';\n\nconst serverContext = createSecureContext({\n cert: readFileSync('server-cert.pem'),\n key: readFileSync('server-key.pem'),\n isServer: true,\n});\n\n// One context, several endpoints.\nconst a = listen(onsession, { secureContext: serverContext, port: 5684 });\nconst b = listen(onsession, { secureContext: serverContext, port: 5685 });\n\nconst clientContext = createSecureContext({\n ca: readFileSync('ca-cert.pem'),\n});\n\n// One context, many connections, each verified against its own name.\nconst s1 = connect('192.0.2.1', 5684, {\n secureContext: clientContext,\n servername: 'a.example.com',\n});\nconst s2 = connect('192.0.2.2', 5684, {\n secureContext: clientContext,\n servername: 'b.example.com',\n});\nAn opaque, reusable bundle of credentials and TLS settings, created by\ndtls.createSecureContext(). It cannot be constructed directly.
Manages a UDP socket and multiplexes DTLS sessions.
", "properties": [ { "textRaw": "Returns: {Object} `{ address, family, port }`", "name": "address", "type": "Object", "desc": "The local address the endpoint is bound to.
", "shortDesc": "`{ address, family, port }`" }, { "textRaw": "Type: {DTLSEndpoint.Stats}", "name": "stats", "type": "DTLSEndpoint.Stats", "meta": { "added": [ "v26.9.0" ], "changes": [] }, "desc": "The statistics collected for this endpoint. Read only. The stats object is\nlive and updated as data flows through the endpoint.
" }, { "textRaw": "{boolean}", "name": "busy", "type": "boolean", "desc": "When true, the endpoint rejects new incoming connections. Can be set\nto implement backpressure.
Gracefully closes the endpoint. All active sessions are closed with\nclose_notify alerts before the UDP socket is released.
Immediately destroys the endpoint without sending close_notify alerts.
Equivalent to calling endpoint.close().
A view of the collected statistics for an endpoint.
", "properties": [ { "textRaw": "Type: {bigint} A timestamp indicating when the endpoint was created. Read only.", "name": "createdAt", "type": "bigint", "meta": { "added": [ "v26.9.0" ], "changes": [] }, "desc": "A timestamp indicating when the endpoint was created. Read only." }, { "textRaw": "Type: {bigint} A timestamp indicating when the endpoint was destroyed. Read only.", "name": "destroyedAt", "type": "bigint", "meta": { "added": [ "v26.9.0" ], "changes": [] }, "desc": "A timestamp indicating when the endpoint was destroyed. Read only." }, { "textRaw": "Type: {bigint} The total number of bytes received by this endpoint. Read only.", "name": "bytesReceived", "type": "bigint", "meta": { "added": [ "v26.9.0" ], "changes": [] }, "desc": "The total number of bytes received by this endpoint. Read only." }, { "textRaw": "Type: {bigint} The total number of bytes sent by this endpoint. Read only.", "name": "bytesSent", "type": "bigint", "meta": { "added": [ "v26.9.0" ], "changes": [] }, "desc": "The total number of bytes sent by this endpoint. Read only." }, { "textRaw": "Type: {bigint} The total number of UDP packets received by this endpoint. Read only.", "name": "packetsReceived", "type": "bigint", "meta": { "added": [ "v26.9.0" ], "changes": [] }, "desc": "The total number of UDP packets received by this endpoint. Read only." }, { "textRaw": "Type: {bigint} The total number of UDP packets sent by this endpoint. Read only.", "name": "packetsSent", "type": "bigint", "meta": { "added": [ "v26.9.0" ], "changes": [] }, "desc": "The total number of UDP packets sent by this endpoint. Read only." }, { "textRaw": "Type: {bigint} The total number of peer-initiated sessions accepted by this endpoint. Read only.", "name": "serverSessions", "type": "bigint", "meta": { "added": [ "v26.9.0" ], "changes": [] }, "desc": "The total number of peer-initiated sessions accepted by this endpoint. Read only." }, { "textRaw": "Type: {bigint} The total number of sessions initiated by this endpoint. Read only.", "name": "clientSessions", "type": "bigint", "meta": { "added": [ "v26.9.0" ], "changes": [] }, "desc": "The total number of sessions initiated by this endpoint. Read only." }, { "textRaw": "Type: {bigint} The total number of incoming connections rejected because the endpoint was marked busy. Read only.", "name": "serverBusyCount", "type": "bigint", "meta": { "added": [ "v26.9.0" ], "changes": [] }, "desc": "The total number of incoming connections rejected because the endpoint was marked busy. Read only." }, { "textRaw": "Type: {bigint} The number of datagrams discarded before a handshake was attempted because they could not be a ClientHello. Read only.", "name": "serverRejectedCount", "type": "bigint", "meta": { "added": [ "v26.10.0" ], "changes": [] }, "desc": "Datagrams arriving at a listening endpoint that do not match an existing\nsession are screened for the shape of a DTLS ClientHello record before any\nstate is allocated for them. A steadily rising value indicates junk or scan\ntraffic rather than failing clients, which are counted as sessions that never\ncomplete.
", "shortDesc": "The number of datagrams discarded before a handshake was attempted because they could not be a ClientHello. Read only." }, { "textRaw": "Type: {bigint} The number of otherwise valid handshake attempts refused because the endpoint was at `maxSessions` or the peer was at `maxSessionsPerHost`. Read only.", "name": "serverRefusedCount", "type": "bigint", "meta": { "added": [ "v26.10.0" ], "changes": [] }, "desc": "The number of otherwise valid handshake attempts refused because the endpoint was at `maxSessions` or the peer was at `maxSessionsPerHost`. Read only." }, { "textRaw": "Type: {boolean}", "name": "isConnected", "type": "boolean", "meta": { "added": [ "v26.9.0" ], "changes": [] }, "desc": "true if the stats object is still connected to the underlying endpoint.\nOnce the endpoint is destroyed, the stats become a stale snapshot.
Represents a DTLS association with a single remote peer.
", "methods": [ { "textRaw": "`session.send(data)`", "name": "send", "type": "method", "signatures": [ { "params": [ { "textRaw": "`data` {string|Buffer|TypedArray|DataView} The data to send. At most 16384 bytes. A view sends the bytes it covers, so an offset or a subarray is sent as given rather than as the whole buffer behind it.", "name": "data", "type": "string|Buffer|TypedArray|DataView", "desc": "The data to send. At most 16384 bytes. A view sends the bytes it covers, so an offset or a subarray is sent as given rather than as the whole buffer behind it." } ], "return": { "textRaw": "Returns: {number} The number of bytes written to the DTLS layer.", "name": "return", "type": "number", "desc": "The number of bytes written to the DTLS layer." } } ], "desc": "Send application data to the peer. The data is encrypted by DTLS before\nbeing sent over UDP. Can only be called after the handshake completes\n(session.opened has resolved).
DTLS carries application data in a single record per datagram and does not\nfragment it, so data must fit in one record. Sending more throws\nERR_OUT_OF_RANGE. This limit is independent of the mtu option: a record\nlarger 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\nsession is closed or destroyed.
A successful return means the data was handed to the DTLS layer and written\nto the socket, not that the peer received it. DTLS runs over UDP, so\napplication data may still be lost in transit.
" }, { "textRaw": "`session.close()`", "name": "close", "type": "method", "signatures": [ { "params": [], "return": { "textRaw": "Returns: {Promise} Resolves when the session is closed.", "name": "return", "type": "Promise", "desc": "Resolves when the session is closed." } } ], "desc": "Initiates a graceful DTLS shutdown by sending a close_notify alert.
Immediately destroys the session without sending close_notify.
Exports keying material from the DTLS session, as defined in\nRFC 5705. This is commonly used with DTLS-SRTP to derive\nencryption keys for media streams.
\nThrows ERR_OUT_OF_RANGE if length is outside the accepted range. The upper\nbound is not imposed by RFC 5705; it exists so that a caller cannot request\nan arbitrarily large allocation, and is far above what any defined exporter\nneeds (DTLS-SRTP uses 60 bytes).
Equivalent to calling session.close().
dtls.listen() this is the listening endpoint, shared with every other\nsession on it; for one from dtls.connect() it is the endpoint created\nto carry that session alone.Rejects if the handshake fails, and also if the session is closed or\ndestroyed before the handshake completes -- in that case with\nERR_INVALID_STATE, or with the error passed to\nsession.destroy() if one was given. The promise always settles, so\nawaiting it cannot hang.
This is the leaf certificate as PEM text and nothing else. For the issuer chain\nand the parsed fields, use session.peerX509Certificate, whose toString()\nreturns this same PEM. Use session.authorized and\nsession.authorizationError for the verification result rather than\nparsing either.
An X509Certificate for the peer's leaf certificate. The issuer chain is\nreachable through its issuerCertificate property, and the parsed fields --\nsubject, issuer, validFrom, validTo, fingerprint256, serialNumber\nand the rest -- are properties of that object.
Where tls.TLSSocket.getPeerCertificate() returns a plain dictionary with\nvalid_from, valid_to and a chain walked through issuerCertificate, this\nreturns the same X509Certificate class that\ntls.TLSSocket.getPeerX509Certificate() does. Call toLegacyObject() on\nit to get the dictionary form.
The same object is returned on every access once the peer's certificate is\navailable.
", "shortDesc": "The peer's certificate, or `undefined` if the peer sent none." }, { "textRaw": "Returns: {Buffer|undefined} An opaque session for resuming this connection later, or `undefined` on a server session or before the handshake completes.", "name": "session", "type": "Buffer|undefined", "meta": { "added": [ "v26.10.0" ], "changes": [] }, "desc": "Pass it as the session option to a later dtls.connect(). It is bound to\nthe host this connection authenticated against and is refused elsewhere; see\nSession resumption.
Server sessions return undefined: a server has no identity to bind the value\nto, 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\n'UNABLE_TO_GET_ISSUER_CERT', so this can be used to distinguish \"no\ncertificate\" from \"a certificate that failed to verify\".
The chain is verified even when rejectUnauthorized is false; the result is\nsimply not enforced. That makes these two properties the way to apply a custom\nauthorization policy:
import { connect } from 'node:dtls';\n\nconst session = connect('192.0.2.1', 4433, {\n ca: [caCert],\n servername: 'example.com',\n rejectUnauthorized: false,\n});\n\nawait session.opened;\n\nif (!session.authorized && session.authorizationError !== 'CERT_HAS_EXPIRED') {\n await session.close();\n}\nIf a server has alpn configured and a client offers only protocols the\nserver does not support, the server sends a fatal no_application_protocol\nalert and the handshake fails, as required by RFC 7301 section 3.2. A\nserver with no alpn configured declines the extension instead, and the\nhandshake completes with no protocol negotiated.
The statistics collected for this session. Read only. The stats object is\nlive and updated as data flows through the session.
" } ], "modules": [ { "textRaw": "Callback properties", "name": "callback_properties", "type": "module", "properties": [ { "textRaw": "{Function}", "name": "onmessage", "type": "Function", "desc": "Set to receive application data from the peer.
", "options": [ { "textRaw": "`data` {Buffer}", "name": "data", "type": "Buffer" } ] }, { "textRaw": "{Function}", "name": "onerror", "type": "Function", "desc": "Set to receive error notifications.
", "options": [ { "textRaw": "`error` {Error}", "name": "error", "type": "Error" } ] }, { "textRaw": "{Function}", "name": "onhandshake", "type": "Function", "desc": "Set to receive handshake completion notifications.
", "options": [ { "textRaw": "`protocol` {string}", "name": "protocol", "type": "string" } ] }, { "textRaw": "{Function}", "name": "onkeylog", "type": "Function", "desc": "Set to receive TLS key log lines (for debugging with Wireshark).
", "options": [ { "textRaw": "`line` {string}", "name": "line", "type": "string" } ] } ], "displayName": "Callback properties" } ] }, { "textRaw": "Class: `DTLSSession.Stats`", "name": "DTLSSession.Stats", "type": "class", "meta": { "added": [ "v26.9.0" ], "changes": [] }, "desc": "A view of the collected statistics for a session.
", "properties": [ { "textRaw": "Type: {bigint} A timestamp indicating when the session was created. Read only.", "name": "createdAt", "type": "bigint", "meta": { "added": [ "v26.9.0" ], "changes": [] }, "desc": "A timestamp indicating when the session was created. Read only." }, { "textRaw": "Type: {bigint} A timestamp indicating when the session was destroyed. Read only.", "name": "destroyedAt", "type": "bigint", "meta": { "added": [ "v26.9.0" ], "changes": [] }, "desc": "A timestamp indicating when the session was destroyed. Read only." }, { "textRaw": "Type: {bigint} A timestamp indicating when `close()` was called. Read only.", "name": "closingAt", "type": "bigint", "meta": { "added": [ "v26.9.0" ], "changes": [] }, "desc": "A timestamp indicating when `close()` was called. Read only." }, { "textRaw": "Type: {bigint} A timestamp indicating when the DTLS handshake completed. Read only.", "name": "handshakeCompletedAt", "type": "bigint", "meta": { "added": [ "v26.9.0" ], "changes": [] }, "desc": "A timestamp indicating when the DTLS handshake completed. Read only." }, { "textRaw": "Type: {bigint} The total number of application data bytes received. Read only.", "name": "bytesReceived", "type": "bigint", "meta": { "added": [ "v26.9.0" ], "changes": [] }, "desc": "The total number of application data bytes received. Read only." }, { "textRaw": "Type: {bigint} The total number of application data bytes sent. Read only.", "name": "bytesSent", "type": "bigint", "meta": { "added": [ "v26.9.0" ], "changes": [] }, "desc": "The total number of application data bytes sent. Read only." }, { "textRaw": "Type: {bigint} The total number of application messages received. Read only.", "name": "messagesReceived", "type": "bigint", "meta": { "added": [ "v26.9.0" ], "changes": [] }, "desc": "The total number of application messages received. Read only." }, { "textRaw": "Type: {bigint} The total number of application messages sent. Read only.", "name": "messagesSent", "type": "bigint", "meta": { "added": [ "v26.9.0" ], "changes": [] }, "desc": "The total number of application messages sent. Read only." }, { "textRaw": "Type: {bigint} The total number of DTLS handshake retransmissions. Read only.", "name": "retransmitCount", "type": "bigint", "meta": { "added": [ "v26.9.0" ], "changes": [] }, "desc": "The total number of DTLS handshake retransmissions. Read only." }, { "textRaw": "Type: {boolean}", "name": "isConnected", "type": "boolean", "meta": { "added": [ "v26.9.0" ], "changes": [] }, "desc": "true if the stats object is still connected to the underlying session.\nOnce the session is destroyed, the stats become a stale snapshot.