diff --git a/draft-ietf-cose-merkle-tree-proofs.md b/draft-ietf-cose-merkle-tree-proofs.md index 48ccff0..98d38d3 100644 --- a/draft-ietf-cose-merkle-tree-proofs.md +++ b/draft-ietf-cose-merkle-tree-proofs.md @@ -47,9 +47,14 @@ normative: RFC9162: certificate-transparency-v2 informative: + RFC7120: + RFC9052: + RFC8610: + RFC8949: RFC8126: iana-considerations-guide BCP205: RFC7942 RFC8392: CWT + I-D.draft-ietf-cbor-edn-literals: cbor-edn-literals I-D.ietf-cose-cwt-claims-in-headers: cwt-header-claims I-D.ietf-cose-typ-header-parameter: cose-typ @@ -71,7 +76,7 @@ Merkle trees can be constructed from simple operations such as concatenation and Verifiable data structure proofs can be used to prove a document is in a database (proof of inclusion), that a database is append only (proof of consistency), that a smaller set of statements are contained in a large set of statements (proof of disclosure, a special case of proof of inclusion), or proof that certain data is not yet present in a database (proofs of non inclusion). Differences in the representation of verifiable data structures, and verifiable data structure proof types, can increase the burden for implementers, and create interoperability challenges for transparency services. This document describes how to convey verifiable data structures, and associated proof types in COSE envelopes. -For conciseness, we refer to a COSE object securing a verifiable data structure and its associated proof types, as a COSE Receipt. +For conciseness, a COSE object securing a verifiable data structure and its associated proofs, is referred to as a COSE Receipt. ## Requirements Notation @@ -83,11 +88,11 @@ Editorial Note (To be removed by RFC Editor). This section will be removed before the document is completed, its purpose is to track the TBD code points references throughout the draft. --111 is TBD_1: +395 is TBD_1: : A requested cose header parameter representing the verifiable data structure used. --222 is TBD_2: +396 is TBD_2: : A requested cose header parameter representing the verifiable data structure parameters map (proofs map). @@ -95,23 +100,29 @@ The other codepoints are assigned from the registries established in this draft, # Terminology -Verifiable Data Structure (vds): +CDDL: +: Concise Data Definition Language (CDDL) is defined in {{RFC8610}}. + +EDN: +: CBOR Extended Diagnostic Notation (EDN) is defined in {{RFC8949}}, where it is referred to as "diagnostic notation", and is revised in {{-cbor-edn-literals}}. + +Verifiable Data Structure (VDS): : A data structure which supports one or more Proof Types. This property is conceptually similar to "alg" (1), it described an algorithm used to maintain the verifiable data structure, for example a binary merkle tree algorithm. -Verifiable Data Structure Parameters (vdp): +Verifiable Data Structure Parameters (VDP): : Parameters to a verifiable data structure that are used to prove properties, such as authentication, inclusion, consistency, and freshness. Parameters can include multiple proofs of a given type, or multiple types of proof (inclusion and consistency). This property is conceptually similar to COSE Header Parameter "epk" (-1) or CBOR Web Token (CWT) claim "cnf" (8), it is applied to a verifiable data structure, to confirm a property. - For example an encrypted message might be decrypted using epk and a private key, a digital signature for authentication might be verified using cnf and the (CWT) claim "nonce" and "audience", and an inclusion proof for a binary merkle tree might be verified with vdp and some entry that is being tested or inclusion in the tree. - + For example an encrypted message might be decrypted using epk and a private key, a digital signature for authentication might be verified using cnf and the (CWT) claim "nonce" and "audience", and an inclusion proof for a binary merkle tree might be verified with VDP and some entry that is being tested or inclusion in the tree. Proof Type: : A verifiable process, that proves properties of a Verifiable Data Structure. + For example, a VDS, such as a binary merkle tree, can support multiple proofs of type "inclusion" where each proof confirms that a given entry is included in a merkle root. Proof Value: @@ -123,7 +134,7 @@ Entry: Receipt: -: A COSE Object containing the header parameters necessary to convey a proof types for verifiable data structures. +: A COSE object, as defined in {{RFC9052}}, containing the header parameters necessary to convey VDP for an associated VDS. # Verifiable Data Structures in CBOR {#sec-generic-verifiable-data-structures} @@ -131,9 +142,11 @@ Receipt: This section describes representations of verifiable data structure proofs in CBOR. For example, construction of a merkle tree leaf, or an inclusion proof from a leaf to a merkle root, might have several different representations, depending on the verifiable data structure used. Differences in representations are necessary to support efficient verification, unique security or privacy properties, and for compatibility with specific implementations. -In order to improve interoperability we define two extension points for enabling verifiable data structures with COSE, and we provide concrete examples for the structures and proofs defined in {{-certificate-transparency-v2}}. +This document defines two extension points for enabling verifiable data structures with COSE and provides concrete examples for the structures and proofs defined in {{-certificate-transparency-v2}}. The design of these structures is influenced by the conventions established for COSE Keys. +During testing and development the experimental range SHOULD be used, unless early assignment for a provisional entry has been completed. + ## Structures {#sec-cose-verifiable-data-structures} Similar to [COSE Key Types](https://www.iana.org/assignments/cose/cose.xhtml#key-type), different verifiable data structures support different algorithms. @@ -141,20 +154,17 @@ As EC2 keys (1: 2) support both digital signature and key agreement algorithms, This document establishes a registry of verifiable data structure algorithms, with the following initial contents: -* Name: The name of the verifiable data structure -* Value: The identifier for the verifiable data structure -* Description: The identifier for the verifiable data structure -* Reference: Where the verifiable data structure is defined - | Name | Value | Description | Reference |--- | N/A | 0 | N/A | N/A | RFC9162_SHA256 | 1 | SHA256 Binary Merkle Tree | {{-certificate-transparency-v2}} +| EXPERIMENTAL | 11 | Unknown | RFC XXXX +| EXPERIMENTAL | 22 | Unknown | RFC XXXX +| EXPERIMENTAL | 33 | Unknown | RFC XXXX {: #cose-verifiable-data-structures align="left" title="COSE Verifiable Data Structures"} When designing new verifiable data structures, please request the next available positive integer as your requested assignment, for example: - | Name | Value | Description | Reference |--- | N/A | 0 | N/A | N/A @@ -172,6 +182,9 @@ This document establishes a registry of verifiable data structure algorithms, wi |--- | 1 | inclusion proofs | -1 | array (of bstr) | Proof of inclusion | {{sec-rfc9162-sha256-inclusion-proof}} | 1 | consistency proofs | -2 | array (of bstr) | Proof of append only property | {{sec-rfc9162-sha256-consistency-proof}} +| 11 | unknown | -1 | array (of bstr) | Unknown | RFC XXXX +| 22 | unknown | -1 | array (of bstr) | Unknown | RFC XXXX +| 33 | unknown | -1 | array (of bstr) | Unknown | RFC XXXX {: #cose-verifiable-data-structures-parameters align="left" title="COSE Verifiable Data Structure Parameters"} Proof types are specific to their associated "verifiable data structure", for example, different Merkle trees might support different representations of "inclusion proof" or "consistency proof". @@ -190,6 +203,54 @@ When designing new verifiable data structure parameters (or proof types), please |TBD (requested assignment 2) | new proof type | -3 | tbd | tbd | Your_Specification {: #cose-verifiable-data-structures-parameters-registration-guidance align="left" title="How to register new parameters"} +## Usage + +This document registered a new COSE Header Parameter `receipts` (394) to enable this Receipts to be conveyed in the protected and unprotected headers of COSE Objects. + +When the receipts parameter is present, the associated verifiable data structure and verifiable data structure proofs MUST match entries present in the registries established in RFC XXXX. + +The following informative CDDL is provided: + +~~~ cddl +Receipt = #6.18(COSE_Sign1) + +Protected_Header = { + * cose-label => cose-value +} + +Unprotected_Header = { + &(receipts: 394) => [+ Receipt] + * cose-label => cose-value +} + +COSE_Sign1 = [ + protected : bstr .cbor Protected_Header, + unprotected : Unprotected_Header, + payload : bstr / nil, + signature : bstr +] +~~~ +{: #fig-receipts-cddl title="CDDL for a COSE Sign1 with attached receipts"} + +The following informative EDN is provided: + +~~~ cbor-diag +18( / COSE Sign 1 / + [ + h'a4012603...6d706c65', / Protected / + { / Unprotected / + 394: [ / Receipts (2) / + h'd284586c...4191f9d2' / Receipt 1 / + h'c624586c...8f4af97e' / Receipt 2 / + ] + }, + nil, / Detached payload / + h'79ada558...3a28bae4' / Signature / + ] +) +~~~ +{: #fig-receipts-edn title="EDN for a COSE Sign1 with attached receipts"} + ### Registration Requirements Each specification MUST define how to encode the verifiable data structure and its parameters (also called proof types) in CBOR. @@ -237,14 +298,14 @@ The protected header for an RFC9162_SHA256 inclusion proof signature is: ~~~~ cddl protected-header-map = { &(alg: 1) => int - &(vds: -111) => int + &(vds: 395) => int * cose-label => cose-value } ~~~~ {: #vds-in-inclusion-receipt-protected-header align="left" title="Protected Header for a Receipt of Inclusion"} * alg (label: 1): REQUIRED. Signature algorithm identifier. Value type: int. -* vds (label: -111): REQUIRED. verifiable data structure algorithm identifier. Value type: int. +* vds (label: 395): REQUIRED. verifiable data structure algorithm identifier. Value type: int. The unprotected header for an RFC9162_SHA256 inclusion proof signature is: @@ -257,26 +318,26 @@ verifiable-proofs = { } unprotected-header-map = { - &(vdp: -222) => verifiable-proofs + &(vdp: 396) => verifiable-proofs * cose-label => cose-value } ~~~~ {: #vdp-in-unprotected-header align="left" title="A Verifiable Data Structure Proofs in an Unprotected Header"} -* vdp (label: -222): REQUIRED. Verifiable data structure proofs. Value type: Map. +* vdp (label: 396): REQUIRED. Verifiable data structure proofs. Value type: Map. * inclusion-proof (label: -1): REQUIRED. Inclusion proofs. Value type: Array of bstr. The payload of an RFC9162_SHA256 inclusion proof signature is the previous Merkle tree hash as defined in {{-certificate-transparency-v2}}. The payload MUST be detached. Detaching the payload forces verifiers to recompute the root from the inclusion proof signature, this protects against implementation errors where the signature is verified but the merkle root does not match the inclusion proof. -The CBOR Extended Diagnostic Notation (EDN) for a Receipt containing an inclusion proof for RFC9162_SHA256 is: +The EDN for a Receipt containing an inclusion proof for RFC9162_SHA256 is: ~~~~ cbor-diag 18( / COSE Sign 1 / [ h'a4012604...6d706c65', / Protected / { / Unprotected / - -222: { / Proofs / + 396: { / Proofs / -1: [ / Inclusion proofs (1) / h'83080783...32568964', / Inclusion proof 1 / ] @@ -289,20 +350,20 @@ The CBOR Extended Diagnostic Notation (EDN) for a Receipt containing an inclusio ~~~~ {: #rfc9162_sha256_inclusion_receipt align="left" title="Example inclusion receipt"} -The CBOR Extended Diagnostic Notation (EDN) for the Protected Header in the example above is: +The EDN for the Protected Header in the example above is: ~~~~ cbor-diag { / Protected / 1: -7, / Algorithm / 4: h'4930714e...7163316b', / Key identifier / - -111: 1, / Verifiable Data Structure / + 395: 1, / Verifiable Data Structure / } ~~~~ {: #rfc9162_sha256_inclusion_receipt_header align="left" title="Example inclusion receipt decoded protected header"} -The vds in the protected header is necessary to understand the vdp in the unprotected header. +The VDS in the protected header is necessary to understand the VDP in the unprotected header. -The CBOR Extended Diagnostic Notation (EDN) for the inclusion proof in the Unprotected Header is: +The EDN for the inclusion proof in the Unprotected Header is: ~~~~ cbor-diag [ / Inclusion proof 1 / @@ -317,7 +378,7 @@ The CBOR Extended Diagnostic Notation (EDN) for the inclusion proof in the Unpro ~~~~ {: #rfc9162_sha256_inclusion_receipt_inclusion_proof align="left" title="Example inclusion receipt decoded inclusion proof"} -The vds in the protected header is necessary to understand the inclusion proof structure in the unprotected header. +The VDS in the protected header is necessary to understand the inclusion proof structure in the unprotected header. The inclusion proof and signature are verified in order. First the verifiers applies the inclusion proof to a possible entry (set member) bytes. @@ -361,7 +422,7 @@ The protected header for an RFC9162_SHA256 consistency proof signature is: ~~~~ cddl protected-header-map = { &(alg: 1) => int - &(vds: -111) => int + &(vds: 395) => int * cose-label => cose-value } ~~~~ @@ -381,26 +442,26 @@ verifiable-proofs = { } unprotected-header-map = { - &(vdp: -222) => verifiable-proofs + &(vdp: 396) => verifiable-proofs * cose-label => cose-value } ~~~~ -* vdp (label: -222): REQUIRED. Verifiable data structure proofs. Value type: Map. +* vdp (label: 396): REQUIRED. Verifiable data structure proofs. Value type: Map. * consistency-proof (label: -2): REQUIRED. Consistency proofs. Value type: Array of bstr. The payload of an RFC9162_SHA256 consistency proof signature is: The latest Merkle tree hash as defined in {{-certificate-transparency-v2}}. The payload MUST be attached. -The CBOR Extended Diagnostic Notation (EDN) for a Receipt containing a consistency proof for RFC9162_SHA256 is: +The EDN for a Receipt containing a consistency proof for RFC9162_SHA256 is: ~~~~ cbor-diag 18( / COSE Sign 1 / [ h'a3012604...392b6601', / Protected / { / Unprotected / - -222: { / Proofs / + 396: { / Proofs / -2: [ / Consistency proofs (1) / h'83040682...2e73a8ab', / Consistency proof 1 / ] @@ -413,20 +474,20 @@ The CBOR Extended Diagnostic Notation (EDN) for a Receipt containing a consisten ~~~~ {: #rfc9162_sha256_consistency_receipt align="left" title="Example consistency receipt"} -The vds in the protected header is necessary to understand the vdp in the unprotected header. +The VDS in the protected header is necessary to understand the VDP in the unprotected header. -The CBOR Extended Diagnostic Notation (EDN) for the Protected Header in the example above is: +The EDN for the Protected Header in the example above is: ~~~~ cbor-diag { / Protected / 1: -7, / Algorithm / 4: h'68747470...6d706c65', / Key identifier / - -111: 1, / Verifiable Data Structure / + 395: 1, / Verifiable Data Structure / } ~~~~ {: #rfc9162_sha256_consistency_receipt_header align="left" title="Example consistency receipt decoded protected header"} -The CBOR Extended Diagnostic Notation (EDN) for the consistency proof in the Unprotected Header is: +The EDN for the consistency proof in the Unprotected Header is: ~~~~ cbor-diag [ / Consistency proof 1 / @@ -440,7 +501,7 @@ The CBOR Extended Diagnostic Notation (EDN) for the consistency proof in the Unp ~~~~ {: #rfc9162_sha256_consistency_receipt_consistency_proof align="left" title="Example consistency receipt decoded consistency proof"} -The vds in the protected header is necessary to understand the consistency proof structure in the unprotected header. +The VDS in the protected header is necessary to understand the consistency proof structure in the unprotected header. The signature and consistency proof are verified in order. @@ -510,21 +571,36 @@ for their contributions (some of which substantial) to this draft and to the ini ### New Entries to the COSE Header Parameters Registry -This document requests IANA to add new values to the 'COSE Algorithms' and to the 'COSE Header Algorithm Parameters' registries in the 'Standards Action With Expert Review category. +This document requests IANA to add new values to the 'COSE Algorithms' and to the 'COSE Header Algorithm Parameters' registries in the 'Standards Action With Expert Review' category. #### COSE Header Algorithm Parameters +##### Receipts + +* Name: receipts +* Label: TBD_0 (requested assignment 394) +* Value type: array (of bstr) +* Value registry: https://www.iana.org/assignments/cose/cose.xhtml#header-parameters +* Description: Priority ordered list of CBOR encoded Receipts. +* Reference: RFC XXXX + +##### Verifiable Data Structure + * Name: vds -* Label: TBD_1 +* Label: TBD_1 (requested assignment 395) * Value type: int * Value registry: https://www.iana.org/assignments/cose/cose.xhtml#header-parameters * Description: Algorithm name for verifiable data structure, used to produce verifiable data structure proofs. +* Reference: RFC XXXX -* Name: vdp +##### Verifiable Data Structure Proofs + +* Name: vdp (requested assignment 396) * Label: TBD_2 -* Value type: int +* Value type: map * Value registry: https://www.iana.org/assignments/cose/cose.xhtml#header-parameters * Description: Location for verifiable data structure proofs in COSE Header Parameters. +* Reference: RFC XXXX ### COSE Verifiable Data Structures {#verifiable-data-structure-registry} @@ -551,7 +627,7 @@ Expert reviewers should take into consideration the following points: Reviewers are encouraged to get sufficient information for registration requests to ensure that the usage is not going to duplicate one that is already registered, and that the point is likely to be used in deployments. * Specifications are required for all point assignments. -Early assignment before a specification is available is considered to be permissible, however, such registrations MUST be marked provisional by prefixing the entry with "PROVISIONAL: ". +Early Allocation is permissible, see Section 2 of {{RFC7120}}. Provisional assignments to expired drafts MUST be removed from the registry. * Points assigned in this registry MUST have references that match the COSE Verifiable Data Structure Parameters registry. @@ -584,7 +660,7 @@ Expert reviewers should take into consideration the following points: Reviewers are encouraged to get sufficient information for registration requests to ensure that the usage is not going to duplicate one that is already registered, and that the point is likely to be used in deployments. * Specifications are required for all point assignments. -Early assignment before a specification is available is considered to be permissible, however, such registrations MUST be marked provisional by prefixing the entry with "PROVISIONAL: ". +Early Allocation is permissible, see Section 2 of {{RFC7120}}. Provisional assignments to expired drafts MUST be removed from the registry. * Points assigned in this registry MUST have references that match the COSE Verifiable Data Structures registry.