diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index a40bb8825..33c19d9ec 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -29,14 +29,15 @@ Usage: notation sign [flags] 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 /@ notation sign /@ ``` +### 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 /@ + +# 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 /@ +``` + ### 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 index b154caac9..e0d8b930d 100644 --- 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 /@ ``` +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 /@ + +The artifact was signed with the following user metadata. + +KEY VALUE + +``` + ## Outline ```text @@ -25,11 +36,12 @@ Usage: notation verify [flags] 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 -``` +``` \ No newline at end of file