COSE Signature Envelope #139
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -17,7 +17,7 @@ The signature manifest has an artifact type that specifies it's a Notary V2 sign | |
|
|
||
| - **`artifactType`** (*string*): This REQUIRED property references the Notary version of the signature: `application/vnd.cncf.notary.v2.signature`. | ||
| - **`blobs`** (*array of objects*): This REQUIRED property contains collection of only one [artifact descriptor](https://github.com/oras-project/artifacts-spec/blob/main/descriptor.md) referencing signature envelope. | ||
| - **`mediaType`** (*string*): This REQUIRED property contains media type of signature envelope blob. The supported value is `application/cose`. | ||
| - **`subject`** (*descriptor*): A REQUIRED artifact descriptor referencing the signed manifest, including, but not limited to image manifest, image index, oras-artifact manifest. | ||
| - **`annotations`** (*string-string map*): This REQUIRED property contains metadata for the artifact manifest. | ||
| It is being used to store information about the signature. | ||
|
|
@@ -70,7 +70,7 @@ A signature envelope consists of the following components: | |
|
|
||
| A signature envelope is `e = {m, v, u, s}` where `s` is signature. | ||
|
|
||
| Notary v2 supports [COSE_Sign1_Tagged](https://datatracker.ietf.org/doc/html/rfc8152#section-4) as signature envelope format with some additional constraints but makes provisions to support additional signature envelope format. | ||
|
|
||
| ### Payload | ||
|
|
||
|
|
@@ -80,7 +80,7 @@ Notary v2 requires Payload to be the content **descriptor** of the subject manif | |
| 1. Descriptor MAY contain `annotations` and if present it MUST follow the [annotation rules](https://github.com/opencontainers/image-spec/blob/main/annotations.md#rules). Notary v2 uses annotations for storing both Notary specific and user defined signed attributes. The prefix `org.cncf.notary` in annotation keys is reserved for use in Notary v2 and MUST NOT be used outside this specification. | ||
| 1. Descriptor MAY contain `artifactType` field for artifact manifests, or the `config.mediaType` for `oci.image` based manifests. | ||
|
|
||
| Examples: The media type of the content descriptor is `application/vnd.cncf.oras.artifact.descriptor.v1+json`. | ||
|
|
||
| ```jsonc | ||
| { | ||
|
|
@@ -120,125 +120,105 @@ Notary v2 requires the signature envelope to support the following signed attrib | |
|
|
||
| ### Supported Signature Envelopes | ||
|
|
||
| #### COSE_Sign1_Tagged | ||
|
|
||
| In COSE ([rfc8152](https://datatracker.ietf.org/doc/html/rfc8152)), data is stored as either payload or headers (protected and unprotected). | ||
| Notary v2 uses [COSE_Sign1_Tagged](https://datatracker.ietf.org/doc/html/rfc8152#section-4.2) object as the signature envelope with some additional constraints on the header fields. | ||
|
|
||
| Unless explicitly specified as OPTIONAL, all fields are required. | ||
|
|
||
| **Payload**: COSE signs the payload as defined in the [Payload](#payload) section. | ||
|
|
||
| **ProtectedHeaders**: Notary v2 supports only the following protected headers: | ||
shizhMSFT marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| ``` | ||
| { | ||
| / crit / 2: [ | ||
| / cty / 3, | ||
| 'signingtime', | ||
|
There was a problem hiding this comment. Is there a reason to use headers of type string instead of int? Do we plan to followup and include these in IANA? https://www.iana.org/assignments/cose/cose.xhtml#header-parameters |
||
| 'expiry' | ||
| ], | ||
| / cty / 3: 'application/vnd.cncf.oras.artifact.descriptor.v1+json', | ||
| 'signingtime': 1234567891000, | ||
| 'expiry': 1234567891011 | ||
| } | ||
| ``` | ||
|
|
||
| Note: The above example is represented using the [extended CBOR diagnostic notation](https://datatracker.ietf.org/doc/html/rfc8152#appendix-C). | ||
|
|
||
| - **`crit`** (*array of integers or strings*): This REQUIRED property (label: `2`) lists the headers that implementation MUST understand and process. | ||
| The array MUST contain `3` (`cty`), and `signingtime`. If `expiry` is presented, the array MUST also contain `expiry`. | ||
| - **`cty`** (*string*): The REQUIRED property content-type (label: `3`) is used to declare the media type of the secured content (the payload). | ||
| - **`signingtime`** (*integer*): The REQUIRED property identifies the time at which the signature was generated. | ||
| - **`expiry`** (*integer*): This OPTIONAL property contains the expiration time on or after which the signature must not be considered valid. | ||
gokarnm marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| **UnprotectedHeaders**: Notary v2 supports only two unprotected headers: `timestamp` and `x5chain`. | ||
|
|
||
| ``` | ||
| { | ||
| 'timestamp': << TimeStampToken >>, | ||
| / x5chain / 33: [ | ||
| << DER(leafCert) >>, | ||
| << DER(intermediate CACert) >>, | ||
| << DER(rootCert) >> | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| Note: `<<` and `>>` are used to notate the byte string resulting from encoding the data item. | ||
|
|
||
| - **`timestamp`** (*byte string*): This OPTIONAL property is used to store time stamp token. | ||
| Only [RFC3161]([rfc3161](https://datatracker.ietf.org/doc/html/rfc3161#section-2.4.2)) compliant TimeStampToken are supported. | ||
| - **`x5chain`** (*array of byte strings*): This REQUIRED property (label: `33` by [IANA](https://www.iana.org/assignments/cose/cose.xhtml#header-parameters)) contains the list of X.509 certificate or certificate chain ([RFC5280](https://datatracker.ietf.org/doc/html/rfc5280)) corresponding to the key used to digitally sign the COSE. | ||
| The certificate containing the public key corresponding to the key used to digitally sign the COSE MUST be the first certificate. | ||
| Optionally, this header can be presented in the protected header. | ||
|
There was a problem hiding this comment. If x5chain is not protected, should require that x5t/34 is. There may also be value in simply requiring that x5chain is protected. This guards against a potential cert substitution attack, at the expense of requiring a larger signature envelope size because the header can't be stripped in environments where the value is known externally. There was a problem hiding this comment. @priteshbandi Should we move There was a problem hiding this comment. @briankr-ms , @shizhMSFT what's the call here? I can make changes if we can conclude on a decision. There was a problem hiding this comment. @briankr-ms could you provide more details for cert substitution attack. Notation will use x5chain in conjunction with trust store configured by the user. As part of verification, the cert chain is checked to terminate in one of the certs in trust store. @shizhMSFT are we using x5t/thumbprint in any other context, other than signature manifest attributes, for matching signature to policy for evaluation? There was a problem hiding this comment. @shizhMSFT The certs in chain are already signed by the next cert in the chain, and is expected to be authenticated against the trust store. Open to discussing if moving it to signed attributes protects us against certain attacks. |
||
|
|
||
| **Signature**: In COSE, signature is calculated by constructing the `Sig_structure` for `COSE_Sign1`. | ||
| The process is described below: | ||
|
|
||
| 1. Encode the protected header into a CBOR object as a byte string named `body_protected`. | ||
| 2. Construct the `Sig_structure` for `COSE_Sign1`. | ||
| ``` | ||
| Sig_structure = [ | ||
| / context / 'Signature1', | ||
| / body_protected / << ProtectedHeaders >>, | ||
| / external_aad / h'', | ||
| / payload / << Payload >>, | ||
| ] | ||
| ``` | ||
| 3. Encode `Sig_structure` into a CBOR object as a byte string named `ToBeSigned`. | ||
| 4. Compute the signature on the `ToBeSigned` constructed in the previous step by using the signature algorithm defined in the corresponding header element: `alg`. | ||
| This is the value of the signature property used in the signature envelope. | ||
|
|
||
| **Signature Envelope**: The final signature envelope is a `COSE_Sign1_Tagged` object, consisting of Payload, ProtectedHeaders, UnprotectedHeaders, and Signature. | ||
|
|
||
| ``` | ||
| 18( | ||
| [ | ||
| / protected / << { | ||
| / crit / 2: [ | ||
| / cty / 3, | ||
| 'signingtime', | ||
| 'expiry' | ||
| ], | ||
| / cty / 3: 'application/vnd.cncf.oras.artifact.descriptor.v1+json', | ||
| 'signingtime': 1234567891000, | ||
| 'expiry': 1234567891011 | ||
| } >>, | ||
| / unprotected / { | ||
| 'timestamp': << TimeStampToken >>, | ||
| / x5chain / 33: [ | ||
| << DER(leafCert) >>, | ||
| << DER(intermediate CACert) >>, | ||
| << DER(rootCert) >> | ||
| ] | ||
| }, | ||
| / payload / << descriptor >>, | ||
shizhMSFT marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| / signature / << sign( << Sig_structure >> ) >> | ||
| ] | ||
| ) | ||
| ``` | ||
|
|
||
| ## Signature Algorithm Requirements | ||
|
|
||
| The implementation MUST support the following set of algorithms: | ||
|
|
@@ -292,10 +272,10 @@ The **timestamping certificate** MUST meet the following minimum requirements: | |
|
|
||
| **Q: How will Notary v2 support multiple signature envelope format?** | ||
|
|
||
| **A:** The idea is to use `mediaType` of artifact manifest's blob to identify the signature envelope type (like COSE, JWS, CMS, DSSE, etc). | ||
| The client implementation can use the aforementioned `mediaType` to parse the signature envelope. | ||
|
|
||
| **Q: How will Notary v2 handle non-backward compatible changes to signature format?** | ||
|
|
||
| **A:** The Signature envelope MUST have a versioning mechanism to support non-backward compatible changes. | ||
| For [COSE_Sign1_Tagged](#cose_sign1_tagged) signature envelope it is achieved by `cty` field in ProtectedHeaders. | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is the intent to disregard any optional parameter e.g.
application/cose; cose-type="cose-sign1"? Notation should probably includecode-typeparam to be more specific.