|
| 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