doc: update notation sign and verify spec for metadata (#498)

Spec update to support notaryproject/roadmap#67 `notation sign`: - user will be able to specify additional key value pairs with the `--user-metadata` flag (`-um` short) that will be signed as part of the payload. `notation verify`: - user will be able to specify additional key value pairs with the `--user-metadata` flag (`-um` short) that must be present in the signature to pass verification. Signed-off-by: Byron Chien <chienb@amazon.com>
notaryproject · Jan 12, 2023 · 6fb9eef · 6fb9eef
1 parent ba4feb4
commit 6fb9eef
Show file tree

Hide file tree

Showing 2 changed files with 66 additions and 15 deletions.
diff --git a/specs/commandline/sign.md b/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

diff --git a/specs/commandline/verify.md b/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>
 ```
 
+A signature can have user defined metadata. 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 was 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,38 @@ 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: unable to find specified metadata in any signatures
+```
+
 ### 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 +167,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
-```
+```