Skip to content

docs(adr): accept ADR-0011, envelope moves to COSE_Sign1 in v0.2 - #242

Merged
imran-siddique merged 1 commit into
mainfrom
docs/adr-0011-accept
Jul 27, 2026
Merged

docs(adr): accept ADR-0011, envelope moves to COSE_Sign1 in v0.2#242
imran-siddique merged 1 commit into
mainfrom
docs/adr-0011-accept

Conversation

@imran-siddique

Copy link
Copy Markdown
Contributor

Records the decision on ADR-0011 part 2 and sequences the work. Follows #241, which posed the question.

Decision

COSE_Sign1, in spec v0.2, aligning with SCITT (RFC 9943).

Three concrete properties, not alignment for its own sake:

  1. The signed bytes travel with the signature. COSE_Sign1 signs the payload as-is, so a verifier never re-serializes anything to check a signature. RFC 8785 stays as the producer-side determinism rule and as the basis of the manifest hash bound into hardware REPORT_DATA, but stops being an input to verification. That removes canonicalize-before-verify, the specific surface DSSE names.
  2. alg sits in the protected header, covered by the signature. The bug we shipped and fixed in 0.6.0 cannot be expressed in this envelope.
  3. Receipts attach where SCITT puts them, matching the transparency_log_entry-after-signing ordering Section 3.6 already describes in prose.

The post-quantum blocker cleared

This was the main technical risk, and checking it changed the plan rather than confirming it. My first search returned draft-ietf-cose-dilithium-11 (Nov 2025, expiring April 2026) with requested code points, which would have forced either provisional identifiers or holding the PQ profile on the old envelope. That result was stale. The draft is now RFC 9964 (Standards Track, May 2026) with final IANA assignments:

  • ML-DSA-65 = COSE alg -49
  • AKP key type = 7
  • Ed25519 = EdDSA (-8), long established

Both profiles have stable registered identifiers. Nothing is pinned to a draft.

Hybrid is the one gap. COSE has no single-signature hybrid mode, so hybrid-Ed25519-ML-DSA-65 becomes either two COSE_Sign1 structures over the same payload or one COSE_Sign with two signers. Deferred to the v0.2 spec work.

Migration

Five phases, each its own PR, gated on the manifest version field rather than a flag, so v0.1 records keep verifying exactly as they do today and no existing record is reinterpreted.

  1. Specify (spec v0.2, no code): protected header, payload content type, receipt placement, hybrid construction, media type.
  2. Implement behind the version gate: COSE path alongside the existing one. Brings a CBOR/COSE library, the first non-cryptography crypto dependency the SDK has taken, and should be reviewed as such.
  3. Conformance: COSE variants of the AM-VEC-* vectors, including negatives only this envelope can express (tampered protected header, alg substitution).
  4. Consumers: cmcp and ca2a move when v0.2 verification is released. The TypeScript SDK is written against COSE from the start rather than ported to v0.1 and migrated twice.
  5. Deprecation: announced end date for issuing v0.1 manifests; verification of v0.1 records stays supported through the retention window, since these are audit records with regulated retention past their 90-day life.

Also here

  • Spec 10.2 gains the v0.2 line item; 3.6's envelope note now says what happens to it instead of leaving it open.
  • docs/index.md FAQ and the ADR index reflect the accepted state.

618 tests pass. No behaviour change in this PR: it is the decision record plus spec roadmap text.

Records the decision on part 2 and the sequence for getting there.

The main technical risk when the migration was first written up was the
post-quantum profile, and it has since cleared: RFC 9964 (Standards
Track, May 2026) gives ML-DSA final IANA code points in COSE, with
ML-DSA-65 as alg -49 and AKP as key type 7. Both profiles therefore have
stable registered identifiers, so nothing has to be pinned to a draft.
Hybrid is the one construction COSE has no single answer for; that choice
is deferred to the v0.2 spec work.

Migration is five phases, each its own PR, gated on the manifest version
field rather than a flag, so v0.1 records keep verifying exactly as they
do today. Spec 10.2 gains the v0.2 line item and 3.6 says what happens to
it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@imran-siddique
imran-siddique merged commit 7ce708e into main Jul 27, 2026
12 checks passed
@imran-siddique
imran-siddique deleted the docs/adr-0011-accept branch July 27, 2026 04:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant