tls-keygen

tls-keygen

Generates a self-signed, trusted TLS certificate that is accepted by browsers for localhost development.

The generated private key (key.pem) and public certificate (cert.pem) files are compatible with Node.js and most other servers.

The generated public certificate (cert.pem) file is added to the native certificate store on Windows, MacOS, and Linux for automatic HTTPS and HTTP/2 browser support.

	Chrome	Safari	Edge	Firefox
MacOS	✅	✅
Windows	✅		✅
Linux	✅			✅

Note: Linux support requires the certutil command to be installed. On Ubuntu and Debian, run: sudo apt-get install libnss3-tools

Use Cases

Easily use TLS in locally hosted websites. Using HTTP/2 or some web platform API's requires the page to be served from an https:// origin. This tool makes it easy to generate the necessary key & certificate files.

The generated certificates are not useful in production deployments on the public internet since they are self-signed and only for local addresses. However they could be used, in combination with local DNS hijacking (e.g. /etc/hosts overrides) to mimick production systems locally.

CLI

npx tls-keygen

npx tls-keygen "key.pem" "cert.pem" [--skip-entrust] [--add-san <name>]

The arguments key.pem and cert.pem are, optionally, the output destination filepaths for the TLS private key and public certificate respectively.

The --skip-entrust option generates the key & certificate pair without registering the certificate with the operating system certificate store.

The --add-san <name> option appends a single name for which this certificate is valid. The <name> value must be either a DNS hostname or IP address. This list is recorded in the certificate as the Subject Alternative Names (SAN).

Type	Example
DNS	--add-san DNS:foo.local
IPv4	--add-san IP:172.16.1.2
IPv6	--add-san IP:fe80::200:5aee:feaa:20a2

Output

Key:
🔑 /Users/seb/key.pem

Certificate:
📜 /Users/seb/cert.pem

Common Name:
  - 🏷  localhost

Subject Alternative Names:
  - 🏷  DNS:localhost
  - 🏷  DNS:*.localhost
  - 🏷  DNS:localhost.localdomain
  - 🏷  IP:127.0.0.1
  - 🏷  IP:0.0.0.0
  - 🏷  IP:::1
  - 🏷  IP:::

🔐 Done!

API

keygen(options)

const {keygen} = require('tls-keygen')

// Returns a promise that
// resolves with `key` and `cert` file paths.
const {key, cert} = await keygen({
  // Default: ./key.pem
  key: '/path/to/output/key.pem',

  // Default: ./cert.pem
  cert: '/path/to/output/cert.pem',

  // Default: localhost
  commonName: 'example.net',

  // Default: [
  //   'DNS:localhost',
  //   'DNS:*.localhost',
  //   'DNS:localhost.localdomain',
  //   'IP:127.0.0.1',
  //   'IP:0.0.0.0',
  //   'IP:::1',
  //   'IP:::'
  // ]
  subjectAltName: [
    'DNS:example.net',
    'DNS:www.example.net'
  ],

  // Set to `false` to skip adding the certificate
  // to the trusted certificate store.
  // Default: true
  entrust: false
})

The default options are exported for convenience.

const {
  defaultKey,
  defaultCert,
  defaultCommonName,
  defaultSubjectAltName
} = require('tls-keygen')

ephemeral(options)

Convenience utility to generate a key & certificate for in-memory use only. Handy when writing tests that use TLS (e.g. HTTPS, HTTP/2).

Accepts the same options as keygen() (see above), except that the key and cert file paths are ignored.

Returns a promise that resolves to an object with fields key and cert that are two Buffers containing the raw key and certificate data.

const {ephemeral} = require('tls-keygen')

const {key, cert} = await ephemeral(options)
// key: <Buffer 2d 2d 2d 2d 2d 42 45 47 49 4e 20 50 ... >
// cert: <Buffer 2d 2d 2d 2d 2d 42 45 47 49 4e 20 43 ... >

Browser Support

• MacOS: Safari and Chrome using Keychain
• Windows: Edge and Chrome using Certificate Service
• Linux: Firefox and Chrome using NSS

Note: Firefox may require a restart to accept the certificate.

Graceful Fallback

Usage with clients that do not support the native operating system certificate stores is the same as regular self-signed certificates.

• Node.js: Use the rejectUnauthorized: false TLS option.
• Curl: Use the --insecure option (alias: -k).
• Firefox: Press "Advanced", then "Add Exception...", and finally "Confirm Security Exception".

Server Support

• Fastify: Use the fastify-tls-keygen plugin
• Node.js: Use the key and cert options with tls.createServer, https.createServer, or http2.createSecureServer
• Apache HTTP Server: Use the SSLCertificateFile and SSLCertificateKeyFile options
• Nginx: Use the ssl_certificate_key and ssl_certificate options

Colophon

Made with 💝 by Sebastiaan Deckers in 🇸🇬 Singapore.