orie@or13.io

stevenlasker@hotmail.com

Fraunhofer SIT

Rheinstrasse 75 Darmstadt 64295 Germany henk.birkholz@ietf.contact

sec cose This document defines new CBOR Object Signing and Encryption (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 hashed payload's content format and availability are defined, providing references to optional discovery mechanisms that can help to find the original payload content.

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 .

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 () 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

• .  Introduction
• .  Terminology
• .  Header Parameters
• .  Hash Envelope CDDL
  • .  Envelope Extended Diagnostic Notation
• .  Security Considerations
  • .  Choice of Hash Function
  • .  COSE_Encrypt
  • .  Payload Verification
• .  IANA Considerations
  • .  COSE Header Parameters
• .  References
  • .  Normative References
  • .  Informative References
• Acknowledgments
• Authors' Addresses

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

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 when, and only when, they appear in all capitals, as shown here. The terms "COSE" and "CDDL" are defined in and , respectively. The term "payload" is defined in for COSE_Sign and in 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).

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

258:

The hash algorithm used to produce the payload.

259:

The content type of the bytes that were hashed (preimage) to produce the payload, given as a content-format number () or as a media-type name optionally with parameters ().

260:

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

Hash Envelope CDDL 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 }

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

Envelope Extended Diagnostic Notation The following informative example uses Extended Diagnostic Notation as defined in Appendix G of and 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 / 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 ]) In this example, a System Package Data Exchange Software Bill of Materials (SBOM) in JSON format is already commonly identified by its SHA-256 hash. 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 SHA-256 hash of "manifest.spdx.json". 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, as defined in , which means using the Elliptic Curve Digital Signature Algorithm (ECDSA) with the SHA-384 hash function and P-384 elliptic curve. This example is chosen to highlight that an existing system may use a hash algorithm such as SHA-256. 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 SHA-384, the to-be-signed structure is as described in . 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.

Security Considerations

Choice of Hash Function The hash/signature algorithm combination is RECOMMENDED to be at least as strong as the payload hash algorithm. For example, if the payload was produced with SHA-256, and is signed with ECDSA, use at least P-256 and SHA-256. Note that, when using a pre-hash algorithm, the algorithm MUST be registered in the IANA "COSE Algorithms" registry and MUST be distinguishable from non-pre-hash variants that may also be present.

COSE_Encrypt Only COSE_Sign/COSE_Sign1 and COSE_Mac/COSE_Mac0 are in scope for this document. COSE_Encrypt/COSE_Encrypt0 is out of scope for this document. At the time of publication, there is no known use case for COSE_Encrypt/COSE_Encrypt0. It may be covered by a future extension, which would address whether the hash function is applied before or after encryption and clarify privacy considerations.

Payload Verification If a payload-location is specified, a verifier can choose to fetch the content and confirm that the digest of it, produced with the function defined by payload-hash-alg, matches the payload bytes. Verifiers that do not have access to the internet and obtain the preimage via other means will not be able to perform that check nor to derive utility from it.

IANA Considerations

COSE Header Parameters IANA has registered the COSE header parameters defined in (as listed in ) in the "COSE Header Parameters" registry . They have been registered in the 'Integer values from 256 to 65535' range per the 'Specification Required' registration policy . Newly Registered COSE Header Parameters

Name	Label	Value Type	Value Registry	Description	Reference
payload-hash-alg	258	int		The hash algorithm used to produce the payload of a COSE_Sign1	RFC 9995,
preimage-content-type	259	uint / tstr		The content-format number or content-type (media-type name) of data that has been hashed to produce the payload of the COSE_Sign1	RFC 9995,
payload-location	260	tstr	(none)	The string or URI hint for the location of the data hashed to produce the payload of a COSE_Sign1	RFC 9995,

References Normative References IANA In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. The Constrained Application Protocol (CoAP) is a specialized web transfer protocol for use with constrained nodes and constrained (e.g., low-power, lossy) networks. The nodes often have 8-bit microcontrollers with small amounts of ROM and RAM, while constrained networks such as IPv6 over Low-Power Wireless Personal Area Networks (6LoWPANs) often have high packet error rates and a typical throughput of 10s of kbit/s. The protocol is designed for machine- to-machine (M2M) applications such as smart energy and building automation. CoAP provides a request/response interaction model between application endpoints, supports built-in discovery of services and resources, and includes key concepts of the Web such as URIs and Internet media types. CoAP is designed to easily interface with HTTP for integration with the Web while meeting specialized requirements such as multicast support, very low overhead, and simplicity for constrained environments. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. This document proposes a notational convention to express Concise Binary Object Representation (CBOR) data structures (RFC 7049). Its main goal is to provide an easy and unambiguous way to express structures for protocol messages and data formats that use CBOR or JSON. Concise Binary Object Representation (CBOR) is a data format designed for small code size and small message size. There is a need to be able to define basic security services for this data format. This document defines the CBOR Object Signing and Encryption (COSE) protocol. This specification describes how to create and process signatures, message authentication codes, and encryption using CBOR for serialization. This specification additionally describes how to represent cryptographic keys using CBOR. This document, along with RFC 9053, obsoletes RFC 8152. The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document describes the overall architecture of HTTP, establishes common terminology, and defines aspects of the protocol that are shared by all versions. In this definition are core protocol elements, extensibility mechanisms, and the "http" and "https" Uniform Resource Identifier (URI) schemes. This document updates RFC 3864 and obsoletes RFCs 2818, 7231, 7232, 7233, 7235, 7538, 7615, 7694, and portions of 7230. Informative References IANA IANA This specification registers cryptographic algorithms and identifiers to be used with the JSON Web Signature (JWS), JSON Web Encryption (JWE), and JSON Web Key (JWK) specifications. It defines several IANA registries for these identifiers. Many protocols make use of points of extensibility that use constants to identify various protocol parameters. To ensure that the values in these fields do not have conflicting uses and to promote interoperability, their allocations are often coordinated by a central record keeper. For IETF protocols, that role is filled by the Internet Assigned Numbers Authority (IANA). To make assignments in a given registry prudently, guidance describing the conditions under which new values should be assigned, as well as when and how modifications to existing values can be made, is needed. This document defines a framework for the documentation of these guidelines by specification authors, in order to assure that the provided guidance for the IANA Considerations is clear and addresses the various issues that are likely in the operation of a registry. This is the third edition of this document; it obsoletes RFC 5226.

Acknowledgments The following individuals provided input into the final form of the document: , , and .

Authors' Addresses

orie@or13.io

stevenlasker@hotmail.com

Fraunhofer SIT

Rheinstrasse 75 Darmstadt 64295 Germany henk.birkholz@ietf.contact