COSE Hash Envelope

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 28 February 2025.¶

Copyright Notice

Copyright (c) 2024 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 (https://trustee.ietf.org/license-info) 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

1. Introduction

COSE defined detached payloads in Section 2 of [RFC9052], 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 Section 4.4 of [RFC9052] 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.¶

2. 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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

The terms COSE, CDDL, and EDN are defined in [RFC9052], [RFC8610], [I-D.draft-ietf-cbor-edn-literals] respectively.¶

3. 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.¶

4. Hash Envelope CDDL

Hash_Envelope_Protected_Header = {
    ; Cryptographic algorithm to use
    ? &(alg: 1) => 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.¶

5. 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.¶

18(                                 / COSE Sign 1                   /
    [
      <<{
        / alg : ES384 / 1: -35,
        / kid / 4: h'75726e3a...32636573',
        / typ / 16: "application/example+cose"
        / payload_hash_alg /
        TBD_1: -16 / sha-256 /
        / payload_preimage_content_type /
        TBD_2: "application/example+json"
        / payload_location /
        TBD_3 : "https://storage.example/a24f9c19"
      }>>
      {}                            / 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/example+json". 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).¶

6. 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.¶

7. Security Considerations

TODO Security¶

8. IANA Considerations

9. References

Appendix A. Implementation Status

Note to RFC Editor: Please remove this section as well as references to [BCP205] 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 [BCP205]. 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 [BCP205], "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".¶

Acknowledgments

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

Authors' Addresses