Add support for incomplete-chain TLS endpoint (ACME & local)

Author: pimterry

src/endpoints/tls/cert-modes.ts

@@ -62,6 +62,21 @@ export const untrustedRoot: TlsEndpoint = {
     }
 };
 
+export const incompleteChain: TlsEndpoint = {
+    sniPart: 'incomplete-chain',
+    configureCertOptions() {
+        return {
+            incompleteChain: true
+        };
+    },
+    meta: {
+        path: 'incomplete-chain',
+        description: 'Serves a TLS certificate without the required intermediate certificate.',
+        examples: ['https://incomplete-chain.testserver.host/'],
+        group: tlsCertificateModes
+    }
+};
+
 export const wrongHost: TlsEndpoint = {
     sniPart: 'wrong-host',
     configureCertOptions() {

src/tls-certificates/cert-definitions.ts

@@ -6,6 +6,10 @@ export interface CertOptions {
     selfSigned?: boolean;
 
     overridePrefix?: string;
+
+    // This is a presentation difference only - cert is the same, we just don't
+    // send the full chain with it.
+    incompleteChain?: boolean;
 }
 
 export function calculateCertCacheKey(domain: string, options: CertOptions) {
@@ -20,4 +24,12 @@ export function calculateCertCacheKey(domain: string, options: CertOptions) {
     }
 
     return `${domain}+${parts.join('+')}`;
+}
+
+const CERT_PEM_PATTERN = /-----BEGIN CERTIFICATE-----[\s\S]*?-----END CERTIFICATE-----/g;
+
+export function extractLeafCertificate(certChainPem: string): string {
+    const leaf = certChainPem.match(CERT_PEM_PATTERN)?.[0];
+    if (!leaf) throw new Error('Could not find any certificate in chain PEM');
+    return leaf + '\n';
 }

src/tls-certificates/local-ca.ts

@@ -175,7 +175,8 @@ function calculateCacheKey(domain: string, options: CertOptions) {
     return `${domain}+${([
         'expired',
         'revoked',
-        'selfSigned'
+        'selfSigned',
+        'incompleteChain'
     ] as const).filter((k: keyof CertOptions) => options[k]).join('+')}`
 }
 
@@ -199,15 +200,24 @@ const KEY_PAIR_ALGO = {
 interface CertGenerationOptions {
     selfSigned?: boolean;
     expired?: boolean;
+    incompleteChain?: boolean;
 }
 
+type IntermediateCA = {
+    cert: x509.X509Certificate,
+    key: CryptoKey,
+    pem: string
+};
+
 export class LocalCA {
     private caCert: x509.X509Certificate;
     private caKey: CryptoKey;
     private options: CAOptions;
 
     private certInMemoryCache: { [domain: string]: LocallyGeneratedCertificate | undefined } = {};
 
+    private intermediateCA?: Promise<IntermediateCA>;
+
     private constructor(
         private caCertPem: string,
         caCert: x509.X509Certificate,
@@ -243,6 +253,60 @@ export class LocalCA {
         return new LocalCA(caOptions.cert.toString(), caCert, caKey, caOptions);
     }
 
+    private getIntermediateCA(): Promise<IntermediateCA> {
+        if (!this.intermediateCA) {
+            this.intermediateCA = this.createIntermediateCA();
+        }
+        return this.intermediateCA;
+    }
+
+    private async createIntermediateCA(): Promise<IntermediateCA> {
+        const keyPair = await crypto.subtle.generateKey(
+            { ...KEY_PAIR_ALGO, modulusLength: this.options.keyLength || 2048 },
+            true,
+            ["sign", "verify"]
+        ) as CryptoKeyPair;
+
+        const subjectDistinguishedName = new x509.Name([
+            { C: [this.options.countryName ?? 'XX'] },
+            { O: ['Testserver'] },
+            { CN: ['Test Intermediate CA'] }
+        ]).toString();
+
+        const notBefore = new Date();
+        notBefore.setDate(notBefore.getDate() - 1);
+        const notAfter = new Date();
+        notAfter.setFullYear(notAfter.getFullYear() + 1);
+
+        const cert = await x509.X509CertificateGenerator.create({
+            serialNumber: generateSerialNumber(),
+            subject: subjectDistinguishedName,
+            issuer: this.caCert.subject,
+            notBefore,
+            notAfter,
+            signingAlgorithm: KEY_PAIR_ALGO,
+            publicKey: keyPair.publicKey as CryptoKey,
+            signingKey: this.caKey,
+            extensions: [
+                new x509.BasicConstraintsExtension(true, 0, 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(this.caCert, false)
+            ]
+        });
+
+        return {
+            cert,
+            key: keyPair.privateKey as CryptoKey,
+            pem: cert.toString('pem')
+        };
+    }
+
     async generateCertificate(
         domain: string,
         options: CertGenerationOptions
@@ -282,9 +346,16 @@ export class LocalCA {
         }
 
         const subjectDistinguishedName = new x509.Name(subjectJsonNameParams).toString();
+
+        const intermediate = options.incompleteChain && !options.selfSigned
+            ? await this.getIntermediateCA()
+            : undefined;
+
         const issuerDistinguishedName = options.selfSigned
             ? subjectDistinguishedName
-            : this.caCert.subject;
+            : intermediate
+                ? intermediate.cert.subject
+                : this.caCert.subject;
 
         const notBefore = new Date();
         const notAfter = new Date();
@@ -325,7 +396,10 @@ export class LocalCA {
 
         // We don't include SubjectKeyIdentifierExtension as that's no longer recommended
         if (!options.selfSigned) {
-            extensions.push(await x509.AuthorityKeyIdentifierExtension.create(this.caCert, false));
+            extensions.push(await x509.AuthorityKeyIdentifierExtension.create(
+                intermediate ? intermediate.cert : this.caCert,
+                false
+            ));
         }
 
         const certificate = await x509.X509CertificateGenerator.create({
@@ -336,7 +410,11 @@ export class LocalCA {
             notAfter,
             signingAlgorithm: KEY_PAIR_ALGO,
             publicKey: leafKeyPair.publicKey,
-            signingKey: options.selfSigned ? leafKeyPair.privateKey as CryptoKey : this.caKey,
+            signingKey: options.selfSigned
+                ? leafKeyPair.privateKey as CryptoKey
+                : intermediate
+                    ? intermediate.key
+                    : this.caKey,
             extensions
         });
 
@@ -346,7 +424,9 @@ export class LocalCA {
                 await crypto.subtle.exportKey("pkcs8", leafKeyPair.privateKey as CryptoKey),
                 "PRIVATE KEY"
             ),
-            cert: certPem,
+            cert: intermediate
+                ? `${certPem.trimEnd()}\n${intermediate.pem.trimEnd()}\n`
+                : certPem,
             ca: options.selfSigned ? certPem : this.caCertPem // Use cached CA cert PEM
         };
 

src/tls-handler.ts

@@ -8,7 +8,7 @@ import { getExtensionData } from 'read-tls-client-hello';
 
 import { ConnectionProcessor } from './process-connection.js';
 import { LocalCA } from './tls-certificates/local-ca.js';
-import { CertOptions, calculateCertCacheKey } from './tls-certificates/cert-definitions.js';
+import { CertOptions, calculateCertCacheKey, extractLeafCertificate } from './tls-certificates/cert-definitions.js';
 import { SecureContextCache } from './tls-certificates/secure-context-cache.js';
 import { tlsEndpoints } from './endpoints/endpoint-index.js';
 import { PROXY_PROTOCOL } from './proxy-protocol.js';
@@ -23,10 +23,11 @@ function calculateContextCacheKey(
     tlsOptions: tls.SecureContextOptions
 ): string {
     const certKey = calculateCertCacheKey(domain, certOptions);
+    const chainKey = certOptions.incompleteChain ? '|incomplete-chain' : '';
     const tlsKey = Object.keys(tlsOptions).length > 0
         ? '|' + JSON.stringify(tlsOptions, Object.keys(tlsOptions).sort())
         : '';
-    return certKey + tlsKey;
+    return certKey + chainKey + tlsKey;
 }
 
 function getCertExpiry(certPem: string): number {
@@ -171,11 +172,19 @@ class TlsConnectionHandler {
 
             const secureContext = await secureContextCache.getOrCreate(cacheKey, async () => {
                 const cert = await this.tlsConfig.generateCertificate(certDomain, certOptions);
+
+                const servedCert = certOptions.incompleteChain
+                    ? extractLeafCertificate(cert.cert)
+                    : cert.cert;
+                const servedCa = certOptions.incompleteChain
+                    ? undefined
+                    : cert.ca;
+
                 return {
                     context: tls.createSecureContext({
                         key: cert.key,
-                        cert: cert.cert,
-                        ca: cert.ca,
+                        cert: servedCert,
+                        ca: servedCa,
                         ...tlsOptions
                     }),
                     // Temporary certs (e.g. local CA fallback while ACME pending) get short cache

test/incomplete-chain.spec.ts

@@ -0,0 +1,109 @@
+import * as net from 'net';
+import * as tls from 'tls';
+
+import { expect } from 'chai';
+import { DestroyableServer, makeDestroyable } from 'destroyable-server';
+
+import { extractLeafCertificate } from '../src/tls-certificates/cert-definitions.js';
+import { createTestServer } from './test-helpers.js';
+
+const fakeCert = (body: string) =>
+    `-----BEGIN CERTIFICATE-----\n${body}\n-----END CERTIFICATE-----`;
+
+describe("extractLeafCertificate", () => {
+
+    it("returns only the leaf from a leaf+intermediates bundle", () => {
+        const bundle = [fakeCert('LEAF'), fakeCert('INTERMEDIATE'), fakeCert('ROOT')].join('\n');
+
+        const leaf = extractLeafCertificate(bundle);
+
+        expect(leaf).to.include('LEAF');
+        expect(leaf).to.not.include('INTERMEDIATE');
+        expect(leaf).to.not.include('ROOT');
+    });
+
+    it("returns the single certificate when there is no intermediate", () => {
+        const leaf = extractLeafCertificate(fakeCert('LEAF'));
+        expect(leaf).to.include('LEAF');
+    });
+
+    it("throws when no certificate is present", () => {
+        expect(() => extractLeafCertificate('not a certificate')).to.throw();
+    });
+
+});
+
+describe("incomplete-chain certificates", () => {
+
+    let server: DestroyableServer;
+    let serverPort: number;
+
+    beforeEach(async () => {
+        server = makeDestroyable(await createTestServer());
+        await new Promise<void>((resolve) => server.listen(resolve));
+        serverPort = (server.address() as net.AddressInfo).port;
+    });
+
+    afterEach(async () => {
+        await server.destroy();
+    });
+
+    const connectAndGetChain = (servername: string, alpn?: string[]) =>
+        new Promise<{ cert: tls.DetailedPeerCertificate, protocol: string | false | null }>((resolve, reject) => {
+            const conn = tls.connect({
+                port: serverPort,
+                servername,
+                ...(alpn ? { ALPNProtocols: alpn } : {}),
+                rejectUnauthorized: false
+            });
+            conn.on('secureConnect', () => {
+                resolve({ cert: conn.getPeerCertificate(true), protocol: conn.alpnProtocol });
+                conn.destroy();
+            });
+            conn.on('error', reject);
+        });
+
+    // Walk the chain the server actually presented, counting distinct certificates.
+    const presentedChainLength = (leaf: tls.DetailedPeerCertificate) => {
+        const seen = new Set<string>();
+        let cert: tls.DetailedPeerCertificate | undefined = leaf;
+        while (cert?.fingerprint256 && !seen.has(cert.fingerprint256)) {
+            seen.add(cert.fingerprint256);
+            cert = cert.issuerCertificate;
+        }
+        return seen.size;
+    };
+
+    it("serves the leaf certificate for the requested domain", async () => {
+        const { cert } = await connectAndGetChain('incomplete-chain.localhost');
+
+        expect(cert.subject.CN).to.equal('incomplete-chain.localhost');
+        expect(cert.subjectaltname).to.equal('DNS:incomplete-chain.localhost');
+    });
+
+    it("issues the leaf via a genuine intermediate CA", async () => {
+        const { cert } = await connectAndGetChain('incomplete-chain.localhost');
+
+        expect(cert.issuer.CN).to.equal('Test Intermediate CA');
+        expect(cert.issuer.CN).to.not.equal(cert.subject.CN);
+    });
+
+    it("presents no intermediate certificates alongside the leaf", async () => {
+        const { cert } = await connectAndGetChain('incomplete-chain.localhost');
+
+        // The intermediate is omitted, so the client receives a single certificate
+        // and cannot build a complete chain even if it trusts the root.
+        expect(presentedChainLength(cert)).to.equal(1);
+    });
+
+    it("can combine incomplete-chain with protocol preferences", async () => {
+        const { cert, protocol } = await connectAndGetChain(
+            'http2--incomplete-chain.localhost',
+            ['http/1.1', 'h2']
+        );
+
+        expect(cert.subject.CN).to.equal('http2--incomplete-chain.localhost');
+        expect(protocol).to.equal('h2');
+    });
+
+});

test/tls-required.spec.ts

@@ -32,6 +32,7 @@ describe("TLS-required endpoints over plain HTTP", () => {
             'self-signed',
             'untrusted-root',
             'wrong-host',
+            'incomplete-chain',
             'http2',
             'http1'
         ]) {