{"$schema":"https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json","id":"dtls","path":"/dtls","type":"module","module":"dtls","title":"DTLS","introducedIn":"v26.9.0","sourceLink":{"path":"lib/dtls.js","url":"https://github.com/nodejs/node/blob/HEAD/lib/dtls.js"},"stability":{"index":"1.1","description":"Active Development"},"added":["v26.9.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"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.\n\nTo 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.\n\n```bash\nnode --experimental-dtls app.mjs\n```\n\n```mjs\nimport { listen, connect } from 'node:dtls';\n```\n\n```cjs\nconst { listen, connect } = require('node:dtls');\n```","summary":"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.","examples":[{"language":"bash","displayName":null,"code":"node --experimental-dtls app.mjs"},{"language":"mjs","displayName":null,"code":"import { listen, connect } from 'node:dtls';"},{"language":"cjs","displayName":null,"code":"const { listen, connect } = require('node:dtls');"}],"children":[{"kind":"section","id":"permission-model","name":"Permission model","title":"Permission model","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"When using the [Permission Model](permissions.html#permission-model), the `--allow-net` flag must be passed to\nallow DTLS network operations. Without it, calling [`dtls.connect()`](#dtlsconnecthost-port-options) or\n[`dtls.listen()`](#dtlslistencallback-options) will throw an `ERR_ACCESS_DENIED` error.\n\n```console\nnode --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}\n```\n\nCreating a [`DTLSEndpoint`](#class-dtlsendpoint) instance without connecting or listening\nis permitted even without `--allow-net`, since no network I/O occurs until\n[`dtls.connect()`](#dtlsconnecthost-port-options) or [`dtls.listen()`](#dtlslistencallback-options) is called.","summary":"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.","examples":[{"language":"console","displayName":null,"code":"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}"}],"children":[]},{"kind":"section","id":"dtls-vs-tls","name":"DTLS vs TLS","title":"DTLS vs TLS","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"DTLS is designed for UDP transport and differs from TLS in several key ways:\n\n* No stream guarantees: Messages may arrive out of order or be lost.\n  DTLS preserves datagram semantics.\n* One socket, many peers: A single UDP socket can serve multiple DTLS\n  sessions. The `DTLSEndpoint` manages this multiplexing.\n* Cookie exchange: DTLS servers use a stateless cookie mechanism\n  (HelloVerifyRequest) to prevent denial-of-service amplification attacks.\n* Retransmission: DTLS handles handshake retransmission internally since\n  UDP does not guarantee delivery.","summary":"DTLS is designed for UDP transport and differs from TLS in several key ways:","examples":[],"children":[]},{"kind":"method","id":"dtlslistencallback-options","name":"listen","title":"`dtls.listen(callback, options)`","scope":"module","overloadOf":null,"stability":null,"added":["v26.9.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[{"name":"callback","type":{"text":"Function","links":[{"name":"Function","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Function","start":0,"end":8}]},"description":"Called for each new DTLS session accepted by the\nserver.","default":null,"optional":false,"rest":false,"properties":[{"name":"session","type":{"text":"DTLSSession","links":[]},"description":"The new session.","default":null,"optional":false,"rest":false,"properties":[]}]},{"name":"options","type":{"text":"Object","links":[{"name":"Object","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object","start":0,"end":6}]},"description":"","default":null,"optional":false,"rest":false,"properties":[{"name":"cert","type":{"text":"string | Buffer","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6},{"name":"Buffer","href":"buffer.html#class-buffer","start":9,"end":15}]},"description":"Server certificate in PEM format. **Required.**","default":null,"optional":false,"rest":false,"properties":[]},{"name":"key","type":{"text":"string | Buffer","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6},{"name":"Buffer","href":"buffer.html#class-buffer","start":9,"end":15}]},"description":"Server private key in PEM format. **Required.**","default":null,"optional":false,"rest":false,"properties":[]},{"name":"secureContext","type":{"text":"DTLSSecureContext","links":[]},"description":"A context from\n[`dtls.createSecureContext()`](#dtlscreatesecurecontextoptions) to use instead of building one from the\ncredential options below. Must have been created with `isServer: true`.\nCannot be combined with any option the context already carries.","default":null,"optional":false,"rest":false,"properties":[]},{"name":"sni","type":{"text":"Object | Function","links":[{"name":"Object","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object","start":0,"end":6},{"name":"Function","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Function","start":9,"end":17}]},"description":"Server Name Indication. A map of host names to the\nidentity to serve them with, or a function returning one. Cannot be\ncombined with `secureContext`; set it on the context instead. See\n[Server Name Indication](#server-name-indication).","default":null,"optional":false,"rest":false,"properties":[]},{"name":"passphrase","type":{"text":"string","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6}]},"description":"Passphrase to decrypt `key`, if it is encrypted.\nIgnored when `key` is not encrypted. Unlike `key` and `cert`, this must be\na string, matching [`tls.createSecureContext()`](tls.html#tlscreatesecurecontextoptions).","default":null,"optional":false,"rest":false,"properties":[]},{"name":"port","type":{"text":"number","links":[{"name":"number","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type","start":0,"end":6}]},"description":"Port to bind to. **Required.**","default":null,"optional":false,"rest":false,"properties":[]},{"name":"host","type":{"text":"string","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6}]},"description":"Address to bind to.","default":"'0.0.0.0'","optional":true,"rest":false,"properties":[]},{"name":"ca","type":{"text":"string | Buffer | string[] | Buffer[]","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6},{"name":"Buffer","href":"buffer.html#class-buffer","start":9,"end":15},{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":18,"end":24},{"name":"Buffer","href":"buffer.html#class-buffer","start":29,"end":35}]},"description":"CA certificates in PEM format.","default":null,"optional":false,"rest":false,"properties":[]},{"name":"ciphers","type":{"text":"string","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6}]},"description":"OpenSSL cipher list string.","default":null,"optional":false,"rest":false,"properties":[]},{"name":"alpn","type":{"text":"string[] | Buffer","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6},{"name":"Buffer","href":"buffer.html#class-buffer","start":11,"end":17}]},"description":"ALPN protocol names. Each name must be between\n1 and 255 bytes. A `Buffer` must already be in ALPN wire format: one\nlength byte followed by that many bytes, repeated.","default":null,"optional":false,"rest":false,"properties":[]},{"name":"srtp","type":{"text":"string","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6}]},"description":"Colon-separated SRTP protection profile names\n(e.g., `'SRTP_AES128_CM_SHA1_80:SRTP_AEAD_AES_128_GCM'`).","default":null,"optional":false,"rest":false,"properties":[]},{"name":"requestCert","type":{"text":"boolean","links":[{"name":"boolean","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#boolean_type","start":0,"end":7}]},"description":"Request a certificate from the client.","default":"false","optional":true,"rest":false,"properties":[]},{"name":"rejectUnauthorized","type":{"text":"boolean","links":[{"name":"boolean","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#boolean_type","start":0,"end":7}]},"description":"Only has an effect together with\n`requestCert`. When `true`, a client that presents no certificate, or one\nthat does not chain to a trusted CA, is rejected during the handshake and\nreceives a TLS alert. When `false`, the certificate is still requested and\nverified but the handshake completes regardless, leaving the decision to\nthe application via [`session.authorized`](#sessionauthorized).","default":"true","optional":true,"rest":false,"properties":[]},{"name":"mtu","type":{"text":"number","links":[{"name":"number","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type","start":0,"end":6}]},"description":"Maximum size in bytes of a DTLS datagram.","default":"1200","optional":true,"rest":false,"properties":[]},{"name":"handshakeTimeout","type":{"text":"number","links":[{"name":"number","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type","start":0,"end":6}]},"description":"Milliseconds a handshake may take before it is\nabandoned. `0` disables it.","default":"`60000`. See Handshake timeout","optional":true,"rest":false,"properties":[]},{"name":"ipv6Only","type":{"text":"boolean","links":[{"name":"boolean","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#boolean_type","start":0,"end":7}]},"description":"When `true`, an IPv6 endpoint serves IPv6 only. When\n`false`, binding `'::'` also accepts IPv4 peers, which arrive with mapped\naddresses such as `'::ffff:203.0.113.1'` -- anything keyed on the peer\naddress, including `maxSessionsPerHost`, sees them in that form. Has no\neffect on an IPv4 endpoint.","default":"false","optional":true,"rest":false,"properties":[]},{"name":"reusePort","type":{"text":"boolean","links":[{"name":"boolean","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#boolean_type","start":0,"end":7}]},"description":"When `true`, sets `SO_REUSEPORT`, so several\nprocesses may bind the same port and the kernel spreads arriving\ndatagrams between them. Every one of them must set it.","default":"false","optional":true,"rest":false,"properties":[]},{"name":"udpReceiveBufferSize","type":{"text":"number","links":[{"name":"number","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type","start":0,"end":6}]},"description":"Size in bytes for the socket's receive\nbuffer (`SO_RCVBUF`). Raising it gives the endpoint room for bursts that\nthe default would drop. The kernel clamps this to its own maximum.","default":"the system default","optional":true,"rest":false,"properties":[]},{"name":"udpSendBufferSize","type":{"text":"number","links":[{"name":"number","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type","start":0,"end":6}]},"description":"Size in bytes for the socket's send buffer\n(`SO_SNDBUF`). Clamped as above.","default":"the system default","optional":true,"rest":false,"properties":[]},{"name":"udpTTL","type":{"text":"number","links":[{"name":"number","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type","start":0,"end":6}]},"description":"IP time-to-live for outgoing datagrams, from `1` to\n`255`.","default":"the system default","optional":true,"rest":false,"properties":[]},{"name":"maxSessions","type":{"text":"number","links":[{"name":"number","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type","start":0,"end":6}]},"description":"The maximum number of concurrent sessions the\nendpoint will hold. Set to `0` for no limit.","default":"10000","optional":true,"rest":false,"properties":[]},{"name":"maxSessionsPerHost","type":{"text":"number","links":[{"name":"number","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type","start":0,"end":6}]},"description":"The maximum number of concurrent sessions\nfrom any single source IP address, ignoring port. Set to `0` for no limit.","default":"1000","optional":true,"rest":false,"properties":[]},{"name":"sessionIdContext","type":{"text":"string","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6}]},"description":"Opaque identifier scoping resumable sessions\nto this server, at most 32 bytes.","default":"a value derived from `process.argv`, as in `tls.createServer()`","optional":true,"rest":false,"properties":[]}]}],"returns":{"type":{"text":"DTLSEndpoint","links":[]},"description":""}},"description":"Creates a DTLS server bound to the specified address and port. The server\nuses automatic HMAC-based cookie exchange for DoS protection. See\n[Denial of service](#denial-of-service).\n\nBinding failures are thrown with the code the operating system gave, as in\n`net` and `dgram`: an address already in use throws an error whose `code` is\n`'EADDRINUSE'`, with `errno` and `syscall` set.\n\n```mjs\nimport { 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);\n```","summary":"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.","examples":[{"language":"mjs","displayName":null,"code":"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);"}],"children":[]},{"kind":"method","id":"dtlsconnecthost-port-options","name":"connect","title":"`dtls.connect(host, port[, options])`","scope":"module","overloadOf":null,"stability":null,"added":["v26.9.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[{"name":"host","type":{"text":"string","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6}]},"description":"Remote host to connect to, as an IPv4 or IPv6 literal.\nHost names are not resolved.","default":null,"optional":false,"rest":false,"properties":[]},{"name":"port","type":{"text":"number","links":[{"name":"number","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type","start":0,"end":6}]},"description":"Remote port to connect to.","default":null,"optional":false,"rest":false,"properties":[]},{"name":"options","type":{"text":"Object","links":[{"name":"Object","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object","start":0,"end":6}]},"description":"","default":null,"optional":true,"rest":false,"properties":[{"name":"ca","type":{"text":"string | Buffer | string[] | Buffer[]","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6},{"name":"Buffer","href":"buffer.html#class-buffer","start":9,"end":15},{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":18,"end":24},{"name":"Buffer","href":"buffer.html#class-buffer","start":29,"end":35}]},"description":"CA certificates in PEM format.","default":null,"optional":false,"rest":false,"properties":[]},{"name":"cert","type":{"text":"string | Buffer","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6},{"name":"Buffer","href":"buffer.html#class-buffer","start":9,"end":15}]},"description":"Client certificate in PEM format.","default":null,"optional":false,"rest":false,"properties":[]},{"name":"key","type":{"text":"string | Buffer","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6},{"name":"Buffer","href":"buffer.html#class-buffer","start":9,"end":15}]},"description":"Client private key in PEM format.","default":null,"optional":false,"rest":false,"properties":[]},{"name":"secureContext","type":{"text":"DTLSSecureContext","links":[]},"description":"A context from\n[`dtls.createSecureContext()`](#dtlscreatesecurecontextoptions) to use instead of building one from the\ncredential options below. Must **not** have been created with\n`isServer: true`. Cannot be combined with any option the context already\ncarries.","default":null,"optional":false,"rest":false,"properties":[]},{"name":"psk","type":{"text":"Object | Function","links":[{"name":"Object","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object","start":0,"end":6},{"name":"Function","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Function","start":9,"end":17}]},"description":"A pre-shared key as `{ identity, key }`, or a\nfunction returning one. See [Pre-shared keys](#pre-shared-keys).","default":null,"optional":false,"rest":false,"properties":[]},{"name":"session","type":{"text":"Buffer","links":[{"name":"Buffer","href":"buffer.html#class-buffer","start":0,"end":6}]},"description":"A session from [`session.session`](#sessionsession) on an earlier\nconnection, to resume rather than handshake in full. See\n[Session resumption](#session-resumption).","default":null,"optional":false,"rest":false,"properties":[]},{"name":"passphrase","type":{"text":"string","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6}]},"description":"Passphrase to decrypt `key`, if it is encrypted.\nIgnored when `key` is not encrypted. Unlike `key` and `cert`, this must be\na string, matching [`tls.createSecureContext()`](tls.html#tlscreatesecurecontextoptions).","default":null,"optional":false,"rest":false,"properties":[]},{"name":"rejectUnauthorized","type":{"text":"boolean","links":[{"name":"boolean","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#boolean_type","start":0,"end":7}]},"description":"When `true`, the server's certificate must\nboth chain to a trusted CA and match the expected identity (`servername`,\nor `host` when `servername` is not set); otherwise the handshake is\naborted and `session.opened` rejects. When `false`, the certificate is\nstill verified and the handshake completes regardless, leaving the\ndecision to the application via [`session.authorized`](#sessionauthorized) and\n[`session.authorizationError`](#sessionauthorizationerror).","default":"true","optional":true,"rest":false,"properties":[]},{"name":"servername","type":{"text":"string","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6}]},"description":"Server name used for the SNI (Server Name\nIndication) extension and as the identity checked during certificate\nverification.","default":"the `host` argument. Set to `''` to disable SNI. SNI is never sent for IP address literals","optional":true,"rest":false,"properties":[]},{"name":"bindHost","type":{"text":"string","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6}]},"description":"Local bind address.","default":"`'::'` when `host` is an IPv6 literal, otherwise `'0.0.0.0'`. The local socket must be in the same address family as the peer","optional":true,"rest":false,"properties":[]},{"name":"bindPort","type":{"text":"number","links":[{"name":"number","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type","start":0,"end":6}]},"description":"Local bind port.","default":"`0` (ephemeral)","optional":true,"rest":false,"properties":[]},{"name":"alpn","type":{"text":"string[] | Buffer","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6},{"name":"Buffer","href":"buffer.html#class-buffer","start":11,"end":17}]},"description":"ALPN protocol names. Each name must be between\n1 and 255 bytes. A `Buffer` must already be in ALPN wire format: one\nlength byte followed by that many bytes, repeated.","default":null,"optional":false,"rest":false,"properties":[]},{"name":"srtp","type":{"text":"string","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6}]},"description":"SRTP protection profile names.","default":null,"optional":false,"rest":false,"properties":[]},{"name":"mtu","type":{"text":"number","links":[{"name":"number","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type","start":0,"end":6}]},"description":"Maximum size in bytes of a DTLS datagram.","default":"1200","optional":true,"rest":false,"properties":[]},{"name":"handshakeTimeout","type":{"text":"number","links":[{"name":"number","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type","start":0,"end":6}]},"description":"Milliseconds a handshake may take before it is\nabandoned and `session.opened` rejects. `0` disables it.","default":"`60000`. See Handshake timeout","optional":true,"rest":false,"properties":[]}]}],"returns":{"type":{"text":"DTLSSession","links":[]},"description":""}},"description":"Connects to a DTLS server. Returns a `DTLSSession` whose `opened` property\nis a `Promise` that resolves when the handshake completes.\n\n```mjs\nimport { 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};\n```","summary":"Connects to a DTLS server. Returns a `DTLSSession` whose `opened` property is a `Promise` that resolves when the handshake completes.","examples":[{"language":"mjs","displayName":null,"code":"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};"}],"children":[]},{"kind":"method","id":"dtlscreatesecurecontextoptions","name":"createSecureContext","title":"`dtls.createSecureContext([options])`","scope":"module","overloadOf":null,"stability":null,"added":["v26.10.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[{"name":"options","type":{"text":"Object","links":[{"name":"Object","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object","start":0,"end":6}]},"description":"","default":null,"optional":true,"rest":false,"properties":[{"name":"alpn","type":{"text":"string[]","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6}]},"description":"ALPN protocols.","default":null,"optional":false,"rest":false,"properties":[]},{"name":"ca","type":{"text":"string | Buffer | Array","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6},{"name":"Buffer","href":"buffer.html#class-buffer","start":9,"end":15},{"name":"Array","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array","start":18,"end":23}]},"description":"CA certificates in PEM format. When omitted,\nthe bundled default certificate authorities are used.","default":null,"optional":false,"rest":false,"properties":[]},{"name":"cert","type":{"text":"string | Buffer","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6},{"name":"Buffer","href":"buffer.html#class-buffer","start":9,"end":15}]},"description":"Certificate in PEM format.","default":null,"optional":false,"rest":false,"properties":[]},{"name":"ciphers","type":{"text":"string","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6}]},"description":"OpenSSL cipher suite list.","default":null,"optional":false,"rest":false,"properties":[]},{"name":"ecdhCurve","type":{"text":"string","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6}]},"description":"Named curve or curve list for ECDH.","default":null,"optional":false,"rest":false,"properties":[]},{"name":"isServer","type":{"text":"boolean","links":[{"name":"boolean","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#boolean_type","start":0,"end":7}]},"description":"Build a context for a server.","default":"false","optional":true,"rest":false,"properties":[]},{"name":"key","type":{"text":"string | Buffer","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6},{"name":"Buffer","href":"buffer.html#class-buffer","start":9,"end":15}]},"description":"Private key in PEM format.","default":null,"optional":false,"rest":false,"properties":[]},{"name":"passphrase","type":{"text":"string","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6}]},"description":"Passphrase for `key`, if it is encrypted.","default":null,"optional":false,"rest":false,"properties":[]},{"name":"rejectUnauthorized","type":{"text":"boolean","links":[{"name":"boolean","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#boolean_type","start":0,"end":7}]},"description":"Verification behaviour, as for\n[`dtls.listen()`](#dtlslistencallback-options) and [`dtls.connect()`](#dtlsconnecthost-port-options).","default":null,"optional":false,"rest":false,"properties":[]},{"name":"requestCert","type":{"text":"boolean","links":[{"name":"boolean","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#boolean_type","start":0,"end":7}]},"description":"Request a certificate from the peer. Servers only.","default":null,"optional":false,"rest":false,"properties":[]},{"name":"sessionIdContext","type":{"text":"string","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6}]},"description":"Session id context. Servers only.","default":null,"optional":false,"rest":false,"properties":[]},{"name":"sni","type":{"text":"Object | Function","links":[{"name":"Object","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object","start":0,"end":6},{"name":"Function","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Function","start":9,"end":17}]},"description":"Server Name Indication. Servers only. See\n[Server Name Indication](#server-name-indication).","default":null,"optional":false,"rest":false,"properties":[]},{"name":"psk","type":{"text":"Object | Function","links":[{"name":"Object","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object","start":0,"end":6},{"name":"Function","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Function","start":9,"end":17}]},"description":"Pre-shared keys. See [Pre-shared keys](#pre-shared-keys).","default":null,"optional":false,"rest":false,"properties":[]},{"name":"pskIdentityHint","type":{"text":"string","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6}]},"description":"Identity hint to advertise, naming which key a\nclient should pick. Requires `psk`. Servers only.","default":null,"optional":false,"rest":false,"properties":[]},{"name":"srtp","type":{"text":"string","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6}]},"description":"SRTP profile list.","default":null,"optional":false,"rest":false,"properties":[]},{"name":"ticketKeys","type":{"text":"Buffer","links":[{"name":"Buffer","href":"buffer.html#class-buffer","start":0,"end":6}]},"description":"Session ticket keys, for resuming sessions across\nendpoints and restarts. Servers only. See [Session resumption](#session-resumption).","default":null,"optional":false,"rest":false,"properties":[]}]}],"returns":{"type":{"text":"DTLSSecureContext","links":[]},"description":""}},"description":"Options 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.\n\nCreates a reusable secure context. Pass it to [`dtls.listen()`](#dtlslistencallback-options) or\n[`dtls.connect()`](#dtlsconnecthost-port-options) as `secureContext` in place of the credential options.\n\nA 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.\n\nThe 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.\n\n`isServer` is fixed when the context is created, because it selects the\nunderlying OpenSSL method. Passing a server context to [`dtls.connect()`](#dtlsconnecthost-port-options),\nor a client context to [`dtls.listen()`](#dtlslistencallback-options), throws.\n\n```mjs\nimport { 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});\n```","summary":"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.","examples":[{"language":"mjs","displayName":null,"code":"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});"}],"children":[]},{"kind":"section","id":"server-name-indication","name":"Server Name Indication","title":"Server Name Indication","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"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\n[`DTLSSecureContext`](#class-dtlssecurecontext) created with `isServer: true`, or a plain object of\nthe same options [`dtls.createSecureContext()`](#dtlscreatesecurecontextoptions) takes:\n\n```mjs\nimport { 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});\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()`](tls.html#tlscreateserveroptions-secureconnectionlistener) differs here: its\n`SNICallback` falls back to the default identity silently.\n\nVerification follows the selected identity, so an entry carrying its own `ca`\naccepts only client certificates issued under it. `requestCert` and\n`rejectUnauthorized` are not per-identity: they belong to the endpoint and\napply to every name it serves.\n\nA function may be given instead of a map, for identities that are chosen\nrather than enumerated:\n\n```mjs\nlisten(onsession, {\n  port: 5684,\n  cert,\n  key,\n  sni: (servername) => contexts.get(servername),\n});\n```\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\n[`dtls.createSecureContext()`](#dtlscreatesecurecontextoptions) 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.\n\nThe 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.\n\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.\n\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.\n\n`sni` belongs to the secure context rather than to the endpoint, so it can be\ngiven to [`dtls.createSecureContext()`](#dtlscreatesecurecontextoptions) and cannot be combined with a\n`secureContext` 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.\n\nA 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.","summary":"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:","examples":[{"language":"mjs","displayName":null,"code":"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});"},{"language":"mjs","displayName":null,"code":"listen(onsession, {\n  port: 5684,\n  cert,\n  key,\n  sni: (servername) => contexts.get(servername),\n});"}],"children":[]},{"kind":"section","id":"denial-of-service","name":"Denial of service","title":"Denial of service","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"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\n[`endpointStats.serverRefusedCount`](#endpointstatsserverrefusedcount).\n\nDeployments serving many clients behind a single NAT may need to raise\n`maxSessionsPerHost`.","summary":"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`.","examples":[],"children":[]},{"kind":"section","id":"handshake-timeout","name":"Handshake timeout","title":"Handshake timeout","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"A handshake that never finishes is abandoned after `handshakeTimeout`\nmilliseconds, and its session error is `DTLS handshake timeout`.\n\nOpenSSL 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\n[Denial of service](#denial-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.\n\nThe 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.\n\nThe timeout covers resumed and PSK handshakes as well, and stops applying once\nthe handshake completes; it is not an idle timeout.\n\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.","summary":"A handshake that never finishes is abandoned after `handshakeTimeout` milliseconds, and its session error is `DTLS handshake timeout`.","examples":[],"children":[]},{"kind":"section","id":"pre-shared-keys","name":"Pre-shared keys","title":"Pre-shared keys","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"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.\n\nA server gives the identities it accepts; a client gives the one it is. No\ncertificate is needed on either side:\n\n```mjs\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});\n```\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 }`:\n\n```mjs\nlisten(onsession, {\n  port: 5684,\n  psk: (identity) => deriveKey(masterSecret, identity),\n});\n```\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.\n\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.","summary":"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.","examples":[{"language":"mjs","displayName":null,"code":"import { 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});"},{"language":"mjs","displayName":null,"code":"listen(onsession, {\n  port: 5684,\n  psk: (identity) => deriveKey(masterSecret, identity),\n});"}],"children":[{"kind":"section","id":"cipher-suites","name":"Cipher suites","title":"Cipher suites","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"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.\n\nA 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.\n\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.\n\nCoAP 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:\n\n```mjs\nlisten(onsession, { port: 5684, psk, ciphers: 'PSK-AES128-CCM8@SECLEVEL=0' });\n```","summary":"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.","examples":[{"language":"mjs","displayName":null,"code":"listen(onsession, { port: 5684, psk, ciphers: 'PSK-AES128-CCM8@SECLEVEL=0' });"}],"children":[]},{"kind":"section","id":"failure-modes","name":"Failure modes","title":"Failure modes","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"A 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.\n\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`](#handshake-timeout), after 60 seconds by default.\n\nAn identity the server does not recognise is refused outright, and the client\nsees the handshake fail.","summary":"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.","examples":[],"children":[]}]},{"kind":"section","id":"session-resumption","name":"Session resumption","title":"Session resumption","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"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.\n\nA client reads [`session.session`](#sessionsession) once the session is open and passes it to\na later [`dtls.connect()`](#dtlsconnecthost-port-options):\n\n```mjs\nimport { 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.\n```\n\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\n[`session.reused`](#sessionreused) is `false`.\n\nThe cookie exchange still happens for a resumed handshake, so resumption is not\na way around the address validation described under [Denial of service](#denial-of-service).","summary":"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.","examples":[{"language":"mjs","displayName":null,"code":"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."}],"children":[{"kind":"section","id":"binding-to-the-authenticated-host","name":"Binding to the authenticated host","title":"Binding to the authenticated host","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"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.\n\nThis 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`](#sessionsession) is rejected outright: nothing\nrecords which identity it belongs to, so it cannot be checked.","summary":"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.","examples":[],"children":[]},{"kind":"section","id":"resuming-under-rejectunauthorized","name":"Resuming under rejectUnauthorized","title":"Resuming under `rejectUnauthorized`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"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:\n\n```mjs\nimport { 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.\n```\n\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`](#sessionauthorized) and [`session.authorizationError`](#sessionauthorizationerror) report\nthe recorded result on a resumed session either way.","summary":"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:","examples":[{"language":"mjs","displayName":null,"code":"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."}],"children":[]},{"kind":"section","id":"ticket-keys","name":"Ticket keys","title":"Ticket keys","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"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:\n\n```mjs\nimport { 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 });\n```\n\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()`](tls.html#tlscreateserveroptions-secureconnectionlistener) uses, which is a layout\n`node:tls` defines for itself. Supplying the wrong length throws and reports\nthe length expected.\n\nTicket 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.","summary":"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:","examples":[{"language":"mjs","displayName":null,"code":"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 });"}],"children":[]}]},{"kind":"class","id":"class-dtlssecurecontext","name":"DTLSSecureContext","title":"Class: `DTLSSecureContext`","scope":"module","overloadOf":null,"stability":null,"added":["v26.10.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"extends":null,"description":"An opaque, reusable bundle of credentials and TLS settings, created by\n[`dtls.createSecureContext()`](#dtlscreatesecurecontextoptions). It cannot be constructed directly.","summary":"An opaque, reusable bundle of credentials and TLS settings, created by `dtls.createSecureContext()`. It cannot be constructed directly.","examples":[],"children":[{"kind":"property","id":"securecontextisserver","name":"isServer","title":"`secureContext.isServer`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"boolean","links":[{"name":"boolean","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#boolean_type","start":0,"end":7}]},"default":null,"description":"`true` if the context was created for a server.","summary":"","examples":[],"children":[]}]},{"kind":"class","id":"class-dtlsendpoint","name":"DTLSEndpoint","title":"Class: `DTLSEndpoint`","scope":"module","overloadOf":null,"stability":null,"added":["v26.9.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"extends":null,"description":"Manages a UDP socket and multiplexes DTLS sessions.","summary":"Manages a UDP socket and multiplexes DTLS sessions.","examples":[],"children":[{"kind":"property","id":"endpointaddress","name":"address","title":"`endpoint.address`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"Object","links":[{"name":"Object","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object","start":0,"end":6}]},"default":null,"description":"`{ address, family, port }`\n\nThe local address the endpoint is bound to.","summary":"The local address the endpoint is bound to.","examples":[],"children":[]},{"kind":"property","id":"endpointstats","name":"stats","title":"`endpoint.stats`","scope":"module","overloadOf":null,"stability":null,"added":["v26.9.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"DTLSEndpoint.Stats","links":[{"name":"DTLSEndpoint.Stats","href":"DTLSEndpoint.html#class-dtlsendpointstats","start":0,"end":18}]},"default":null,"description":"The statistics collected for this endpoint. Read only. The stats object is\nlive and updated as data flows through the endpoint.","summary":"The statistics collected for this endpoint. Read only. The stats object is live and updated as data flows through the endpoint.","examples":[],"children":[]},{"kind":"property","id":"endpointbusy","name":"busy","title":"`endpoint.busy`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"boolean","links":[{"name":"boolean","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#boolean_type","start":0,"end":7}]},"default":null,"description":"When `true`, the endpoint rejects new incoming connections. Can be set\nto implement backpressure.","summary":"When `true`, the endpoint rejects new incoming connections. Can be set to implement backpressure.","examples":[],"children":[]},{"kind":"method","id":"endpointclose","name":"close","title":"`endpoint.close()`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[],"returns":{"type":{"text":"Promise","links":[{"name":"Promise","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise","start":0,"end":7}]},"description":"Resolves when the endpoint is fully closed."}},"description":"Gracefully closes the endpoint. All active sessions are closed with\n`close_notify` alerts before the UDP socket is released.","summary":"Gracefully closes the endpoint. All active sessions are closed with `close_notify` alerts before the UDP socket is released.","examples":[],"children":[]},{"kind":"method","id":"endpointdestroyerror","name":"destroy","title":"`endpoint.destroy([error])`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[{"name":"error","type":null,"description":"","default":null,"optional":true,"rest":false,"properties":[]}],"returns":null},"description":"Immediately destroys the endpoint without sending `close_notify` alerts.","summary":"Immediately destroys the endpoint without sending `close_notify` alerts.","examples":[],"children":[]},{"kind":"property","id":"endpointdestroyed","name":"destroyed","title":"`endpoint.destroyed`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"boolean","links":[{"name":"boolean","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#boolean_type","start":0,"end":7}]},"default":null,"description":"True once the endpoint has been destroyed.","summary":"","examples":[],"children":[]},{"kind":"property","id":"endpointclosed","name":"closed","title":"`endpoint.closed`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"Promise","links":[{"name":"Promise","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise","start":0,"end":7}]},"default":null,"description":"Resolves when the endpoint has fully closed.","summary":"","examples":[],"children":[]},{"kind":"method","id":"endpointsymbolasyncdispose","name":"[Symbol.asyncDispose]","title":"`endpoint[Symbol.asyncDispose]()`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[],"returns":null},"description":"Equivalent to calling `endpoint.close()`.","summary":"Equivalent to calling `endpoint.close()`.","examples":[],"children":[]}]},{"kind":"class","id":"class-dtlsendpointstats","name":"Stats","title":"Class: `DTLSEndpoint.Stats`","scope":"module","overloadOf":null,"stability":null,"added":["v26.9.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"extends":null,"description":"A view of the collected statistics for an endpoint.","summary":"A view of the collected statistics for an endpoint.","examples":[],"children":[{"kind":"property","id":"endpointstatscreatedat","name":"createdAt","title":"`endpointStats.createdAt`","scope":"module","overloadOf":null,"stability":null,"added":["v26.9.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"bigint","links":[{"name":"bigint","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type","start":0,"end":6}]},"default":null,"description":"A timestamp indicating when the endpoint was created. Read only.","summary":"","examples":[],"children":[]},{"kind":"property","id":"endpointstatsdestroyedat","name":"destroyedAt","title":"`endpointStats.destroyedAt`","scope":"module","overloadOf":null,"stability":null,"added":["v26.9.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"bigint","links":[{"name":"bigint","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type","start":0,"end":6}]},"default":null,"description":"A timestamp indicating when the endpoint was destroyed. Read only.","summary":"","examples":[],"children":[]},{"kind":"property","id":"endpointstatsbytesreceived","name":"bytesReceived","title":"`endpointStats.bytesReceived`","scope":"module","overloadOf":null,"stability":null,"added":["v26.9.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"bigint","links":[{"name":"bigint","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type","start":0,"end":6}]},"default":null,"description":"The total number of bytes received by this endpoint. Read only.","summary":"","examples":[],"children":[]},{"kind":"property","id":"endpointstatsbytessent","name":"bytesSent","title":"`endpointStats.bytesSent`","scope":"module","overloadOf":null,"stability":null,"added":["v26.9.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"bigint","links":[{"name":"bigint","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type","start":0,"end":6}]},"default":null,"description":"The total number of bytes sent by this endpoint. Read only.","summary":"","examples":[],"children":[]},{"kind":"property","id":"endpointstatspacketsreceived","name":"packetsReceived","title":"`endpointStats.packetsReceived`","scope":"module","overloadOf":null,"stability":null,"added":["v26.9.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"bigint","links":[{"name":"bigint","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type","start":0,"end":6}]},"default":null,"description":"The total number of UDP packets received by this endpoint. Read only.","summary":"","examples":[],"children":[]},{"kind":"property","id":"endpointstatspacketssent","name":"packetsSent","title":"`endpointStats.packetsSent`","scope":"module","overloadOf":null,"stability":null,"added":["v26.9.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"bigint","links":[{"name":"bigint","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type","start":0,"end":6}]},"default":null,"description":"The total number of UDP packets sent by this endpoint. Read only.","summary":"","examples":[],"children":[]},{"kind":"property","id":"endpointstatsserversessions","name":"serverSessions","title":"`endpointStats.serverSessions`","scope":"module","overloadOf":null,"stability":null,"added":["v26.9.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"bigint","links":[{"name":"bigint","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type","start":0,"end":6}]},"default":null,"description":"The total number of peer-initiated sessions accepted by this\nendpoint. Read only.","summary":"","examples":[],"children":[]},{"kind":"property","id":"endpointstatsclientsessions","name":"clientSessions","title":"`endpointStats.clientSessions`","scope":"module","overloadOf":null,"stability":null,"added":["v26.9.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"bigint","links":[{"name":"bigint","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type","start":0,"end":6}]},"default":null,"description":"The total number of sessions initiated by this endpoint. Read only.","summary":"","examples":[],"children":[]},{"kind":"property","id":"endpointstatsserverbusycount","name":"serverBusyCount","title":"`endpointStats.serverBusyCount`","scope":"module","overloadOf":null,"stability":null,"added":["v26.9.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"bigint","links":[{"name":"bigint","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type","start":0,"end":6}]},"default":null,"description":"The total number of incoming connections rejected because the\nendpoint was marked busy. Read only.","summary":"","examples":[],"children":[]},{"kind":"property","id":"endpointstatsserverrejectedcount","name":"serverRejectedCount","title":"`endpointStats.serverRejectedCount`","scope":"module","overloadOf":null,"stability":null,"added":["v26.10.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"bigint","links":[{"name":"bigint","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type","start":0,"end":6}]},"default":null,"description":"The number of datagrams discarded before a handshake was\nattempted because they could not be a ClientHello. Read only.\n\nDatagrams 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.","summary":"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.","examples":[],"children":[]},{"kind":"property","id":"endpointstatsserverrefusedcount","name":"serverRefusedCount","title":"`endpointStats.serverRefusedCount`","scope":"module","overloadOf":null,"stability":null,"added":["v26.10.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"bigint","links":[{"name":"bigint","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type","start":0,"end":6}]},"default":null,"description":"The number of otherwise valid handshake attempts refused\nbecause the endpoint was at `maxSessions` or the peer was at\n`maxSessionsPerHost`. Read only.","summary":"","examples":[],"children":[]},{"kind":"property","id":"endpointstatsisconnected","name":"isConnected","title":"`endpointStats.isConnected`","scope":"module","overloadOf":null,"stability":null,"added":["v26.9.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"boolean","links":[{"name":"boolean","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#boolean_type","start":0,"end":7}]},"default":null,"description":"`true` if the stats object is still connected to the underlying endpoint.\nOnce the endpoint is destroyed, the stats become a stale snapshot.","summary":"`true` if the stats object is still connected to the underlying endpoint. Once the endpoint is destroyed, the stats become a stale snapshot.","examples":[],"children":[]}]},{"kind":"class","id":"class-dtlssession","name":"DTLSSession","title":"Class: `DTLSSession`","scope":"module","overloadOf":null,"stability":null,"added":["v26.9.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"extends":null,"description":"Represents a DTLS association with a single remote peer.","summary":"Represents a DTLS association with a single remote peer.","examples":[],"children":[{"kind":"method","id":"sessionsenddata","name":"send","title":"`session.send(data)`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[{"name":"data","type":{"text":"string | Buffer | TypedArray | DataView","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6},{"name":"Buffer","href":"buffer.html#class-buffer","start":9,"end":15},{"name":"TypedArray","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/TypedArray","start":18,"end":28},{"name":"DataView","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/DataView","start":31,"end":39}]},"description":"The data to send. At most 16384\nbytes. A view sends the bytes it covers, so an offset or a subarray is sent\nas given rather than as the whole buffer behind it.","default":null,"optional":false,"rest":false,"properties":[]}],"returns":{"type":{"text":"number","links":[{"name":"number","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type","start":0,"end":6}]},"description":"The number of bytes written to the DTLS layer."}},"description":"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).\n\nDTLS carries application data in a single record per datagram and does not\nfragment it, so `data` must fit in one record. Sending more throws\n`ERR_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.\n\nThrows `ERR_INVALID_STATE` if the handshake has not completed, or if the\nsession is closed or destroyed.\n\nA 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.","summary":"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).","examples":[],"children":[]},{"kind":"method","id":"sessionclose","name":"close","title":"`session.close()`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[],"returns":{"type":{"text":"Promise","links":[{"name":"Promise","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise","start":0,"end":7}]},"description":"Resolves when the session is closed."}},"description":"Initiates a graceful DTLS shutdown by sending a `close_notify` alert.","summary":"Initiates a graceful DTLS shutdown by sending a `close_notify` alert.","examples":[],"children":[]},{"kind":"method","id":"sessiondestroyerror","name":"destroy","title":"`session.destroy([error])`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[{"name":"error","type":null,"description":"","default":null,"optional":true,"rest":false,"properties":[]}],"returns":null},"description":"Immediately destroys the session without sending `close_notify`.","summary":"Immediately destroys the session without sending `close_notify`.","examples":[],"children":[]},{"kind":"property","id":"sessiondestroyed","name":"destroyed","title":"`session.destroyed`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"boolean","links":[{"name":"boolean","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#boolean_type","start":0,"end":7}]},"default":null,"description":"True once the session has been destroyed, whether by\n[`session.destroy()`](#sessiondestroyerror), by a close, or by its endpoint going away.","summary":"","examples":[],"children":[]},{"kind":"property","id":"sessionendpoint","name":"endpoint","title":"`session.endpoint`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"DTLSEndpoint","links":[]},"default":null,"description":"The endpoint carrying this session. For a session from\n[`dtls.listen()`](#dtlslistencallback-options) this is the listening endpoint, shared with every other\nsession on it; for one from [`dtls.connect()`](#dtlsconnecthost-port-options) it is the endpoint created\nto carry that session alone.","summary":"","examples":[],"children":[]},{"kind":"property","id":"sessionservername","name":"servername","title":"`session.servername`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"string | undefined","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6},{"name":"undefined","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#undefined_type","start":9,"end":18}]},"default":null,"description":"The server name for this session: the name the client\nsent in the SNI extension, read on either side of the connection.\n`undefined` when no name was sent. See [Server name indication](#server-name-indication).","summary":"","examples":[],"children":[]},{"kind":"property","id":"sessionopened","name":"opened","title":"`session.opened`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"Promise","links":[{"name":"Promise","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise","start":0,"end":7}]},"default":null,"description":"Resolves with `{ protocol }` when the DTLS handshake completes.\n\nRejects if the handshake fails, and also if the session is closed or\ndestroyed before the handshake completes -- in that case with\n`ERR_INVALID_STATE`, or with the error passed to\n[`session.destroy()`](#sessiondestroyerror) if one was given. The promise always settles, so\nawaiting it cannot hang.","summary":"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.","examples":[],"children":[]},{"kind":"property","id":"sessionclosed","name":"closed","title":"`session.closed`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"Promise","links":[{"name":"Promise","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise","start":0,"end":7}]},"default":null,"description":"Settles when the session is fully closed. Resolves when the close\nwas graceful, and rejects with the error when the session was destroyed with\none, or when its endpoint was. The promise always settles, so awaiting it\ncannot hang.","summary":"","examples":[],"children":[]},{"kind":"property","id":"sessionremoteaddress","name":"remoteAddress","title":"`session.remoteAddress`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"Object","links":[{"name":"Object","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object","start":0,"end":6}]},"default":null,"description":"`{ address, family, port }`","summary":"","examples":[],"children":[]},{"kind":"property","id":"sessionprotocol","name":"protocol","title":"`session.protocol`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"string","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6}]},"default":null,"description":"The negotiated DTLS protocol version\n(e.g., `'DTLSv1.2'`).","summary":"","examples":[],"children":[]},{"kind":"property","id":"sessioncipher","name":"cipher","title":"`session.cipher`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"Object","links":[{"name":"Object","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object","start":0,"end":6}]},"default":null,"description":"`{ name, standardName, version }`","summary":"","examples":[],"children":[]},{"kind":"property","id":"sessionpeercertificate","name":"peerCertificate","title":"`session.peerCertificate`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"string | undefined","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6},{"name":"undefined","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#undefined_type","start":9,"end":18}]},"default":null,"description":"The peer's certificate in PEM format, or\n`undefined` if the peer sent none.\n\nThis is the leaf certificate as PEM text and nothing else. For the issuer chain\nand the parsed fields, use [`session.peerX509Certificate`](#sessionpeerx509certificate), whose `toString()`\nreturns this same PEM. Use [`session.authorized`](#sessionauthorized) and\n[`session.authorizationError`](#sessionauthorizationerror) for the verification result rather than\nparsing either.","summary":"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.","examples":[],"children":[]},{"kind":"property","id":"sessionpeerx509certificate","name":"peerX509Certificate","title":"`session.peerX509Certificate`","scope":"module","overloadOf":null,"stability":null,"added":["v26.10.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"X509Certificate | undefined","links":[{"name":"X509Certificate","href":"crypto.html#class-x509certificate","start":0,"end":15},{"name":"undefined","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#undefined_type","start":18,"end":27}]},"default":null,"description":"The peer's certificate, or `undefined`\nif the peer sent none.\n\nAn [`X509Certificate`](crypto.html#class-x509certificate) for the peer's leaf certificate. The issuer chain is\nreachable through its `issuerCertificate` property, and the parsed fields --\n`subject`, `issuer`, `validFrom`, `validTo`, `fingerprint256`, `serialNumber`\nand the rest -- are properties of that object.\n\nWhere [`tls.TLSSocket.getPeerCertificate()`](tls.html#tlssocketgetpeercertificatedetailed) returns a plain dictionary with\n`valid_from`, `valid_to` and a chain walked through `issuerCertificate`, this\nreturns the same `X509Certificate` class that\n[`tls.TLSSocket.getPeerX509Certificate()`](tls.html#tlssocketgetpeerx509certificate) does. Call `toLegacyObject()` on\nit to get the dictionary form.\n\nThe same object is returned on every access once the peer's certificate is\navailable.","summary":"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.","examples":[],"children":[]},{"kind":"property","id":"sessionsession","name":"session","title":"`session.session`","scope":"module","overloadOf":null,"stability":null,"added":["v26.10.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"Buffer | undefined","links":[{"name":"Buffer","href":"buffer.html#class-buffer","start":0,"end":6},{"name":"undefined","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#undefined_type","start":9,"end":18}]},"default":null,"description":"An opaque session for resuming this connection\nlater, or `undefined` on a server session or before the handshake completes.\n\nPass it as the `session` option to a later [`dtls.connect()`](#dtlsconnecthost-port-options). It is bound to\nthe host this connection authenticated against and is refused elsewhere; see\n[Session resumption](#session-resumption).\n\nServer sessions return `undefined`: a server has no identity to bind the value\nto, and it is the client that carries a session between connections.","summary":"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.","examples":[],"children":[]},{"kind":"property","id":"sessionreused","name":"reused","title":"`session.reused`","scope":"module","overloadOf":null,"stability":null,"added":["v26.10.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"boolean","links":[{"name":"boolean","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#boolean_type","start":0,"end":7}]},"default":null,"description":"`true` if this connection resumed an earlier session\nrather than performing a full handshake.\n\nLike [`session.authorized`](#sessionauthorized), this reads `false` once the session is closed.","summary":"Like `session.authorized`, this reads `false` once the session is closed.","examples":[],"children":[]},{"kind":"property","id":"sessionauthorized","name":"authorized","title":"`session.authorized`","scope":"module","overloadOf":null,"stability":null,"added":["v26.10.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"boolean","links":[{"name":"boolean","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#boolean_type","start":0,"end":7}]},"default":null,"description":"`true` if the peer presented a certificate chain that\nverified against the configured certificate authorities, and, for a client,\nmatched the requested identity. `false` before the handshake completes.","summary":"","examples":[],"children":[]},{"kind":"property","id":"sessionauthorizationerror","name":"authorizationError","title":"`session.authorizationError`","scope":"module","overloadOf":null,"stability":null,"added":["v26.10.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"string | undefined","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6},{"name":"undefined","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#undefined_type","start":9,"end":18}]},"default":null,"description":"The short X509 verification error code, for\nexample `'CERT_HAS_EXPIRED'` or `'HOSTNAME_MISMATCH'`, or `undefined` if the\npeer's chain verified.\n\nA 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\".\n\nThe 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:\n\n```mjs\nimport { 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}\n```","summary":"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\".","examples":[{"language":"mjs","displayName":null,"code":"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}"}],"children":[]},{"kind":"property","id":"sessionalpnprotocol","name":"alpnProtocol","title":"`session.alpnProtocol`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"string | undefined","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6},{"name":"undefined","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#undefined_type","start":9,"end":18}]},"default":null,"description":"The negotiated ALPN protocol, or `undefined` if\nALPN was not used.\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](https://www.rfc-editor.org/rfc/rfc7301) section 3.2. A\nserver with no `alpn` configured declines the extension instead, and the\nhandshake completes with no protocol negotiated.","summary":"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.","examples":[],"children":[]},{"kind":"property","id":"sessionsrtpprofile","name":"srtpProfile","title":"`session.srtpProfile`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"string | undefined","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6},{"name":"undefined","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#undefined_type","start":9,"end":18}]},"default":null,"description":"The negotiated SRTP protection profile name.","summary":"","examples":[],"children":[]},{"kind":"property","id":"sessionstats","name":"stats","title":"`session.stats`","scope":"module","overloadOf":null,"stability":null,"added":["v26.9.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"DTLSSession.Stats","links":[{"name":"DTLSSession.Stats","href":"DTLSSession.html#class-dtlssessionstats","start":0,"end":17}]},"default":null,"description":"The statistics collected for this session. Read only. The stats object is\nlive and updated as data flows through the session.","summary":"The statistics collected for this session. Read only. The stats object is live and updated as data flows through the session.","examples":[],"children":[]},{"kind":"method","id":"sessionexportkeyingmateriallength-label-context","name":"exportKeyingMaterial","title":"`session.exportKeyingMaterial(length, label[, context])`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[{"name":"length","type":{"text":"number","links":[{"name":"number","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type","start":0,"end":6}]},"description":"Number of bytes to export. Must be an integer between\n`1` and `65536`.","default":null,"optional":false,"rest":false,"properties":[]},{"name":"label","type":{"text":"string","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6}]},"description":"The label for the exported keying material.","default":null,"optional":false,"rest":false,"properties":[]},{"name":"context","type":{"text":"Buffer","links":[{"name":"Buffer","href":"buffer.html#class-buffer","start":0,"end":6}]},"description":"Optional context value.","default":null,"optional":true,"rest":false,"properties":[]}],"returns":{"type":{"text":"Buffer","links":[{"name":"Buffer","href":"buffer.html#class-buffer","start":0,"end":6}]},"description":""}},"description":"Exports keying material from the DTLS session, as defined in\n[RFC 5705](https://www.rfc-editor.org/rfc/rfc5705). This is commonly used with DTLS-SRTP to derive\nencryption keys for media streams.\n\nThrows `ERR_OUT_OF_RANGE` if `length` is outside the accepted range. The upper\nbound is not imposed by [RFC 5705](https://www.rfc-editor.org/rfc/rfc5705); 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).","summary":"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.","examples":[],"children":[]},{"kind":"section","id":"callback-properties","name":"Callback properties","title":"Callback properties","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"","summary":"","examples":[],"children":[{"kind":"property","id":"sessiononmessage","name":"onmessage","title":"`session.onmessage`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"Function","links":[{"name":"Function","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Function","start":0,"end":8}]},"default":null,"description":"Set to receive application data from the peer.","summary":"Set to receive application data from the peer.","examples":[],"children":[]},{"kind":"property","id":"sessiononerror","name":"onerror","title":"`session.onerror`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"Function","links":[{"name":"Function","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Function","start":0,"end":8}]},"default":null,"description":"Set to receive error notifications.","summary":"Set to receive error notifications.","examples":[],"children":[]},{"kind":"property","id":"sessiononhandshake","name":"onhandshake","title":"`session.onhandshake`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"Function","links":[{"name":"Function","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Function","start":0,"end":8}]},"default":null,"description":"Set to receive handshake completion notifications.","summary":"Set to receive handshake completion notifications.","examples":[],"children":[]},{"kind":"property","id":"sessiononkeylog","name":"onkeylog","title":"`session.onkeylog`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"Function","links":[{"name":"Function","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Function","start":0,"end":8}]},"default":null,"description":"Set to receive TLS key log lines (for debugging with Wireshark).","summary":"Set to receive TLS key log lines (for debugging with Wireshark).","examples":[],"children":[]}]},{"kind":"method","id":"sessionsymbolasyncdispose","name":"[Symbol.asyncDispose]","title":"`session[Symbol.asyncDispose]()`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[],"returns":null},"description":"Equivalent to calling `session.close()`.","summary":"Equivalent to calling `session.close()`.","examples":[],"children":[]}]},{"kind":"class","id":"class-dtlssessionstats","name":"Stats","title":"Class: `DTLSSession.Stats`","scope":"module","overloadOf":null,"stability":null,"added":["v26.9.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"extends":null,"description":"A view of the collected statistics for a session.","summary":"A view of the collected statistics for a session.","examples":[],"children":[{"kind":"property","id":"sessionstatscreatedat","name":"createdAt","title":"`sessionStats.createdAt`","scope":"module","overloadOf":null,"stability":null,"added":["v26.9.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"bigint","links":[{"name":"bigint","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type","start":0,"end":6}]},"default":null,"description":"A timestamp indicating when the session was created. Read only.","summary":"","examples":[],"children":[]},{"kind":"property","id":"sessionstatsdestroyedat","name":"destroyedAt","title":"`sessionStats.destroyedAt`","scope":"module","overloadOf":null,"stability":null,"added":["v26.9.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"bigint","links":[{"name":"bigint","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type","start":0,"end":6}]},"default":null,"description":"A timestamp indicating when the session was destroyed. Read only.","summary":"","examples":[],"children":[]},{"kind":"property","id":"sessionstatsclosingat","name":"closingAt","title":"`sessionStats.closingAt`","scope":"module","overloadOf":null,"stability":null,"added":["v26.9.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"bigint","links":[{"name":"bigint","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type","start":0,"end":6}]},"default":null,"description":"A timestamp indicating when `close()` was called. Read only.","summary":"","examples":[],"children":[]},{"kind":"property","id":"sessionstatshandshakecompletedat","name":"handshakeCompletedAt","title":"`sessionStats.handshakeCompletedAt`","scope":"module","overloadOf":null,"stability":null,"added":["v26.9.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"bigint","links":[{"name":"bigint","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type","start":0,"end":6}]},"default":null,"description":"A timestamp indicating when the DTLS handshake completed. Read only.","summary":"","examples":[],"children":[]},{"kind":"property","id":"sessionstatsbytesreceived","name":"bytesReceived","title":"`sessionStats.bytesReceived`","scope":"module","overloadOf":null,"stability":null,"added":["v26.9.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"bigint","links":[{"name":"bigint","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type","start":0,"end":6}]},"default":null,"description":"The total number of application data bytes received. Read only.","summary":"","examples":[],"children":[]},{"kind":"property","id":"sessionstatsbytessent","name":"bytesSent","title":"`sessionStats.bytesSent`","scope":"module","overloadOf":null,"stability":null,"added":["v26.9.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"bigint","links":[{"name":"bigint","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type","start":0,"end":6}]},"default":null,"description":"The total number of application data bytes sent. Read only.","summary":"","examples":[],"children":[]},{"kind":"property","id":"sessionstatsmessagesreceived","name":"messagesReceived","title":"`sessionStats.messagesReceived`","scope":"module","overloadOf":null,"stability":null,"added":["v26.9.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"bigint","links":[{"name":"bigint","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type","start":0,"end":6}]},"default":null,"description":"The total number of application messages received. Read only.","summary":"","examples":[],"children":[]},{"kind":"property","id":"sessionstatsmessagessent","name":"messagesSent","title":"`sessionStats.messagesSent`","scope":"module","overloadOf":null,"stability":null,"added":["v26.9.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"bigint","links":[{"name":"bigint","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type","start":0,"end":6}]},"default":null,"description":"The total number of application messages sent. Read only.","summary":"","examples":[],"children":[]},{"kind":"property","id":"sessionstatsretransmitcount","name":"retransmitCount","title":"`sessionStats.retransmitCount`","scope":"module","overloadOf":null,"stability":null,"added":["v26.9.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"bigint","links":[{"name":"bigint","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type","start":0,"end":6}]},"default":null,"description":"The total number of DTLS handshake retransmissions. Read only.","summary":"","examples":[],"children":[]},{"kind":"property","id":"sessionstatsisconnected","name":"isConnected","title":"`sessionStats.isConnected`","scope":"module","overloadOf":null,"stability":null,"added":["v26.9.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"boolean","links":[{"name":"boolean","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#boolean_type","start":0,"end":7}]},"default":null,"description":"`true` if the stats object is still connected to the underlying session.\nOnce the session is destroyed, the stats become a stale snapshot.","summary":"`true` if the stats object is still connected to the underlying session. Once the session is destroyed, the stats become a stale snapshot.","examples":[],"children":[]}]},{"kind":"section","id":"dtls-srtp-example","name":"DTLS-SRTP example","title":"DTLS-SRTP example","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"DTLS-SRTP is used by WebRTC for media encryption. The DTLS handshake\nnegotiates the SRTP protection profile and provides keying material.\n\n```mjs\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');\n```","summary":"DTLS-SRTP is used by WebRTC for media encryption. The DTLS handshake negotiates the SRTP protection profile and provides keying material.","examples":[{"language":"mjs","displayName":null,"code":"import { 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');"}],"children":[]},{"kind":"section","id":"mtu-considerations","name":"MTU considerations","title":"MTU considerations","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Since 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.\n\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\n[`session.send()`](#sessionsenddata), which is limited by the DTLS record size instead.\n\nThe MTU can be configured via the `mtu` option:\n\n```mjs\n// For a local network where you know the path MTU\nconst endpoint = listen(callback, {\n  // ...\n  mtu: 1400,\n});\n```\n\nThe minimum allowed MTU is 256 bytes. The maximum is 65535.","summary":"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.","examples":[{"language":"mjs","displayName":null,"code":"// For a local network where you know the path MTU\nconst endpoint = listen(callback, {\n  // ...\n  mtu: 1400,\n});"}],"children":[]}]}