Skip to main content

Module session_pq_overlay

Module session_pq_overlay 

Source
Expand description

Session-scoped PQ binding overlay: trust-on-first-use continuity for browser and other dynamically-identified clients, with out-of-band promotion.

§Why this exists

crate::envelope::KeyedPqTrustStore is admin-anchored and immutable after install: an operator enrolls each peer’s ML-DSA-65 key out of band. A browser’s Ed25519 identity is user/device-generated, so no operator can pre-enroll it, and under the mandatory Hybrid suite an unanchored identity cannot have its signature checked at all — the request is dropped.

This overlay is the additive answer. It is consulted by the envelope verify path after the admin-anchored store misses, and it never mutates that store: its entries are established out of band by contract, and the federation perimeter deliberately leaves it untouched. Consult-then-fall- back, never write-through.

§The load-bearing property

A PqProvenance::TofuBound entry makes a signature verifiable without making the signer more trusted. Those are two different questions and this module answers them through two different methods that share no return type:

§What a composite has to prove before anything is recorded

The nested composite binds inner→outer — the outer ML-DSA-65 layer signs payload ‖ inner_signature — and not outer→inner. So a composite that verifies proves possession of the ML-DSA-65 key plus possession of one Ed25519 signature, which is not the same as possession of the Ed25519 private key: anyone holding a copy of a valid inner layer can drop the outer, re-sign with an ML-DSA key of their own, and produce a composite that verifies under the captured identity.

That is survivable while the PQ key is always resolved from a trust store, and fatal the moment it is recorded. So a binding is established only from a composite whose inner EdDSA layer commits to the key above it (crate::crypto::cose_sign::PQ_BINDING_HEADER_LABEL) — a commitment that lives inside the Ed25519 signature. An uncommitted composite still verifies; it just cannot establish a binding.

§Rebinding is loud by construction

TOFU’s security value is change detection, not initial trust. A silent last-write-wins rebind voids every guarantee here, so the API offers no way to perform one:

§Promotion and revocation

Promotion to PqProvenance::OobVerified requires presenting the composite_fingerprint — a hash over ed25519 ‖ ml_dsa_65, covering the pair, because fingerprinting the PQ half alone confirms possession of a key without binding it to the identity it claims to belong to. The value must have been obtained through a channel with different compromise assumptions from the one being bootstrapped; this module verifies the value matches, and cannot verify where the operator got it.

TofuBound entries expire with the session. An OobVerified promotion outlives one, so it has an explicit revocation path (SessionPqOverlay::revoke_promotion, SessionPqOverlay::revoke_binding) — an irreversible promotion would be worse than no promotion.

Structs§

RebindApproval
An operator decision to replace an established binding, carrying the event it answers.
RebindEvent
A surfaced attempt to bind an already-bound identity to a different PQ key.
SessionPqOverlay
Additive, session-scoped PQ binding overlay.
TracingPqBindingEventSink
Sink that records events to tracing at warning level.

Enums§

FirstContactOutcome
Outcome of offering a first-contact observation.
PqProvenance
How a PQ verifying key came to be associated with an Ed25519 identity.
PromotionError
Why a promotion was refused.

Constants§

DEFAULT_MAX_ENTRIES
Default ceiling on retained bindings.
DEFAULT_TOFU_TTL_MS
Default lifetime of a first-contact binding. It is session continuity, not enrollment: it lapses so that a device that stops appearing stops being remembered.

Traits§

PqBindingEventSink
Sink for binding lifecycle events.

Functions§

composite_fingerprint
The fingerprint compared over the out-of-band channel.
format_fingerprint
Render a fingerprint the way it is shown to a human performing the comparison: uppercase hex in space-separated quads, so a mismatch in any position is easy to spot when read aloud or compared by eye.
global_session_pq_overlay
The installed process-global overlay, if any.
install_session_pq_overlay
Install the process-global overlay. First write wins.