You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Replace 'enableFingerprinting' with 'trackClientHellos'
This also changes the resulting field name that's attached from
tlsFingerprint to tlsClientHello, and restructures it to match the rest
of the new API.
Copy file name to clipboardExpand all lines: README.md
+25-26Lines changed: 25 additions & 26 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,50 +12,49 @@ Be aware that fingerprinting is _not_ a 100% reliable test. Most clients can mod
12
12
13
13
## Docs
14
14
15
-
### Reading a TLS client hello
16
-
17
-
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.
18
-
19
-
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.
20
-
21
-
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.
22
-
23
-
The returned promise resolves to an object, containing:
24
-
25
-
*`serverName` - The server name requested in the client hello (or undefined if SNI was not used)
26
-
*`alpnProtocols` - A list of ALPN protcol names requested in the client hello (or undefined if ALPN was not used)
27
-
*`fingerprintData` - The raw components used for JA3 TLS fingerprinting (see the next section)
28
-
29
-
### TLS fingerprinting
15
+
### TLS server helper
30
16
31
-
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:
17
+
The easiest way to use this is to use the built-in `trackClientHellos` helper, which can be applied to any `tls.TLSServer` instance, including `https.Server` instances, like so:
constserver=newhttps.Server({ /* your TLS options etc */ });
38
24
39
-
enableFingerprinting(server);
25
+
trackClientHellos(server);// <-- Automatically track everything on this server
40
26
41
27
server.on('request', (request, response) => {
42
-
// In your normal request handler, check `tlsFingerprint` on the request's socket:
43
-
console.log('Received request with fingerprint:', request.socket.tlsFingerprint);
28
+
// In your normal request handler, check `tlsClientHello` on the request's socket:
29
+
console.log('Received request with TLS client hello:', request.socket.tlsClientHello);
44
30
});
45
31
```
46
32
47
-
The `tlsFingerprint` property contains two fields:
33
+
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`.
48
34
49
-
*`ja3` - The JA3 hash for the incoming request, e.g. `cd08e31494f9531f560d64c695473da9`
50
-
*`data` - The raw data components used to calculate the hash, as an array:
35
+
### Reading a TLS client hello
36
+
37
+
To read all available data from a TLS client hello manually, 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.
38
+
39
+
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.
40
+
41
+
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.
42
+
43
+
The returned promise resolves to an object, containing:
44
+
45
+
*`serverName` - The server name requested in the client hello (or undefined if SNI was not used)
46
+
*`alpnProtocols` - A array of ALPN protcol names requested in the client hello (or undefined if ALPN was not used)
47
+
*`fingerprintData` - An array containing the raw components used for JA3 TLS fingerprinting:
51
48
1. The TLS version number as a Uint16 (771 for TLS 1.2+)
52
49
2. An array of cipher ids (excluding GREASE)
53
50
3. An array of extension ids (excluding GREASE)
54
51
4. An array of supported group ids (excluding GREASE)
55
52
5. An array of supported elliptic curve ids
56
53
57
-
It is also possible to calculate TLS fingerprints manually. The module exports a few methods for this:
54
+
### TLS fingerprinting
55
+
56
+
To calculate TLS fingerprints manually, there are a few options exported from this module:
58
57
59
-
*`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.
60
-
*`getTlsFingerprintAsJa3` - Reads from a stream, just like `readTlsClientHello`, but returns a promise for the JA3 hash, instead of raw hello data.
58
+
*`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.
59
+
*`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.
61
60
*`calculateJa3FromFingerprintData(data)` - Takes raw TLS fingerprint data, and returns the corresponding JA3 hash.
0 commit comments