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.
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.
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.
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
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.encryptedistrueon HTTPS requests;req.socket.getProtocol()andgetCipher()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(); seehttp2.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.