Expand description
Policy-gated composite signing and verification for did:at9p records
(capsules and update-records), per design #879 §4.4 (Hybrid-pinning) and
review rules R4/R8 (findings A18/A19).
§GATE 2: Hybrid is PINNED, not configurable
CryptoPolicy::{Hybrid, Classical} is per-node runtime configuration for
the general RPC plane. at9p records do not honor it: capsule,
update-record, and manifest signatures always require BOTH composite
components (EdDSA + ML-DSA-65) to verify, regardless of the node’s policy.
A Classical-configured node still rejects an Ed25519-only-valid capsule
(§4.4, A19/R4) — otherwise an attacker holding only a stolen classical key
could forge identities for every such node.
The pin is built into this module’s API surface so it cannot be bypassed:
- Signing takes a
&MlDsaSigningKeyby value, never anOption. There is no code path that calls the underlying [hyprstream_crypto::cose_sign::sign_composite] withpq_sk = None(review rule R4 —sign_compositedoes not self-enforce policy; its callers do). The one call site is [sign_record], and it always passesSome(pq_sk). - Verification always calls
[
hyprstream_crypto::cose_sign::verify_composite] withrequire_pq = trueand a non-Noneanchored ML-DSA-65 key. A missing outer layer (stripped or classical-only) fails closed.
§Per-record-type COSE context strings (R8, A18)
Every at9p record type binds its context string
(at9p-capsule/1, at9p-update/1) into the COSE protected header, which is
folded into BOTH signature layers as external_aad (RFC 9052 §4.4). The
context is checked on verify against the record type being verified, so
a signature minted for one record type (or an RPC envelope) cannot be
replayed as another — cross-context signature reuse (A18) is defeated.
Traits§
- Capsule
Ed25519 Signer - An Ed25519 capsule signer whose secret half may live outside the process.
Functions§
- sign_
capsule - Sign a capsule body with one of its subject keys, producing a fully-signed
Capsule. Self-certifying: the signing keys MUST match some publishedbody.subject_keysentry (an atomic Ed25519↔ML-DSA-65 pair), not a positional “primary” —subjectKeysis a set (#1188 / #1183). - sign_
capsule_ detached sign_capsulefor an authority whose Ed25519 leg signs out-of-band (YubiKey PIV, KMS). Applies the identical subject-key self-certification checks and the identical pinned-Hybrid composite construction.- sign_
update_ record - Sign an update-record’s content with the authorizing hybrid keypair,
producing a fully-signed
UpdateRecord. - verify_
capsule - Verify a genesis/self-certifying
Capsule: the composite signature must verify (pinned Hybrid) against some published subject key. - verify_
update_ record - Verify an
UpdateRecordunder PINNED Hybrid policy against the authorizingsignerkeypair. The caller (rotation-chain validator, #884) decides which key is authorized; this function enforces the crypto + context binding.