Tighten up CA cert generation, using @peculiar/x509 over node-forge

pimterry · pimterry · commit 8006cc970430 · 2025-05-21T19:07:11.000+02:00
This migrates CA generation (but not yet site cert generation) away
from node-forge (now unmaintained) and improves our matching to
official TLS baseline requirements: extends the CA lifespan, orders
CA subject fields, drops nonRepudiation etc. This now passes the BR TLS
server root requirement linting checks.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -23,8 +23,10 @@ jobs:
 
       - run: npm run ci-tests
         env:
-          # The new type stripping breaks our existing ts-node testing set up, so disable it for Node 22+
-          NODE_OPTIONS: ${{ !startsWith(matrix.node-version, '20') && !startsWith(matrix.node-version, '18') && '--no-experimental-strip-types' || '' }}
+          # Node v18 needs webcrypto, Node v22+ needs no strip-types (because we use ts-node for full TS instead)
+          NODE_OPTIONS: >-
+            ${{ startsWith(matrix.node-version, '18') && '--experimental-global-webcrypto' ||
+                (!startsWith(matrix.node-version, '20') && !startsWith(matrix.node-version, '18') && '--no-experimental-strip-types') || '' }}
 
       - name: Deploy docs
         if: github.ref == 'refs/heads/main' && matrix.node-version == 'v22.14.0'
diff --git a/package.json b/package.json
@@ -165,6 +165,9 @@
     "@httptoolkit/subscriptions-transport-ws": "^0.11.2",
     "@httptoolkit/util": "^0.1.6",
     "@httptoolkit/websocket-stream": "^6.0.1",
+    "@peculiar/asn1-schema": "^2.3.15",
+    "@peculiar/asn1-x509": "^2.3.15",
+    "@peculiar/x509": "^1.12.3",
     "@types/cors": "^2.8.6",
     "@types/node": "*",
     "async-mutex": "^0.5.0",
diff --git a/src/util/tls.ts b/src/util/tls.ts
@@ -1,10 +1,16 @@
 import * as _ from 'lodash';
 import * as fs from 'fs/promises';
 import { v4 as uuid } from "uuid";
-import * as forge from 'node-forge';
 
+import * as x509 from '@peculiar/x509';
+import * as asn1X509 from '@peculiar/asn1-x509';
+import * as asn1Schema from '@peculiar/asn1-schema';
+
+import * as forge from 'node-forge';
 const { asn1, pki, md, util } = forge;
 
+const crypto = globalThis.crypto;
+
 export type CAOptions = (CertDataOptions | CertPathOptions);
 
 export interface CertDataOptions extends BaseCAOptions {
@@ -50,6 +56,23 @@ export type GeneratedCertificate = {
     ca: string
 };
 
+const SUBJECT_NAME_MAP: { [key: string]: string } = {
+    commonName: "CN",
+    organizationName: "O",
+    organizationalUnitName: "OU",
+    countryName: "C",
+    localityName: "L",
+    stateOrProvinceName: "ST",
+    domainComponent: "DC",
+    serialNumber: "2.5.4.5"
+};
+
+function arrayBufferToPem(buffer: ArrayBuffer, label: string): string {
+    const base64 = Buffer.from(buffer).toString('base64');
+    const lines = base64.match(/.{1,64}/g) || [];
+    return `-----BEGIN ${label}-----\n${lines.join('\n')}\n-----END ${label}-----\n`;
+}
+
 /**
  * Generate a CA certificate for mocking HTTPS.
  *
@@ -68,123 +91,118 @@ export async function generateCACertificate(options: {
     },
     bits?: number,
     nameConstraints?: {
+        /**
+         * Array of permitted domains
+         */
         permitted?: string[]
     }
 } = {}) {
-    options = _.defaults({}, options, {
+    options = {
         bits: 2048,
-    });
-
-    const subjectOptions = _.defaults({}, options.subject, {
-        // These subject fields are required for a fully valid CA cert that will be
-        // accepted when imported anywhere:
-        commonName: 'Mockttp Testing CA - DO NOT TRUST - TESTING ONLY',
-        organizationName: 'Mockttp',
-        countryName: 'XX', // ISO-3166-1 alpha-2 'unknown country' code
-    });
+        ...options,
+        subject: {
+            commonName: 'Mockttp Testing CA - DO NOT TRUST - TESTING ONLY',
+            organizationName: 'Mockttp',
+            countryName: 'XX', // ISO-3166-1 alpha-2 'unknown country' code
+            ...options.subject
+        },
+    };
 
-    const keyPair = await new Promise<forge.pki.rsa.KeyPair>((resolve, reject) => {
-        pki.rsa.generateKeyPair({ bits: options.bits }, (error, keyPair) => {
-            if (error) reject(error);
-            else resolve(keyPair);
-        });
-    });
+    // We use RSA for now for maximum compatibility
+    const keyAlgorithm = {
+        name: "RSASSA-PKCS1-v1_5",
+        modulusLength: options.bits,
+        publicExponent: new Uint8Array([1, 0, 1]), // Standard 65537 fixed value
+        hash: "SHA-256"
+    };
 
-    const cert = pki.createCertificate();
-    cert.publicKey = keyPair.publicKey;
-    cert.serialNumber = generateSerialNumber();
+    const keyPair = await crypto.subtle.generateKey(
+        keyAlgorithm,
+        true, // Key should be extractable to be exportable
+        ["sign", "verify"]
+    ) as CryptoKeyPair;
+
+    // Baseline requirements set a specific order for standard CA fields:
+    const orderedKeys = ["countryName", "organizationName", "organizationalUnitName", "commonName"];
+    const subjectNameParts: x509.JsonNameParams = [];
+
+    for (const key of orderedKeys) {
+        const value = options.subject![key];
+        if (!value) continue;
+        const mappedKey = SUBJECT_NAME_MAP[key] || key;
+        subjectNameParts.push({ [mappedKey]: [value] });
+    }
+    for (const key in options.subject) {
+        if (orderedKeys.includes(key)) continue; // Already added above
+        const value = options.subject[key]!;
+        const mappedKey = SUBJECT_NAME_MAP[key] || key;
+        subjectNameParts.push({ [mappedKey]: [value] });
+    }
+    const subjectDistinguishedName = new x509.Name(subjectNameParts).toString();
 
-    cert.validity.notBefore = new Date();
+    const notBefore = new Date();
     // Make it valid for the last 24h - helps in cases where clocks slightly disagree
-    cert.validity.notBefore.setDate(cert.validity.notBefore.getDate() - 1);
-
-    cert.validity.notAfter = new Date();
-    // Valid for the next year by default.
-    cert.validity.notAfter.setFullYear(cert.validity.notAfter.getFullYear() + 1);
-
-    cert.setSubject(Object.entries(subjectOptions).map(([key, value]) => ({
-        name: key,
-        value: value
-    })));
-
-    const extensions: any[] = [
-        { name: 'basicConstraints', cA: true, critical: true },
-        { name: 'keyUsage', keyCertSign: true, digitalSignature: true, nonRepudiation: true, cRLSign: true, critical: true },
-        { name: 'subjectKeyIdentifier' },
+    notBefore.setDate(notBefore.getDate() - 1);
+
+    const notAfter = new Date();
+    // Valid for the next 10 years by default (BR sets an 8 year minimum)
+    notAfter.setFullYear(notAfter.getFullYear() + 10);
+
+    const extensions: x509.Extension[] = [
+        new x509.BasicConstraintsExtension(
+            true, // cA = true
+            undefined, // We don't set any path length constraint (should we? Not required by BR)
+            true
+        ),
+        new x509.KeyUsagesExtension(
+            x509.KeyUsageFlags.keyCertSign |
+            x509.KeyUsageFlags.digitalSignature |
+            x509.KeyUsageFlags.cRLSign,
+            true
+        ),
+        await x509.SubjectKeyIdentifierExtension.create(keyPair.publicKey as CryptoKey, false),
+        await x509.AuthorityKeyIdentifierExtension.create(keyPair.publicKey as CryptoKey, false)
     ];
+
     const permittedDomains = options.nameConstraints?.permitted || [];
-    if(permittedDomains.length > 0) {
-        extensions.push({
-            critical: true,
-            id: '2.5.29.30',
-            name: 'nameConstraints',
-            value: generateNameConstraints({
-              permitted: permittedDomains,
-            }),
-        })
+    if (permittedDomains.length > 0) {
+        const permittedSubtrees = permittedDomains.map(domain => {
+            const generalName = new asn1X509.GeneralName({ dNSName: domain });
+            return new asn1X509.GeneralSubtree({ base: generalName });
+        });
+        const nameConstraints = new asn1X509.NameConstraints({
+            permittedSubtrees: new asn1X509.GeneralSubtrees(permittedSubtrees)
+        });
+        extensions.push(new x509.Extension(
+            asn1X509.id_ce_nameConstraints,
+            true,
+            asn1Schema.AsnConvert.serialize(nameConstraints))
+        );
     }
-    cert.setExtensions(extensions);
 
-    // Self-issued too
-    cert.setIssuer(cert.subject.attributes);
+    const certificate = await x509.X509CertificateGenerator.create({
+        serialNumber: generateSerialNumber(),
+        subject: subjectDistinguishedName,
+        issuer: subjectDistinguishedName, // Self-signed
+        notBefore,
+        notAfter,
+        signingAlgorithm: keyAlgorithm,
+        publicKey: keyPair.publicKey as CryptoKey,
+        signingKey: keyPair.privateKey as CryptoKey,
+        extensions
+    });
 
-    // Self-sign the certificate - we're the root
-    cert.sign(keyPair.privateKey, md.sha256.create());
+    const privateKeyBuffer = await crypto.subtle.exportKey("pkcs8", keyPair.privateKey as CryptoKey);
+    const privateKeyPem = arrayBufferToPem(privateKeyBuffer, "RSA PRIVATE KEY");
+    const certificatePem = certificate.toString("pem");
 
     return {
-        key: pki.privateKeyToPem(keyPair.privateKey),
-        cert: pki.certificateToPem(cert)
+        key: privateKeyPem,
+        cert: certificatePem
     };
 }
 
 
-type GenerateNameConstraintsInput = {
-    /**
-     * Array of permitted domains
-     */
-    permitted?: string[];
-};
-
-/**
- * Generate name constraints in conformance with
- * [RFC 5280 § 4.2.1.10](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.10)
- */
-function generateNameConstraints(
-    input: GenerateNameConstraintsInput
-): forge.asn1.Asn1 {
-    const domainsToSequence = (ips: string[]) =>
-        ips.map((domain) => {
-            return asn1.create(asn1.Class.UNIVERSAL, asn1.Type.SEQUENCE, true, [
-                asn1.create(
-                    asn1.Class.CONTEXT_SPECIFIC,
-                    2,
-                    false,
-                    util.encodeUtf8(domain)
-                ),
-            ]);
-        });
-
-    const permittedAndExcluded: forge.asn1.Asn1[] = [];
-
-    if (input.permitted && input.permitted.length > 0) {
-        permittedAndExcluded.push(
-            asn1.create(
-                asn1.Class.CONTEXT_SPECIFIC,
-                0,
-                true,
-                domainsToSequence(input.permitted)
-            )
-        );
-    }
-
-    return asn1.create(
-        asn1.Class.UNIVERSAL,
-        asn1.Type.SEQUENCE,
-        true,
-        permittedAndExcluded
-    );
-}
-
 export function generateSPKIFingerprint(certPem: PEM) {
     let cert = pki.certificateFromPem(certPem.toString('utf8'));
     return util.encode64(
diff --git a/test/ca.spec.ts b/test/ca.spec.ts
@@ -91,7 +91,7 @@ nodeOnly(() => {
                 await new Promise<void>((resolve) => server.listen(4430, resolve));
 
                 const req = localhostRequest({hostname: "hello.other.com", port: 4430});
-                return new Promise<void>((resolve, reject) => {
+                return new Promise<void>((resolve) => {
                     req.on("error", (err) => {
                         expect(err.message).to.equal("permitted subtree violation");
                         resolve();
@@ -117,9 +117,9 @@ nodeOnly(() => {
             const caCertificate = await caCertificatePromise;
 
             expect(caCertificate.cert.length).to.be.greaterThan(1000);
-            expect(caCertificate.cert.split('\r\n')[0]).to.equal('-----BEGIN CERTIFICATE-----');
+            expect(caCertificate.cert.split('\n')[0]).to.equal('-----BEGIN CERTIFICATE-----');
             expect(caCertificate.key.length).to.be.greaterThan(1000);
-            expect(caCertificate.key.split('\r\n')[0]).to.equal('-----BEGIN RSA PRIVATE KEY-----');
+            expect(caCertificate.key.split('\n')[0]).to.equal('-----BEGIN RSA PRIVATE KEY-----');
         });
 
         it("should generate a CA certificate that can be used to create domain certificates", async () => {
@@ -128,10 +128,10 @@ nodeOnly(() => {
 
             const { cert, key } = ca.generateCertificate('localhost');
 
-            expect(caCertificate.cert.length).to.be.greaterThan(1000);
-            expect(caCertificate.cert.split('\r\n')[0]).to.equal('-----BEGIN CERTIFICATE-----');
-            expect(caCertificate.key.length).to.be.greaterThan(1000);
-            expect(caCertificate.key.split('\r\n')[0]).to.equal('-----BEGIN RSA PRIVATE KEY-----');
+            expect(cert.length).to.be.greaterThan(1000);
+            expect(cert.split('\r\n')[0]).to.equal('-----BEGIN CERTIFICATE-----');
+            expect(key.length).to.be.greaterThan(1000);
+            expect(key.split('\r\n')[0]).to.equal('-----BEGIN RSA PRIVATE KEY-----');
         });
 
         it("should be able to generate a CA certificate that passes lintcert checks", async function () {
@@ -149,7 +149,7 @@ nodeOnly(() => {
                         'b64input': cert,
                         'format': 'json',
                         'severity': 'warning',
-                        'profile': 'autodetect'
+                        'profile': 'tbr_root_tlsserver' // TLS Baseline root CA
                     })
                 }),
                 { context: this }
@@ -193,8 +193,7 @@ nodeOnly(() => {
         });
 
         it("should generate wildcard certs that pass lintcert checks for invalid subdomain names", async function () {
-            this.timeout(5000); // Large cert + remote request can make this slow
-            this.retries(3); // Remote server can be unreliable
+            this.timeout(10_000); // Large cert + remote request can make this slow
 
             const caCertificate = await caCertificatePromise;
             const ca = new CA({ key: caCertificate.key, cert: caCertificate.cert, keyLength: 2048 });
@@ -210,7 +209,7 @@ nodeOnly(() => {
                     headers: { 'content-type': 'application/x-www-form-urlencoded' },
                     body: new URLSearchParams({'b64cert': cert})
                 }),
-                { context: this }
+                { context: this, timeout: 9000 }
             );
 
             expect(response.status).to.equal(200);
@@ -257,8 +256,8 @@ nodeOnly(() => {
                     body: new URLSearchParams({
                         'b64input': cert,
                         'format': 'json',
-                        'severity': 'warning',
-                        'profile': 'autodetect'
+                        'severity': 'error',
+                        'profile': 'tbr_root_tlsserver' // TLS Baseline root CA
                     })
                 }),
                 { context: this }
diff --git a/test/test-utils.ts b/test/test-utils.ts
@@ -124,7 +124,7 @@ export async function ignoreNetworkError<T extends RequestPromise | Promise<Resp
 
     const result = await Promise.race([
         request,
-        delay(options.timeout ?? 1000).then(() => { throw TimeoutError; })
+        delay(options.timeout ?? 1500).then(() => { throw TimeoutError; })
     ]).catch(error => {
         console.log(error);
         if (error === TimeoutError || error.name === 'FetchError') {
