DTLSSession

Represents a DTLS association with a single remote peer.

session.send(data): number

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

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

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

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

session.close(): Promise

Initiates a graceful DTLS shutdown by sending a close_notify alert.

session.destroy(error?): void

Immediately destroys the session without sending close_notify.

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

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

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

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

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

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

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

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

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

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

import { connect } from 'node:dtls';

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

await session.opened;

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

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

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

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

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

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

Set to receive application data from the peer.

Set to receive error notifications.

Set to receive handshake completion notifications.

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

session[Symbol.asyncDispose](): void

Equivalent to calling session.close().