Provide a convenient helper for setup on an existing TLS/HTTPS server

Author: pimterry

src/index.ts

@@ -1,5 +1,7 @@
 import * as stream from 'stream';
 import * as crypto from 'crypto';
+import * as tls from 'tls';
+import * as net from 'net';
 
 const collectBytes = (stream: stream.Readable, byteLength: number) => {
     if (byteLength === 0) return Buffer.from([]);
@@ -164,4 +166,76 @@ export function calculateJa3FromFingerprintData(fingerprintData: TlsFingerprintD
 
 export async function getTlsFingerprintAsJa3(rawStream: stream.Readable) {
     return calculateJa3FromFingerprintData(await getTlsFingerprintData(rawStream));
+}
+
+interface FingerprintedSocket extends net.Socket {
+    tlsFingerprint?: {
+        data: TlsFingerprintData;
+        ja3: string;
+    }
+}
+
+declare module 'tls' {
+    interface TLSSocket {
+        /**
+         * This module extends the global TLS types so that all TLS sockets may include
+         * TLS fingerprint data.
+         *
+         * This is only set if the socket came from a TLS server where fingerprinting
+         * has been enabled with `enableFingerprinting`.
+         */
+        tlsFingerprint?: {
+            data: TlsFingerprintData;
+            ja3: string;
+        }
+    }
+}
+
+/**
+ * Modify a TLS server, so that the TLS fingerprint is always parsed and attached to all
+ * sockets at the point when the 'secureConnection' event fires.
+ *
+ * This method mutates and returns the TLS server provided. TLS fingerprint data is
+ * available from all TLS sockets afterwards in the `socket.tlsFingerprint` property.
+ *
+ * This will work for all standard uses of a TLS server or similar (e.g. an HTTPS server)
+ * but may behave unpredictably for advanced use cases, e.g. if you are already
+ * manually injecting connections, hooking methods or events or otherwise doing something
+ * funky & complicated. In those cases you probably want to use the fingerprint
+ * calculation methods directly inside your funky logic instead.
+ */
+export function enableFingerprinting(tlsServer: tls.Server) {
+    // Disable the normal TLS 'connection' event listener that triggers TLS setup:
+    const tlsConnectionListener = tlsServer.listeners('connection')[0] as (socket: net.Socket) => {};
+    if (!tlsConnectionListener) throw new Error('TLS server is not listening for connection events');
+    tlsServer.removeListener('connection', tlsConnectionListener);
+
+    // Listen ourselves for connections, get the fingerprint first, then let TLS setup resume:
+    tlsServer.on('connection', async (socket: FingerprintedSocket) => {
+        try {
+            const fingerprintData = await getTlsFingerprintData(socket);
+
+            socket.tlsFingerprint = {
+                data: fingerprintData,
+                ja3: calculateJa3FromFingerprintData(fingerprintData)
+            };
+        } catch (e) {
+            console.warn(`TLS fingerprint not available for TLS connection from ${
+                socket.remoteAddress ?? 'unknown address'
+            }: ${(e as Error).message ?? e}`);
+        }
+
+        // Once we have a fingerprint, TLS handshakes can continue as normal:
+        tlsConnectionListener.call(tlsServer, socket);
+    });
+
+    tlsServer.prependListener('secureConnection', (tlsSocket: tls.TLSSocket) => {
+        const fingerprint = (tlsSocket as unknown as {
+            _parent?: FingerprintedSocket, // Private TLS socket field which points to the source
+        })._parent?.tlsFingerprint;
+
+        tlsSocket.tlsFingerprint = fingerprint;
+    });
+
+    return tlsServer;
 }

test/test.spec.ts

@@ -2,6 +2,7 @@ import * as path from 'path';
 import * as fs from 'fs';
 import * as net from 'net';
 import * as tls from 'tls';
+import * as http from 'http';
 import * as https from 'https';
 import { makeDestroyable, DestroyableServer } from 'destroyable-server';
 
@@ -16,7 +17,9 @@ import {
 import {
     getTlsFingerprintData,
     getTlsFingerprintAsJa3,
-    calculateJa3FromFingerprintData
+    calculateJa3FromFingerprintData,
+    enableFingerprinting,
+
 } from '../src/index';
 
 const nodeMajorVersion = parseInt(process.version.slice(1).split('.')[0], 10);
@@ -202,11 +205,47 @@ describe("Read-TLS-Fingerprint", () => {
         });
 
         const tlsSocket = await tlsSocketPromise;
-        const fingerprint = (tlsSocket as any).tlsFingerprint;
+        const fingerprint = tlsSocket.tlsFingerprint;
         expect(fingerprint).to.be.oneOf([
             '76cd17e0dc73c98badbb6ee3752dcf4c', // Node 12 - 16
             '6521bd74aad3476cdb3daa827288ec35' // Node 17+
         ]);
     });
 
+    it("can be calculated automatically with the provided helper", async () => {
+        const httpsServer = makeDestroyable(
+            enableFingerprinting(
+                https.createServer({ key: testKey, cert: testCert })
+            )
+        );
+        server = httpsServer;
+
+        const tlsSocketPromise = new Promise<tls.TLSSocket>((resolve) =>
+            httpsServer.on('request', (request: http.IncomingMessage) =>
+                resolve(request.socket as tls.TLSSocket)
+            )
+        );
+
+        httpsServer.listen();
+        await new Promise((resolve) => httpsServer.on('listening', resolve));
+
+        const port = (httpsServer.address() as net.AddressInfo).port;
+        https.get({
+            host: 'localhost',
+            ca: [testCert],
+            port
+        }).on('error', () => {}); // No response, we don't care
+
+        const tlsSocket = await tlsSocketPromise;
+        const fingerprint = tlsSocket.tlsFingerprint;
+
+        expect(fingerprint!.data[0]).to.equal(771); // Is definitely a TLS 1.2+ fingerprint
+        expect(fingerprint!.data.length).to.equal(5); // Full data is checked in other tests
+
+        expect(fingerprint!.ja3).to.be.oneOf([
+            '398430069e0a8ecfbc8db0778d658d77', // Node 12 - 16
+            '0cce74b0d9b7f8528fb2181588d23793' // Node 17+
+        ]);
+    });
+
 });