dtls.listen

History

dtls.listen(callback, options): DTLSEndpoint

Attributes

callback:Function

Called for each new DTLS session accepted by the server.

session:DTLSSession

The new session.

options:Object

cert:string | Buffer

Server certificate in PEM format. Required.

key:string | Buffer

Server private key in PEM format. Required.

secureContext:DTLSSecureContext

A context from dtls.createSecureContext() to use instead of building one from the credential options below. Must have been created with isServer: true. Cannot be combined with any option the context already carries.

sni:Object | Function

Server Name Indication. A map of host names to the identity to serve them with, or a function returning one. Cannot be combined with secureContext; set it on the context instead. See Server Name Indication.

passphrase:string

Passphrase to decrypt key, if it is encrypted. Ignored when key is not encrypted. Unlike key and cert, this must be a string, matching tls.createSecureContext().

port:number

Port to bind to. Required.

host?:string

Address to bind to. Default: '0.0.0.0'.

ca:string | Buffer | string[] | Buffer[]

CA certificates in PEM format.

ciphers:string

OpenSSL cipher list string.

alpn:string[] | Buffer

ALPN protocol names. Each name must be between 1 and 255 bytes. A Buffer must already be in ALPN wire format: one length byte followed by that many bytes, repeated.

srtp:string

Colon-separated SRTP protection profile names (e.g., 'SRTP_AES128_CM_SHA1_80:SRTP_AEAD_AES_128_GCM').

requestCert?:boolean

Request a certificate from the client. Default: false.

rejectUnauthorized?:boolean

Only has an effect together with requestCert. When true, a client that presents no certificate, or one that does not chain to a trusted CA, is rejected during the handshake and receives a TLS alert. When false, the certificate is still requested and verified but the handshake completes regardless, leaving the decision to the application via session.authorized. Default: true.

mtu?:number

Maximum size in bytes of a DTLS datagram. Default: 1200.

handshakeTimeout?:number

Milliseconds a handshake may take before it is abandoned. 0 disables it. Default: 60000. See Handshake timeout.

ipv6Only?:boolean

When true, an IPv6 endpoint serves IPv6 only. When false, binding '::' also accepts IPv4 peers, which arrive with mapped addresses such as '::ffff:203.0.113.1' -- anything keyed on the peer address, including maxSessionsPerHost, sees them in that form. Has no effect on an IPv4 endpoint. Default: false.

reusePort?:boolean

When true, sets SO_REUSEPORT, so several processes may bind the same port and the kernel spreads arriving datagrams between them. Every one of them must set it. Default: false.

udpReceiveBufferSize?:number

Size in bytes for the socket's receive buffer (SO_RCVBUF). Raising it gives the endpoint room for bursts that the default would drop. The kernel clamps this to its own maximum. Default: the system default.

udpSendBufferSize?:number

Size in bytes for the socket's send buffer (SO_SNDBUF). Clamped as above. Default: the system default.

udpTTL?:number

IP time-to-live for outgoing datagrams, from 1 to 255. Default: the system default.

maxSessions?:number

The maximum number of concurrent sessions the endpoint will hold. Set to 0 for no limit. Default: 10000.

maxSessionsPerHost?:number

The maximum number of concurrent sessions from any single source IP address, ignoring port. Set to 0 for no limit. Default: 1000.

sessionIdContext?:string

Opaque identifier scoping resumable sessions to this server, at most 32 bytes. Default: a value derived from process.argv, as in tls.createServer().

Returns:DTLSEndpoint

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

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

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

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

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

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

JavaScript