Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท HTTP, HTTPS, net, TLS, dgram and dns

Node.js https.createServer() method

Reference for https.createServer() in Node.js: serve HTTP over TLS with a key and certificate, TLS options, SNI, client certificates and common mistakes.

https.createServer([options][, requestListener]) creates an https.Server: an HTTP server that talks TLS. It works exactly like http.createServer() for everything above the transport. Your request listener receives the same IncomingMessage and ServerResponse objects. The difference is the options object, which must carry the private key and certificate (or a pfx bundle, or an SNICallback) that the server presents to clients.

https.Server extends tls.Server, so every TLS option from tls.createServer() is accepted too. In production the certificate comes from a certificate authority, often through your reverse proxy; this page shows the Node side.

NODE
import https from 'node:https';
import fs from 'node:fs';

https.createServer({
  key: fs.readFileSync('key.pem'),
  cert: fs.readFileSync('cert.pem'),
}, (req, res) => res.end('secure\n')).listen(8443);

Try it

The examples embed a throwaway key and a self-signed certificate for localhost and 127.0.0.1, created only for these demos. Never reuse an embedded key for anything real.

Node.js An HTTPS server and a client that trusts it

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js What happens without trust

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
https.createServer([options][, requestListener])
// returns https.Server (extends tls.Server and http.Server)
Name Description
options.key Private key in PEM format (string, Buffer, or an array). Required with cert, unless you use pfx or SNICallback.
options.cert Certificate chain in PEM format. Put intermediates after the leaf certificate.
options.pfx, options.passphrase A PKCS#12 bundle (key and certificate together) and the password for it or for an encrypted key.
options.ca Trusted authorities used to verify client certificates.
options.requestCert, options.rejectUnauthorized Ask clients for a certificate; with rejectUnauthorized: true (the default) refuse clients that fail verification.
options.minVersion, options.maxVersion Lowest and highest TLS version, such as 'TLSv1.2' and 'TLSv1.3'. The default minimum is TLS 1.2.
options.ciphers, options.honorCipherOrder Cipher list for TLS 1.2 and below, and who picks.
options.ALPNProtocols Protocols offered during negotiation (for example ['h2', 'http/1.1']).
options.SNICallback(servername, cb) Choose a certificate per host name; call cb(null, secureContext).
options.ticketKeys, options.sessionTimeout TLS session resumption settings.
options.headersTimeout, options.requestTimeout, options.keepAliveTimeout, options.maxHeaderSize, options.joinDuplicateHeaders, options.IncomingMessage, options.ServerResponse The same HTTP options as http.createServer().
requestListener Added as a listener for 'request'.

Returns: an https.Server. Call listen() on it as with an HTTP server.

Errors: malformed key or cert text throws when the server is created (for example ERR_OSSL_PEM_NO_START_LINE). Leaving out the key and certificate entirely does not throw; clients then fail the handshake. A client that fails the handshake triggers 'tlsClientError' on the server, not an exception in your handler.

Usage notes

  • Listen for 'tlsClientError'. Handshake failures (a plain HTTP client, a probe, a protocol mismatch) never reach the request listener; this event is where you log them.
  • req.socket.encrypted is true on HTTPS requests; req.socket.getProtocol() and getCipher() describe the negotiated connection.
  • Self-signed certificates are trusted only when the client passes them as ca. Turning off verification (rejectUnauthorized: false) on a client defeats the point of TLS; use it for local tests at most.
  • Most production setups terminate TLS elsewhere (a load balancer or nginx) and let Node speak plain HTTP on a private network. Do that when you can; certificate renewal is easier there.
  • Renewing certificates without a restart: call server.setSecureContext({ key, cert }) with the new material.
  • HTTP/2 over TLS uses http2.createSecureServer(); see http2.createServer().
  • Protect the key file: a private key in source control or in a web root is a compromise.
  • Port 443 needs elevated privileges on most systems; use a high port with a proxy or a capability instead of running as root.