Removes restrictions, clarifies flag description, reorders examples

Signed-off-by: Byron Chien <[email protected]>
notaryproject · Jan 4, 2023 · c7c5128 · c7c5128
1 parent 9eebe91
commit c7c5128
Show file tree

Hide file tree

Showing 2 changed files with 18 additions and 29 deletions.
diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md
@@ -40,11 +40,6 @@ Flags:
   -um, --user-metadata strings    {key}={value} pairs that are added to the signature
 ```
 
-### User Metadata Restrictions
-- `notation sign` must fail if metadata keys or values are not strings
-- `notation sign` must fail if duplicate metadata keys are provided
-- `notation sign` must fail if metadata keys conflict with reserved Notary or OCI keys
-
 ## Usage
 
 ### Sign an OCI artifact

diff --git a/specs/commandline/verify.md b/specs/commandline/verify.md
@@ -40,7 +40,7 @@ Flags:
        --plain-http              registry access via plain HTTP
        --plugin-config strings   {key}={value} pairs that are passed as it is to a plugin, if the verification is associated with a verification plugin, refer plugin documentation to set appropriate values
   -u,  --username string         username for registry operations (default to $NOTATION_USERNAME if not specified)
-  -um, --user-metadata strings   {key}={value} pairs that must be present in the signature for successful verification if provided
+  -um, --user-metadata strings   user defined {key}={value} pairs that must be present in the signature for successful verification if provided
 ```
 
 ## Usage
@@ -124,60 +124,54 @@ An example of output messages for a successful verification:
 Successfully verified signature for localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9
 ```
 
-### Verify signatures on an OCI artifact identified by a tag
+### Verify signatures on an OCI artifact with user metadata
 
-A tag is resolved to a digest first before verification.
+Use the `--user-metadata` flag to verify that provided key-value pairs are present in the payload of the valid signature.
 
 ```shell
-# Prerequisites: Signatures are stored in a registry referencing the signed OCI artifact
-
-# Verify signatures on an OCI artifact identified by the tag
-notation verify localhost:5000/net-monitor:v1
+# Verify signatures on the supplied OCI artifact identified by the digest and verify that io.wabbit-networks.data=foo is present in the signed payload
+notation verify localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 --user-metadata io.wabbit-networks.data=foo
 ```
 
 An example of output messages for a successful verification:
 
 ```text
-Resolved artifact tag `v1` to digest `sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9` before verification.
-Warning: The resolved digest may not point to the same signed artifact, since tags are mutable.
 Successfully verified signature for localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9
+
+User Metadata:
+- io.wabbit-networks.data : foo
 ```
 
-### Verify signatures on an OCI artifact with user metadata
+### Verify signatures on an OCI artifact and format output as json
 
-Use the `--user-metadata` flag to verify that provided key-value pairs are present in the payload of the valid signature.
+Use the `--output` flag to configure the format of signature information returned on successful verification.
 
 ```shell
-# Prerequisites: Signatures are stored in a registry referencing the signed OCI artifact
-# Verify signatures on an OCI artifact identified by the tag and verify that io.wabbit-networks.data=foo is present in the signed payload
-notation verify localhost:5000/net-monitor:v1 --user-metadata io.wabbit-networks.data=foo
+
+# Verify signatures on the supplied OCI artifact identified by the digest and output result as json
+notation verify localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 --output json
 ```
 
 An example of output messages for a successful verification:
 
 ```text
-Resolved artifact tag `v1` to digest `sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9` before verification.
-Warning: The resolved digest may not point to the same signed artifact, since tags are mutable.
-Successfully verified signature for localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9
-
-User Metadata:
-- io.wabbit-networks.data : foo
+{"reference":"localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9","outcome":"Success","signatures":[{"digest":"sha256:73c803930ea3ba1e54bc25c2bdc53edd0284c62ed651fe7b00369da519a3c333","userMetadata":{"io.wabbit-networks.data":"foo"}}]}
 ```
 
-### Verify signatures on an OCI artifact and format output as json
+### Verify signatures on an OCI artifact identified by a tag
 
-Use the `--output` flag to configure the format of signature information returned on successful verification.
+A tag is resolved to a digest first before verification.
 
 ```shell
 # Prerequisites: Signatures are stored in a registry referencing the signed OCI artifact
 # Verify signatures on an OCI artifact identified by the tag
-notation verify localhost:5000/net-monitor:v1 --output json
+notation verify localhost:5000/net-monitor:v1
 ```
 
 An example of output messages for a successful verification:
 
 ```text
 Resolved artifact tag `v1` to digest `sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9` before verification.
 Warning: The resolved digest may not point to the same signed artifact, since tags are mutable.
-{"reference":"localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9","outcome":"Success","signatures":[{"digest":"sha256:73c803930ea3ba1e54bc25c2bdc53edd0284c62ed651fe7b00369da519a3c333","userMetadata":{"io.wabbit-networks.data":"foo"}}]}
+Successfully verified signature for localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9
 ```