COSE Hash Envelope

Status of This Memo

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 4 September 2025.¶

Copyright Notice

Copyright (c) 2025 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.¶

Table of Contents

1. Introduction

COSE defined detached payloads in Section 2 of [RFC9052], using nil as the payload. In order to verify a signature over a cose-sign1, the signature checker requires access to the payload content. Hashes are already used on a regular basis as identifiers for payload data, such as documents or software components. As hashes typically are smaller than the payload data they represent, they are simpler to transport. Additional hints in the protected header ensure cryptographic agility for the hashing and signing algorithms. Hashes and other identifiers are commonly used as hints to discover and distinguish resources. Using a hash as an identifier for a resource has the advantage of enabling integrity checking. In some applications, such as remote signing procedures, conveyance of hashes instead original payload content reduce transmission time and costs.¶

2. Terminology

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.¶

The terms COSE, CDDL, and EDN are defined in [RFC9052], [RFC8610], [I-D.draft-ietf-cbor-edn-literals] respectively.¶

3. Header Parameters

This document specifies the following new header parameters commonly used alongside hashes to identify resources:¶

TBD_1:

the hash algorithm used to produce the payload.¶

TBD_2:

the content type of the bytes that were hashed (preimage) to produce the payload, given as a content-format number (Section 12.3 of [RFC7252]) or as a media-type name optionally with parameters (Section 8.3 of [RFC9110]).¶

TBD_3:

an identifier enabling retrieval of the original resource (preimage) identified by the payload.¶

4. Hash Envelope CDDL

Hash_Envelope_Protected_Header = {
    ? &(alg: 1) => int,
    &(payload_hash_alg: TBD_1) => int
    &(payload_preimage_content_type: TBD_2) => uint / tstr
    ? &(payload_location: TBD_3) => tstr
    * int / tstr => any
}

Hash_Envelope_Unprotected_Header = {
    * int / tstr => 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)

• Label 1 (alg) Cryptographic algorithm to use¶

• 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 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.¶

Profiles that rely on this specification MAY choose to mark TBD_1, TBD_2, TBD_3 (or other header parameters) critical, see Appendix C.1.3 of [RFC9052] for more details.¶

5. Envelope EDN

The following informative example demonstrates how to construct a hash envelope for a resource already commonly referenced by its hash.¶

18([ # cose-sign1
  <<{
    / signature alg   / 1: -35, # ES384
    / key identifier  / 4: h'75726e3a...32636573',
    / cose sign1 type / 16: "application/example+cose",
    / hash algorithm  / TBD_1: -16, # sha256
    / media type      / TBD_2: "application/spdx+json",
    / location        /
         TBD_3: "https://sbom.example/.../manifest.spdx.json"
  }>>
  / unprotected / {},
  / payload     / h'935b5a91...e18a588a',
         # As seen in manifest.spdx.json.sha256
  / signature   / h'15280897...93ef39e5'
         # ECDSA Signature with SHA 384 and P-384
])

In this example, an SPDX software bill of materials (SBOM) in JSON format is already commonly identified by its SHA256 hash. For example, some tooling generates a file, such as manifest.spdx.json.sha256, which contains the SHA256 hash of the corresponding manifest.spdx.json file.¶

The content type for manifest.spdx.json is already well known as application/spdx+json, and is registered with IANA.¶

The full JSON SBOM is available at a URL, such as https://sbom.example/.../manifest.spdx.json.¶

The payload of this COSE_Sign1 is the SHA256 hash of the manifest.spdx.json, which is typically found in an adjacent file (manifest.spdx.json.sha256).¶

The type of this COSE_Sign1 is application/example+cose, but other types may be used to establish more specific media types for signatures of hashes.¶

The signature is produced using ES384 which means using ECDSA with SHA384 hash function and P-384 elliptic curve.¶

This example is chosen to highlight that an existing system may use a hash algorithm such as sha256. This hash becomes the payload of a COSE-Sign1. When signed with a signature algorithm that is parameterized via a hash function, such as ECDSA with SHA384, the to be signed structure as described in Section 4.4 of RFC9052.¶

The resulting signature is computed over the protected header and payload, providing integrity and authenticity for the hash algorithm, content type and location of the associated resource, in this case a software bill of materials.¶

6. Security Considerations

7. IANA Considerations

8. References

Appendix A. 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".¶

Acknowledgments

The following individuals provided input into the final form of the document: Carsten Bormann, Henk Birkholz, Antoine Delignat-Lavaud, Cedric Fournet.¶

Authors' Addresses