chore: removed TODOs, updated outdated specs etc (#231)

* housekeeping: removed todos, updated specs etc * remove Notes ed-off-by: Pritesh Bandi <[email protected]>
notaryproject · Feb 2, 2023 · a56d1d9 · a56d1d9
1 parent ab8c0a0
commit a56d1d9
Show file tree

Hide file tree

Showing 8 changed files with 22 additions and 29 deletions.
diff --git a/definitions-terms.md → requirements/definitions-terms.md b/definitions-terms.md → requirements/definitions-terms.md
diff --git a/key-revocation.md → requirements/key-revocation.md b/key-revocation.md → requirements/key-revocation.md
diff --git a/keymanagementrequirements.md → requirements/keymanagementrequirements.md b/keymanagementrequirements.md → requirements/keymanagementrequirements.md
diff --git a/requirements.md → requirements/requirements.md b/requirements.md → requirements/requirements.md
diff --git a/scenarios.md → requirements/scenarios.md b/scenarios.md → requirements/scenarios.md
diff --git a/verification-by-reference.md → requirements/verification-by-reference.md b/verification-by-reference.md → requirements/verification-by-reference.md
diff --git a/specs/plugin-extensibility.md b/specs/plugin-extensibility.md
@@ -424,8 +424,6 @@ All response attributes are required.
 
 ## Verification extensibility
 
-[notaryproject/roadmap#27](https://github.com/notaryproject/roadmap/issues/27)
-
 ### Requirements
 
 * The interface MUST NOT be tied to a specific signature envelope format.
@@ -493,13 +491,21 @@ This allows Notary v2 implementations to perform the same logic themselves, if t
     { 
        "contentType" : "application/vnd.cncf.notary.payload.v1+json",
        // One of notary.default.x509 or notary.signingAuthority.x509
-       "signingScheme" : "notary.default.x509",
+       "signingScheme" : "notary.default.x509" | "notary.signingAuthority.x509",
        // Value is always RFC 3339 formatted date time string
        "expiry": "2022-10-06T07:01:20Z", 
+       // if signingScheme is notary.signingAuthority.x509.
+       "authenticSigningTime": "2022-04-06T07:01:20Z",
+       // Name of the verification plugin
+       "verificationPlugin": "com.example.nv2plugin",
+       // Optional plugin minimum version, if present.
+       "verificationPluginMinVersion": "1.0.0",
+       // Map of extended attributes
+       // Extended attributes values support JSON primitive values string, number and null
        "extendedAttributes" : {
            // Map of extended attributes
           // Extended attributes values support JSON primitive values string, number and null.
-           "name" : primitive-value 
+           "name" : "<primitive-value>" 
        }
     },
 
@@ -535,11 +541,8 @@ All response attributes are required.
 ```jsonc
 {
   "verificationResults" : {
-    // Map of results. Key must match the set of
-    // verification capabilities 
-    // in verify-signature request's trustPolicy.signatureVerification attribute.
-    //  SIGNATURE_VERIFIER.TRUSTED_IDENTITY
-    //  SIGNATURE_VERIFIER.REVOCATION_CHECK
+        // Map of results. Key must match the set of verification capabilities 
+        // in verify-signature request's trustPolicy.signatureVerification attribute.
         "SIGNATURE_VERIFIER.TRUSTED_IDENTITY" :
         {
             // The result of a verification check
@@ -579,18 +582,8 @@ All response attributes are required.
 * THROTTLED - The verification process was throttled and can be retried by Notation.
 * ERROR - Any general error that does not fall into previous error categories.
 
-## Threat Model
-
-TBD [#135](https://github.com/notaryproject/notaryproject/issues/135)
-
 ## FAQ
 
 **Q: Will Notation generate timestamp signature for Signature Envelope Generator plugin or its responsibility of plugin publisher?**
 
 **A :** If the envelope generated by a Signature Envelope Generator plugin contains timestamp signature, Notation will not append additional timestamp signature, else it will generate the timestamp signature and append it to the envelope as an unsigned attribute.
-
-## Open Items
-
-* [Issue #151](https://github.com/notaryproject/notation/issues/151) - Add Notation command line options to pass raw signature generated by existing crypto tools.
-* What standard providers should be supported?
-* Support for chaining plugins. It allows us to separate out and compose things like signing, TSA integration, push to transparency log.
diff --git a/specs/trust-store-trust-policy.md b/specs/trust-store-trust-policy.md
@@ -39,18 +39,22 @@ $XDG_CONFIG_HOME/notation/trust-store
                   /sub-dir       # sub directory is ignored
                     cert-3.pem   # certs under sub directory is ignored
             /acme-rockets-ca2
-                cert1.pem
+                cert4.pem
             /wabbit-networks
-                cert3.crt
+                cert5.crt
+        /signingAuthority
+            /acme-network-sa
+                cert10.pem
         /tsa
             /publicly-trusted-tsa
                 tsa-cert1.pem
 ```
 
-The Trust store currently supports two kinds of identities, additional identities may be supported in future :
+The Trust store currently supports three kinds of identities, additional identities may be supported in future :
 
 - **Certificates**: The `x509/ca` trust store contains named stores that contain Certificate Authority (CA) root certificates.
-- **Timestamping Certificates**: The `x509/tsa` trust store contains named stores with Time Stamping Authority (TSA) root certificates. **NOTE** TSA based timestamping will not be available in `notation` RC1.
+- **SigningAuthority Certificate**: The `x509/signingAuthority` trust store contains named stores that contain Siging Authority's root certificates.
+- **Timestamping Certificates**: The `x509/tsa` trust store contains named stores with Time Stamping Authority (TSA) root certificates.
 
 Any additional sub directories under names stores and certificates in it are ignored. **NOTE**: Implementation SHOULD warn if it finds sub directories with certificates under a named store, to help diagnose misconfigured store.
 
@@ -160,8 +164,7 @@ Trust policy for the scenario where ACME Rockets uses some artifacts signed by W
   An *object* that specifies a predefined verification level, with an option to override Notary v2 defined verification level if user wants to specify a [custom verification level](#custom-verification-level).
     - **`level`**(*string*): A REQUIRED property that specifies the verification level, supported values are `strict`, `permissive`, `audit` and `skip`. Detailed explaination of each level is present [here](#signatureverification-details).
     - **`override`**(*map of string-string*): This OPTIONAL map is used to specify a [custom verification level](#custom-verification-level).
-  - **`trustStores`**(*array of string*): This REQUIRED property specifies a set of one or more named trust stores, each of which contain the trusted roots against which signatures are verified. Each named trust store uses the format `{trust-store-type}:{named-store}`. Currently supported values for `trust-store-type` are `ca` and `tsa`.
-    - **NOTE**: When support for publicly trusted TSA is available, `tsa:publicly-trusted-tsa` is the default value, and implied without explictly specifying it. If a custom TSA is used the format `ca:acme-rockets,tsa:acme-tsa` is supported to specify it.
+  - **`trustStores`**(*array of string*): This REQUIRED property specifies a set of one or more named trust stores, each of which contain the trusted roots against which signatures are verified. Each named trust store uses the format `{trust-store-type}:{named-store}`. Currently supported values for `trust-store-type` are `ca`, `signingAuthority` and `tsa`. For publicly trusted TSA, `tsa:publicly-trusted-tsa` is the default value, and implied without explictly specifying it. If a custom TSA is used the format `ca:acme-rockets,tsa:acme-tsa` is supported to specify it.
   - **`trustedIdentities`**(*array of strings*): This REQUIRED property specifies a set of identities that the user trusts. For X.509 PKI, it supports list of elements/attributes of the signing certificate's subject. For more information, see [identities constraints](#trusted-identities-constraints) section. A value `*` is supported if user trusts any identity (signing certificate) issued by the CA(s) in `trustStore`.
 
 #### Signature Verification details
@@ -206,8 +209,6 @@ The following table shows the resultant validation action, either *enforced* (ve
 
 **Revocation check** : Guarantees that the signing identity is still trusted at signature verification time. Events such as key or system compromise can make a signing identity that was previously trusted, to be subsequently untrusted. This guarantee typically requires a verification-time call to an external system, which may not be consistently reliable. The `permissive` verification level only logs failures of revocation check and does not enforce it. If a particular revocation mechanism is reliable, use `strict` verification level instead.
 
-- **NOTE** : `notation` RC1 will not have in built support for Revocation Check feature, see [Key Management - Rescinding Signatures (CRL)](https://github.com/notaryproject/notaryproject/issues/72) for details. When this feature is subsequently implemented, the `strict` verification level will **enforce** this validation, and will fail signatures which would previously pass signature verification when revocation checks were not supported. This is considered a **breaking change**, but is the appropriate behavior for a `strict` verification level.
-
 #### Custom Verification Level
 
 Signature verification levels provide Notary v2 defined behavior for each validation e.g. `strict` will always *enforce* authenticity validation. For fine grained control over validations that occur during signature verification, users can define a custom level which overrides the behavior of an existing verification level.
@@ -282,9 +283,8 @@ The RDN consists of an attribute type name followed by an equal sign and the str
 
 ### Extended Validation
 
-The implementation must allow the user to execute custom validations. These custom validation MUST have access to all the information available in the signature envelope like payload, signed attributes, unsigned attributes, and signature.
+Notary v2 allows user to execute custom validations during verificaton using plugins. Please refer [plugin-extensibility.md](plugin-extensibility.md#verification-extensibility) for more information.
 
-TODO: Update this section after [verification plugin spec](https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md#verification-extensibility) is ready.
 
 ## Signature Verification