Read SNI data from hellos, and restructure API to include that

Author: pimterry

README.md

@@ -12,11 +12,26 @@ Be aware that fingerprinting is _not_ a 100% reliable test. Most clients can mod
 
 ## Docs
 
-The easiest way to use this is with the exported `enableFingerprinting` helper, which can be applied to any `tls.TLSServer` instance, including `https.Server` instances, like so:
+### Reading a TLS client hello
+
+To read all available data from a TLS client hello, pass a stream (e.g. a `net.Socket`) to the exported `readTlsClientHello(stream)`, before the TLS handshake (or any other processing) starts. This returns a promise containing all data parsed from the client hello.
+
+This method reads the initial data from the socket, parses it, and then unshifts it back into the socket, so that once the returned promise resolves the stream can be used like new, to start a normal TLS session using the same client hello.
+
+If parsing fails, this method will throw an error, but will still ensure all data is returned to the socket first, so that non-TLS streams can also be processed as normal.
+
+The returned promise resolves to an object, containing:
+
+* `serverName` - The server name requested in the client hello (or undefined if SNI was not used)
+* `fingerprintData` - The raw components used for JA3 TLS fingerprinting (see the next section)
+
+### TLS fingerprinting
+
+The easiest way to use this for fingerprinting is with the exported `enableFingerprinting` helper, which can be applied to any `tls.TLSServer` instance, including `https.Server` instances, like so:
 
 ```javascript
 const https = require('https');
-const { enableFingerprinting } = require('read-tls-fingerprint');
+const { enableFingerprinting } = require('read-tls-client-hello');
 
 const server = new https.Server({ /* your TLS options etc */ });
 
@@ -40,6 +55,6 @@ The `tlsFingerprint` property contains two fields:
 
 It is also possible to calculate TLS fingerprints manually. The module exports a few methods for this:
 
-* `getTlsFingerprintData(stream)` - Reads from a stream of incoming TLS client data, returning a promise for the raw fingerprint data, and unshifting the data back into the stream when it's done. Nothing else should attempt to read from the stream until the returned promise resolves (i.e. don't start TLS negotiation until this completes).
-* `getTlsFingerprintAsJa3` - Reads from a stream like `getTlsFingerprintData` but returns a promise for the JA3 hash, instead of raw data.
+* `readTlsClientHello(stream)` - Reads from a stream of incoming TLS client data, returning a promise for parsed TLS hello, and unshifting the data back into the stream when it's done. Nothing else should attempt to read from the stream until the returned promise resolves (i.e. don't start TLS negotiation until this completes). The `fingerprintData` of the resulting value contains the raw fingerprint components.
+* `getTlsFingerprintAsJa3` - Reads from a stream, just like `readTlsClientHello`, but returns a promise for the JA3 hash, instead of raw hello data.
 * `calculateJa3FromFingerprintData(data)` - Takes raw TLS fingerprint data, and returns the corresponding JA3 hash.

src/index.ts

@@ -54,6 +54,11 @@ const getUint16BE = (buffer: Buffer, offset: number) =>
 // TLS fields, reserving 0a0a, 1a1a, 2a2a, etc for ciphers, extension ids & supported groups.
 const isGREASE = (value: number) => (value & 0x0f0f) == 0x0a0a;
 
+export type TlsHelloData = {
+    serverName: string | undefined;
+    fingerprintData: TlsFingerprintData;
+};
+
 export type TlsFingerprintData = [
     tlsVersion: number,
     ciphers: number[],
@@ -107,7 +112,33 @@ async function extractTlsHello(inputStream: stream.Readable): Promise<Buffer> {
     }
 }
 
-export async function getTlsFingerprintData(inputStream: stream.Readable): Promise<TlsFingerprintData> {
+function parseSniData(data: Buffer) {
+    // SNI is almost always just one value - and is arguably required to be, since there's only one type
+    // in the RFC and you're only allowed one name per type, but it's still structured as a list:
+    let offset = 0;
+    while (offset < data.byteLength) {
+        const entryLength = data.readUInt16BE(offset);
+        offset += 2;
+        const entryType = data[offset];
+        offset += 1;
+        const nameLength = data.readUInt16BE(offset);
+        offset += 2;
+
+        if (nameLength !== entryLength - 3) {
+            throw new Error('Invalid length in SNI entry');
+        }
+
+        const name = data.slice(offset, offset + nameLength).toString('ascii');
+        offset += nameLength;
+
+        if (entryType === 0x0) return name;
+    }
+
+    // No data, or no names with DNS hostname type.
+    return undefined;
+}
+
+export async function readTlsClientHello(inputStream: stream.Readable): Promise<TlsHelloData> {
     const wasFlowing = inputStream.readableFlowing;
     if (wasFlowing) inputStream.pause(); // Pause other readers, so we have time to precisely get the data we need.
 
@@ -164,7 +195,7 @@ export async function getTlsFingerprintData(inputStream: stream.Readable): Promi
         readExtensionsDataLength += 4 + extensionLength;
     }
 
-    // All data parsed! Now turn it into the fingerprint format:
+    // All data received & parsed! Now turn it into the fingerprint format:
     //SSLVersion,Cipher,SSLExtension,EllipticCurve,EllipticCurvePointFormat
 
     const tlsVersionFingerprint = clientTlsVersion.readUint16BE()
@@ -196,13 +227,25 @@ export async function getTlsFingerprintData(inputStream: stream.Readable): Promi
         ?? Buffer.from([]);
     const curveFormatsFingerprint: number[] = Array.from(curveFormatsData.slice(1)); // Drop length prefix
 
-    return [
+    const fingerprintData = [
         tlsVersionFingerprint,
         cipherFingerprint,
         extensionsFingerprint,
         groupsFingerprint,
         curveFormatsFingerprint
-    ];
+    ] as TlsFingerprintData;
+
+    // And capture other client hello data that might be interesting:
+    const sniExtensionData = extensions.find(({ id }) => id.equals(Buffer.from([0x0, 0x0])))?.data;
+
+    const serverName = sniExtensionData
+        ? parseSniData(sniExtensionData)
+        : undefined;
+
+    return {
+        serverName,
+        fingerprintData
+    };
 }
 
 export function calculateJa3FromFingerprintData(fingerprintData: TlsFingerprintData) {
@@ -218,7 +261,9 @@ export function calculateJa3FromFingerprintData(fingerprintData: TlsFingerprintD
 }
 
 export async function getTlsFingerprintAsJa3(rawStream: stream.Readable) {
-    return calculateJa3FromFingerprintData(await getTlsFingerprintData(rawStream));
+    return calculateJa3FromFingerprintData(
+        (await readTlsClientHello(rawStream)).fingerprintData
+    );
 }
 
 interface FingerprintedSocket extends net.Socket {
@@ -266,7 +311,7 @@ export function enableFingerprinting(tlsServer: tls.Server) {
     // 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);
+            const { fingerprintData } = await readTlsClientHello(socket);
 
             socket.tlsFingerprint = {
                 data: fingerprintData,

test/test.spec.ts

@@ -15,7 +15,7 @@ import {
 } from './test-util';
 
 import {
-    getTlsFingerprintData,
+    readTlsClientHello,
     getTlsFingerprintAsJa3,
     calculateJa3FromFingerprintData,
     enableFingerprinting,
@@ -24,7 +24,7 @@ import {
 
 const nodeMajorVersion = parseInt(process.version.slice(1).split('.')[0], 10);
 
-describe("Read-TLS-Fingerprint", () => {
+describe("Read-TLS-Client-Hello", () => {
 
     let server: DestroyableServer<net.Server>;
 
@@ -46,15 +46,15 @@ describe("Read-TLS-Fingerprint", () => {
         }).on('error', () => {}); // Socket will fail, since server never responds, that's OK
 
         const incomingSocket = await incomingSocketPromise;
-        const fingerprint = await getTlsFingerprintData(incomingSocket);
+        const { fingerprintData } = await readTlsClientHello(incomingSocket);
 
         const [
             tlsVersion,
             ciphers,
             extension,
             groups,
             curveFormats
-        ] = fingerprint;
+        ] = fingerprintData;
 
         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]);
@@ -137,10 +137,17 @@ describe("Read-TLS-Fingerprint", () => {
         expect(ourFingerprint).to.equal(remoteFingerprint);
     });
 
+    it("can capture the server name from a Chrome request", async () => {
+        const incomingData = fs.createReadStream(path.join(__dirname, 'fixtures', 'chrome-tls-connect.bin'));
+
+        const { serverName } = await readTlsClientHello(incomingData);
+        expect(serverName).to.equal('localhost');
+    });
+
     it("can calculate the correct TLS fingerprint from a Chrome request", async () => {
         const incomingData = fs.createReadStream(path.join(__dirname, 'fixtures', 'chrome-tls-connect.bin'));
 
-        const fingerprintData = await getTlsFingerprintData(incomingData);
+        const { fingerprintData } = await readTlsClientHello(incomingData);
 
         const [
             tlsVersion,
@@ -303,15 +310,15 @@ describe("Read-TLS-Fingerprint", () => {
         }).on('error', () => {}); // Socket will fail, since server never responds, that's OK
 
         const incomingSocket = await incomingSocketPromise;
-        const fingerprint = await getTlsFingerprintData(incomingSocket);
+        const { fingerprintData } = await readTlsClientHello(incomingSocket);
 
         const [
             tlsVersion,
             ciphers,
             extension,
             groups,
             curveFormats
-        ] = fingerprint;
+        ] = fingerprintData;
 
         expect(tlsVersion).to.equal(769); // TLS 1!
         expect(ciphers.slice(0, 3)).to.deep.equal([49162, 49172, 57]);