]>

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.

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 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. > / 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 Informative References IANA IANA

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