]> 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 detached payload, the verifier must have access to the payload content. Storing a hash of the content allows for small signature envelopes, that are easy to transport and verify independently. Additional hints in the protected header ensure cryptographic agility for the hashing & signing algorithms, and discoverability for the original content which could be prohibitively large to move over a network. When producing COSE_sign1 with remote signing services, such as a signing api exposed over HTTPS and backed by an HSM, the "ToBeSigned" bytes as described in need to be transmitted to the HSM in order to be signed. Some signature algorithms such as ES256 or ES384 allow the "ToBeSigned" to be hashed on the client and sent to the server along with metadata in order to produce a signature. Other signature algorithms such as EdDSA with Ed25519, or ML-DSA do not expose such a capability. By producing the "ToBeSigned" on the client, and ensuring that the payload is always a hashed value, the total size of the message to be sent to the service for signing is constrained. It is still possible for the protected header to be large, but the payload will always be of a fixed size, associated with the hash function chosen.

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 To represent a hash of a payload, the following headers are defined:

TBD_1:

the hash algorithm used to produce the payload.

TBD_2:

the content type of the bytes that were hashed to produce the payload.

TBD_3:

an identifier enabling a verifier to retrieve the bytes which were hashed to produce the payload.

Hash Envelope CDDL int, ; Type of the envelope ? &(typ: 16) => int / tstr ; Hash algorithm used to produce the payload from content ; -16 for SHA-256, ; See https://www.iana.org/assignments/cose/cose.xhtml &(payload_hash_alg: TBD_1) => int ; Content type of the preimage ; (content to be hashed) of the payload ; 50 for application/json, ; See https://datatracker.ietf.org/doc/html/rfc7252#section-12.3 &(payload_preimage_content_type: TBD_2) => int ; Location the content of the hashed payload is stored ; For example: ; storage.example/244f...9c19 ? &(payload_location: TBD_3) => 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 16 (typ) MAY be used to assign a content format or media type to the entire hash envelope.
• Label TBD_1 (payload hash alg) MUST be present in the protected header and MUST NOT be present in the unprotected header.
• Label TBD_2 (content type of the preimage of the payload) MAY be present in the protected header or unprotected header.
• Label TBD_3 (payload_location) MAY be added to the protected header and MUST NOT be presented 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 TBD_2 payload_preimage_content_type. The difference between content_type (3) and payload_preimage_content_type (TBD2) 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 TBD_1, TBD_2, TBD_3 (or other header parameters) critical, see for more details.

Envelope EDN A hashed payload functions equivalently to an attached payload, with the benefits of being compact in size and providing the ability to validate the signature. > {} / Unprotected / h'935b5a91...e18a588a', / Payload / h'15280897...93ef39e5' / Signature / ] ) ]]> In this example, the sha256 hash algorithm (-16) is used to hash the payload, which is of content type application/json-patch+json identified by the content format 51. The full payload is located at "https://storage.example/244f...9c19". The COSE_sign1 is of type "application/example+cose". The sha256 hash is signed with ES384 which starts by taking the sha384 hash of the payload (which is a sha256 hash).

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.

Security Considerations TODO Security

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. It is also possible to use this specification with signature algorithms that support pre-hashing such as Ed25519ph which is described in , or HashML-DSA which is described in . 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 confisderation 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.

IANA Considerations

COSE Header Algorithm Parameters IANA is requested to add the following entries to the COSE Header Algorithm Parameters Registry.

Payload Hash Algorithm

• Name: payload_hash_alg
• Label: TBD_1
• Value type: int
• Value registry: https://www.iana.org/assignments/cose/cose.xhtml#algorithms
• Description: Hash algorithm used to produce the payload.

Payload Pre-image Content Type

• Name: payload_preimage_content_type
• Label: TBD_2
• Value type: int
• Value registry: https://www.iana.org/assignments/core-parameters/core-parameters.xhtml#content-formats
• Description: The content format associated with the bytes that were hashed to produce the payload.

Payload Location

• Name: payload_location
• Label: TBD_3
• Value type: tstr
• Value registry: none
• Description: A string or URI as a hint for the location of the payload

References Normative References 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. 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. Universität Bremen TZI The Concise Binary Object Representation (CBOR) (STD 94, RFC 8949) is a data format whose design goals include the possibility of extremely small code size, fairly small message size, and extensibility without the need for version negotiation. In addition to the binary interchange format, CBOR from the outset (RFC 7049) defined a text-based "diagnostic notation" in order to be able to converse about CBOR data items without having to resort to binary data. RFC 8610 extended this into what is known as Extended Diagnostic Notation (EDN). This document consolidates the definition of EDN, sets forth a further step of its evolution, and is intended to serve as a single reference target in specifications that use EDN. It specifies an extension point for adding application-oriented extensions to the diagnostic notation. It then defines two such extensions that enhance EDN with text representations of epoch-based date/times and of IP addresses and prefixes (RFC 9164). A few further additions close some gaps in usability. The document modifies one extension originally specified in Appendix G.4 of RFC 8610 to enable further increasing usability. To facilitate tool interoperation, this document specifies a formal ABNF grammar, and it adds media types. // The present revision -12 reflects the branch "roll-up" in the // repository, an attempt to contain the entire specification of EDN // in this document, instead of describing updates to the existing // documents RFC 8949 and RFC 8610. While the WG hasn't taken a // decision to follow this updated editorial approach, the feedback // has been sufficiently positive that the author believes it is not // misleading to make this revision available as the current WG // Internet-Draft as well. That said, this is still a snapshot. The // editorial work on the branch "roll-up" is not complete. Content // will continue to move between sections. The exact reflection of // this document being a replacement for both Section 8 of RFC 8949 // and Appendix G of RFC 8610 needs to be recorded in the metadata // and in abstract and introduction. 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. 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. This document describes elliptic curve signature scheme Edwards-curve Digital Signature Algorithm (EdDSA). The algorithm is instantiated with recommended parameters for the edwards25519 and edwards448 curves. An example implementation and test vectors are provided. n.d.

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.