| Internet-Draft | -COSE Hash Envelope | -July 2024 | -
| Steele, et al. | -Expires 9 January 2025 | -[Page] | -
This document defines new COSE header parameters for signaling a payload as an output of a hash function. -This mechanism enables faster validation as access to the original payload is not required for signature validation. -Additionally, hints of the detached payload's content format and availability are defined providing references to optional discovery mechanisms that can help to find original payload content.¶
-This note is to be removed before publishing as an RFC.¶
-- The latest revision of this draft can be found at https://OR13.github.io/draft-steele-cose-hash-envelope/draft-steele-cose-hash-envelope.html. - Status information for this document may be found at https://datatracker.ietf.org/doc/draft-steele-cose-hash-envelope/.¶
-- Discussion of this document takes place on the - CBOR Object Signing and Encryption Working Group mailing list (mailto:cose@ietf.org), - which is archived at https://mailarchive.ietf.org/arch/browse/cose/. - Subscribe at https://www.ietf.org/mailman/listinfo/cose/.¶
-Source for this draft and an issue tracker can be found at - https://github.com/OR13/draft-steele-cose-hash-envelope.¶
-- This Internet-Draft is submitted in full conformance with the - provisions of BCP 78 and BCP 79.¶
-- Internet-Drafts are working documents of the Internet Engineering Task - Force (IETF). Note that other groups may also distribute working - documents as Internet-Drafts. The list of current Internet-Drafts is - at https://datatracker.ietf.org/drafts/current/.¶
-- Internet-Drafts are draft documents valid for a maximum of six months - and may be updated, replaced, or obsoleted by other documents at any - time. It is inappropriate to use Internet-Drafts as reference - material or to cite them other than as "work in progress."¶
-- This Internet-Draft will expire on 9 January 2025.¶
-- Copyright (c) 2024 IETF Trust and the persons identified as the - document authors. All rights reserved.¶
-- This document is subject to BCP 78 and the IETF Trust's Legal - Provisions Relating to IETF Documents - (https://trustee.ietf.org/license-info) in effect on the date of - publication of this document. Please review these documents - carefully, as they describe your rights and restrictions with - respect to this document. Code Components extracted from this - document must include Revised BSD License text as described in - Section 4.e of the Trust Legal Provisions and are provided without - warranty as described in the Revised BSD License.¶
-COSE defined detached payloads in Section 2 of [RFC9052], 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.¶
-COSE_sign1 envelope with an attached payload, providing for signature validation.¶
-
-18( / COSE Sign 1 /
- [
- h'a4013822...3a616263', / Protected /
- {} / Unprotected /
- h'317cedc7...c494e772', / Payload /
- h'15280897...93ef39e5' / Signature /
- ]
-)
-¶
-COSE_sign1 envelope with a detached payload (nil), which is compact but the payload must be distributed out of band to validate the signature¶
-18( / COSE Sign 1 /
- [
- h'a4013822...3a616263', / Protected /
- {} / Unprotected /
- nil, / Detached Payload /
- h'15280897...93ef39e5' / Signature /
- ]
-)
-¶
-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.¶
-
-18( / COSE Sign 1 /
- [
- h'a4013822...3a616263', / Protected /
- {} / Unprotected /
- h'935b5a91...e18a588a', / Payload /
- h'15280897...93ef39e5' / Signature /
- ]
-)
-¶
-To represent a hash of a payload, the following headers are defined:¶
-the hash algorithm used to generate the hash of the payload¶
-the content type of the payload the hash represents¶
-an identifier enabling a verifier to retrieve the full payload preimage.¶
-
-Hash_Envelope_Protected_Header = {
- ; Cryptographic algorithm to use
- ? &(alg: 1) => int,
-
- ; Type of the envelope
- ? &(typ: 16) => int / tstr
-
- ; Hash algorithm used to produce the payload from content
- ; -16 for SHA-256,
- ; See https://www.iana.org/assignments/cose/cose.xhtml
- &(payload_hash_alg: TBD_1) => int
-
- ; Content type of the preimage
- ; (content to be hashed) of the payload
- ; 50 for application/json,
- ; See https://datatracker.ietf.org/doc/html/rfc7252#section-12.3
- &(payload_preimage_content_type: TBD_2) => int
-
- ; Location the content of the hashed payload is stored
- ; For example:
- ; storage.example/244f...9c19
- ? &(payload_location: TBD_3) => tstr
-
- * int => any
-}
-
-Hash_Envelope_Unprotected_Header = {
- * int => any
-}
-
-Hash_Envelope_as_COSE_Sign1 = [
- protected : bstr .cbor Hash_Envelope_Protected_Header,
- unprotected : Hash_Envelope_Unprotected_Header,
- payload: bstr / nil,
- signature : bstr
-]
-
-Hash_Envelope = #6.18(Hash_Envelope_as_COSE_Sign1)
-¶
-16 (typ), TBD_1 (payload hash alg) and 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. -TBD_3 (payload_location) MAY be added to the protected header and MUST NOT be presented in the unprotected header.¶
-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
-}
-¶
-Should we define this?¶
-TODO Security¶
-It is RECOMMENDED to align the strength of the chosen hash function to the strength of the chosen signature algorithm. -For example, when signing with ECDSA using P-256 and SHA-256, use SHA-256 to hash the payload.¶
-The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", -"MAY", and "OPTIONAL" in this document are to be interpreted as -described in BCP 14 [RFC2119] [RFC8174] when, and only when, they -appear in all capitals, as shown here.¶
-Name: SHAKE256¶
-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¶
-Name: ASCON128¶
-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¶
-The following individuals provided input into the final form of the document: Carsten Bormann, Henk Birkholz, Antoine Delignat-Lavaud, Cedric Fournet.¶
-