Skip to content

Commit 9bbc508

Browse files
committed
Assess what sni would cost on the QUIC carrier, rather than assuming
The refusal message said certificate verification was unimplemented and the estimate behind it was 'feed a trust store into aws-lc'. That estimate is the expensive option and it is not the one to take. Android already has anchors, path building, policy, blocklists and hostname matching. Handing the DER chain up through JNI and running the platform's own X509TrustManager inherits all of it, including every future update, and is roughly the size of the pin work. Copying the store into an X509_STORE inherits only what was copied, at the moment it was copied, and has to be maintained forever. The Apple client is the precedent and settles which shape is normal: its QUIC path evaluates SecTrust with an SSL policy one level up from the handshake rather than feeding anchors into its crypto library, and short-circuits on a pin match with the comment that a pin is the user's full trust decision. The ADR ends in a recommendation and a decision point rather than in work, because L4's scope was fixed before the assessment existed and the assessment's own finding is that this belongs in the next run. What does not survive is the previous state, where the cost was unknown and the node was refused with nothing behind the refusal.
1 parent ff8b3a8 commit 9bbc508

2 files changed

Lines changed: 131 additions & 3 deletions

File tree

‎README.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -32,9 +32,9 @@ which is a QUIC node, because the specification's default for both directions is
3232
emulator. Private DNS over DoT, IPv6-only and NAT64 networks, a real Wi-Fi to
3333
cellular change, Doze and a path MTU below 1500 are all things an emulator
3434
cannot represent, and all things a VPN meets on the first real device.
35-
- **The QUIC carrier does no certificate verification.** A node carrying `sni`
36-
or `pin` is refused rather than carried without it. The TLS carrier implements
37-
both.
35+
- **The QUIC carrier does not verify a certificate chain.** `pin` works on both
36+
carriers; a node carrying `sni` is refused rather than carried without it. See
37+
[ADR-0002](docs/adr-0002-quic-certificate-verification.md).
3838
- **No release has been published**, and no signing key exists.
3939

4040
## Roadmap
@@ -129,6 +129,7 @@ conformance/scripts/portal-for-tests.sh --stop
129129
| [`docs/brand.md`](docs/brand.md) | The brand hue, which carries no protocol meaning and is derived rather than picked |
130130
| [`docs/i18n.md`](docs/i18n.md) | The three shipping locales, and the rule that machine identifiers stay English while sentences translate |
131131
| [`docs/adr-0001-tls-exporter.md`](docs/adr-0001-tls-exporter.md) | Why the TLS exporter has two sources, and why `minSdk` is 26 |
132+
| [`docs/adr-0002-quic-certificate-verification.md`](docs/adr-0002-quic-certificate-verification.md) | How `pin` is verified on the QUIC carrier, and what `sni` would cost — with the estimate that made it look expensive named as the wrong option |
132133
| [`docs/privacy.md`](docs/privacy.md) | What is stored, what leaves the device, and the longer list of what is not collected |
133134
| [`docs/store-policy.md`](docs/store-policy.md) | What a VPN-class listing requires, what is already satisfied, and what is still someone's decision |
134135

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# ADR-0002 · Certificate verification on the QUIC carrier
2+
3+
**Status:** `pin` **implemented and verified against a live Portal**, 2026-08-29.
4+
`sni` **assessed, not implemented** — a decision point, not an assumption ·
5+
**Decides:** D-20
6+
7+
## Context
8+
9+
A `nowhere://` node names one of three certificate policies, and upstream's
10+
precedence is `pin` over `sni` over nothing:
11+
12+
| Parameter | What upstream does |
13+
|---|---|
14+
| `pin=<64 hex>` | The leaf's SHA-256 must match. The chain is not consulted |
15+
| `sni=<name>` | Chain verification against that name |
16+
| neither | **No verification at all**, which is what every URL current dashboards emit produces |
17+
18+
The TLS carrier has implemented all three since L1. The QUIC carrier
19+
implemented none, and a node asking for either was refused rather than carried
20+
without it — honest, and unusable for anyone whose dashboard emits a pin.
21+
22+
The two halves are not the same size, which is why D-20 splits them.
23+
24+
## `pin` — decided and done
25+
26+
The comparison happens in the bridge, inside a BoringSSL custom verify callback
27+
(`SSL_set_custom_verify`), against the SHA-256 of the leaf's DER encoding. That
28+
is the same value `pin=` carries and the same one the TLS carrier compares, and
29+
the conversion from hex to bytes is written once so the two carriers cannot
30+
disagree about what a pin is.
31+
32+
Three properties are worth stating because each was a choice:
33+
34+
- **The chain is deliberately not consulted.** A pinned certificate is commonly
35+
self-signed. Checking the chain first would reject the very certificate the
36+
pin names, and pinning would work only for certificates that did not need it.
37+
The TLS carrier makes the same choice. So does the Apple client, whose
38+
`CertificatePolicy.verify` short-circuits on a pin match with the comment
39+
"the pin is the user's full trust decision".
40+
- **The comparison is constant time** (`CRYPTO_memcmp`). A short-circuiting
41+
comparison leaks how many leading bytes matched. That an attacker would need a
42+
fresh handshake per byte makes it slow rather than impossible.
43+
- **A pin of the wrong length is refused at both ends**, neither padded nor
44+
truncated. Either would produce a connection verifying against something
45+
nobody asked for, which is worse than not connecting.
46+
47+
Verified against a live Portal by reading the pin off the Portal's **own leaf
48+
over an independent TLS connection** and handing it back, so a pass cannot be
49+
the client agreeing with itself; and verified to fail with the callback not
50+
installed.
51+
52+
## `sni` — the assessment
53+
54+
### What it would need
55+
56+
ngtcp2 drives a TLS 1.3 handshake through aws-lc. The certificate arrives in the
57+
verify callback as a chain of `CRYPTO_BUFFER`s — DER, leaf first. Turning that
58+
into a trust decision needs three things Android has and aws-lc does not:
59+
60+
1. **Anchors.** The system store lives at `/system/etc/security/cacerts/`, with
61+
user- and admin-added anchors elsewhere, and the set changes with OS updates
62+
and with the user's own configuration.
63+
2. **Path building and policy.** Expiry, key usage, basic constraints, name
64+
constraints, and the blocklists Android ships against certificates that have
65+
been distrusted since.
66+
3. **Hostname matching.** SAN and wildcard rules against the `sni` name.
67+
68+
### Three ways to get them
69+
70+
| Option | Cost | What it inherits |
71+
|---|---|---|
72+
| **A. Ask the platform.** Keep the custom verify callback, hand the DER chain up through JNI, and run Android's own `X509TrustManager` plus `HostnameVerifier` | Small — an upcall, a chain marshalled as byte arrays, and a thread-safety rule | Everything: the current store, user-added anchors, admin policy, blocklists, and every future update, for free |
73+
| **B. Feed anchors into aws-lc.** Load the system store into an `X509_STORE` and let the library verify | Large, and permanently so — the store has to be re-read when it changes, user-added anchors have to be found, and Android's blocklist has no equivalent in BoringSSL | Only what is copied in, at the moment it is copied |
74+
| **C. Do not implement.** Keep refusing `sni` on QUIC | None | Nothing. A node that a dashboard emits with `sni` cannot use the QUIC carrier at all |
75+
76+
**Option A is the recommendation**, and the Apple client is the precedent: its
77+
QUIC path does not feed anchors into its crypto library either — it evaluates
78+
`SecTrust` with an SSL policy for the server name, one level up from the
79+
handshake, exactly the shape option A has.
80+
81+
The estimate that made this look expensive — "feed a trust store into aws-lc" —
82+
was option B. Option B is expensive. Option A is roughly the size of the `pin`
83+
work, plus care about which thread the upcall happens on.
84+
85+
### What option A costs that is not code
86+
87+
- **A JNI upcall from the QUIC owner thread.** The bridge caches the `JavaVM*`
88+
in `JNI_OnLoad` and already reaches Kotlin from C on the lwIP side, so the
89+
mechanism exists. The verify callback runs on the connection's owner thread,
90+
which is the thread that pumps; a slow trust evaluation stalls it. Android's
91+
evaluation is local and fast, but this is the property to watch.
92+
- **A second place that can say no.** Two verification paths — the platform's
93+
for `sni`, the bridge's for `pin` — must not be able to disagree about
94+
precedence. Upstream's precedence is `pin` first, which the client already
95+
applies when it parses the URL, so only one of the two is ever installed.
96+
- **`checkNativeBridge` stays satisfied**: an upcall opens no socket, and the
97+
rule that no address may be resolved or dialled inside the bridge is
98+
untouched.
99+
100+
### Failure modes to design against
101+
102+
- **A trust decision that fails open.** If the upcall throws — a detached
103+
thread, a missing class after R8 renames it — the callback must refuse, not
104+
accept. R8 is the realistic one: the JNI callback resolved by name is exactly
105+
what `checkReleaseArtifact` exists to catch, and a new one needs a new rule.
106+
- **A hostname that is not the connection's.** The `sni` name is the user's, and
107+
it is what the certificate must match; matching against the Portal's address
108+
instead would accept a certificate for the wrong host.
109+
- **Captive portals and clock skew**, which make chain verification fail for
110+
reasons that are not the Portal's fault and need a message that says so.
111+
112+
## Decision
113+
114+
**`pin`: accepted and implemented.**
115+
116+
**`sni`: recommended as option A, and not implemented in this run.** The reason
117+
is scope rather than cost — L4's scope was fixed before this assessment existed,
118+
and the assessment's own finding is that it belongs in the next one rather than
119+
being squeezed into this. What must not survive is the state this replaced,
120+
where the cost was unknown and the app refused the node with no estimate behind
121+
the refusal.
122+
123+
Until it lands, a QUIC node carrying `sni` is refused, and the message now says
124+
that a pin works on both carriers rather than that verification is unsupported.
125+
126+
**Decided by:** the requester, on this assessment. **By:** before any release a
127+
third party installs.

0 commit comments

Comments
 (0)