nick/amethyst
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

fix(quic): RFC 9001 §4.8 TLS alert mapping + RFC 9000 §22 CRYPTO_BUFFER_EXCEEDED

Browse Source 
The remaining 🟦 cosmetic items from the 2026-05-09 audit. Pre-fix the
connection's `closeErrorCode` was effectively unused — TLS handshake
failures bubbled up as generic `QuicCodecException` and observers had
to grep the reason string for the spec category. Now closeErrorCode
carries the RFC 9000 §20.1 transport code or the RFC 9001 §4.8
TLS-alert-mapped CRYPTO_ERROR.

Implementation:

  * `TlsAlertException(alertCode, message)` carrier raised by the
    TLS layer for the well-defined cases:
      - HelloRetryRequest received (handshake_failure = 40)
      - TLS 1.3 not negotiated (protocol_version = 70)
      - Unsupported cipher (illegal_parameter = 47)
      - ALPN mismatch (no_application_protocol = 120)
      - Cert chain validation failure (bad_certificate = 42)
      - CertificateVerify signature failure (decrypt_error = 51)
      - Server Finished MAC mismatch (decrypt_error = 51)
      - TLS KeyUpdate over QUIC (unexpected_message = 10) — RFC 9001
        §6 mandates this specific code; fixes the misleading prior
        message that said "rotation not implemented" (we DO implement
        QUIC's own KEY_PHASE-bit rotation).
    The QUIC parser maps `0x100 + alertCode` per RFC 9001 §4.8 and
    stamps `closeErrorCode`.

  * `QuicTransportError` constants object covering the RFC 9000 §20.1
    table (NO_ERROR through NO_VIABLE_PATH including the previously-
    flagged CRYPTO_BUFFER_EXCEEDED 0x0d, KEY_UPDATE_ERROR 0x0e,
    AEAD_LIMIT_REACHED 0x0f).

  * `markClosedExternally(reason, errorCode = NO_ERROR)` overload —
    backward compatible; lets call sites pin the spec code on
    `closeErrorCode` for qlog observability without changing the
    wire-emit semantics (still no CONNECTION_CLOSE frame, same as
    before — that's a separate, larger refactor).

  * RFC 9000 §22 CRYPTO_BUFFER_EXCEEDED enforcement — pre-insert
    per-level cap of 64 KiB on inbound CRYPTO data. Generous enough
    for an RSA-4096 cert chain with intermediates; bounds the
    worst-case heap a misbehaving peer can pin to 192 KiB across
    all 3 encryption levels. Fires before the receive buffer
    actually allocates.

  * INVALID_TOKEN — N/A for client role (only servers validate Retry
    tokens). KEY_UPDATE_ERROR — exposed as a constant; no current
    failure path maps to it (PN regression on a key-update packet
    is spec-allowed to handle silently per RFC 9001 §6.1, which we
    do).

Tests: `ErrorCodeMappingTest` (6 cases) covers TlsAlertException
construction + offset, alert code bounds, markClosedExternally
preservation, CRYPTO_BUFFER_EXCEEDED close, sanity-check that small
CRYPTO frames don't trip the cap, and §20.1 numeric values.
`HelloRetryRequestTest` updated to expect TlsAlertException(40)
instead of generic QuicCodecException.

Plan updated to mark the §4.8 + §22 (CRYPTO_BUFFER_EXCEEDED) items
resolved; KEY_UPDATE_ERROR documented as TLS-side covered + QUIC-side
spec-allowed-silent; INVALID_TOKEN documented as N/A for client.

https://claude.ai/code/session_01XGmmaVuy2wsSZQx2AqN2ik
This commit is contained in:
Claude
2026-05-09 13:44:35 +00:00
parent cdb9d87a2e
commit 6cc1bf6433
9 changed files with 412 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files
quic/plans/2026-04-26-quic-stack-status.md
+2 -2
View File
@@ -320,8 +320,8 @@ file:line evidence. Severity:
| RFC § | Sev | Gap | Evidence |
|---|---|---|---|
| RFC 9001 §4.8 | 🟦 | **TLS alerts not mapped to CRYPTO_ERROR + alert_code.** Connection still closes (a generic `QuicCodecException` propagates) but the alert code is lost — debuggability hit, not a wire-spec violation. | `TlsClient.kt:311-317` (catches as `Throwable`) |
| RFC 9000 §22 | 🟦 | **Several error codes never emitted.** INVALID_TOKEN (no Retry token validation), CRYPTO_BUFFER_EXCEEDED (no buffer limit), KEY_UPDATE_ERROR (uses generic exception path on KeyUpdate failures, despite key update being implemented). | various |
| RFC 9001 §4.8 | ~~🟦~~ | ~~**TLS alerts not mapped to CRYPTO_ERROR + alert_code.**~~ **Resolved 2026-05-09** — new `TlsAlertException(alertCode, ...)` carrier raised by the well-defined TLS error sites (HRR, TLS 1.3 version mismatch, cipher mismatch, ALPN mismatch, cert chain validation, CertificateVerify, Finished MAC, TLS KeyUpdate forbidden over QUIC). The QUIC parser's `feedDatagram` catches it and stamps `closeErrorCode = 0x100 + alertCode` per §4.8. Generic `QuicCodecException` falls back to `0x100 + 80` (internal_error). Tests in `ErrorCodeMappingTest`. |
| RFC 9000 §22 | ~~🟦~~ | ~~**Several error codes never emitted.**~~ **Partially resolved 2026-05-09:**<br>• **CRYPTO_BUFFER_EXCEEDED (0x0d)** — pre-insert per-level cap of 64 KiB on inbound CRYPTO data (covers worst-case RSA-4096 cert chains with headroom; bounds heap to 192 KiB across all 3 levels). Closes with the spec code on overshoot.<br>• **KEY_UPDATE_ERROR (0x0e)** — the original audit point referred to TLS KeyUpdate over QUIC, which is now mapped to CRYPTO_ERROR(unexpected_message=0x10a) via the `TlsAlertException` path above (RFC 9001 §6 mandates that specific code, NOT 0x0e). Constant exposed for future use; no QUIC-level rotation failure currently maps to it (PN-regression on a key-update packet is spec-allowed to handle silently per §6.1, which we do).<br>• **INVALID_TOKEN (0x0b)** — N/A for client role (only servers validate Retry tokens).<br>• Added `QuicTransportError` constants object covering the full §20.1 table; `markClosedExternally(reason, errorCode)` overload lets call sites pin the spec code on `closeErrorCode` for qlog observability. |
### Gaps the 2026-05-09 audit got WRONG