doc: update notation sign and verify spec for metadata

specs/commandline/sign.md

@@ -29,14 +29,15 @@ Usage:
   notation sign [flags] <reference>
 
 Flags:
-  -e, --expiry duration          optional expiry that provides a "best by use" time for the artifact. The duration is specified in minutes(m) and/or hours(h). For example: 12h, 30m, 3h20m
-  -h, --help                     help for sign
-  -k, --key string               signing key name, for a key previously added to notation's key list.
-  -p, --password string          password for registry operations (default to $NOTATION_PASSWORD if not specified)
-      --plain-http               registry access via plain HTTP
-      --plugin-config strings    {key}={value} pairs that are passed as it is to a plugin, refer plugin's documentation to set appropriate values
-      --signature-format string  signature envelope format, options: 'jws', 'cose' (default "jws")
-  -u, --username string          username for registry operations (default to $NOTATION_USERNAME if not specified)
+  -e,  --expiry duration          optional expiry that provides a "best by use" time for the artifact. The duration is specified in minutes(m) and/or hours(h). For example: 12h, 30m, 3h20m
+  -h,  --help                     help for sign
+  -k,  --key string               signing key name, for a key previously added to notation's key list.
+  -p,  --password string          password for registry operations (default to $NOTATION_PASSWORD if not specified)
+       --plain-http               registry access via plain HTTP
+       --plugin-config strings    {key}={value} pairs that are passed as it is to a plugin, refer plugin's documentation to set appropriate values
+       --signature-format string  signature envelope format, options: 'jws', 'cose' (default "jws")
+  -u,  --username string          username for registry operations (default to $NOTATION_USERNAME if not specified)
+  -m,  --user-metadata strings    {key}={value} pairs that are added to the signature payload
 ```
 
 ## Usage
@@ -82,6 +83,19 @@ notation sign --signature-format cose <registry>/<repository>@<digest>
 notation sign <registry>/<repository>@<digest>
 ```
 
+### Sign an OCI Artifact with user metadata
+
+```shell
+# Prerequisites: 
+# A default signing key is configured using CLI "notation key"
+
+# sign an artifact stored in a registry and add user-metadata io.wabbit-networks.buildId=123 to the payload
+notation sign --user-metadata io.wabbit-networks.buildId=123 <registry>/<repository>@<digest>
+
+# sign an artifact stored in a registry and add user-metadata io.wabbit-networks.buildId=123 and io.wabbit-networks.buildTime=1672944615 to the payload
+notation sign --user-metadata io.wabbit-networks.buildId=123 --user-metadata io.wabbit-networks.buildTime=1672944615 <registry>/<repository>@<digest>
+```
+
 ### Sign an OCI artifact stored in a registry and specify the signature expiry duration, for example 24 hours
 
 ```shell

specs/commandline/verify.md

@@ -16,6 +16,17 @@ Warning: The resolved digest may not point to the same signed artifact, since ta
 Successfully verified signature for <registry>/<repository>@<digest>
 ```
 
+The signed descriptor may have user defined metadata attached. If the signature for the OCI artifact contains any metadata, the output message is as follows:
+
+```text
+Successfully verified signature for <registry>/<repository>@<digest>
+
+The artifact is signed with the following user metadata.
+
+KEY    VALUE
+<key>  <value>
+```
+
 ## Outline
 
 ```text
@@ -25,11 +36,12 @@ Usage:
   notation verify [flags] <reference>
 
 Flags:
-  -h, --help                    help for verify
-  -p, --password string         password for registry operations (default to $NOTATION_PASSWORD if not specified)
-      --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)
+  -h,  --help                    help for verify
+  -p,  --password string         password for registry operations (default to $NOTATION_PASSWORD if not specified)
+       --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)
+  -m,  --user-metadata strings   user defined {key}={value} pairs that must be present in the signature for successful verification if provided
 ```
 
 ## Usage
@@ -113,13 +125,59 @@ 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 with user metadata
+
+Use the `--user-metadata` flag to verify that provided key-value pairs are present in the payload of the valid signature.
+
+```shell
+# Verify signatures on the supplied OCI artifact identified by the digest and verify that io.wabbit-networks.buildId=123 is present in the signed payload
+notation verify --user-metadata io.wabbit-networks.buildId=123 localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9
+```
+
+An example of output messages for a successful verification:
+
+```text
+Successfully verified signature for localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9
+
+The artifact is signed with the following user metadata.
+
+KEY                         VALUE
+io.wabbit-networks.buildId  123
+```
+
+An example of output messages for an unsuccessful verification:
+
+```text
+Error: signature verification failed for all the signatures associated with localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9
+```
+
+An example of output messages for an unsuccessful verification with verbose logging enabled:
+
+```text
+INFO Checking whether signature verification should be skipped or not
+INFO Check over. Trust policy is not configured to skip signature verification
+INFO Processing signature with digest: sha256:dbb22c0686b714ccbb53e4579771ee0f9ab9d37cd77cadb767549322742979f3
+INFO User Metadata flag is present. Checking signature metadata for specified values.
+Error: signature verification failed for all the signatures associated with localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9
+```
+
+An example of output messages for an unsuccessful verification with debug logging enabled:
+
+```text
+...
+INFO User Metadata flag is present. Checking signature metadata for specified values.
+DEBU[2023-01-05T11:35:07-08:00] Verifying that metadata { "io.wabbit-networks.buildId":"123" } is present in signature metadata.
+DEBU[2023-01-05T11:35:07-08:00] Signature metadata: { "io.wabbit-networks.buildId":"321" }
+DEBU[2023-01-05T11:35:07-08:00] Error: specified metadata is not present in the signature.
+Error: signature verification failed for all the signatures associated with localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9
+```
+
 ### Verify signatures on an OCI artifact identified by a tag
 
 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
 ```
@@ -130,4 +188,4 @@ An example of output messages for a successful verification:
 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
-```
+```