]> Transmute

orie@transmute.industries

DataTrails

steve.lasker@datatrails.ai

Fraunhofer SIT

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

Security Internet-Draft 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. About This Document The latest revision of this draft can be found at . Status information for this document may be found at . Discussion of this document takes place on the CBOR Object Signing and Encryption Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction COSE defined detached payloads in Section 2 of , 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.

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, CDDL, and EDN are defined in , , respectively.

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 } 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 258 (payload hash alg) MUST be present in the protected header and MUST NOT be present in the unprotected header.
• Label 259 (content type of the preimage of the payload) 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 is easily confused with label 259 payload_preimage_content_type. The difference between content_type (3) and payload_preimage_content_type (259) 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 258, 259, 260 (or other header parameters) critical, see for more details.

Envelope EDN The following informative example demonstrates how to construct a hash envelope for a resource already commonly referenced by its hash. > / 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.

Security Considerations

Choice of Hash Function 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. Note that when using a pre-hash algorithm, the algorithm SHOULD be registered in the IANA COSE Algorithms registry, and should be distinguishable from non-pre hash variants that may also be present. The approach this specification takes is just one way to perform application agnostic pre-hashing, meaning the pre hashing is not done with binding or consideration for a specific application context, while preforming application (cose) specific signing, meaning the to be signed bytes include the cose structures necessary to distinguish a cose signature from other digital signature formats.

Encrypted Hashes When present in COSE_Encrypt, the header parameters registered in this document leak information about the ciphertext. These parameters SHOULD NOT be present in COSE_Encrypt headers unless this disclosure is acceptable. When present in a protected header, the semantics are the same as for a COSE_Sign1: decrypted payload is expected to be the output of the hash function specified in the protected header.

IANA Considerations

COSE Header Parameters IANA is requested to add the COSE header parameters defined in , as listed in , to the "COSE Header Parameters" registry , in the 'Integer values from 256 to 65535' range ('Specification Required' Registration Procedure). Newly registered COSE Header Parameters 
(1): Value Registry 
(2): https://www.iana.org/assignments/cose/cose.xhtml#algorithms 
(3): https://www.iana.org/assignments/core-parameters/core-parameters.xhtml#content-formats

Name	Label	Value Type	(1)	Description	Reference
payload-hash-alg	258	int	(2)	The hash algorithm used to produce the payload of a COSE_Sign1	RFCthis,
preimage-content-type	259	uint / tstr	(3)	The content-format number or content-type (media-type name) of data that has been hashed to produce the payload of the COSE_Sign1	RFCthis,
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	RFCthis,

References Normative References 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. 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. 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. 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. IANA Informative References Universität Bremen TZI This document formalizes and consolidates the definition of the Extended Diagnostic Notation (EDN) of the Concise Binary Object Representation (CBOR), addressing implementer experience. Replacing EDN's previous informal descriptions, it updates RFC 8949, obsoleting its Section 8, and RFC 8610, obsoleting its Appendix G. It also specifies and uses registry-based extension points, using one to support text representations of epoch-based dates/times and of IP addresses and prefixes. // (This cref will be removed by the RFC editor:) The present // revision (–16) addresses the first half of the WGLC comments, // except for the issues around the specific way how to best achieve // pluggable ABNF grammars for application-extensions. It is // intended for use as a reference document for the mid-WGLC CBOR WG // interim meeting on 2025-01-08. This document describes a simple process that allows authors of Internet-Drafts to record the status of known implementations by including an Implementation Status section. 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. This process is not mandatory. Authors of Internet-Drafts are encouraged to consider using the process for their documents, and working groups are invited to think about applying the process to all of their protocol specifications. This document obsoletes RFC 6982, advancing it to a Best Current Practice.

Implementation Status Note to RFC Editor: Please remove this section as well as references to 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 . 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 , "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".

Transmute Prototype Organization: Transmute Industries Inc Name: https://github.com/transmute-industries/transmute Description: A command line tool and GitHub action for securing software artifacts in GitHub workflows. Maturity: Prototype Coverage: The current version ('main') implements this specification and demonstrates hash envelope signing with Azure Key Vault and Google Cloud KMS in addition to supporting local keys. License: Apache-2.0 Implementation Experience: No interop testing has been done yet. The code works as proof of concept, but is not yet production ready. Contact: Orie Steele (orie@transmute.industries)

DataTrails Preview Organization: DataTrails Name: https://github.com/datatrails/scitt-action Description: A GitHub Action for registering statements about artifacts on a transparency service. Maturity: Preview Coverage: The current version ('main') implements this specification and demonstrates hash envelope signing with DataTrails implementation of SCITT. License: MIT Implementation Experience: Interop testing has been performed between DigiCert and DataTrails. The code works as proof of concept, but is not yet production ready. Contact: Steve Lasker (steve.lasker@datatrails.ai)

DigiCert Preview Organization: DigiCert Name: https://github.com/digicert/scitt-action Description: A GitHub Action for remote signing and registering statements about artifacts on a transparency service. Maturity: Preview Coverage: The current version ('main') implements this specification and demonstrates hash envelope signing with DigiCert Software Trust Manager. License: MIT Implementation Experience: Interop testing has been performed between DigiCert and DataTrails. The code works as proof of concept, but is not yet production ready. Contact: Corey Bonnell (Corey.Bonnell@digicert.com)

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