client-hello-mirror/DOC.md

API Documentation

There are two JSON endpoints:

• /json/v1 - basic
• /json/v2 - detailed

The v2 endpoint expands numeric identifiers (of TLS versions, cipher suites, signature algorithms, etc) into objects containing more information. The name field in these objects is taken from the IANA registries; note that these names may differ from those used in TLS libraries (example).

The v1 endpoint is not deprecated, it is a lighter version of v2. v1 is a better fit for CI tests, while v2 might be preferable on the user-facing side, where names are more appropriate than numeric identifiers.

The outline of the v1 output is:

{
  "client_hello": {
    "raw": "...",
    "record_header_tls_version": 769,
    "client_tls_version": 771,
    "random": "...",
    "session_id": "...",
    "cipher_suites": [
      ...
    ],
    "compression_methods": [
      0
    ],
    "extensions": [
      ...
    ],
    "highlights": {
      "gmt_unix_time": 3563154493,
      "secure_renegotiation_support": true,
      "ocsp_stapling_support": false,
      "sct_support": false,
      "ja3": "...",
      "ja3_md5": "...",
      "nja3v1": "...",
      "nja3v1_sha256_128": "..."
    }
  },
  "connection_info": {
    "tls_version": 772,
    "cipher_suite": 4867,
    "session_resumed": false,
    "alpn_negotiated_protocol": "http/1.1"
  }
}

The client_hello object contains a highlights object, which includes:

• the deprecated gmt_unix_time value extracted from the client random, which should NOT represent the current timestamp anymore;
• boolean values that show whether the client supports secure renegotiation, OCSP stapling and SCTs (Signed Certificate Timestamps);
• the JA3 fingerprint, both its expanded form and its MD5 hash;
• the NJA3 fingerprint, both its expanded form and its SHA256/128 hash.

Aside from client_hello, there is a connection_info object containing the TLS version, cipher suite and ALPN protocol that were negotiated for the connection, as well as a boolean value that shows whether the TLS session was resumed.

In v2 numeric identifiers are expanded, for example "cipher_suite": 4867 becomes:

"cipher_suite": {
  "code": 4867,
  "hex_code": "1303",
  "name": "TLS_CHACHA20_POLY1305_SHA256",
  "recommended": true
},

In both JSON endpoints, raw byte values are represented as hexadecimal strings.

Both JSON endpoints accept a raw hex-encoded Client Hello message as a query string (/json/v1?16030102...). If one is provided, the response will contain the decoded query string and the connection_info object will be omitted.

IANA-assigned codes for TLS parameters and extensions are documented at:

• TLS parameters
• TLS extensions

The API is largely stable - fields may be added, but existing fields will not be modified or removed.