dtls.createSecureContext

dtls.createSecureContext(options?): DTLSSecureContext

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

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

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

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

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

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

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

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

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

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