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:
SessionPqOverlay::verifying_key_for— verifiability. Returns a key and nothing else, so the verify path structurally cannot learn provenance from it and therefore cannot launder it into an assurance decision.SessionPqOverlay::provenance_for— trust. The MAC assurance seam reads this, andPqProvenance::key_materialrefuses to mapTofuBoundto anything aboveClassical.
§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:
SessionPqOverlay::observe_first_contactinserts into a vacant slot only. An occupied slot naming a different key yieldsFirstContactOutcome::RebindRefused, and theRebindEventis published to the event sink before that value is returned, so a caller that discards the return value has still surfaced the event.- The only way to change an established binding is
SessionPqOverlay::apply_rebind, which takes aRebindApproval. ARebindApprovalcan only be built by consuming aRebindEvent, which only the overlay can mint, and only by refusing a rebind. Legitimate key rotation therefore travels the same visible path as an attack.
§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§
- Rebind
Approval - An operator decision to replace an established binding, carrying the event it answers.
- Rebind
Event - A surfaced attempt to bind an already-bound identity to a different PQ key.
- Session
PqOverlay - Additive, session-scoped PQ binding overlay.
- Tracing
PqBinding Event Sink - Sink that records events to
tracingat warning level.
Enums§
- First
Contact Outcome - Outcome of offering a first-contact observation.
- PqProvenance
- How a PQ verifying key came to be associated with an Ed25519 identity.
- Promotion
Error - 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§
- PqBinding
Event Sink - 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.