Skip to content

Commit

Permalink
Merge pull request #11 from OR13/steve/streamline
Browse files Browse the repository at this point in the history 
Updates for 120 Submission
  • Loading branch information
@SteveLasker
SteveLasker authored Jul 6, 2024
2 parents d102df6 + 0b62dcf commit b0500d1
Showing 1 changed file with 85 additions and 90 deletions.
175 changes: 85 additions & 90 deletions draft-steele-cose-hash-envelope.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,88 +38,115 @@ author:

normative:
RFC9052: RFC9052
I-D.ietf-cose-typ-header-parameter: COSE-TYP
RFC9596: COSE-TYP

informative:

--- abstract

This document defines new COSE header parameters for signaling that a payload is the output of a hash function.
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.
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.

--- middle

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

## Requirements Notation
## Attached Payload

{::boilerplate bcp14-tagged}
COSE_sign1 envelope with an attached payload, providing for signature validation.

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

## Detached Payload

COSE_sign1 envelope with a detached payload (`nil`), which is compact but the payload must be distributed out of band to validate the signature

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

## Hashed Payload

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.

~~~~ cbor-diag
18( / COSE Sign 1 /
[
h'a4013822...3a616263', / Protected /
{} / Unprotected /
h'935b5a91...e18a588a', / Payload /
h'15280897...93ef39e5' / Signature /
]
)
~~~~

# Header Parameters

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

TBD 0:
: will be assigned by {{-COSE-TYP}}, represents the content type of the code envelope, including the protected header and payload

TBD 1:
TBD_1:
: the hash algorithm used to generate the hash of the payload

TBD 2:
TBD_2:
: the content type of the payload the hash represents

TBD 3:
TBD_3:
: an identifier enabling a verifier to retrieve the full payload preimage.

## Signed Hash Envelopes Example

~~~ cddl

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

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

; Identifier for an artifact repository
; Location the content of the hashed payload is stored
; 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.

}
; storage.example/244f...9c19
? &(payload_location: TBD_3) => tstr

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

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

Hash_Envelope_as_COSE_Sign1 = [
Expand All @@ -134,58 +161,22 @@ Hash_Envelope = #6.18(Hash_Envelope_as_COSE_Sign1)

## Protected Header

TBD 0 (typ), TBD 1 (payload hash alg) and TBD 2 (content type of the preimage of the payload) MUST be present in the protected header and MUST NOT be present in the unprotected header.
16 (typ), TBD_1 (payload hash alg) and TBD_2 (content type of the preimage of the payload) MUST be present in the protected header and MUST NOT be present in the unprotected header.
TBD_3 (payload_location) MAY be added to the protected header and MUST NOT be presented in the unprotected header.

For example:

~~~~ cbor-diag
{
/ 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
/ typ / 16: application/hashed+cose
/ payload_hash_alg sha-256 / TBD_1: 1
/ payload_preimage_content_type / TBD_2: application/jwk+json
/ payload_location / TBD_3 : storage.example/244f...9c19
}
~~~~

TBD 0 will be assigned by {{-COSE-TYP}}, it represents the content type of the code envelope, which includes the protected header and payload.

TBD 1 will be assigned by this draft.
TBD 2 will be assigned by this draft.
TBD 3 will be assigned by this draft.

## Attached Payload

The payload MAY be attached.

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

## Detached Payload

The payload MAY be detached.

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

# Encrypted Hashes

Should we define this?
Expand All @@ -201,27 +192,31 @@ For example, when signing with ECDSA using P-256 and SHA-256, use SHA-256 to has

# IANA Considerations

## Requirements Notation

{::boilerplate bcp14-tagged}

## COSE Header Algorithm Parameters

* Name: payload hash algorithm
* Label: TBD_1
* Value type: int
* Value registry: https://www.iana.org/assignments/named-information/named-information.xhtml
* Description: Hash algorithm used to produce the payload.
- Name: payload hash algorithm
- Label: TBD_1
- Value type: int
- Value registry: https://www.iana.org/assignments/named-information/named-information.xhtml
- Description: Hash algorithm used to produce the payload.

## Named Information Hash Algorithm Registry

* Name: SHAKE256
* Label: TBD_2
* Value type: int
* Value registry: https://www.iana.org/assignments/named-information/named-information.xhtml
* Description: SHAKE256 a described in https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf

* Name: ASCON128
* Label: TBD_3
* Value type: int
* Value registry: https://www.iana.org/assignments/named-information/named-information.xhtml
* Description: ASCON128 a described in https://csrc.nist.gov/CSRC/media/Projects/lightweight-cryptography/documents/round-2/spec-doc-rnd2/ascon-spec-round2.pdf
- Name: SHAKE256
- Label: TBD_2
- Value type: int
- Value registry: https://www.iana.org/assignments/named-information/named-information.xhtml
- Description: SHAKE256 a described in https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf

- Name: ASCON128
- Label: TBD_3
- Value type: int
- Value registry: https://www.iana.org/assignments/named-information/named-information.xhtml
- Description: ASCON128 a described in https://csrc.nist.gov/CSRC/media/Projects/lightweight-cryptography/documents/round-2/spec-doc-rnd2/ascon-spec-round2.pdf

--- back

Expand Down

0 comments on commit b0500d1

Please sign in to comment.