Merge pull request #4 from kriztalz/ja4

Added JA4 support

Author: pimterry

README.md

@@ -30,7 +30,7 @@ server.on('request', (request, response) => {
 });
 ```
 
-A `tlsClientHello` property will be attached to all sockets, containing the parsed data returned by `readTlsClientHello` (see below) and a `ja3` property with the JA3 TLS fingerprint for the client hello, e.g. `cd08e31494f9531f560d64c695473da9`.
+A `tlsClientHello` property will be attached to all sockets, containing the parsed data returned by `readTlsClientHello` (see below), a `ja3` property with the JA3 TLS fingerprint for the client hello, e.g. `cd08e31494f9531f560d64c695473da9` and a `ja4` property with the JA4 TLS fingerprint for the client hello, e.g. `t13d591000_a33745022dd6_1f22a2ca17c4`.
 
 ### Reading a TLS client hello
 
@@ -50,11 +50,14 @@ The returned promise resolves to an object, containing:
     3. An array of extension ids (excluding GREASE)
     4. An array of supported group ids (excluding GREASE)
     5. An array of supported elliptic curve ids
+    6. An array of signature algorithms (TLS 1.3)
 
 ### TLS fingerprinting
 
 To calculate TLS fingerprints manually, there are a few options exported from this module:
 
 * `getTlsFingerprintAsJa3` - Reads from a stream, just like `readTlsClientHello` above, but returns a promise for the JA3 hash string, e.g. `cd08e31494f9531f560d64c695473da9`, instead of the raw hello components.
-* `readTlsClientHello(stream)` - Reads the entire hello (see above). In the returned object, you can read the raw data components used for fingerprinting from the `fingerprintData` property.
-* `calculateJa3FromFingerprintData(data)` - Takes raw TLS fingerprint data, and returns the corresponding JA3 hash.
+* `getTlsFingerprintAsJa4` - Reads from a stream, just like `readTlsClientHello` above, but returns a promise for the JA4 hash string, e.g. `t13d591000_a33745022dd6_1f22a2ca17c4`, instead of the raw hello components.
+* `readTlsClientHello(stream)` - Reads the entire hello (see above). In the returned object, you can read the raw data components used for JA3 fingerprinting from the `fingerprintData` property.
+* `calculateJa3FromFingerprintData(data)` - Takes raw TLS fingerprint data, and returns the corresponding JA3 hash.
+* `calculateJa4FromHelloData(data)` - Takes the full hello data, including the serverName, alpnProtocols & fingerprinting parameters returned by `readTlsClientHello`, and returns the corresponding JA4 hash, eg. `t13d591000_a33745022dd6_1f22a2ca17c4`.

package.json

@@ -26,7 +26,9 @@
     "client-hello",
     "alpn",
     "sni",
-    "https"
+    "https",
+    "ja3",
+    "ja4"
   ],
   "licenses": [
     {

src/index.ts

@@ -65,7 +65,8 @@ export type TlsFingerprintData = [
     ciphers: number[],
     extensions: number[],
     groups: number[],
-    curveFormats: number[]
+    curveFormats: number[],
+    sigAlgorithms: number[]
 ];
 
 /**
@@ -206,12 +207,22 @@ export async function readTlsClientHello(inputStream: stream.Readable): Promise<
     const extensionsLength = (await collectBytes(helloDataStream, 2)).readUint16BE();
     let readExtensionsDataLength = 0;
     const extensions: Array<{ id: Buffer, data: Buffer }> = [];
+    let signatureAlgorithms: number[] = [];
 
     while (readExtensionsDataLength < extensionsLength) {
         const extensionId = await collectBytes(helloDataStream, 2);
         const extensionLength = (await collectBytes(helloDataStream, 2)).readUint16BE();
         const extensionData = await collectBytes(helloDataStream, extensionLength);
 
+        if (extensionId.readUInt16BE() === 13) {
+            const sigAlgsLength = extensionData.readUInt16BE(0);
+            const sigAlgs: number[] = [];
+            for (let i = 2; i < sigAlgsLength + 2; i += 2) {
+                sigAlgs.push(extensionData.readUInt16BE(i));
+            }
+            signatureAlgorithms = sigAlgs;
+        }
+
         extensions.push({ id: extensionId, data: extensionData });
         readExtensionsDataLength += 4 + extensionLength;
     }
@@ -253,7 +264,8 @@ export async function readTlsClientHello(inputStream: stream.Readable): Promise<
         cipherFingerprint,
         extensionsFingerprint,
         groupsFingerprint,
-        curveFormatsFingerprint
+        curveFormatsFingerprint,
+        signatureAlgorithms
     ] as TlsFingerprintData;
 
     // And capture other client hello data that might be interesting:
@@ -292,9 +304,109 @@ export async function getTlsFingerprintAsJa3(rawStream: stream.Readable) {
     );
 }
 
+export interface Ja4Data {
+    protocol: 't' | 'q' | 'd'; // TLS, QUIC, DTLS (only TLS supported for now)
+    version: '10' | ' 11' | '12' | '13'; // TLS version
+    sni: 'd' | 'i'; // 'd' if a domain was provided via SNI, 'i' otherwise (for IP)
+    cipherCount: number;
+    extensionCount: number;
+    alpn: string; // First and last character of the ALPN value or '00' if none
+    cipherSuites: number[];
+    extensions: number[];
+    sigAlgorithms: number[];
+}
+
+export function calculateJa4FromHelloData(
+    { serverName, alpnProtocols, fingerprintData }: TlsHelloData
+): string {
+    const [tlsVersion, ciphers, extensions, , , sigAlgorithms] = fingerprintData;
+
+    // Part A: Protocol info
+    const protocol = 't'; // We only handle TCP for now
+
+    const version = extensions.includes(0x002B)
+        ? '13' // TLS 1.3 uses the supported versions extension, and 1.4+ doesn't exist (yet)
+        : { // Previous TLS sets the version in the handshake up front:
+            0x0303: '12',
+            0x0302: '11',
+            0x0301: '10'
+        }[tlsVersion]
+        ?? '00'; // Other unknown version
+
+    const sni = !serverName ? 'i' : 'd'; // 'i' for IP (no SNI), 'd' for domain
+
+    // Handle different ALPN protocols
+    let alpn = '00';
+    const firstProtocol = alpnProtocols?.[0];
+    if (firstProtocol && firstProtocol.length >= 1) {
+        // Take first and last character of the protocol string
+        alpn = firstProtocol.length >= 2
+            ? `${firstProtocol[0]}${firstProtocol[firstProtocol.length - 1]}`
+            : `${firstProtocol[0]}${firstProtocol[0]}`;
+    }
+
+    // Format numbers as fixed-width hex
+    const cipherCount = ciphers.length.toString().padStart(2, '0');
+    const extensionCount = extensions.length.toString().padStart(2, '0');
+
+    const ja4_a = `${protocol}${version}${sni}${cipherCount}${extensionCount}${alpn}`;
+
+    // Part B: Truncated SHA256 of cipher suites
+    // First collect all hex values and sort them
+    const cipherHexValues = ciphers
+        .filter(c => !isGREASE(c))
+        .map(c => c.toString(16).padStart(4, '0'));
+    const sortedCiphers = [...cipherHexValues].sort().join(',');
+    const cipherHash = ciphers.length
+        ? crypto.createHash('sha256')
+            .update(sortedCiphers)
+            .digest('hex')
+            .slice(0, 12)
+        : '000000000000'; // No ciphers provided
+
+    // Part C: Truncated SHA256 of extensions + sig algorithms
+    // Get extensions (excluding SNI and ALPN)
+    const extensionsStr = extensions
+        .filter(e => {
+            if (e === 0x0 || e === 0x10) return false; // Filter SNI and ALPN
+            return !isGREASE(e);
+        })
+        .sort((a, b) => a - b)
+        .map(e => e.toString(16).padStart(4, '0'))
+        .join(',');
+
+    // Get signature algorithms from the actual TLS hello data
+    const signatureAlgorithmsStr = sigAlgorithms
+        ? sigAlgorithms
+            .filter(s => !isGREASE(s))
+            .map(s => s.toString(16).padStart(4, '0'))
+            .join(',')
+        : '';
+
+    // Add separator only if we have signature algorithms
+    const separator = signatureAlgorithmsStr ? '_' : '';
+
+    // Combine and hash
+    const ja4_c_raw = `${extensionsStr}${separator}${signatureAlgorithmsStr}`;
+
+    const extensionHash = crypto.createHash('sha256')
+        .update(ja4_c_raw)
+        .digest('hex')
+        .slice(0, 12);
+
+    return `${ja4_a}_${cipherHash}_${extensionHash}`;
+}
+
+export async function getTlsFingerprintAsJa4(rawStream: stream.Readable) {
+    return calculateJa4FromHelloData(
+        (await readTlsClientHello(rawStream))
+    );
+}
+
 interface SocketWithHello extends net.Socket {
     tlsClientHello?: TlsHelloData & {
         ja3: string;
+        ja4: string;
     }
 }
 
@@ -309,6 +421,7 @@ declare module 'tls' {
          */
         tlsClientHello?: TlsHelloData & {
             ja3: string;
+            ja4: string;
         }
     }
 }
@@ -339,7 +452,8 @@ export function trackClientHellos(tlsServer: tls.Server) {
 
             socket.tlsClientHello = {
                 ...helloData,
-                ja3: calculateJa3FromFingerprintData(helloData.fingerprintData)
+                ja3: calculateJa3FromFingerprintData(helloData.fingerprintData),
+                ja4: calculateJa4FromHelloData(helloData)
             };
         } catch (e) {
             if (!(e instanceof NonTlsError)) { // Ignore totally non-TLS traffic

test/test.spec.ts

@@ -17,13 +17,26 @@ import {
 import {
     readTlsClientHello,
     getTlsFingerprintAsJa3,
+    getTlsFingerprintAsJa4,
     calculateJa3FromFingerprintData,
     trackClientHellos,
-
+    calculateJa4FromHelloData
 } from '../src/index';
 
 const nodeMajorVersion = parseInt(process.version.slice(1).split('.')[0], 10);
 
+interface EchoResponse {
+    tls: {
+        ja3: {
+            hash: string;
+        };
+        ja4: {
+            hash: string;
+            raw: string;
+        };
+    };
+}
+
 describe("Read-TLS-Client-Hello", () => {
 
     let server: DestroyableServer<net.Server>;
@@ -122,7 +135,7 @@ describe("Read-TLS-Client-Hello", () => {
         ]);
     });
 
-    it("calculates the same fingerprint as ja3.zone", async () => {
+    it("can read Node's JA4 fingerprint", async () => {
         server = makeDestroyable(new net.Server());
 
         server.listen();
@@ -138,25 +151,53 @@ describe("Read-TLS-Client-Hello", () => {
         }).on('error', () => {}); // Socket will fail, since server never responds, that's OK
 
         const incomingSocket = await incomingSocketPromise;
-        const ourFingerprint = await getTlsFingerprintAsJa3(incomingSocket);
+        const fingerprint = await getTlsFingerprintAsJa4(incomingSocket);
+
+        expect(fingerprint).to.be.oneOf([
+            't13d591000_a33745022dd6_5ac7197df9d2', // Node 12 - 16
+            't13d591000_a33745022dd6_1f22a2ca17c4' // Node 17+
+        ]);
+    });
+
+    it("calculates the same fingerprint as echo.ramaproxy.org", async () => {
+        server = makeDestroyable(new net.Server());
 
-        const remoteFingerprint = await new Promise((resolve, reject) => {
-            const response = https.get('https://check.ja3.zone/');
+        server.listen();
+        await new Promise((resolve) => server.on('listening', resolve));
+
+        let incomingSocketPromise = getDeferred<net.Socket>();
+        server.on('connection', (socket) => incomingSocketPromise.resolve(socket));
+
+        const port = (server.address() as net.AddressInfo).port;
+        https.request({
+            host: 'localhost',
+            port
+        }).on('error', () => {}); // Socket will fail, since server never responds, that's OK
+
+        const incomingSocket = await incomingSocketPromise;
+        const helloData = await readTlsClientHello(incomingSocket);
+        const ourJa3 = await getTlsFingerprintAsJa3(incomingSocket);
+        const ourJa4 = calculateJa4FromHelloData(helloData);
+
+        const remoteFingerprints = await new Promise<EchoResponse>((resolve, reject) => {
+            const response = https.get('https://echo.ramaproxy.org/');
             response.on('response', async (resp) => {
-                if (resp.statusCode !== 200) reject(new Error(`Unexpected ${resp.statusCode} from ja3.zon`));
+                if (resp.statusCode !== 200) reject(new Error(`Unexpected ${resp.statusCode} from echo.ramaproxy.org`));
 
                 try {
                     const rawData = await streamToBuffer(resp);
-                    const data = JSON.parse(rawData.toString());
-                    resolve(data.hash);
+                    const data = JSON.parse(rawData.toString()) as EchoResponse;
+                    resolve(data);
                 } catch (e) {
                     reject(e);
                 }
             });
             response.on('error', reject);
         });
 
-        expect(ourFingerprint).to.equal(remoteFingerprint);
+        // Check both JA3 and JA4 hashes
+        expect(ourJa3).to.equal(remoteFingerprints.tls.ja3.hash);
+        expect(ourJa4).to.equal(remoteFingerprints.tls.ja4.hash);
     });
 
     it("can capture the server name from a Chrome request", async () => {
@@ -276,18 +317,24 @@ describe("Read-TLS-Client-Hello", () => {
         }).on('error', () => {}); // No response, we don't care
 
         const tlsSocket = await tlsSocketPromise;
-        const helloData = tlsSocket.tlsClientHello!;
 
-        expect(helloData.serverName).to.equal('localhost');
-        expect(helloData.alpnProtocols).to.deep.equal(undefined);
-
-        expect(helloData.fingerprintData[0]).to.equal(771); // Is definitely a TLS 1.2+ fingerprint
-        expect(helloData.fingerprintData.length).to.equal(5); // Full data is checked in other tests
+        const [
+            tlsVersion,
+            ciphers,
+            extension,
+            groups,
+            curveFormats,
+            sigAlgorithms
+        ] = tlsSocket.tlsClientHello!.fingerprintData;
+
+        expect(tlsSocket.tlsClientHello!.fingerprintData.length).to.equal(6);
+        expect(tlsVersion).to.equal(771);
+        expect(ciphers.length).to.be.greaterThan(0);
+        expect(extension.length).to.be.greaterThan(0);
+        expect(groups.length).to.be.greaterThan(0);
+        expect(curveFormats.length).to.be.greaterThan(0);
+        expect(sigAlgorithms.length).to.be.greaterThan(0);
 
-        expect(helloData.ja3).to.be.oneOf([
-            '398430069e0a8ecfbc8db0778d658d77', // Node 12 - 16
-            '0cce74b0d9b7f8528fb2181588d23793' // Node 17+
-        ]);
     });
 
     it("doesn't break non-TLS connections", async () => {

test/tsconfig.json

@@ -6,4 +6,4 @@
         "./**/*.ts",
         "../package.json"
     ]
-}
+}