Crypto agility and migration¶
N-AALP tracks four independent axes that a migration can confuse if it treats them as one. Each changes on its own trigger, is carried by its own wire mechanism, and moving one never silently moves another.
| Axis | Carrier | Current / default | Changes on |
|---|---|---|---|
| Envelope wire version | naalp-version (protected header + field 9) |
2 |
A grammar-breaking change to the signed envelope shape |
| Signature suite | Field 14 (suite); absent = pure |
pure ML-DSA (MTI); opt-in LAMPS composite | An operator's own opt-in decision, or a future default flip (§ below) |
| Profile (security posture) | Field 9 (protected header + body) | Public / Enterprise / Sovereign | An operator's own deployment choice |
| Signer identity | The self-certifying signer id (derived from the public key) |
— | A key rotation or revocation |
1. Envelope wire version¶
The naalp-version field is the grammar-breaking axis: it changes only when the signed envelope's
own shape changes (a new required field, a changed field semantics), never for an algorithm swap or
a profile choice. It is checked and rejected fail-closed (UnsupportedVersion) on mismatch by every
reference SDK; the Go reference names it envelope.NaalpVersion (currently 2). Algorithm agility
and profile choice are deliberately decoupled from this axis — adding the opt-in composite suite
and the audience field both landed as the same naalp-version = 2 bump precisely because they
extend the grammar; a future algorithm change that does not touch the envelope shape would not need
a version bump at all.
2. Signature suite: pure ML-DSA (default) vs. the opt-in composite¶
The default and mandatory-to-implement (MTI) signature is pure ML-DSA (FIPS 204, deterministic,
rnd = 0) — no object pays for a classical leg unless a deployment opts in. Algorithm agility itself
is COSE's own alg header parameter (RFC 9052): changing the profile's signature algorithm changes
the alg value and the key type, with no change to the COSE_Sign1 construction or the envelope.
| Algorithm | COSE alg |
Role |
|---|---|---|
| ML-DSA-87 | -50 | PQ signature, level 5 (Sovereign default/mandate) |
| ML-DSA-65 | -49 | PQ signature, level 3 (Public/Enterprise default, MTI) |
| ML-DSA-44 | -48 | PQ signature, level 2 (optional edge/light tier only, never a silent downgrade) |
| Ed25519 | -19 | classical, opt-in composite leg only — never a standalone signature |
The opt-in composite is one signature, not two¶
The optional hybrid is a negotiable opt-in, retained for a deployment bridging classical peers and, for durability, as a pre-declared migration path should ML-DSA ever be weakened. It is not two independent signatures: it is a single COSE_Sign1 whose signature value is the IETF LAMPS composite of an ML-DSA and an Ed25519 signature over one domain-separated message representative — verification is valid iff both components validate. A stripped object has no valid signature at all, even to a non-strict verifier.
Which suite signed an object is itself a signed field carried under the signature (field 14,
suite) — absent for a pure object, 1 for the Public/Enterprise composite
(COMPSIG-MLDSA65-Ed25519-SHA512). Turning the composite on for a deployment, or flipping the
default suite later, is a suite-id change through this field — not a wire break.
import "github.com/bubblefish-tech/naalp_protocol/impl/go/cose"
// Pure (default): no composite signer, field 14 absent.
signed, err := envelope.Sign(obj, cose.MLDSA65Signer{SK: sk})
// Opt-in composite: both an ML-DSA and an Ed25519 key. Sign() reads the composite alg off
// the signer and sets field 14 = SuiteMLDSA65Ed25519 automatically — a caller never sets
// the suite field by hand.
composite := cose.CompositeSigner{ML65: mlSK, Ed: edSK}
signed, err = envelope.Sign(obj, composite)
Sovereign is never composite¶
The Sovereign profile signs with pure ML-DSA-87 and carries no classical leg — CNSA 2.0 mandates
ML-DSA-87 for national-security signatures. A Sovereign verifier refuses a composite object
(CompositeRefused); this is a hard profile rule, never a negotiable default.
Migrating a deployment onto the composite¶
- Decide the trigger. The composite exists for two reasons: bridging a classical-only peer during a transition, or a pre-declared response if ML-DSA is ever weakened. Do not enable it as a default performance or compatibility choice — it costs an extra signature verification per object for no security benefit when both peers already trust ML-DSA alone.
- Generate the Ed25519 leg alongside the existing ML-DSA key for every signer that needs it. The ML-DSA leg's key and identity are unchanged; the composite adds a second key, it does not replace the first.
- Sign with the composite signer — the SDK sets the signed suite field (14) automatically from
the signer's algorithm; a caller never sets it by hand. A verifier that has not opted in to
accepting composite objects will reject an unrecognized
algvalue (UnknownAlg) — coordinate rollout so verifiers are updated before signers start emitting composite objects. - Never let Sovereign accept it. If any signer in the deployment operates under the Sovereign profile, confirm the composite path is never reachable for that signer's keys — a Sovereign verifier rejects it regardless, but a Sovereign signer should never attempt it.
- Unforgeability note. Pure ML-DSA is SUF-CMA (strongly unforgeable); the opt-in composite is EUF-CMA but not SUF-CMA. N-AALP never keys a security decision off raw signature bytes regardless — the single-use consume ledger binds the content id and receipt chain, not the signature — so this is a property to be aware of, not a load-bearing gap.
3. Profile: Public, Enterprise, Sovereign¶
Profile is a separate axis from the signature suite: it is the operator's own security-posture choice, fixing the minimum signature level a verifier accepts and whether the composite is even permitted.
| Property | Public (1) | Enterprise (2) | Sovereign (3) |
|---|---|---|---|
| Default signature | ML-DSA-65 | ML-DSA-65 | ML-DSA-87 |
| Minimum signature level | 3 | 3 | 5 (refuse below) |
| Opt-in composite | permitted | permitted | refused |
| Digest | SHA-384 | SHA-384 | SHA-384+ |
The profile is bound under the signature (field 9 + protected header), so stripping or downgrading it invalidates the object. A Sovereign verifier refuses any object whose signature is below level 5. No edition is a fork — one binding, one construction, one parameter row per profile on one codebase.
Migrating a deployment's profile (e.g. Public → Enterprise, or onboarding a Sovereign segment) is an endpoint-configuration change: raise the accepted/emitted profile on the endpoints that need it, and confirm no downstream verifier still pinned to the old profile silently accepts an object it should now refuse at the higher floor. A profile can only ever be raised deliberately by configuration — an object cannot claim a profile its own signature does not meet.
4. Key rotation and revocation¶
A signer's key is not permanent. Because the signer id is a pure function of the public key, a rotation needs its own durable-identity mechanism so a receipt signed under an old key stays attributable to the same identity after the key changes.
Rotation: a co-signed statement, never a lone new-key claim¶
A Rotation object (Identity channel 0x0003, kind 0) is {old: signer_old, new: signer_new,
not_before, prev_rotation?}, carried as a tagged COSE_Sign (tag 98) with exactly two
COSE_Signature legs in fixed order — old key, then new key. A verifier requires both legs to
validate; a rotation presented as an ordinary single-signature COSE_Sign1 (tag 18) is rejected
RotationUnauthorized — closing the gap where a lone new-key signature would otherwise verify like
any other object with no old-key check at all. A substitution not co-signed by the old key is not a
rotation.
signed, err := envelope.SignRotation(rotationObj, oldSigner, newSigner) // envelope/rotation.go
// A verifier holding a trusted old key and the object's new key:
obj, err := envelope.VerifyRotationObject(profile, oldVerifier, newVerifier, kindOK, nil, signed)
A chain of rotation objects gives a durable identity thread across arbitrarily many rotations: the current signer is the last binding in a verified chain, and a receipt signed under any earlier key in the chain stays attributable to the same durable identity. Composite legs are undecided inside a rotation's old/new co-signature and are rejected fail-closed — rotate with pure ML-DSA (or pure Ed25519) keys, not a composite signer.
Old-leg profile floor. By default, when a Sovereign/High verifier checks a rotation whose old
key is below the profile's signature floor, the floor applies to both legs (a below-floor old
key is rejected ProfileDowngrade). A deployment may explicitly relax this to the new (go-forward)
leg only — this is a deployment-configured toggle, not a wire choice.
Revocation: distinct from rotation, and terminal¶
A Revocation object {key: signer, not_after}, signed by the key itself (or by a
deployer-configured recovery key), marks a key dead from not_after. It carries no new key and
does not continue the identity thread — where rotation hands off the thread, revocation ends it.
An object whose authoritative receipt position falls after not_after is rejected; objects fixed
before it stay valid. Absent any configured recovery key, only the revoked key may sign its own
revocation (SignerMismatch otherwise).
Migrating (rotating) a live deployment's keys¶
- Generate the new key for the signer while the old key is still valid and unrevoked.
- Build and co-sign the Rotation object with both the old and new keys, setting
not_beforeto when the new key becomes authoritative. - Distribute the rotation object to every counterparty that verifies this signer's objects
before
not_beforearrives, so no verifier is surprised by a new signer id it cannot yet chain back to the old one. - Confirm chain continuity: a verifier walking the rotation chain should resolve the new signer id back to the original durable identity, and pre-rotation receipts signed under the old key should remain independently verifiable and attributable to the same identity thread.
- Only revoke the old key if it is compromised or permanently retired — a clean rotation does not require revoking the old key at all; the old key simply stops being used going forward while remaining valid for verifying its own historical signatures.
5. Operational checklist¶
- [ ] Confirm every counterparty's SDK checks
naalp-versionand rejects an unsupported version fail-closed (UnsupportedVersion) rather than guessing at an unrecognized grammar. - [ ] Decide the composite-suite trigger (classical-bridge or pre-declared ML-DSA-weakening response) before enabling it anywhere — it is not a default performance choice.
- [ ] If enabling the composite, roll out verifier support (accepting the
suitefield and the compositealg) before any signer starts emitting composite objects. - [ ] Never enable the composite path for a Sovereign-profile signer; confirm a Sovereign verifier's refusal is exercised in the deployment's own test suite, not merely assumed from the spec.
- [ ] For a profile raise (Public → Enterprise, or onboarding Sovereign), confirm no downstream verifier is still pinned to the old, lower floor.
- [ ] For a key rotation, build and distribute the co-signed Rotation object before the new key's
not_before, and confirm chain continuity resolves the new id back to the original identity. - [ ] Revoke a key only on compromise or permanent retirement, never as a routine part of rotation.
6. Non-scope¶
This page does not cover: the eight non-Go/Rust SDK ports' own key-management or CLI tooling (each language's own I/O and key-storage integration is that SDK's own concern; the wire mechanisms above are identical across all ten); a general registry-of-registries for future signature algorithms beyond the reserved SLH-DSA (FIPS 205) code points; and the N-PAMP transport's own independent key-exchange rotation, which is a substrate concern that never lands on the N-AALP object signature.
7. References¶
- The object model — the signed envelope this page's fields live in.
- Design decision 0003 — why ML-DSA is mandatory-to-implement.
vectors/registry/signatures.csv— the authoritative COSE algorithm code-point registry.impl/go/cose,impl/go/identity,impl/go/envelope/rotation.go— the reference implementation this page's code snippets are drawn from.