For years, generating a TLS certificate from Node.js meant shelling out to openssl or pulling in a large library such as node-forge. That is changing. The Node.js 27 alpha line adds crypto.generateX509Certificate() and crypto.generateX509CertificateSync(), which create and sign X.509 v3 certificates natively, including signing a certificate signing request (CSR). The feature landed in Node.js 27.0.0-alpha.0.1.0 (12 November 2026) and is in the current alpha, 27.0.0-alpha.0.1.1 (16 November).

This tutorial shows how to create a self-signed certificate, build a tiny local certificate authority, sign a CSR safely and inspect the result. Sources: the Node.js 27.0.0-alpha.0.1.0 release notes and the alpha crypto API docs.

Important: this is alpha software

Node.js 27 is in alpha, so don’t use it in production. The new functions are marked Stability: 1.2 – Release candidate, meaning the API is close to final but could still change. Use it to experiment, build dev tooling and test your CI ahead of time.

Download a build from the 27.0.0-alpha.0.1.1 release page (installers and tarballs are listed there), then confirm:

node -v   # v27.0.0-alpha.0.1.1

The API in one minute

generateX509Certificate(options, callback) creates and signs a certificate. The sync version, generateX509CertificateSync(options), returns an X509Certificate directly. The main options are:

  • subject – the distinguished name, e.g. [{ name: 'commonName', value: 'localhost' }].
  • publicKey – the public key for the certificate.
  • issuer – an X509Certificate for the signing CA. Omit it for a self-signed certificate.
  • serialNumber – a positive bigint from 1n up to (1n << 159n) - 1n.
  • notBefore / notAfter – Date objects for the validity window.
  • signature – { key, digest }, the signing private key and digest name.
  • extensions – an ordered list such as basicConstraints, keyUsage, extendedKeyUsage and subjectAltName.
  • csr with selectExtensions – to sign a CSR (more on this below).

One rule to remember: no extensions are added implicitly. If you want a Subject Alternative Name, you must add it yourself.

Example 1: A self-signed certificate for local HTTPS

// selfsigned.mjs
import {
  generateKeyPairSync,
  generateX509CertificateSync,
  randomBytes,
} from 'node:crypto';
import { createServer } from 'node:https';

const { publicKey, privateKey } = generateKeyPairSync('ec', {
  namedCurve: 'P-256',
});

const now = new Date();
const inThirtyDays = new Date(now.getTime() + 30 * 24 * 60 * 60 * 1000);

const cert = generateX509CertificateSync({
  subject: [{ name: 'commonName', value: 'localhost' }],
  publicKey,
  serialNumber: BigInt('0x' + randomBytes(16).toString('hex')) + 1n,
  notBefore: now,
  notAfter: inThirtyDays,
  signature: { key: privateKey, digest: 'sha256' },
  extensions: [
    { type: 'basicConstraints', ca: false },
    { type: 'keyUsage', critical: true, usages: ['digitalSignature'] },
    { type: 'extendedKeyUsage', usages: ['serverAuth'] },
    {
      type: 'subjectAltName',
      names: [
        { type: 'dns', value: 'localhost' },
        { type: 'ip', value: '127.0.0.1' },
      ],
    },
  ],
});

createServer(
  {
    key: privateKey.export({ type: 'pkcs8', format: 'pem' }),
    cert: cert.toString(),
  },
  (req, res) => res.end('Hello over HTTPS\n'),
).listen(8443, () => console.log('https://localhost:8443'));

A 128-bit random serial plus one stays well within the allowed range and is always positive. Browsers will still warn because nothing trusts this certificate, but curl -k https://localhost:8443 works.

Example 2: A tiny local certificate authority

Self-signed certificates are fine for one service, but a local CA lets you trust one root and issue many certificates. First create the CA:

// ca.mjs
import {
  generateKeyPairSync,
  generateX509CertificateSync,
} from 'node:crypto';

export const caKeys = generateKeyPairSync('ec', { namedCurve: 'P-256' });

export const caCert = generateX509CertificateSync({
  subject: [
    { name: 'organizationName', value: 'Dev Lab' },
    { name: 'commonName', value: 'Dev Lab Root CA' },
  ],
  publicKey: caKeys.publicKey,
  serialNumber: 1n,
  notBefore: new Date(),
  notAfter: new Date(Date.now() + 365 * 24 * 60 * 60 * 1000),
  signature: { key: caKeys.privateKey, digest: 'sha256' },
  extensions: [
    { type: 'basicConstraints', critical: true, ca: true, pathLength: 0 },
    { type: 'keyUsage', critical: true, usages: ['keyCertSign', 'crlSign'] },
    { type: 'subjectKeyIdentifier', value: 'auto' },
  ],
});

The docs enforce sensible structure here: a Key Usage containing keyCertSign requires CA Basic Constraints, and pathLength is only allowed on a CA that can sign certificates.

Now issue a server certificate signed by that CA:

// issue.mjs
import { generateKeyPairSync, generateX509CertificateSync } from 'node:crypto';
import { caKeys, caCert } from './ca.mjs';

const serverKeys = generateKeyPairSync('ec', { namedCurve: 'P-256' });

const serverCert = generateX509CertificateSync({
  subject: [{ name: 'commonName', value: 'api.dev.test' }],
  publicKey: serverKeys.publicKey,
  issuer: caCert,
  serialNumber: 2n,
  notBefore: new Date(),
  notAfter: new Date(Date.now() + 90 * 24 * 60 * 60 * 1000),
  signature: { key: caKeys.privateKey, digest: 'sha256' },
  extensions: [
    { type: 'basicConstraints', ca: false },
    { type: 'keyUsage', critical: true, usages: ['digitalSignature'] },
    { type: 'extendedKeyUsage', usages: ['serverAuth'] },
    { type: 'subjectAltName', names: [{ type: 'dns', value: 'api.dev.test' }] },
    { type: 'authorityKeyIdentifier', value: 'auto' },
  ],
});

console.log(serverCert.checkIssued(caCert));          // true
console.log(serverCert.verify(caCert.publicKey));     // true

When issuer is set, the issuer’s public key must match signature.key. Note that the generated certificate is standalone: the CA certificate is not attached as a chain, so serve the CA certificate alongside it if clients need it.

Example 3: Signing a CSR safely

The most interesting part of the new API is CSR support. Pass the request with csr, and the request provides the subject and public key. You must supply a selectExtensions callback that decides which requested extensions end up in the certificate:

import { generateX509Certificate, X509Certificate } from 'node:crypto';
import { readFileSync } from 'node:fs';
import { promisify } from 'node:util';

const generate = promisify(generateX509Certificate);

const allowedExtensionOids = new Set([
  '2.5.29.15', // Key Usage
  '2.5.29.17', // Subject Alternative Name
]);

const cert = await generate({
  csr: readFileSync('request.csr'),
  issuer: new X509Certificate(readFileSync('issuer-cert.pem')),
  serialNumber: 1001n,
  notBefore: new Date(),
  notAfter: new Date(Date.now() + 90 * 24 * 60 * 60 * 1000),
  signature: { key: readFileSync('issuer-key.pem'), digest: 'sha256' },
  selectExtensions(requestedExtensions) {
    return requestedExtensions.filter(({ oid }) => allowedExtensionOids.has(oid));
  },
});

console.log(cert.toString());

Why the strictness? According to the docs, selectExtensions runs before the CSR signature is verified, so it sees unauthenticated data. Treat it as your issuing policy: allow-list extension OIDs and never blindly copy everything a requester asks for. The good news is that the request signature is still checked before signing, so an invalid proof of possession can’t produce a certificate. The callback must be synchronous; returning a Promise isn’t supported.

Inspecting certificates with the new getters

The same alpha adds inspection getters to X509Certificate, including subjectName, issuerName, extensions, version, tbs and signature:

console.log(cert.version);                 // 3
console.log(cert.subjectName.rdns);        // [[{ oid: '2.5.4.3', value: '...' }]]
for (const ext of cert.extensions) {
  console.log(ext.oid, ext.critical, ext.value.length);
}

extensions returns raw values (not decoded), which is useful for auditing what you actually issued.

Other notable changes in the same alpha

  • subprocess.timedOut tells you whether a child process was killed because its timeout expired.
  • dns.lookup() coalesces identical concurrent requests, cutting duplicate lookups under load.
import { spawn } from 'node:child_process';

const child = spawn('sleep', ['10'], { timeout: 100 });
child.on('exit', () => console.log('timed out?', child.timedOut)); // true

Key takeaways

  • Node.js 27 alpha adds native X.509 certificate generation with generateX509Certificate() and a sync variant.
  • You can create self-signed certificates, run a small dev CA and sign CSRs without OpenSSL on the command line.
  • No extensions are added automatically, and CSR signing requires a strict selectExtensions policy.
  • It’s alpha and “release candidate” stability: experiment now, adopt when Node.js 27 is stable.

See the Node.js 27 alpha crypto docs for the full option reference.