]>

orie@or13.io

stevenlasker@hotmail.com

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 , 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) 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 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 which are hashed to produce the payload. For example, when the actual content is a bstr, a Verifier appraising a content-type bstr has to decicde if that bstr describes the digest bytes or the preimage bytes. Setting preimage-content-type to bstr, makes it clear that the preimage bytes themselves were a bstr.

Envelope Extended Diagnostic Notation (). 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 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, as defined in , which means using ECDSA with the 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 is 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.

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 the scope of this document.

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 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 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 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. n.d. 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.

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@or13.io)

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 (stevenlasker@hotmail.com)

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)

Microsoft CoseSignTool Organization: Microsoft Name: https://github.com/microsoft/CoseSignTool Description: A platform-agnostic command line application to create and validate COSE signatures. Maturity: This is an alpha release. Coverage: The current version (1.6.5) implements this specification through the 'indirect-sign' and 'indirect-verify' plugins. License: MIT Implementation Experience: Tests are run with CDDL schema-validated inputs and outputs. No direct interoperability testing with other implementations has been performed so far. Contact: The COSE Sign Tool team, via GitHub Issues (https://github.com/microsoft/CoseSignTool/issues)

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