From 5078ad1039a0917ef7ea9edd86c25ee61c780fa2 Mon Sep 17 00:00:00 2001 From: Orie Steele Date: Fri, 16 Aug 2024 18:04:54 -0500 Subject: [PATCH 1/6] Misc cleanup --- draft-ietf-cose-hash-envelope.md | 102 ++++++++++++++++++++++++------- 1 file changed, 79 insertions(+), 23 deletions(-) diff --git a/draft-ietf-cose-hash-envelope.md b/draft-ietf-cose-hash-envelope.md index ed26fb3..d424e32 100644 --- a/draft-ietf-cose-hash-envelope.md +++ b/draft-ietf-cose-hash-envelope.md @@ -40,6 +40,7 @@ normative: RFC9052: RFC9052 informative: + BCP205: --- abstract @@ -57,6 +58,16 @@ Storing a hash of the content allows for small signature envelopes, that are eas Additional hints in the protected header ensure cryptographic agility for the hashing & signing algorithms, and discoverability for the original content which could be prohibitively large to move over a network. +When producing COSE_sign1 with remote signing services, such as a signing api exposed over HTTPS and backed by an HSM, the "ToBeSigned" bytes as described in Section 4.4 of RFC 9052 need to be transmitted to the HSM in order to be signed. + +Some signature algorithms such as ES256 or ES384 allow the "ToBeSigned" to be hashed on the client and sent to the server along with metadata in order to produce a signature. + +Other signature algorithms such as EdDSA with Ed25519, or ML-DSA do not expose such a capability. + +By producing the "ToBeSigned" on the client, and ensuring that the payload is always a hashed value, the total size of the message to be sent to the servce for signing is constrained. + +It is still possible for the protected header to be large, but the payload will always be of a fixed size, associated with the hash function chosen. + ## Attached Payload COSE_sign1 envelope with an attached payload, providing for signature validation. @@ -107,13 +118,13 @@ A hashed payload functions equivalently to an attached payload, with the benefit To represent a hash of a payload, the following headers are defined: TBD_1: - : the hash algorithm used to generate the hash of the payload + : the hash algorithm used to produce the payload. TBD_2: - : the content type of the payload the hash represents + : the content type of the bytes that were hashed to produce the payload. TBD_3: - : an identifier enabling a verifier to retrieve the full payload preimage. + : an identifier enabling a verifier to retrieve the bytes which were hashed to produce the payload. ## Signed Hash Envelopes Example @@ -158,13 +169,15 @@ Hash_Envelope_as_COSE_Sign1 = [ Hash_Envelope = #6.18(Hash_Envelope_as_COSE_Sign1) ~~~ -## Protected Header - -Label `16` (typ), label `TBD_1` (payload hash alg) and label `TBD_2` (content type of the preimage of the payload) MUST be present in the protected header and MUST NOT be present in the unprotected header. +## Headers +Label `16` (typ) MAY be used to assign a content format or media type to the entire hash envelope. +Label `TBD_1` (payload hash alg) MUST be present in the protected header and MUST NOT be present in the unprotected header. +Label `TBD_2` (content type of the preimage of the payload) MAY be present in the protected header or unprotected header. Label `TBD_3` (payload_location) MAY be added to the protected header and MUST NOT be presented in the unprotected header. - -Label `3` (content_type) MUST NOT be used as it is easily confused with label `TBD_2` payload_preimage_content_type). +Label `3` (content_type) MUST NOT be present in the protected or unprotected headers. +Label `3` is easily confused with label `TBD_2` payload_preimage_content_type. +The difference between content_type (3) and payload_preimage_content_type (TBD2) is that content_type is used to identify the content format associated with payload, whereas payload_preimage_content_type is used to identify the content format of the bytes which are hashed to produce the payload. For example: @@ -172,16 +185,22 @@ For example: { / alg : ES384 / 1: -35, / kid / 4: h'75726e3a...32636573', - / typ / 16: application/hashed+cose - / payload_hash_alg sha-256 / TBD_1: 1 - / payload_preimage_content_type / TBD_2: application/jwk+json - / payload_location / TBD_3 : storage.example/244f...9c19 + / typ / 16: "application/example+cose" + / payload_hash_alg sha-256 / TBD_1: -16 + / payload_preimage_content_type / TBD_2: "application/example+json" + / payload_location / TBD_3 : "https://storage.example/244f" + ... "9c19" } ~~~~ +In this example, the sha256 hash algorithm (-16) is used to hash the payload, which is of content type "application/example+json". +The full payload is located at "https://storage.example/244f...9c19". +The entire cose sign1 is of type "application/example+cose". +The sha256 hash is signed with ES384 which starts by taking the sha384 hash of the payload (which is a sha256 hash). + # Encrypted Hashes -The cose headers defined in this document SHOULD NOT be used in unprotected or protected headers associated with COSE_Encrypt. +When present in COSE_Encrypt, the header parameters registered in this document leak information about the ciphertext. +These parameters SHOULD NOT be present in COSE_Encrypt headers unless this disclosure is acceptable. # Security Considerations @@ -200,28 +219,65 @@ For example, when signing with ECDSA using P-256 and SHA-256, use SHA-256 to has ## COSE Header Algorithm Parameters -- Name: payload hash algorithm +### Payload Hash Algorithm + +- Name: payload_hash_alg - Label: TBD_1 - Value type: int -- Value registry: https://www.iana.org/assignments/named-information/named-information.xhtml +- Value registry: https://www.iana.org/assignments/cose/cose.xhtml#algorithms - Description: Hash algorithm used to produce the payload. -## Named Information Hash Algorithm Registry -- Name: SHAKE256 +### Payload Pre-image Content Type + +- Name: payload_preimage_content_type - Label: TBD_2 - Value type: int -- Value registry: https://www.iana.org/assignments/named-information/named-information.xhtml -- Description: SHAKE256 a described in https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf +- Value registry: https://www.iana.org/assignments/core-parameters/core-parameters.xhtml#content-formats +- Description: The content format associated with the bytes that were hashed to produce the payload. -- Name: ASCON128 +### Payload Location + +- Name: payload_location - Label: TBD_3 -- Value type: int -- Value registry: https://www.iana.org/assignments/named-information/named-information.xhtml -- Description: ASCON128 a described in https://csrc.nist.gov/CSRC/media/Projects/lightweight-cryptography/documents/round-2/spec-doc-rnd2/ascon-spec-round2.pdf +- Value type: tstr +- Value registry: none +- Description: A string or URI as a hint for the location of the payload --- back +# Implementation Status + +Note to RFC Editor: Please remove this section as well as references to {{BCP205}} before AUTH48. + +This section records the status of known implementations of the protocol defined by this specification at the time of posting of this Internet-Draft, and is based on a proposal described in {{BCP205}}. +The description of implementations in this section is intended to assist the IETF in its decision processes in progressing drafts to RFCs. +Please note that the listing of any individual implementation here does not imply endorsement by the IETF. +Furthermore, no effort has been spent to verify the information presented here that was supplied by IETF contributors. +This is not intended as, and must not be construed to be, a catalog of available implementations or their features. +Readers are advised to note that other implementations may exist. + +According to {{BCP205}}, "this will allow reviewers and working groups to assign due consideration to documents that have the benefit of running code, which may serve as evidence of valuable experimentation and feedback that have made the implemented protocols more mature. +It is up to the individual working groups to use this information as they see fit". + +## Transmute Prototype + +Organization: Transmute Industries Inc + +Name: https://github.com/transmute-industries/transmute + +Description: A command line tool and GitHub action for securing software artifacts in GitHub workflows. + +Maturity: Prototype + +Coverage: The current version ('main') implements this specification and demonstrates hash envelope signing with Azure Key Vault and Google Cloud KMS in addition to supporting local keys. + +License: Apache-2.0 + +Implementation Experience: No interop testing has been done yet. The code works as proof of concept, but is not yet production ready. + +Contact: Orie Steele (orie@transmute.industries) + # Acknowledgments {:numbered="false"} From 7fbf51149f0b96177779990179d120b9a188f076 Mon Sep 17 00:00:00 2001 From: Orie Steele Date: Fri, 16 Aug 2024 18:21:37 -0500 Subject: [PATCH 2/6] organize --- draft-ietf-cose-hash-envelope.md | 103 +++++++++++-------------------- 1 file changed, 36 insertions(+), 67 deletions(-) diff --git a/draft-ietf-cose-hash-envelope.md b/draft-ietf-cose-hash-envelope.md index d424e32..bdc560d 100644 --- a/draft-ietf-cose-hash-envelope.md +++ b/draft-ietf-cose-hash-envelope.md @@ -37,7 +37,9 @@ author: country: Germany normative: - RFC9052: RFC9052 + RFC9052: COSE + RFC8610: CDDL + I-D.draft-ietf-cbor-edn-literals: EDN informative: BCP205: @@ -52,13 +54,13 @@ Additionally, hints of the detached payload's content format and availability ar # Introduction -COSE defined detached payloads in Section 2 of {{-RFC9052}}, using `nil` as the payload. +COSE defined detached payloads in Section 2 of {{-COSE}}, using `nil` as the payload. In order to verify a signature over a detached payload, the verifier must have access to the payload content. Storing a hash of the content allows for small signature envelopes, that are easy to transport and verify independently. Additional hints in the protected header ensure cryptographic agility for the hashing & signing algorithms, and discoverability for the original content which could be prohibitively large to move over a network. -When producing COSE_sign1 with remote signing services, such as a signing api exposed over HTTPS and backed by an HSM, the "ToBeSigned" bytes as described in Section 4.4 of RFC 9052 need to be transmitted to the HSM in order to be signed. +When producing COSE_sign1 with remote signing services, such as a signing api exposed over HTTPS and backed by an HSM, the "ToBeSigned" bytes as described in {{Section 4.4 of RFC9052}} need to be transmitted to the HSM in order to be signed. Some signature algorithms such as ES256 or ES384 allow the "ToBeSigned" to be hashed on the client and sent to the server along with metadata in order to produce a signature. @@ -68,52 +70,11 @@ By producing the "ToBeSigned" on the client, and ensuring that the payload is al It is still possible for the protected header to be large, but the payload will always be of a fixed size, associated with the hash function chosen. -## Attached Payload +# Terminology -COSE_sign1 envelope with an attached payload, providing for signature validation. - -~~~~ cbor-diag -18( / COSE Sign 1 / - [ - h'a4013822...3a616263', / Protected / - {} / Unprotected / - h'317cedc7...c494e772', / Payload / - h'15280897...93ef39e5' / Signature / - ] -) -~~~~ - -## Detached Payload - -COSE_sign1 envelope with a detached payload (`nil`), which is compact but the payload must be distributed out of band to validate the signature - -~~~~ cbor-diag -18( / COSE Sign 1 / - [ - h'a4013822...3a616263', / Protected / - {} / Unprotected / - nil, / Detached Payload / - h'15280897...93ef39e5' / Signature / - ] -) -~~~~ - -## Hashed Payload - -A hashed payload functions equivalently to an attached payload, with the benefits of being compact in size and providing the ability to validate the signature. - -~~~~ cbor-diag -18( / COSE Sign 1 / - [ - h'a4013822...3a616263', / Protected / - {} / Unprotected / - h'935b5a91...e18a588a', / Payload / - h'15280897...93ef39e5' / Signature / - ] -) -~~~~ +{::boilerplate bcp14-tagged} -# Header Parameters +The terms COSE, CDDL, and EDN are defined in {{-COSE}}, {{-CDDL}}, {{-EDN}} respectively. To represent a hash of a payload, the following headers are defined: @@ -126,7 +87,8 @@ TBD_2: TBD_3: : an identifier enabling a verifier to retrieve the bytes which were hashed to produce the payload. -## Signed Hash Envelopes Example + +# Hash Envelope CDDL ~~~ cddl Hash_Envelope_Protected_Header = { @@ -152,11 +114,11 @@ Hash_Envelope_Protected_Header = { ; storage.example/244f...9c19 ? &(payload_location: TBD_3) => tstr - * int => any + * int / tstr => any } Hash_Envelope_Unprotected_Header = { - * int => any + * int / tstr => any } Hash_Envelope_as_COSE_Sign1 = [ @@ -169,8 +131,6 @@ Hash_Envelope_as_COSE_Sign1 = [ Hash_Envelope = #6.18(Hash_Envelope_as_COSE_Sign1) ~~~ -## Headers - Label `16` (typ) MAY be used to assign a content format or media type to the entire hash envelope. Label `TBD_1` (payload hash alg) MUST be present in the protected header and MUST NOT be present in the unprotected header. Label `TBD_2` (content type of the preimage of the payload) MAY be present in the protected header or unprotected header. @@ -179,22 +139,34 @@ Label `3` (content_type) MUST NOT be present in the protected or unprotected hea Label `3` is easily confused with label `TBD_2` payload_preimage_content_type. The difference between content_type (3) and payload_preimage_content_type (TBD2) is that content_type is used to identify the content format associated with payload, whereas payload_preimage_content_type is used to identify the content format of the bytes which are hashed to produce the payload. -For example: +# Envelope EDN + +A hashed payload functions equivalently to an attached payload, with the benefits of being compact in size and providing the ability to validate the signature. ~~~~ cbor-diag -{ - / alg : ES384 / 1: -35, - / kid / 4: h'75726e3a...32636573', - / typ / 16: "application/example+cose" - / payload_hash_alg sha-256 / TBD_1: -16 - / payload_preimage_content_type / TBD_2: "application/example+json" - / payload_location / TBD_3 : "https://storage.example/244f" + ... "9c19" -} +18( / COSE Sign 1 / + [ + <<{ + / alg : ES384 / 1: -35, + / kid / 4: h'75726e3a...32636573', + / typ / 16: "application/example+cose" + / payload_hash_alg / + TBD_1: -16 / sha-256 / + / payload_preimage_content_type / + TBD_2: "application/example+json" + / payload_location / + TBD_3 : "https://storage.example/244f" + ... "9c19" + }>> + {} / Unprotected / + h'935b5a91...e18a588a', / Payload / + h'15280897...93ef39e5' / Signature / + ] +) ~~~~ In this example, the sha256 hash algorithm (-16) is used to hash the payload, which is of content type "application/example+json". The full payload is located at "https://storage.example/244f...9c19". -The entire cose sign1 is of type "application/example+cose". +The COSE_sign1 is of type "application/example+cose". The sha256 hash is signed with ES384 which starts by taking the sha384 hash of the payload (which is a sha256 hash). # Encrypted Hashes @@ -213,12 +185,10 @@ For example, when signing with ECDSA using P-256 and SHA-256, use SHA-256 to has # IANA Considerations -## Requirements Notation - -{::boilerplate bcp14-tagged} - ## COSE Header Algorithm Parameters +IANA is requested to add the following entries to the [COSE Header Algorithm Parameters Registry](https://www.iana.org/assignments/cose/cose.xhtml). + ### Payload Hash Algorithm - Name: payload_hash_alg @@ -227,7 +197,6 @@ For example, when signing with ECDSA using P-256 and SHA-256, use SHA-256 to has - Value registry: https://www.iana.org/assignments/cose/cose.xhtml#algorithms - Description: Hash algorithm used to produce the payload. - ### Payload Pre-image Content Type - Name: payload_preimage_content_type From d62df6a76309a4be30407ff71cf5080a36cfa50f Mon Sep 17 00:00:00 2001 From: Orie Steele Date: Mon, 19 Aug 2024 08:35:20 -0500 Subject: [PATCH 3/6] Apply suggestions from code review Removed whitespace Co-authored-by: Steve Lasker --- draft-ietf-cose-hash-envelope.md | 1 - 1 file changed, 1 deletion(-) diff --git a/draft-ietf-cose-hash-envelope.md b/draft-ietf-cose-hash-envelope.md index bdc560d..fcea2a0 100644 --- a/draft-ietf-cose-hash-envelope.md +++ b/draft-ietf-cose-hash-envelope.md @@ -87,7 +87,6 @@ TBD_2: TBD_3: : an identifier enabling a verifier to retrieve the bytes which were hashed to produce the payload. - # Hash Envelope CDDL ~~~ cddl From dc35d9c2b049a66fed92b906afff5c76f054520e Mon Sep 17 00:00:00 2001 From: Steve Lasker Date: Wed, 21 Aug 2024 10:34:09 -0700 Subject: [PATCH 4/6] Update draft-ietf-cose-hash-envelope.md --- draft-ietf-cose-hash-envelope.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft-ietf-cose-hash-envelope.md b/draft-ietf-cose-hash-envelope.md index fcea2a0..e586e9d 100644 --- a/draft-ietf-cose-hash-envelope.md +++ b/draft-ietf-cose-hash-envelope.md @@ -154,7 +154,7 @@ A hashed payload functions equivalently to an attached payload, with the benefit / payload_preimage_content_type / TBD_2: "application/example+json" / payload_location / - TBD_3 : "https://storage.example/244f" + ... "9c19" + TBD_3 : "https://storage.example/a24f9c19" }>> {} / Unprotected / h'935b5a91...e18a588a', / Payload / From 79051732f5eb5af7aedd7879aaa39a0b9ade7fb4 Mon Sep 17 00:00:00 2001 From: Orie Steele Date: Wed, 21 Aug 2024 16:50:25 -0500 Subject: [PATCH 5/6] Apply suggestions from code review Co-authored-by: Steve Lasker --- draft-ietf-cose-hash-envelope.md | 50 ++++++++++++++++++++++++++++---- 1 file changed, 44 insertions(+), 6 deletions(-) diff --git a/draft-ietf-cose-hash-envelope.md b/draft-ietf-cose-hash-envelope.md index e586e9d..813bd98 100644 --- a/draft-ietf-cose-hash-envelope.md +++ b/draft-ietf-cose-hash-envelope.md @@ -76,6 +76,8 @@ It is still possible for the protected header to be large, but the payload will The terms COSE, CDDL, and EDN are defined in {{-COSE}}, {{-CDDL}}, {{-EDN}} respectively. +# Header Parameters + To represent a hash of a payload, the following headers are defined: TBD_1: @@ -130,13 +132,14 @@ Hash_Envelope_as_COSE_Sign1 = [ Hash_Envelope = #6.18(Hash_Envelope_as_COSE_Sign1) ~~~ -Label `16` (typ) MAY be used to assign a content format or media type to the entire hash envelope. -Label `TBD_1` (payload hash alg) MUST be present in the protected header and MUST NOT be present in the unprotected header. -Label `TBD_2` (content type of the preimage of the payload) MAY be present in the protected header or unprotected header. -Label `TBD_3` (payload_location) MAY be added to the protected header and MUST NOT be presented in the unprotected header. -Label `3` (content_type) MUST NOT be present in the protected or unprotected headers. +- Label `16` (typ) MAY be used to assign a content format or media type to the entire hash envelope. +- Label `TBD_1` (payload hash alg) MUST be present in the protected header and MUST NOT be present in the unprotected header. +- Label `TBD_2` (content type of the preimage of the payload) MAY be present in the protected header or unprotected header. +- Label `TBD_3` (payload_location) MAY be added to the protected header and MUST NOT be presented in the unprotected header. +- Label `3` (content_type) MUST NOT be present in the protected or unprotected headers. + Label `3` is easily confused with label `TBD_2` payload_preimage_content_type. -The difference between content_type (3) and payload_preimage_content_type (TBD2) is that content_type is used to identify the content format associated with payload, whereas payload_preimage_content_type is used to identify the content format of the bytes which are hashed to produce the payload. +The difference between content_type (3) and payload_preimage_content_type (TBD2) is content_type is used to identify the content format associated with payload, whereas payload_preimage_content_type is used to identify the content format of the bytes which are hashed to produce the payload. # Envelope EDN @@ -246,6 +249,41 @@ Implementation Experience: No interop testing has been done yet. The code works Contact: Orie Steele (orie@transmute.industries) +## DataTrails Preview + +Organization: DataTrails + +Name: https://github.com/datatrails/scitt-action + +Description: A GitHub Action for registering statements about artifacts on a transparency service. + +Maturity: Preview + +Coverage: The current version ('main') implements this specification and demonstrates hash envelope signing with DataTrails implementation of SCITT. + +License: MIT + +Implementation Experience: Interop testing has been performed between DigiCert and DataTrails. The code works as proof of concept, but is not yet production ready. + +Contact: Steve Lasker (steve.lasker@datatrails.ai) + +## DigiCert Preview + +Organization: DigiCert + +Name: https://github.com/digicert/scitt-action + +Description: A GitHub Action for remote signing and registering statements about artifacts on a transparency service. + +Maturity: Preview + +Coverage: The current version ('main') implements this specification and demonstrates hash envelope signing with DigiCert Software Trust Manager. + +License: MIT + +Implementation Experience: Interop testing has been performed between DigiCert and DataTrails. The code works as proof of concept, but is not yet production ready. + +Contact: Corey Bonnell (Corey.Bonnell@digicert.com>) # Acknowledgments {:numbered="false"} From 5b182b3fdcc573d04c6c4d7ae7dd761000107137 Mon Sep 17 00:00:00 2001 From: Steve Lasker Date: Wed, 21 Aug 2024 15:36:17 -0700 Subject: [PATCH 6/6] Update draft-ietf-cose-hash-envelope.md --- draft-ietf-cose-hash-envelope.md | 1 + 1 file changed, 1 insertion(+) diff --git a/draft-ietf-cose-hash-envelope.md b/draft-ietf-cose-hash-envelope.md index 813bd98..d1cfcfd 100644 --- a/draft-ietf-cose-hash-envelope.md +++ b/draft-ietf-cose-hash-envelope.md @@ -284,6 +284,7 @@ License: MIT Implementation Experience: Interop testing has been performed between DigiCert and DataTrails. The code works as proof of concept, but is not yet production ready. Contact: Corey Bonnell (Corey.Bonnell@digicert.com>) + # Acknowledgments {:numbered="false"}