RFC 9995: CBOR Object Signing and Encryption (COSE) Hash Envelope

Status of This Memo

This is an Internet Standards Track document.¶

This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841.¶

Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at https://www.rfc-editor.org/info/rfc9995.¶

Copyright Notice

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

1. Introduction

Section 2 of [RFC9052] defines detached payloads for COSE, using nil as the payload. In order to verify a COSE_Sign or a COSE_Mac, the recipient 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 of original payload content reduces 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" and "CDDL" are defined in [RFC9052] and [RFC8610], respectively. The term "payload" is defined in Section 4.1 of [RFC9052] for COSE_Sign and in Section 6.1 of [RFC9052] for COSE_Mac. The term "preimage" refers to the set of input values to a function that produce a given output, called the "image". A hash function applied to a message (preimage) produces a digest value (image).¶

3. Header Parameters

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

The hash algorithm used to produce the payload.¶

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

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

4. Hash Envelope CDDL

<CODE BEGINS>
Hash_Envelope = #6.18(Hash_Envelope_as_COSE_Sign1)

Hash_Envelope_as_COSE_Sign1 = [
 protected: bstr .cbor Hash_Envelope_Protected_Header,
 unprotected: Hash_Envelope_Unprotected_Header,
 payload: bstr / nil,
 signature: bstr
]

Hash_Envelope_Protected_Header = {
 ? &(alg: 1) => int,
 &(payload_hash_alg: 258) => int,
 ? &(payload_preimage_content_type: 259) => uint / tstr,
 ? &(payload_location: 260) => tstr,
 * (int / tstr) => any
}

Hash_Envelope_Unprotected_Header = {
 * (int / tstr) => any
}

<CODE ENDS>

• Label 1 (alg) is the cryptographic algorithm to use.¶

• Label 258 (payload_hash_alg) MUST be present in the protected header and MUST NOT be present in the unprotected header.¶

• Label 259 (payload_preimage_content_type) MAY be present in the protected header and MUST NOT be present in the unprotected header.¶

• Label 260 (payload_location) MAY be present in the protected header and MUST NOT be present in the unprotected header.¶

• Label 3 (content_type) MUST NOT be present in the protected or unprotected headers.¶

Label 3 (content_type) is easily confused with Label 259 (payload_preimage_content_type). The difference between content_type (3) and payload_preimage_content_type (259) 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 that are hashed to produce the payload.¶

Output from hash algorithms is generally small; thus, the payload is typically expected to be inline. But it can also be detached, as in any other COSE message [RFC9052].¶

For example, when the actual content is a byte string (bstr), a verifier appraising the payload has to decide whether that bstr represents the digest bytes or the preimage bytes. Setting payload_preimage_content_type to bstr makes clear that the preimage bytes themselves were a bstr.¶

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

5. Security Considerations

6. IANA Considerations

7. References

Acknowledgments

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

Authors' Addresses