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 23 December 2024.¶

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

2. Header Parameters

To represent a hash of a detached payload, the following headers are defined:¶

TBD 0:

will be assigned by [I-D.ietf-cose-typ-header-parameter], represents the content type of the code envelope, including the protected header and payload¶

TBD 1:

the hash algorithm used to generate the hash of the payload¶

TBD 2:

the content type of the payload the hash represents¶

TBD 3:

an identifier enabling a verifier to retrieve the full payload preimage.¶

Hash_Envelope_Protected_Header = {
    ; Cryptographic algorithm to use
    ? &(alg: 1) => int,

    ; Type of the envelope
    ? &(typ: TBD_0) => 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 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

    ; Identifier for an artifact repository
    ; For example:
    ; pkg:container...image@sha256:244f...9c?repo..._url=dev.example
    ? &(artifact_repository: TBD) => tstr

    ; Type of Verifiable Data Structure, e.g. RFC9162_SHA256
    ; ? &(verifiable-data-structure: -111) => int,

    ; additional parameters allows.

}

Verifiable_Data_Proofs = {
  ? &(inclusion-proofs: -1) => [ bstr .cbor inclusion-proof ]
  ? &(consistency-proofs: -2) => [ bstr .cbor consistency-proof ]
  ; ... other proofs are allowed here.
}

Hash_Envelope_Unprotected_Header = {
  ; ? &(verifiable-data-proofs: 222) => Verifiable_Data_Proofs
  ; ... other unprotected header values are still allowed here.
}

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)

{
  / alg : ES384 / 1: -35,
  / kid / 4: h'75726e3a...32636573',
  / typ / TBD 0: application/hashed+cose
  / payload_hash_alg sha-256 / TBD 1: 1
  / payload_preimage_content_type / TBD 2: application/jwk+json
  / artifact_repository / TBD 3 : \
  pkg:container/image@sha256:244f...?repository_url=dev.example
}

18(                                 / COSE Sign 1                   /
    [
      h'a4013822...3a616263',       / Protected                     /
      {}                            / Unprotected                   /
      h'317cedc7...c494e772',       / Payload                       /
      h'15280897...93ef39e5'        / Signature                     /
    ]
)

18(                                 / COSE Sign 1                   /
    [
      h'a4013822...3a616263',       / Protected                     /
      {}                            / Unprotected                   /
      nil,                          / Detached payload              /
      h'15280897...93ef39e5'        / Signature                     /
    ]
)

3. Encrypted Hashes

Should we define this?¶

4. Security Considerations

TODO Security¶

5. IANA Considerations

6. Normative References

[I-D.ietf-cose-typ-header-parameter]

Jones, M. B. and O. Steele, "COSE "typ" (type) Header Parameter", Work in Progress, Internet-Draft, draft-ietf-cose-typ-header-parameter-05, 3 April 2024, <https://datatracker.ietf.org/doc/html/draft-ietf-cose-typ-header-parameter-05>.

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/rfc/rfc2119>.

[RFC8174]

Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

[RFC9052]

Schaad, J., "CBOR Object Signing and Encryption (COSE): Structures and Process", STD 96, RFC 9052, DOI 10.17487/RFC9052, August 2022, <https://www.rfc-editor.org/rfc/rfc9052>.

Acknowledgments

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

Authors' Addresses