TLS and HTTPS in Node: ship the whole chain

A TLS server in Node, and what it actually serves

https.createServer is a thin wrapper over tls.createServer: you hand it a private key and a certificate, it terminates TLS, and your request handler runs over the decrypted stream. The single most consequential field is cert — and it must contain the full chain, not just your server’s own (leaf) certificate.

import { readFileSync } from "node:fs";
import { createServer } from "node:https";

const server = createServer(
  {
    key: readFileSync("privkey.pem"),
    // fullchain.pem = leaf certificate FOLLOWED BY every intermediate, in order.
    // This is the #1 production TLS bug: shipping cert.pem (leaf only) instead.
    cert: readFileSync("fullchain.pem"),
  },
  (req, res) => {
    res.writeHead(200);
    res.end("hello over TLS\n");
  },
);
server.listen(443);

A certificate is an X.509 document binding a public key to a set of names (the Subject Alternative Names, or SANs) and signed by an issuer. Your leaf is signed by an intermediate CA, which is signed by a root CA that lives in the client’s trust store. Verification is the client walking that chain upward until it reaches a root it already trusts. The client only inherently trusts roots — it does not have your intermediate. So if your server sends only the leaf, the client cannot connect leaf → root, and verification fails. Let’s Encrypt’s fullchain.pem exists precisely to solve this: it is the leaf concatenated with the intermediate(s). Use it, not cert.pem.

The handshake: how a key gets agreed without leaking

Before any HTTP byte flows, client and server run the TLS handshake: agree on parameters, prove the server’s identity with its certificate, and derive a shared symmetric key. TLS 1.3 streamlined this into a single round trip (1-RTT) because the client guesses the key-exchange group and sends its key share in the very first message, so the server can reply with everything needed to start encrypting.

The client verifies the certificate chain (signatures valid up to a trusted root, not expired, and the requested hostname present in the leaf’s SANs), checks CertificateVerify to prove the server holds the matching private key, and then both sides switch to symmetric encryption. The asymmetric crypto authenticates and exchanges the key; the bulk of the traffic is fast symmetric (AES-GCM or ChaCha20). TLS 1.2 needed two round trips; if you can require 1.3, the handshake is meaningfully cheaper.

SNI: many certs on one socket

A single IP and port often serve many hostnames. The client tells the server which hostname it wants in the SNI (Server Name Indication) extension of the ClientHello — in plaintext, before the certificate is chosen — so the server can present the right certificate. In Node you select per-name certs with SNICallback, returning a SecureContext built per hostname:

import tls from "node:tls";
import { readFileSync } from "node:fs";
import { createServer } from "node:https";

const contexts = {
  "a.example.com": tls.createSecureContext({
    key: readFileSync("a.key"), cert: readFileSync("a.fullchain.pem"),
  }),
  "b.example.com": tls.createSecureContext({
    key: readFileSync("b.key"), cert: readFileSync("b.fullchain.pem"),
  }),
};

createServer({
  SNICallback(servername, cb) {
    const ctx = contexts[servername];
    cb(ctx ? null : new Error("unknown host"), ctx);
  },
}, handler).listen(443);

tls.createSecureContext is the reusable bundle of key, chain, ciphers, and protocol settings; SNICallback lets you pick one at handshake time. This is how a reverse proxy or multi-tenant server hosts dozens of domains on one listener.

Session resumption: skip the expensive part

The full handshake costs asymmetric crypto and a round trip. Resumption lets a returning client reuse the previously negotiated secret and skip most of that. Two mechanisms: session IDs, where the server stores session state keyed by an ID and the client presents the ID to resume (server-side memory, doesn’t scale across a cluster without shared storage); and session tickets (RFC 5077), where the server encrypts the session state into an opaque blob the client stores and replays — stateless on the server, which is why it scales horizontally. In TLS 1.3, resumption uses pre-shared keys derived from tickets and can even carry 0-RTT early data. Resumption turns a multi-message, asymmetric handshake into a fast abbreviated one, cutting connection latency for repeat visitors.

The cert errors you actually hit

These four account for most real TLS support tickets. The constant tells you the cause:

Notice none of the fixes is “turn off checking.” Each error is the verification machinery correctly reporting a real defect in the chain, validity window, or naming. When you see one of these constants in a log, read it as a precise diagnosis, not as a prompt to disable verification — the constant tells you exactly what to fix.