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– anX509Certificatefor the signing CA. Omit it for a self-signed certificate.serialNumber– a positivebigintfrom1nup to(1n << 159n) - 1n.notBefore/notAfter–Dateobjects for the validity window.signature–{ key, digest }, the signing private key and digest name.extensions– an ordered list such asbasicConstraints,keyUsage,extendedKeyUsageandsubjectAltName.csrwithselectExtensions– 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.timedOuttells you whether a child process was killed because itstimeoutexpired.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
selectExtensionspolicy. - 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.
