Skip to content

feat(tls): apply client-fingerprint instead of warning about it - #1503

Closed
Rushan4eg wants to merge 7 commits into
ibigbug:masterfrom
Rushan4eg:feature/utls
Closed

Rushan4eg wants to merge 7 commits into
ibigbug:masterfrom
Rushan4eg:feature/utls

Conversation

@Rushan4eg

@Rushan4eg Rushan4eg commented Aug 22, 2026 •

Copy link
Copy Markdown

Depends on Watfaq/rustls#11 — the mechanism lives there, the browser table lives here.

Draft until that merges. So the branch can actually build and be reviewed, Cargo.toml points at that PR's branch on my fork, marked in place as not for merge; it goes back to Watfaq/rustls the moment #11 lands.

Why

Every VLESS or AnyTLS proxy with client-fingerprint set gets this:

WARN clash-lib/src/proxy/converters/vless.rs:35:
client-fingerprint (uTLS) is not yet implemented, ignored for main-out

Reality connects and carries traffic, but the ClientHello is recognisably rustls: no GREASE, no signed_certificate_timestamp, no ALPS, and a cipher list that is exactly the fifteen-minus-six suites rustls happens to implement. That separates it from a browser before a byte of application data moves, which is the one thing Reality exists to prevent.

What changed

client-fingerprint is now applied, for VLESS (Reality and plain TLS) and for AnyTLS.

The numbers come from uTLS HelloChrome_133, not from memory — clash-lib/src/common/tls_fingerprint.rs is the whole table, and it is the only file that knows anything about browsers.

accepted value profile
chrome, edge, android, 360, qq Chrome 133
random, randomized rustls' own hello, plus GREASE
anything else falls back to random with a warning

That last row is deliberate. Firefox and Safari are real profiles that are simply not modelled here; quietly substituting Chrome for them would be worse than saying so, because a config asking for Firefox and getting Chrome is a mismatch nobody would think to look for.

What the Chrome profile sets

  • cipher suites — Chrome's fifteen, in order. Six of them (static RSA and CBC) rustls cannot negotiate and will never be selected; they are advertised because the count and the order are the first half of the fingerprint.
  • GREASE — cipher list, supported groups, key shares, supported versions, and two extensions.
  • supported groups — X25519MLKEM768, X25519, P-256, P-384. rustls derives the key shares from that order on its own, and the pair it produces is the pair Chrome sends.
  • signature algorithms — Chrome's eight, in order, via a verifier wrapper that also narrows what will be accepted. Same trade the browser makes.
  • renegotiation_info — rustls signals "no renegotiation" with the SCSV in the cipher list; browsers use the extension. Pinning the suite list removes the SCSV, so the extension takes its place.
  • signed_certificate_timestamp and ALPS (0x44cd, the codepoint Chrome 133 uses) as verbatim extensions.
  • ALPN h2, http/1.1 — only when the caller has none of its own. A transport that must negotiate h2 has a functional requirement, and looking like a browser does not outrank it.
  • GREASE ECH — a placeholder full of random data, X25519, matching what browsers send. Off without the aws-lc-rs feature: rustls only ships HPKE for that provider.
  • compress_certificate — brotli, the only algorithm Chrome offers. See the note on the brotli feature below.
  • no padding — Chrome 131 dropped it; with GREASE ECH the hello no longer lands in the range padding existed for.

Measured, not just asserted

The tests say the profile is assembled correctly. This says what actually left the socket, read back from tls.peet.ws:

JA4
clash-rs today t13d1011h1_61a7ad8aa9b6_f9531d972513
this branch, no client-fingerprint t13d1012h1_61a7ad8aa9b6_41631feb4e62
this branch, client-fingerprint: chrome t13d1516h1_8daaf6152771_d8a2da3f94cd

The middle row is the whole cost of the brotli commit, stated below: one extension more on every connection, and the cipher hash unchanged.

1516 is fifteen cipher suites and sixteen extensions, which are Chrome's counts. h1 rather than h2 is the probe's own doing — it speaks HTTP/1.1 so it can read the reply, and JA4 records the ALPN it saw.

The raw form is the part worth reading:

t13d1516h1_002f,0035,009c,009d,1301,1302,1303,c013,c014,c02b,c02c,c02f,c030,cca8,cca9
          _0005,000a,000b,000d,0012,0017,001b,0023,002b,002d,0033,44cd,fe0d,ff01
          _0403,0804,0401,0503,0805,0501,0806,0601

Cipher list, extension list and signature algorithms: field for field what uTLS records for HelloChrome_133.

On hardware, and what it changed

Flashed onto a GL-XE300 (mips_24kc, OpenWrt 25.12.5) running podkop with a real VLESS+Reality outbound, and the ClientHello read back off the wire with tcpdump:

ClientHello, 299 bytes, session_id 32 bytes
cipher suites (16, 15 real):
  GREASE 1301 1302 1303 c02b c02f c02c c030 cca9 cca8 c013 c014 009c 009d 002f 0035
extensions: GREASE, session_ticket, psk_key_exchange_modes, key_share,
  extended_master_secret, compress_certificate, alpn, supported_versions,
  status_request, supported_groups, server_name, signature_algorithms,
  ec_point_formats, renegotiation_info, signed_certificate_timestamp,
  application_settings, GREASE
JA4 counts: 15 ciphers, 15 extensions

Tunnel healthy throughout — 148, 155, 157 ms across three delay tests — and the client-fingerprint (uTLS) is not yet implemented line is gone from the log.

But the profile is provider-dependent, and routers get the reduced one. The MIPS targets build with -F ring, and against x86 with aws-lc-rs the same code produced sixteen extensions and five groups. Two things are missing on ring, both for the same reason:

on ring why
encrypted_client_hello absent rustls ships HPKE only for aws-lc-rs
X25519MLKEM768 absent from groups and key shares ring has no ML-KEM

So on a router the hello is 15 ciphers / 15 extensions against Chrome's 15 / 16, and the group list is X25519, P-256, P-384 where Chrome leads with the post-quantum hybrid.

Neither is silent — the code says so:

WARN tls_fingerprint.rs: key exchange group X25519MLKEM768 is unavailable, dropped from the hello
WARN tls_fingerprint.rs: GREASE ECH needs the aws-lc-rs provider, which this build does not have

Worth knowing before anyone assumes a router build gets the same disguise a desktop build does. Closing either gap means HPKE and ML-KEM for ring, which is upstream rustls work, not this PR.

The one line that touches everything else

rustls = { version = "0.23", default-features = false, features = ["brotli"] }

Chrome offers brotli certificate compression. Without a decompressor rustls omits the extension entirely, and that was the single extension standing between 1515 and 1516.

It is a separate commit because it is a separate decision, and not a free one: it applies to every TLS client in clash-rs, not only fingerprinted ones. The default hello goes from eleven extensions to twelve, and a brotli decompressor is linked in. Both are arguably improvements — smaller handshakes, and a default hello marginally less unlike a browser's — but dropping the commit is a supported outcome. The cost of dropping it is one extension out of sixteen.

No fingerprint, no change

Without client-fingerprint nothing about the hello moves, SCSV included. There is a test asserting it, because a feature like this quietly altering every other connection would be a bad trade.

TlsClient::new keeps its signature; the fingerprint goes through new_with_fingerprint, so trojan, vmess, socks5, websocket and the rest are untouched.

Tests

Nineteen, and eleven of them read the bytes that actually left a ClientConnection rather than the struct that produced them — a profile correct in a struct and lost on the way to the socket would pass every other kind of test:

  • Chrome's cipher list arrives in order, GREASE in front, sixteen entries
  • GREASE reaches supported groups, supported versions and key shares
  • three key share entries: GREASE, X25519MLKEM768, X25519 — what Chrome sends
  • signed_certificate_timestamp, ALPS and renegotiation_info present with the right bodies
  • the SCSV is gone and renegotiation_info replaced it
  • ALPN is h2, http/1.1
  • compress_certificate offers brotli and only brotli
  • the GREASE ECH placeholder is there, with a 32 byte encapsulated key
  • TLS 1.2 survived the ECH extension (rustls pins 1.3 for real ECH, and must not for GREASE)
  • with no fingerprint: no GREASE anywhere, no browser extensions, SCSV still there
  • an unknown profile name resolves to random, never to Chrome
cargo test -p clash-lib --lib --features aws-lc-rs,zero_copy,tuic
test result: ok. 19 passed; 0 failed

Every VLESS or AnyTLS proxy with client-fingerprint set got this and
nothing else:

    client-fingerprint (uTLS) is not yet implemented, ignored for main-out

Reality connected and carried traffic, but the ClientHello was
recognisably rustls: no GREASE, no signed_certificate_timestamp, no ALPS,
and a cipher list that was exactly the suites rustls implements. That
separates it from a browser before a byte of application data moves,
which is the one thing Reality exists to prevent.

The mechanism is rustls ClientHelloProfile (Watfaq-legacy/rustls#11). What is
here is the browser table, taken from uTLS HelloChrome_133 rather than
from memory, and confined to one file.

    chrome, edge, android, 360, qq   Chrome 133
    random, randomized               rustls own hello, plus GREASE
    anything else                    random, with a warning

That last line is deliberate. Firefox and Safari are real profiles that
are simply not modelled; substituting Chrome for them silently would be
worse than saying so, because a config asking for Firefox and getting
Chrome is a mismatch nobody would think to look for.

The Chrome profile sets the cipher list (fifteen suites in order, six of
which rustls cannot negotiate and advertises anyway - the count and order
are the fingerprint), GREASE across suites, groups, key shares and
versions, the group order that makes rustls derive Chrome's key share
pair on its own, Chrome's eight signature algorithms via a verifier
wrapper, and renegotiation_info, signed_certificate_timestamp and ALPS as
verbatim extensions. ALPN falls back to h2,http/1.1 only where the caller
has none: a transport that must negotiate h2 has a functional
requirement, and looking like a browser does not outrank it.

Two differences from Chrome remain, both deliberate rather than missed:
GREASE ECH, and compress_certificate - the latter needs rustls brotli
feature, which would change the hello for every TLS client in clash-rs
and not just fingerprinted ones. Both are noted in the PR.

Without client-fingerprint nothing moves, SCSV included, and there is a
test for it. TlsClient::new keeps its signature; the fingerprint goes
through new_with_fingerprint, so trojan, vmess, socks5 and websocket are
untouched.

Sixteen tests, eight of which read the bytes that actually left a
ClientConnection rather than the struct that produced them: a profile
correct in a struct and lost on the way to the socket would pass any
other kind of test.
@coderabbitai

coderabbitai Bot commented Aug 22, 2026 •

Copy link
Copy Markdown
Contributor

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 7fc731fb-70b0-4b24-992f-bbb8416df253

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

CI runs cargo +nightly fmt --check and my code was not run through it.

The rustls dependency temporarily points at the branch of
Watfaq-legacy/rustls#11 so the build can actually happen - a PR that cannot
compile is hard to review. Marked in Cargo.toml as not for merge; it goes
back to Watfaq/rustls once that PR lands.
@codecov

codecov Bot commented Aug 22, 2026 •

Copy link
Copy Markdown

The last extension separating the Chrome profile from Chrome. It carries
random data, negotiates nothing, and its absence is as visible as any
other missing extension - the extension set is what the common
fingerprints hash.

X25519, because that is the KEM browsers GREASE with and the KEM decides
the length of the encapsulated key on the wire. Off without the
aws-lc-rs feature: that is the only provider rustls ships HPKE for, and
there is nothing to build the placeholder from otherwise.

Needs the two ECH fixes in the rustls branch this depends on - the KEM
was fixed to P-256 there, and GREASE mode pinned TLS 1.3 and so dropped
TLS 1.2 from the hello.

Two more tests reading the bytes: the placeholder is there with a 32 byte
encapsulated key, and TLS 1.2 survived it.
EchGreaseConfig is only reachable with aws-lc-rs, and importing it at the
top of the module left it unused everywhere else. With -D warnings that is
an error, which is why mips, mipsel and freebsd went red - all three build
with -F ring.

Moved into the branch that uses it.
Chrome offers it, and without a decompressor rustls omits the extension
entirely. That was the single extension standing between the profile and
Chrome's - measured against tls.peet.ws, JA4 went from

    t13d1515h1_8daaf6152771_fa2c1db240d0

to

    t13d1516h1_8daaf6152771_d8a2da3f94cd

and the raw form - cipher list, extension list, signature algorithms -
became field for field what uTLS records for HelloChrome_133.

A separate commit because it is a separate decision and not a free one.
It applies to every TLS client in clash-rs, not only fingerprinted ones:
the default hello goes from eleven extensions to twelve, and a brotli
decompressor is linked in. Both are arguably improvements - smaller
handshakes, and a default hello marginally less unlike a browser's - but
dropping this commit is a supported outcome. It costs one extension out
of sixteen.
rustls ships HPKE only for aws-lc-rs, so on a ring build the placeholder
is silently absent and the hello comes out one extension short of the
profile it claims.

Routers are the common case for ring - aws-lc-rs has no MIPS support - so
this is not an exotic corner. Caught by reading the ClientHello off a
GL-XE300 with tcpdump: fifteen extensions where x86 produced sixteen. The
missing key exchange group already warned; this one did not.
The placeholder now comes from EchGreaseConfig::without_provider, so the
ring builds - every MIPS and embedded target - get it too. Reading the
ClientHello off a GL-XE300 was what turned this up: fifteen extensions
where x86 sent sixteen, and encrypted_client_hello the one missing.

Needs the matching change in the rustls branch, where GREASE no longer
requires an HPKE implementation it has no use for.

The key share test was written against aws-lc-rs and failed under ring
for a real reason: no X25519MLKEM768 there, so no second share to pair
with it. It now checks the property rustls actually guarantees - the
share is for the group asked for first - and states the difference
between the two providers rather than asserting one of them everywhere.
@Rushan4eg

Copy link
Copy Markdown
Author

Closing — keeping this in a fork for now rather than asking for review time. Thanks.

@Rushan4eg Rushan4eg closed this Aug 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant