Add client cert endpoints

Author: pimterry

src/endpoints/endpoint-config.ts

@@ -56,9 +56,11 @@ export function getEndpointConfig(serverNameParts: string[]) {
 
     resolveEnabledVersions(tlsOptions);
 
-    // Pull out our non-OpenSSL marker so what's left is a clean SecureContextOptions.
+    // Pull out our non-OpenSSL markers so what's left is a clean SecureContextOptions.
     const rejectTls = tlsOptions.rejectTls === true;
     delete tlsOptions.rejectTls;
+    const requireClientCert = tlsOptions.requireClientCert === true;
+    delete tlsOptions.requireClientCert;
 
     if (rejectTls && serverNameParts.length > 1) {
         throw new Error(`'no-tls' can't be combined with other endpoints in '${serverNameParts.join('--')}'`);
@@ -68,7 +70,8 @@ export function getEndpointConfig(serverNameParts: string[]) {
         certOptions: certOptions as CertOptions,
         tlsOptions: tlsOptions as tls.SecureContextOptions,
         alpnPreferences,
-        rejectTls
+        rejectTls,
+        requireClientCert
     };
 }
 

src/endpoints/groups.ts

@@ -134,9 +134,16 @@ export const tlsCiphers: EndpointGroup = {
     description: 'Endpoints that offer only a specific weak or legacy cipher suite (over TLS 1.2), to test how your client handles it. A well-configured client should refuse to connect.'
 };
 
+export const tlsClientAuth: EndpointGroup = {
+    id: 'client-auth',
+    name: 'Client Authentication',
+    description: 'Endpoints that require the client to present a certificate (mutual TLS).'
+};
+
 export const tlsGroupOrder: EndpointGroup[] = [
     tlsCertificateModes,
     tlsProtocolNegotiation,
     tlsVersions,
-    tlsCiphers
+    tlsCiphers,
+    tlsClientAuth
 ];

src/endpoints/http/tls-certs.ts

@@ -3,7 +3,7 @@ import { httpTls } from '../groups.js';
 
 const PREFIX = '/tls/certs/';
 
-const CERT_NAMES = ['untrusted-root', 'intermediate', 'self-signed'] as const;
+const CERT_NAMES = ['untrusted-root', 'intermediate', 'self-signed', 'client-cert'] as const;
 type CertName = typeof CERT_NAMES[number];
 
 // The downloadable certificates, keyed by name. Registered as lazy providers at server
@@ -35,15 +35,21 @@ export const tlsCertificates: HttpEndpoint = {
 
         const pem = await (resolved[name] ??= provider());
 
+        // client-cert is a certificate + private key bundle, not a bare CA cert.
+        const contentType = name === 'client-cert'
+            ? 'application/x-pem-file'
+            : 'application/x-x509-ca-cert';
+
         res.writeHead(200, {
-            'content-type': 'application/x-x509-ca-cert',
+            'content-type': contentType,
             'content-disposition': `attachment; filename="testserver-${name}.pem"`
         });
         res.end(pem);
     },
     meta: {
         path: '/tls/certs/{name}',
-        description: 'Download the TLS certificates used by the local CA configuration, in PEM format.',
+        description: 'Download the TLS certificates used by the local CA configuration, in PEM ' +
+            'format. client-cert is a certificate + key bundle for the mTLS client-cert endpoint.',
         examples: CERT_NAMES.map(name => `${PREFIX}${name}`),
         group: httpTls
     }

src/endpoints/tls-index.ts

@@ -9,6 +9,7 @@ export type { EndpointMeta, EndpointGroup };
 export interface TlsOptionContribution extends Partial<tls.SecureContextOptions> {
     enabledVersions?: tls.SecureVersion[];
     rejectTls?: boolean;
+    requireClientCert?: boolean;
 }
 
 export interface TlsEndpoint {
@@ -24,6 +25,7 @@ export interface TlsEndpoint {
 export * from './tls/alpn-specifiers.js';
 export * from './tls/cert-modes.js';
 export * from './tls/ciphers.js';
+export * from './tls/client-cert.js';
 export * from './tls/example.js';
 export * from './tls/no-tls.js';
 export * from './tls/tls-versions.js';

src/endpoints/tls/client-cert.ts

@@ -0,0 +1,17 @@
+import { TlsEndpoint } from '../tls-index.js';
+import { tlsClientAuth } from '../groups.js';
+
+export const clientCert: TlsEndpoint = {
+    sniPart: 'client-cert',
+    configureTlsOptions() {
+        return { requireClientCert: true };
+    },
+    meta: {
+        path: 'client-cert',
+        description: 'Requires the client to present a certificate (mutual TLS). The handshake ' +
+            "is rejected unless the client presents a certificate issued by this server's " +
+            'dedicated client-auth CA. Download one to use from /tls/certs/client-cert.',
+        examples: ['https://client-cert.testserver.host/'],
+        group: tlsClientAuth
+    }
+};

src/server.ts

@@ -234,7 +234,9 @@ const createTcpHandler = async (options: ServerOptions = {}) => {
         'intermediate': () => tlsConfig.localCA.getIntermediateCertificatePem(),
         'self-signed': () => tlsConfig.localCA
             .generateCertificate(tlsConfig.rootDomain, { selfSigned: true })
-            .then((cert) => cert.cert)
+            .then((cert) => cert.cert),
+        'client-cert': () => tlsConfig.localCA.getClientCertificate()
+            .then((client) => `${client.cert.trimEnd()}\n${client.key.trimEnd()}\n`)
     });
     const tlsHandler = await createTlsHandler(tlsConfig, connProcessor);