Add support for https.keyLog option for logging TLS keys

pimterry · pimterry · commit 6f97801bd757 · 2025-09-18T19:27:01.000+02:00
This allows advanced use cases where you want to combine a tool like
Wireshark with Mockttp.

Currently the keys for all inbound traffic, and all outbound HTTP/1
traffic are exported. Keys from outbound HTTP/2 traffic is not yet
listed but is intended to be included in future.
diff --git a/karma.conf.js b/karma.conf.js
@@ -30,7 +30,8 @@ module.exports = function(config) {
                     "request-promise-native": require.resolve('./test/empty-stub.js'),
                     "portfinder": require.resolve('./test/empty-stub.js'),
                     "dns2": require.resolve('./test/empty-stub.js'),
-                    "ws": require.resolve('./test/empty-stub.js')
+                    "ws": require.resolve('./test/empty-stub.js'),
+                    "tmp-promise": require.resolve('./test/empty-stub.js')
                 },
                 fallback: {
                     // With Webpack 5, we need explicit mocks for all node modules. Because the
diff --git a/src/mockttp.ts b/src/mockttp.ts
@@ -787,6 +787,17 @@ export type MockttpHttpsOptions = CAOptions & {
     tlsServerOptions?: {
         minVersion?: 'TLSv1.3' | 'TLSv1.2' | 'TLSv1.1' | 'TLSv1';
     };
+
+    /**
+     * The path to a file where TLS session keys should be logged. This allows you to combine
+     * Mockttp with Wireshark and similar, allowing to you inspect the decrypted raw bytes
+     * and full TLS handshake details, while also using Mockttp for high-level capture
+     * & traffic modification.
+     *
+     * When set, the keys for both client & server sessions will be logged, allowing you
+     * to examine both sides of the proxied connection.
+     */
+    keyLogFile?: string;
 };
 
 export interface MockttpOptions {
diff --git a/src/rules/requests/request-rule.ts b/src/rules/requests/request-rule.ts
@@ -1,4 +1,5 @@
 import { Buffer } from 'buffer';
+import { Writable } from 'stream';
 
 import * as _ from 'lodash';
 
@@ -22,6 +23,7 @@ export interface RequestRule extends Explainable {
     handle(request: OngoingRequest, response: OngoingResponse, options: {
         record: boolean,
         debug: boolean,
+        keyLogStream?: Writable,
         emitEventCallback?: (type: string, event: unknown) => void
     }): Promise<void>;
     isComplete(): boolean | null;
@@ -78,12 +80,14 @@ export class RequestRule implements RequestRule {
     handle(req: OngoingRequest, res: OngoingResponse, options: {
         record?: boolean,
         debug: boolean,
+        keyLogStream?: Writable,
         emitEventCallback?: (type: string, event: unknown) => void
     }): Promise<void> {
         let stepsPromise = (async () => {
             for (let step of this.steps) {
                 const result = await step.handle(req, res, {
                     emitEventCallback: options.emitEventCallback,
+                    keyLogStream: options.keyLogStream,
                     debug: options.debug
                 });
 
diff --git a/src/rules/requests/request-step-impls.ts b/src/rules/requests/request-step-impls.ts
@@ -1,9 +1,10 @@
 import { Buffer } from 'buffer';
-import type dns = require('dns');
-import url = require('url');
-import net = require('net');
-import http = require('http');
-import https = require('https');
+import { Writable } from 'stream';
+import * as url from 'url';
+import type * as dns from 'dns';
+import * as net from 'net';
+import * as http from 'http';
+import * as https from 'https';
 
 import * as _ from 'lodash';
 import * as fs from 'fs/promises';
@@ -165,6 +166,7 @@ export interface RequestStepImpl extends RequestStepDefinition {
 
 export interface RequestStepOptions {
     emitEventCallback?: (type: string, event: unknown) => void;
+    keyLogStream?: Writable;
     debug: boolean;
 }
 
@@ -1064,6 +1066,12 @@ export class PassThroughStepImpl extends PassThroughStep {
                 // make multiple requests. If/when that happens, we don't need more event listeners.
                 if (this.outgoingSockets.has(socket)) return;
 
+                if (options.keyLogStream) {
+                    socket.on('keylog', (line) => {
+                        options.keyLogStream!.write(line);
+                    });
+                }
+
                 // Add this port to our list of active ports, once it's connected (before then it has no port)
                 if (socket.connecting) {
                     socket.once('connect', () => {
diff --git a/src/rules/websockets/websocket-rule.ts b/src/rules/websockets/websocket-rule.ts
@@ -1,3 +1,4 @@
+import { Writable } from 'stream';
 import * as net from 'net';
 import * as http from 'http';
 
@@ -32,6 +33,7 @@ export interface WebSocketRule extends Explainable {
         options: {
             record: boolean,
             debug: boolean,
+            keyLogStream?: Writable,
             emitEventCallback?: (type: string, event: unknown) => void
         }
     ): Promise<void>;
@@ -93,6 +95,7 @@ export class WebSocketRule implements WebSocketRule {
         options: {
             record: boolean,
             debug: boolean,
+            keyLogStream?: Writable,
             emitEventCallback?: (type: string, event: unknown) => void
         }
     ): Promise<void> {
diff --git a/src/rules/websockets/websocket-step-impls.ts b/src/rules/websockets/websocket-step-impls.ts
@@ -377,8 +377,9 @@ export class PassThroughWebSocketStepImpl extends PassThroughWebSocketStep {
             })
         } as WebSocket.ClientOptions & { lookup: any, maxPayload: number });
 
+        const upstreamReq = (upstreamWebSocket as any as { _req: http.ClientRequest })._req;
+
         if (options.emitEventCallback) {
-            const upstreamReq = (upstreamWebSocket as any as { _req: http.ClientRequest })._req;
             // This is slower than req.getHeaders(), but gives us (roughly) the correct casing
             // of the headers as sent. Still not perfect (loses dupe ordering) but at least it
             // generally matches what's actually sent on the wire.
@@ -409,6 +410,12 @@ export class PassThroughWebSocketStepImpl extends PassThroughWebSocketStep {
             });
         }
 
+        if (options.keyLogStream) {
+            upstreamReq.on('socket', (socket) => {
+                socket.on('keylog', (line) => options.keyLogStream!.write(line));
+            });
+        }
+
         upstreamWebSocket.once('open', () => {
             // Used in the subprotocol selection handler during the upgrade:
             (req as InterceptedWebSocketRequest).upstreamWebSocketProtocol = upstreamWebSocket.protocol || false;
diff --git a/src/server/http-combo-server.ts b/src/server/http-combo-server.ts
@@ -1,9 +1,10 @@
 import _ = require('lodash');
 import now = require('performance-now');
-import net = require('net');
-import tls = require('tls');
-import http = require('http');
-import http2 = require('http2');
+import { Writable } from 'stream';
+import * as net from 'net';
+import * as tls from 'tls';
+import * as http from 'http';
+import * as http2 from 'http2';
 
 import * as semver from 'semver';
 import { makeDestroyable, DestroyableServer } from 'destroyable-server';
@@ -151,6 +152,7 @@ export interface ComboServerOptions {
     http2: boolean | 'fallback';
     socks: boolean | SocksServerOptions;
     passthroughUnknownProtocols: boolean;
+    keyLogStream: Writable | undefined,
 
     requestListener: (req: http.IncomingMessage, res: http.ServerResponse) => void;
     tlsClientErrorListener: (socket: tls.TLSSocket, req: TlsHandshakeFailure) => void;
@@ -220,6 +222,12 @@ export async function createComboServer(options: ComboServerOptions): Promise<De
             }
         });
 
+        if (options.keyLogStream) {
+            tlsServer.on('keylog', (line: string) => {
+                options.keyLogStream?.write(line);
+            });
+        }
+
         analyzeAndMaybePassThroughTls(
             tlsServer,
             options.https.tlsPassthrough,
diff --git a/src/server/mockttp-server.ts b/src/server/mockttp-server.ts
@@ -1,4 +1,6 @@
 import { Buffer } from 'buffer';
+import * as stream from 'stream';
+import * as fs from 'fs';
 import * as net from "net";
 import * as tls from "tls";
 import * as http from "http";
@@ -122,6 +124,8 @@ export class MockttpServer extends AbstractMockttp implements Mockttp {
     private socksOptions: boolean | SocksServerOptions;
     private passthroughUnknownProtocols: boolean;
     private maxBodySize: number;
+    private keyLogFilePath: string | undefined;
+    private keyLogStream: fs.WriteStream | undefined;
 
     private app: connect.Server;
     private server: DestroyableServer<net.Server> | undefined;
@@ -140,6 +144,8 @@ export class MockttpServer extends AbstractMockttp implements Mockttp {
         this.socksOptions = options.socks ?? false;
         this.passthroughUnknownProtocols = options.passthrough?.includes('unknown-protocol') ?? false;
         this.maxBodySize = options.maxBodySize ?? Infinity;
+        this.keyLogFilePath = options.https?.keyLogFile;
+
         this.eventEmitter = new EventEmitter();
 
         this.app = connect();
@@ -158,12 +164,20 @@ export class MockttpServer extends AbstractMockttp implements Mockttp {
     }
 
     async start(portParam: number | PortRange = { startPort: 8000, endPort: 65535 }): Promise<void> {
+        if (this.keyLogFilePath) {
+            this.keyLogStream = fs.createWriteStream(this.keyLogFilePath, { flags: 'a' });
+            this.keyLogStream.on('error', (err) => {
+                console.warn(`Error writing TLS key log file ${this.keyLogFilePath}:`, err);
+            });
+        }
+
         this.server = await createComboServer({
             debug: this.debug,
             https: this.httpsOptions,
             http2: this.isHttp2Enabled,
             socks: this.socksOptions,
             passthroughUnknownProtocols: this.passthroughUnknownProtocols,
+            keyLogStream: this.keyLogStream,
 
             requestListener: this.app,
             tlsClientErrorListener: this.announceTlsErrorAsync.bind(this),
@@ -222,6 +236,8 @@ export class MockttpServer extends AbstractMockttp implements Mockttp {
 
         if (this.server) await this.server.destroy();
 
+        if (this.keyLogStream) this.keyLogStream.end();
+
         this.reset();
     }
 
@@ -837,6 +853,7 @@ export class MockttpServer extends AbstractMockttp implements Mockttp {
                 await nextRule.handle(request, response, {
                     record: this.recordTraffic,
                     debug: this.debug,
+                    keyLogStream: this.keyLogStream,
                     emitEventCallback: (this.eventEmitter.listenerCount('rule-event') !== 0)
                         ? (type, event) => this.announceRuleEventAsync(request.id, nextRule!.id, type, event)
                         : undefined
@@ -912,6 +929,7 @@ export class MockttpServer extends AbstractMockttp implements Mockttp {
                 await nextRule.handle(request, socket, head, {
                     record: this.recordTraffic,
                     debug: this.debug,
+                    keyLogStream: this.keyLogStream,
                     emitEventCallback: (this.eventEmitter.listenerCount('rule-event') !== 0)
                         ? (type, event) => this.announceRuleEventAsync(request.id, nextRule!.id, type, event)
                         : undefined
diff --git a/test/integration/https.spec.ts b/test/integration/https.spec.ts
@@ -2,17 +2,18 @@ import * as http from 'http';
 import * as tls from 'tls';
 import * as https from 'https';
 import * as fs from 'fs/promises';
+import * as tmp from 'tmp-promise';
+import * as WebSocket from 'isomorphic-ws';
 
-import { getLocal } from "../..";
+import { getLocal, Mockttp } from "../..";
 import {
     expect,
     fetch,
     nodeOnly,
     delay,
     openRawSocket,
     openRawTlsSocket,
-    http2ProxyRequest,
-    nodeSatisfies
+    http2ProxyRequest
 } from "../test-utils";
 import { streamToBuffer } from '../../src/util/buffer-utils';
 
@@ -483,5 +484,82 @@ describe("When configured for HTTPS", () => {
                 tlsSocket.destroy();
             });
         });
+
+        describe("with a keylog file configured", () => {
+
+            const remoteNonLoggingServer = getLocal({
+                https: {
+                    keyPath: './test/fixtures/test-ca.key',
+                    certPath: './test/fixtures/test-ca.pem',
+                }
+            });
+
+            let server: Mockttp;
+            let keyLogFile!: string;
+
+            beforeEach(async () => {
+                keyLogFile = await tmp.tmpName();
+                server = getLocal({
+                    https: {
+                        keyPath: './test/fixtures/test-ca.key',
+                        certPath: './test/fixtures/test-ca.pem',
+                        keyLogFile
+                    }
+                });
+                await server.start();
+                await remoteNonLoggingServer.start();
+            });
+
+            afterEach(async () => {
+                await server.stop().catch(() => {});
+                await remoteNonLoggingServer.stop().catch(() => {});
+                await fs.unlink(keyLogFile).catch(() => {});
+            });
+
+            it("should log downstream TLS keys to the file", async () => {
+                await server.forGet('/').thenReply(200);
+                await fetch(server.url);
+
+                const keyLogContents = await fs.readFile(keyLogFile, 'utf8');
+
+                expect(keyLogContents).to.include('CLIENT_HANDSHAKE_TRAFFIC_SECRET');
+                expect(keyLogContents).to.include('SERVER_HANDSHAKE_TRAFFIC_SECRET');
+                expect(keyLogContents).to.include('CLIENT_TRAFFIC_SECRET_0');
+                expect(keyLogContents).to.include('SERVER_TRAFFIC_SECRET_0');
+            });
+
+            it("should log upstream TLS keys to the file", async () => {
+                // Make an HTTP request, but proxy to an HTTPS server:
+                await server.forGet('/').thenForwardTo(remoteNonLoggingServer.url);
+                await fetch(`http://localhost:${server.port}/`);
+
+                const keyLogContents = await fs.readFile(keyLogFile, 'utf8');
+
+                expect(keyLogContents).to.include('CLIENT_HANDSHAKE_TRAFFIC_SECRET');
+                expect(keyLogContents).to.include('SERVER_HANDSHAKE_TRAFFIC_SECRET');
+                expect(keyLogContents).to.include('CLIENT_TRAFFIC_SECRET_0');
+                expect(keyLogContents).to.include('SERVER_TRAFFIC_SECRET_0');
+            });
+
+            it("should log upstream WebSocket TLS keys to the file", async () => {
+                await server.forAnyWebSocket().thenForwardTo(remoteNonLoggingServer.url);
+                await remoteNonLoggingServer.forAnyWebSocket().thenEcho();
+
+                const ws = new WebSocket(`ws://localhost:${server.port}/`);
+                await new Promise((resolve, reject) => {
+                    ws.addEventListener('open', resolve);
+                    ws.addEventListener('error', reject);
+                });
+                ws.close(1000);
+
+                const keyLogContents = await fs.readFile(keyLogFile, 'utf8');
+
+                expect(keyLogContents).to.include('CLIENT_HANDSHAKE_TRAFFIC_SECRET');
+                expect(keyLogContents).to.include('SERVER_HANDSHAKE_TRAFFIC_SECRET');
+                expect(keyLogContents).to.include('CLIENT_TRAFFIC_SECRET_0');
+                expect(keyLogContents).to.include('SERVER_TRAFFIC_SECRET_0');
+            });
+
+        });
     });
 });
