spec: update cose and signature spec according to review comments (#204)

* spec: update according to review comments * update to RFC for the fields of the sig_structure * update description for field context Signed-off-by: Yi Zha <[email protected]>
notaryproject · Nov 17, 2022 · 6fc8e1d · 6fc8e1d
1 parent 5e2f76a
commit 6fc8e1d
Show file tree

Hide file tree

Showing 2 changed files with 20 additions and 137 deletions.
diff --git a/signature-envelope-cose.md → specs/signature-envelope-cose.md b/signature-envelope-cose.md → specs/signature-envelope-cose.md
@@ -37,6 +37,21 @@ Signature Manifest Example
 
 The COSE envelope contains a [Notary v2 Payload](./signature-specification.md#payload).
 
+Example of Notary v2 payload:
+
+```jsonc
+{
+  "targetArtifact": {
+    "mediaType": "application/vnd.oci.image.manifest.v1+json",
+    "digest": "sha256:73c803930ea3ba1e54bc25c2bdc53edd0284c62ed651fe7b00369da519a3c333",
+    "size": 16724,
+    "annotations": {
+        "io.wabbit-networks.buildId": "123"  // user defined metadata
+    }
+  }
+}
+```
+
 ## Protected Header
 
 The COSE envelope for Notary v2 uses the following header parameters:
@@ -90,9 +105,9 @@ Note: The above examples are represented using the [extended CBOR diagnostic not
 - **[`crit`](https://datatracker.ietf.org/doc/html/rfc8152#section-3.1)** (*array of int/tstr*): This REQUIRED parameter (label `2`) lists the header parameters that implementations MUST understand and process. It MUST only contain parameters apart from integer labels in the range of 0 to 8. This header MUST contain `io.cncf.notary.signingScheme` which is a required critical header, and optionally contain `io.cncf.notary.authenticSigningTime` and `io.cncf.notary.expiry` if these critical headers are present in the signature.
 - **[`content type`](https://datatracker.ietf.org/doc/html/rfc8152#section-3.1)** (*tstr*): The REQUIRED parameter content type (label `3`) is used to declare the media type of the secured content (the payload). The supported value is `application/vnd.cncf.notary.payload.v1+json`.
 - **`io.cncf.notary.signingScheme`** (*tstr*, critical): This REQUIRED header specifies the [Notary v2 Signing Scheme](./signing-scheme.md) used by the signature. Supported values are `notary.x509` and `notary.x509.signingAuthority`.
-- **`io.cncf.notary.signingTime`** (*date/time*): This header specifies the time at which the signature was generated. This is an untrusted date/time, and therefore not used in trust decisions. Its value is an Epoch-Based Date/Time defined in [RFC 8949](https://datatracker.ietf.org/doc/html/rfc8949#section-3.4.2). This claim is REQUIRED and only valid when signing scheme is `notary.x509`.
-- **`io.cncf.notary.authenticSigningTime`** (*date/time*, critical): This header specifies the authenticated time at which the signature was generated. Its value is an Epoch-Based Date/Time defined in [RFC 8949](https://datatracker.ietf.org/doc/html/rfc8949#section-3.4.2). This claim is REQUIRED and only valid when signing scheme is `notary.x509.signingAuthority` .
-- **`io.cncf.notary.expiry`** (*date/time*, critical): This OPTIONAL header provides a "best by use" time for the artifact, as defined by the signer. Its value is an Epoch-Based Date/Time defined in [RFC 8949](https://datatracker.ietf.org/doc/html/rfc8949#section-3.4.2).
+- **`io.cncf.notary.signingTime`** (*date/time*): This header specifies the time at which the signature was generated. This is an untrusted date/time, and therefore not used in trust decisions. Its value is an Epoch-Based Date/Time defined in [RFC 8949](https://datatracker.ietf.org/doc/html/rfc8949#section-3.4.2). The optional fractional seconds SHOULD NOT be used. This claim is REQUIRED and only valid when signing scheme is `notary.x509`.
+- **`io.cncf.notary.authenticSigningTime`** (*date/time*, critical): This header specifies the authenticated time at which the signature was generated. Its value is an Epoch-Based Date/Time defined in [RFC 8949](https://datatracker.ietf.org/doc/html/rfc8949#section-3.4.2). The optional fractional seconds SHOULD NOT be used. This claim is REQUIRED and only valid when signing scheme is `notary.x509.signingAuthority` .
+- **`io.cncf.notary.expiry`** (*date/time*, critical): This OPTIONAL header provides a "best by use" time for the artifact, as defined by the signer. Its value is an Epoch-Based Date/Time defined in [RFC 8949](https://datatracker.ietf.org/doc/html/rfc8949#section-3.4.2). The optional fractional seconds SHOULD NOT be used.
 
 ## Unprotected Headers
 
@@ -128,7 +143,7 @@ In COSE, signature is calculated by constructing the `Sig_structure` for `COSE_S
 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`.
+2. Construct the `Sig_structure` for `COSE_Sign1`. The field `context` is set to `Signature1` for `COSE_Sign1` as specified by [RFC9052](https://www.rfc-editor.org/rfc/rfc9052.html#section-4.4).
     ```yaml
     Sig_structure = [
         / context / 'Signature1',
@@ -138,7 +153,7 @@ The process is described below:
     ]
     ```
 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`.
+4. Compute the signature on the `ToBeSigned` constructed in the previous step by using the signature algorithm of the signing key, which MUST match the corresponding protected header element `alg`.
    This is the value of the signature property used in the signature envelope.
 
 ## Signature Envelope

diff --git a/specs/signature-specification.md b/specs/signature-specification.md
@@ -159,7 +159,6 @@ A use case for this feature is for a plugin publisher to address security bug in
 
 See [Guidelines for Notary v2 Implementors](#guidelines-for-notary-v2-implementors) for options to handle these attributes during signature verification.
 
-
 ### Unsigned Attributes
 
 These attributes are considered unsigned with respect to the signing key that generates the signature. These attributes are typically signed by a third party (e.g. CA, TSA).
@@ -168,127 +167,6 @@ These attributes are considered unsigned with respect to the signing key that ge
 - **Timestamp signature** : An OPTIONAL counter signature which provides [authentic timestamp](#signing-time)e.g. Time Stamp Authority (TSA) generated timestamp signature. Only [RFC3161](ietf-rfc3161) compliant TimeStampToken are currently supported.
 - **Signing Agent**: An OPTIONAL claim that provides the identifier of the software (e.g. Notation) that produced the signature on behalf of the user. It is an opaque string set by the software that produces the signature. It's intended primarily for diagnostic and troubleshooting purposes, this attribute is unsigned, the verifier MUST NOT validate formatting, or fail validation based on the content of this claim. The suggested format is one or more tokens of the form `{id}/{version}` containing identifier and version of the software, seperated by spaces. E.g. “notation/1.0.0”, “notation/1.0.0 com.example.nv2plugin/0.8”.
 
-### Supported Signature Envelopes
-
-#### JWS JSON Serialization
-
-In JWS JSON Serialization ([RFC7515](https://datatracker.ietf.org/doc/html/rfc7515)), data is stored as either claims or headers (protected and unprotected).
-Notary v2 uses JWS JSON Serialization for the signature envelope with some additional constraints on the structure of claims and headers.
-
-Unless explicitly specified as OPTIONAL, all fields are required.
-Also, there shouldn’t be any additional fields other than ones specified in JWSPayload, ProtectedHeader, and UnprotectedHeader.
-
-**JWSPayload a.k.a. Claims**:
-Notary v2 is using one private claim (`notary`) and two public claims (`iat` and `exp`).
-An example of the claim is described below
-
-```json
-{
-   "subject": {
-      "mediaType": "application/vnd.oci.image.manifest.v1+json",
-      "digest": "sha256:73c803930ea3ba1e54bc25c2bdc53edd0284c62ed651fe7b00369da519a3c333",
-      "size": 16724,
-      "annotations": {
-         "key1": "value1",
-         "key2": "value2",
-         ...
-      }
-   },
-   "iat": 1234567891000,
-   "exp": 1234567891011
-}
-```
-
-The payload contains the subject manifest and other attributes that have to be integrity protected.
-
-- **`subject`**(*descriptor*): A REQUIRED top-level node consisting of the manifest that needs to be integrity protected.
-  Please refer [Payload](#payload) section for more details.
-- **`iat`**(*number*): The REQUIRED property Issued-at(`iat`) identifies the time at which the signature was issued.
-- **`exp`**(*number*): This OPTIONAL property contains the expiration time on or after which the signature must not be considered valid.
-
-To leverage JWS claims validation functionality already provided by libraries, we have defined `iat`, `exp` as top-level nodes.
-
-**ProtectedHeaders**: Notary v2 supports only three protected headers: `alg`, `cty`, and `crit`.
-
-```json
-{
-    "alg": "RS256",
-    "cty": "application/vnd.cncf.notary.v2.jws.v1",
-    "crit":["cty"]
-}
-```
-
-- **`alg`**(*string*): This REQUIRED property defines which algorithm was used to generate the signature.
-  JWS needs an algorithm(`alg`) to be present in the header, so we have added it as a protected header.
-- **`cty`**(*string*): The REQUIRED property content-type(cty) is used to declare the media type of the secured content(the payload).
-  This will be used to version different variations of JWS signature.
-  The supported value is `application/vnd.cncf.notary.v2.jws.v1`.
-- **`crit`**(*array of strings*): This REQUIRED property lists the headers that implementation MUST understand and process.
-  The value MUST be `["cty"]`.
-
-**UnprotectedHeaders**: Notary v2 supports only two unprotected headers: timestamp and x5c.
-
-```json
-{
-    "timestamp": "<Base64(TimeStampToken)>",
-    "x5c": ["<Base64(DER(leafCert))>", "<Base64(DER(intermediateCACert))>", "<Base64(DER(rootCert))>"]
-}
-```
-
-- **`timestamp`** (*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.
-- **`x5c`** (*array of strings*): This REQUIRED property 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 JWS.
-  The certificate containing the public key corresponding to the key used to digitally sign the JWS MUST be the first certificate.
-
-- **`timestamp`** (*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.
-- **`x5c`** (*array of strings*): This REQUIRED property 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 JWS.
-  The certificate containing the public key corresponding to the key used to digitally sign the JWS MUST be the first certificate.
-
-**Signature**: In JWS signature is calculated by combining JWSPayload and protected headers.
-The process is described below:
-
-1. Compute the Base64Url value of ProtectedHeaders.
-1. Compute the Base64Url value of JWSPayload.
-1. Build message to be signed by concatenating the values generated in step 1 and step 2 using '.'
-`ASCII(BASE64URL(UTF8(ProtectedHeaders)) ‘.’ BASE64URL(JWSPayload))`
-1. Compute the signature on the message constructed in the previous step by using the signature algorithm defined in the corresponding header element: `alg`.
-1. Compute the Base64Url value of the signature produced in the previous step.
-   This is the value of the signature property used in the signature envelope.
-
-**Signature Envelope**: The final signature envelope comprises of Claims, ProtectedHeaders, UnprotectedHeaders, and signature.
-
-Since Notary v2 restricts one signature per signature envelope, the compliant signature envelope MUST be in flattened JWS JSON format.
-
-```json
-{
-    "payload": "<Base64Url(JWSPayload)>",
-    "protected": "<Base64Url(ProtectedHeaders)>",
-    "header": {
-        "timestamp": "<Base64(TimeStampToken)>",
-        "x5c": ["<Base64(DER(leafCert))>", "<Base64(DER(intermediateCACert))>", "<Base64(DER(rootCert))>"]
-    },
-    "signature": "Base64Url( sign( ASCII( <Base64Url(ProtectedHeader)>.<Base64Url(JWSPayload)> )))"  
-}
-```
-
-**Implementation Constraints**: Notary v2 implementation MUST enforce the following constraints on signature generation and verification:
-
-1. `alg` header value MUST NOT be `none` or any symmetric-key algorithm such as `HMAC`.
-1. `alg` header value MUST be same as that of signature algorithm identified using signing certificate's public key algorithm and size.
-1. `alg` header values for various signature algorithms:
-  | Signature Algorithm             | `alg` Param Value |
-  | ------------------------------- | ----------------- |
-  | RSASSA-PSS with SHA-256         | PS256             |
-  | RSASSA-PSS with SHA-384         | PS384             |
-  | RSASSA-PSS with SHA-512         | PS512             |
-  | ECDSA on secp256r1 with SHA-256 | ES256             |
-  | ECDSA on secp384r1 with SHA-384 | ES384             |
-  | ECDSA on secp521r1 with SHA-512 | ES512             |
-1. Signing certificate MUST be a valid codesigning certificate.
-1. Only JWS JSON flattened format is supported.
-   See 'Signature Envelope' section.
-
 ## Signature Algorithm Requirements
 
 The implementation MUST support the following set of algorithms:
@@ -317,16 +195,6 @@ The signing certificate's public key algorithm and size MUST be used to determin
 
 ### Certificate Requirements
 
-The **signing certificate** MUST meet the following minimum requirements:
-
-- The keyUsage extension MUST be present and MUST be marked critical.
-  The bit positions for digitalSignature MUST be set ([RFC-5280](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.3)).
-- The extKeyUsage extension MUST be present and its value MUST be id-kp-codeSigning ([RFC-5280](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.12)).
-- If the basicConstraints extension is present, the cA field MUST be set false ([RFC-5280](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.9)).
-- The certificate MUST abide by the following key length restrictions:
-- For RSA public key, the key length MUST be 2048 bits or higher.
-  - For ECDSA public key, the key length MUST be 256 bits or higher.
-
 The codesigning and timestamping certificates MUST meet the following requirements. These requirements are validated both at signature generation time and signature verification time, and are applied to the certificate chain in the signature envelope. These validations are independent of certificate chain validation against a trust store.
 
 #### Root and Intermediate CA Certificates