Skip to content

Make QUIC token secrets configurable#13397

Open
bneradt wants to merge 1 commit into
apache:masterfrom
bneradt:quic-token-secret
Open

Make QUIC token secrets configurable#13397
bneradt wants to merge 1 commit into
apache:masterfrom
bneradt:quic-token-secret

Conversation

@bneradt

@bneradt bneradt commented Jul 16, 2026

Copy link
Copy Markdown
Contributor

QUIC address-validation and stateless-reset tokens use fixed
compile-time secrets, allowing anyone with the source to reproduce
valid token MACs.

This replaces the fixed values with reloadable 32-byte keys and a
random per-process fallback. Multiple file keys allow rotation without
immediately invalidating address-validation tokens, and HMAC-SHA256
protects all token types.

This also rejects malformed tokens before parsing and adds coverage for
file loading, key rotation, invalid files, and fallback-key stability.

QUIC address-validation and stateless-reset tokens use fixed
compile-time secrets, allowing anyone with the source to reproduce
valid token MACs.

This replaces the fixed values with reloadable 32-byte keys and a
random per-process fallback. Multiple file keys allow rotation without
immediately invalidating address-validation tokens, and HMAC-SHA256
protects all token types.

This also rejects malformed tokens before parsing and adds coverage for
file loading, key rotation, invalid files, and fallback-key stability.
Copilot AI review requested due to automatic review settings July 16, 2026 18:30
@bneradt bneradt added this to the 11.0.0 milestone Jul 16, 2026
@bneradt bneradt self-assigned this Jul 16, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR hardens QUIC token security in ATS by replacing fixed, compile-time secrets for address-validation (Retry/Resumption) and stateless-reset tokens with reloadable 32-byte secret keys (plus a per-process random fallback when unset). It integrates the new key material into the config reload flow and updates token generation/validation to use HMAC-SHA256, including stricter malformed-token rejection.

Changes:

  • Add a reloadable record (proxy.config.quic.server.token_key.filename) and wire it into mgmt’s config reread triggers.
  • Introduce QUICTokenKeyConfig to load/rotate one-or-more 32-byte keys (or generate a stable per-process random key when unset).
  • Update QUIC token generation/validation to HMAC-SHA256 and add unit tests + admin documentation for key files and rotation.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated no comments.

Show a summary per file
File Description
src/records/RecordsConfig.cc Adds the new reloadable QUIC token key filename record.
src/mgmt/config/FileManager.cc Ensures the QUIC token key filename record participates in reread/reload triggering (like SSL ticket keys).
src/iocore/net/unit_tests/test_QUICTokenKeyConfig.cc Adds Catch2 coverage for key loading, rotation behavior, invalid key files, and random-fallback stability.
src/iocore/net/quic/QUICTypes.cc Switches token MACs to HMAC-SHA256, validates against multiple keys, and rejects malformed tokens before parsing.
src/iocore/net/quic/QUICConfig.cc Implements QUICTokenKeyConfig (load/generate/cleanse) and starts it during QUIC startup.
src/iocore/net/CMakeLists.txt Builds the new QUIC token key unit test when QUIC is enabled.
include/iocore/net/quic/QUICTypes.h Introduces MAC_LENGTH, hardens token buffer construction, and initializes _token_len safely.
include/iocore/net/quic/QUICConfig.h Declares QUICTokenKeyConfig{,Params} public interfaces and key storage types.
doc/admin-guide/files/records.yaml.en.rst Documents the new record, key file format/rotation semantics, and clarifies proxy.config.quic.instance_id semantics.

@bneradt
bneradt requested a review from maskit July 16, 2026 18:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

Status: No status
Status: No status

Development

Successfully merging this pull request may close these issues.

2 participants