Fully calculate the base JA3 TLS fingerprint data

This doesn't yet hash the data - but it does successfully parse every
detail we need in the fingerprint and calculate the correct values, and
the raw format is more useful for analysis in many cases.

Author: pimterry

src/index.ts

@@ -1,6 +1,128 @@
-import * as stream from "stream";
+import * as stream from 'stream';
 
-export async function getTlsFingerprint(data: stream.Readable) {
-    const firstData: any = await new Promise((resolve) => data.on('data', resolve));
-    return firstData[0].toString();
+const collectBytes = (stream: stream.Readable, byteLength: number) => {
+    if (byteLength === 0) return Buffer.from([]);
+
+    return new Promise<Buffer>(async (resolve, reject) => {
+        const closeReject = () => reject(new Error('Stream closed before expected data could be read'));
+
+        try {
+            stream.on('error', reject);
+            stream.on('close', closeReject);
+
+            const data: Buffer[] = [];
+            let dataLength = 0;
+            let readNull = false;
+            do {
+                if (!stream.readable || readNull) await new Promise<Buffer>((resolve) => stream.once('readable', resolve));
+
+                const nextData = stream.read(byteLength - dataLength)
+                    ?? stream.read(); // If less than wanted data is available, at least read what we can get
+
+                if (nextData === null) {
+                    // Still null => tried to read, not enough data
+                    readNull = true;
+                    continue;
+                }
+
+                data.push(nextData);
+                dataLength += nextData.byteLength;
+            } while (dataLength < byteLength)
+
+            return resolve(Buffer.concat(data, byteLength));
+        } catch (e) {
+            reject(e);
+        } finally {
+            stream.removeListener('error', reject);
+            stream.removeListener('close', closeReject);
+        }
+    });
+};
+
+const getUint16BE = (buffer: Buffer, offset: number) =>
+    (buffer[offset] << 8) + buffer[offset+1];
+
+export async function getTlsFingerprint(rawStream: stream.Readable) {
+    // Create a separate stream, which isn't flowing, so we can read byte-by-byte regardless of how else
+    // the stream is being used.
+    const inputStream = new stream.PassThrough();
+    rawStream.pipe(inputStream);
+
+    const [recordType] = await collectBytes(inputStream, 1);
+    if (recordType !== 0x16) throw new Error("Can't calculate TLS fingerprint - not a TLS stream");
+
+    const tlsRecordVersion = await collectBytes(inputStream, 2);
+    const recordLength = (await collectBytes(inputStream, 2)).readUint16BE();
+
+    // Collect all the hello bytes, and then give us a stream of exactly only those bytes, so we can
+    // still process them step by step in order:
+    const helloDataStream = stream.Readable.from(await collectBytes(inputStream, recordLength), { objectMode: false });
+    rawStream.unpipe(inputStream); // Don't need any more data now, thanks.
+
+    const [helloType] = (await collectBytes(helloDataStream, 1));
+    if (helloType !== 0x1) throw new Error("Can't calculate TLS fingerprint - not a TLS client hello");
+
+    const helloLength = (await collectBytes(helloDataStream, 3)).readIntBE(0, 3);
+    if (helloLength !== recordLength - 4) throw new Error(
+        `Unexpected client hello length: ${helloLength} (or ${recordLength})`
+    );
+
+    const clientTlsVersion = await collectBytes(helloDataStream, 2);
+    const clientRandom = await collectBytes(helloDataStream, 32);
+
+    const [sessionIdLength] = await collectBytes(helloDataStream, 1);
+    const sessionId = await collectBytes(helloDataStream, sessionIdLength);
+
+    const cipherSuitesLength = (await collectBytes(helloDataStream, 2)).readUint16BE();
+    const cipherSuites = await collectBytes(helloDataStream, cipherSuitesLength);
+
+    const [compressionMethodsLength] = await collectBytes(helloDataStream, 1);
+    const compressionMethods = await collectBytes(helloDataStream, compressionMethodsLength);
+
+    const extensionsLength = (await collectBytes(helloDataStream, 2)).readUint16BE();
+    let readExtensionsDataLength = 0;
+    const extensions: Array<{ id: Buffer, data: Buffer }> = [];
+
+    while (readExtensionsDataLength < extensionsLength) {
+        const extensionId = await collectBytes(helloDataStream, 2);
+        const extensionLength = (await collectBytes(helloDataStream, 2)).readUint16BE();
+        const extensionData = await collectBytes(helloDataStream, extensionLength);
+
+        extensions.push({ id: extensionId, data: extensionData });
+        readExtensionsDataLength += 4 + extensionLength;
+    }
+
+    // All data parsed! Now turn it into the fingerprint format:
+    //SSLVersion,Cipher,SSLExtension,EllipticCurve,EllipticCurvePointFormat
+
+    const tlsVersionFingerprint = clientTlsVersion.readUint16BE()
+
+    const cipherFingerprint: number[] = [];
+    for (let i = 0; i < cipherSuites.length; i += 2) {
+        cipherFingerprint.push(getUint16BE(cipherSuites, i));
+    }
+
+    const extensionsFingerprint: number[] = extensions.map(({ id }) => getUint16BE(id, 0));
+
+    const supportedGroupsData = (
+        extensions.find(({ id }) => id.equals(Buffer.from([0x0, 0x0a])))?.data
+        ?? Buffer.from([])
+    ).slice(2) // Drop the length prefix
+
+    const groupsFingerprint: number[] = [];
+    for (let i = 0; i < supportedGroupsData.length; i += 2) {
+        groupsFingerprint.push(getUint16BE(supportedGroupsData, i));
+    }
+
+    const curveFormatsData = extensions.find(({ id }) => id.equals(Buffer.from([0x0, 0x0b])))?.data
+        ?? Buffer.from([]);
+    const curveFormatsFingerprint: number[] = Array.from(curveFormatsData.slice(1)); // Drop length prefix
+
+    return [
+        tlsVersionFingerprint,
+        cipherFingerprint,
+        extensionsFingerprint,
+        groupsFingerprint,
+        curveFormatsFingerprint
+    ] as const;
 }

test/test.spec.ts

@@ -2,10 +2,12 @@ import * as net from 'net';
 import * as tls from 'tls';
 import { makeDestroyable, DestroyableServer } from 'destroyable-server';
 
+import { expect } from 'chai';
 import { getDeferred } from './test-util';
 
 import { getTlsFingerprint } from '../src/index';
-import { expect } from 'chai';
+
+const nodeMajorVersion = parseInt(process.version.slice(1).split('.')[0], 10);
 
 describe("Read-TLS-Fingerprint", () => {
 
@@ -22,16 +24,40 @@ describe("Read-TLS-Fingerprint", () => {
         let incomingSocketPromise = getDeferred<net.Socket>();
         server.on('connection', (socket) => incomingSocketPromise.resolve(socket));
 
-        console.log(server.address());
         const port = (server.address() as net.AddressInfo).port;
         tls.connect({
-            host: '127.0.0.1',
+            host: 'localhost',
             port
         }).on('error', () => {}); // Socket will fail, since server never responds, that's OK
 
         const incomingSocket = await incomingSocketPromise;
         const fingerprint = await getTlsFingerprint(incomingSocket);
 
-        expect(fingerprint).to.equal('22'); // Basic WIP test: yes, this is TLS
+        const [
+            tlsVersion,
+            ciphers,
+            extension,
+            groups,
+            curveFormats
+        ] = fingerprint;
+
+        expect(tlsVersion).to.equal(771); // TLS 1.2 - now set even for TLS 1.3 for backward compat
+        expect(ciphers.slice(0, 3)).to.deep.equal([4866, 4867, 4865]);
+        expect(extension).to.deep.equal([
+            11,
+            10,
+            35,
+            22,
+            23,
+            13,
+            43,
+            45,
+            51
+        ]);
+        expect(groups).to.deep.equal([
+            29, 23, 30, 25, 24,
+            ...(nodeMajorVersion >= 17 ? [256, 257, 258, 259, 260] : [])
+        ]);
+        expect(curveFormats).to.deep.equal([0, 1, 2]);
     });
 });