feat: cose hash envelope

[shizhMSFT]

Important

This PR implements an RFC draft, which is "work in progress".

This PR implements the RFC draft COSE Hash Envelope (draft-04).

[codecov]

Codecov Report

Attention: Patch coverage is 93.28358% with 9 lines in your changes missing coverage. Please review.

Project coverage is 91.38%. Comparing base (cfe4231) to head (dde1237).

Files with missing lines	Patch %	Lines
hash_envelope.go	91.26%	6 Missing and 3 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #212      +/-   ##
==========================================
+ Coverage   91.27%   91.38%   +0.10%     
==========================================
  Files          12       13       +1     
  Lines        2006     2135     +129     
==========================================
+ Hits         1831     1951     +120     
- Misses        119      125       +6     
- Partials       56       59       +3     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull Request Overview

This PR implements the experimental COSE Hash Envelope feature as defined in the RFC draft, including new APIs for signing and verifying hash envelopes, new header parameters, and supporting changes to algorithm handling.

• Added an example demonstrating signing and verification of hash envelopes in example_test.go.
• Introduced SignHashEnvelope and VerifyHashEnvelope functions along with helper functions in hash_envelope.go.
• Updated header handling and algorithm constants in headers.go and algorithm.go, and adjusted example naming in cwt_test.go.

Reviewed Changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
example_test.go	Added a new example for COSE Hash Envelope signing and verification.
hash_envelope.go	Introduced new functions and header settings for hash envelope support.
headers.go	Added new header setters/getters for hash envelope parameters.
algorithm.go	Updated algorithm constants and hash function support for SHA variants.
cwt_test.go	Renamed an example function to reflect the new API usage.

Comments suppressed due to low confidence (3)

cwt_test.go:13

• [nitpick] The example function name 'Example_cWTMessage' includes an underscore and does not follow Go naming conventions. Consider renaming it to 'ExampleCWTMessage'.

func Example_cWTMessage() {

example_test.go:490

• [nitpick] The example function name 'Example_hashEnvelope' uses underscores which are unconventional in Go example naming. Consider renaming it to 'ExampleHashEnvelope' for consistency.

func Example_hashEnvelope() {

hash_envelope.go:123

• The use of 'maps.Clone' requires Go 1.21 or later. Please ensure that the project documentation specifies the minimum supported Go version.

header := maps.Clone(base)

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Pull Request Overview

This PR implements the experimental COSE Hash Envelope API, following the draft specification, and includes new signing and verification functions along with supporting tests and updated header and algorithm handling.

• Updated error messages for algorithm handling in headers.
• Added tests for payload hash algorithm conversion across various numeric types.
• Introduced examples and new constants for SHA-based algorithms.

Reviewed Changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
headers_test.go	Updated tests for error messages and payload hash algorithm tests.
example_test.go	Added an example demonstrating signing and verifying a hash envelope.
hash_envelope.go	Implemented signing and verifying functions for the hash envelope.
headers.go	Updated header constants and error handling in algorithm extraction.
algorithm_test.go	Extended tests to cover new SHA algorithms and hash function behaviors.
algorithm.go	Added SHA algorithm support and adjusted constant definitions.

Comments suppressed due to low confidence (1)

headers.go:163

• [nitpick] Consider aligning the error messaging for unsupported algorithm types between the Algorithm() and PayloadHashAlgorithm() functions to maintain a consistent behavior across header extraction methods.

return AlgorithmReserved, fmt.Errorf("Algorithm(%q): %w", alg, ErrAlgorithmNotSupported)

[SteveLasker]

Thanks, @shizhMSFT
We pushed version 04 to DataTracker which adds the pre-allocation COSE headers, so you're not dependent on a github PR:
https://www.ietf.org/archive/id/draft-ietf-cose-hash-envelope-04.html#name-iana-considerations

We'll update the iana reference as well

[shizhMSFT]

@SteveLasker I've updated the docs in the code to be draft-04.

[JeyJeyGao]

What happens if PreimageContentType exists in both the protected and unprotected headers? Is it a valid case? If it is valid, what happens if they have different values? This scenario is not defined in the draft.

[SteveLasker]

Thanks @JeyJeyGao,
This is a good question that I've opened cose-wg/draft-ietf-cose-hash-envelope#49

For future reference, you can always ask the question to the associated IETF discussion group. In this case:
[email protected] with a subject that contains: draft-ietf-cose-hash-envelope

The mail archive can be viewed here: https://mailarchive.ietf.org/arch/browse/cose?q=draft-ietf-cose-hash-envelope

[shizhMSFT]

I've double checked the RFC 9052 section 3, it states

Applications SHOULD verify that the same label does not occur in both the protected and unprotected header parameters. If the message is not rejected as malformed, attributes MUST be obtained from the protected bucket, and only if an attribute is not found in the protected bucket can that attribute be obtained from the unprotected bucket.

In other words, the same label can exist in both headers although it is not suggested. It really depends on the application. Therefore, I would keep the current implementation and leave the discussion to the hash envelope draft.

[SteveLasker]

While the end result of above is the same, I'd suggest holding to minimize churn while we sort out cose-wg/draft-ietf-cose-hash-envelope#50
We're all here in Bangkok this week for IETF 122, so I'm sure we can solve this quickly.
This shouldn't be left ambiguous.

[OR13]

I'd limit this library to simple validation of int / tstr for the labels, and leave use of these parameters to applications that build on this library.

[SteveLasker]

We've updated the hash-envelope draft to clarify the protected/unprotected headers: https://datatracker.ietf.org/doc/draft-ietf-cose-hash-envelope/05/