diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index 995ce60b6..a40bb8825 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -4,7 +4,21 @@ Use `notation sign` to sign artifacts. -Signs an OCI artifact that is stored in a registry. Upon successful signing, the generated signature is pushed to the registry with the digest of the OCI artifact returned. +Signs an OCI artifact stored in the registry. Always sign artifact using digest(`@sha256:...`) rather than a tag(`:v1`) because tags are mutable and a tag reference can point to a different artifact than the one signed. If a tag is used, notation resolves the tag to the `digest` before signing. + +Upon successful signing, the generated signature is pushed to the registry and associated with the signed OCI artifact. The output message is printed out as following: + +```text +Successfully signed /@ +``` + +If a `tag` is used to identify the OCI artifact, the output message is as following: + +```test +Warning: Always sign the artifact using digest(`@sha256:...`) rather than a tag(`:`) because tags are mutable and a tag reference can point to a different artifact than the one signed. +Resolved artifact tag `` to digest `` before signing. +Successfully signed /@ +``` ## Outline @@ -27,37 +41,38 @@ Flags: ## Usage -### Sign a container image +### Sign an OCI artifact ```shell -# Add a key which uses a local private key and certificate, and make it a default signing key -notation key add --default --name - -# Or change the default signing key to an existing signing key -notation key update --default +# Prerequisites: +# - A signing plugin is installed. See plugin documentation (https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md) for more details. +# - Configure the signing plugin as instructed by plugin vendor. -# Sign a container image using the default signing key -notation sign /: +# Add a default signing key referencing the remote key identifier, and the plugin associated with it. +notation key add --default --name --plugin --id -# Or using container image digests instead of tags. A container image digest uniquely and immutably identifies a container image. +# sign an artifact stored in a registry notation sign /@ ``` -### Sign a container image using a remote key +An example for a successful signing: + +```console +$ notation sign localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 +Successfully signed localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 +``` + +### Sign an OCI artifact using COSE signature format ```shell # Prerequisites: -# - A compliant signing plugin is installed in notation. See notation plugin documentation (https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md) for more details. -# - User creates keys and certificates in a 3rd party key provider (e.g. key vault, key management service). The signing plugin installed in previous step must support generating signatures using this key provider. - -# Add a default signing key referencing the key identifier for the remote key, and the plugin associated with it. -notation key add --default --name --plugin --id +# A default signing key is configured using CLI "notation key" -# sign a container image using a remote key -notation sign /: +# Use option "--signature-format" to set the signature format to COSE. +notation sign --signature-format cose /@ ``` -### Sign an OCI artifact using the default signing key +### Sign an OCI artifact stored in a registry using the default signing key ```shell # Prerequisites: @@ -67,18 +82,37 @@ notation sign /: notation sign /@ ``` -### Sign a container image and specify the signature expiry duration, for example 1 day +### Sign an OCI artifact stored in a registry and specify the signature expiry duration, for example 24 hours ```shell -notation sign --expiry 1d /: +notation sign --expiry 24h /@ ``` -### Sign a container image using a specified signing key +### Sign an OCI artifact stored in a registry using a specified signing key ```shell # List signing keys to get the key name notation key list # Sign a container image using the specified key name -notation sign --key /: +notation sign --key /@ +``` + +### Sign an OCI artifact identified by a tag + +```shell +# Prerequisites: +# A default signing key is configured using CLI "notation key" + +# Use a tag to identify a container image +notation sign /: +``` + +An example for a successful signing: + +```console +$ notation sign localhost:5000/net-monitor:v1 +Warning: Always sign the artifact using digest(`@sha256:...`) rather than a tag(`:v1`) because tags are mutable and a tag reference can point to a different artifact than the one signed. +Resolved artifact tag `v1` to digest `sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9` before signing. +Successfully signed localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 ```