spec: update cli sign spec for tag to digest translation (#439)

This PR is mainly to improve the output message of `notation sign`
command for tag to digest translation.

Signed-off-by: Yi Zha <[email protected]>
Signed-off-by: Yi Zha <[email protected]>

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 <registry>/<repository>@<digest>
+```
+
+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(`:<tag>`) because tags are mutable and a tag reference can point to a different artifact than the one signed.
+Resolved artifact tag `<tag>` to digest `<digest>` before signing.
+Successfully signed <registry>/<repository>@<digest>
+```
 
 ## 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 <key_name> <key_path> <cert_path>
-
-# Or change the default signing key to an existing signing key
-notation key update --default <key_name>
+# 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 <registry>/<repository>:<tag>
+# Add a default signing key referencing the remote key identifier, and the plugin associated with it.
+notation key add --default --name <key_name> --plugin <plugin_name> --id <remote_key_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 <registry>/<repository>@<digest>
 ```
 
-### 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 <key_name> --plugin <plugin_name> --id <remote_key_id>
+# A default signing key is configured using CLI "notation key"
 
-# sign a container image using a remote key
-notation sign <registry>/<repository>:<tag>
+# Use option "--signature-format" to set the signature format to COSE.
+notation sign --signature-format cose <registry>/<repository>@<digest>
 ```
 
-### 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 <registry>/<repository>:<tag>
 notation sign <registry>/<repository>@<digest>
 ```
 
-### 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 <registry>/<repository>:<tag>
+notation sign --expiry 24h <registry>/<repository>@<digest>
 ```
 
-### 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 <key_name> <registry>/<repository>:<tag>
+notation sign --key <key_name> <registry>/<repository>@<digest>
+```
+
+### 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 <registry>/<repository>:<tag>
+```
+
+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
 ```