From df1e729f1bd22e1365bc746cc06dfbd738d1103e Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Thu, 18 Aug 2022 15:59:19 +0800 Subject: [PATCH 01/13] Build:Bump dependencies Signed-off-by: Yi Zha --- go.mod | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/go.mod b/go.mod index 947a2fcc2..2a30d9923 100644 --- a/go.mod +++ b/go.mod @@ -5,12 +5,12 @@ go 1.18 require ( github.com/distribution/distribution/v3 v3.0.0-20220729163034-26163d82560f github.com/docker/docker-credential-helpers v0.6.4 - github.com/notaryproject/notation-core-go v0.0.0-20220809210532-f0a54093ba32 - github.com/notaryproject/notation-go v0.9.0-alpha.1.0.20220816013743-c350ef73e5f0 + github.com/notaryproject/notation-core-go v0.10.0-alpha.3 + github.com/notaryproject/notation-go v0.10.0-alpha.3 github.com/opencontainers/go-digest v1.0.0 github.com/spf13/cobra v1.5.0 github.com/spf13/pflag v1.0.5 - oras.land/oras-go/v2 v2.0.0-rc.1.0.20220727034506-eb13fdfeefa6 + oras.land/oras-go/v2 v2.0.0-rc.2 ) require ( From bcc2ea4cfbd993b53d00697057ecf3079697d60f Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Thu, 18 Aug 2022 16:29:35 +0800 Subject: [PATCH 02/13] Build: Bump dependencies Signed-off-by: Yi Zha --- go.mod | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/go.mod b/go.mod index 2a30d9923..abf82bccb 100644 --- a/go.mod +++ b/go.mod @@ -5,7 +5,7 @@ go 1.18 require ( github.com/distribution/distribution/v3 v3.0.0-20220729163034-26163d82560f github.com/docker/docker-credential-helpers v0.6.4 - github.com/notaryproject/notation-core-go v0.10.0-alpha.3 + github.com/notaryproject/notation-core-go v0.1.0-alpha.3 github.com/notaryproject/notation-go v0.10.0-alpha.3 github.com/opencontainers/go-digest v1.0.0 github.com/spf13/cobra v1.5.0 From f72b2a67ec987115f250637a7b4a51f320434788 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Thu, 18 Aug 2022 16:49:37 +0800 Subject: [PATCH 03/13] Build: Bump dependencies Signed-off-by: Yi Zha --- go.sum | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/go.sum b/go.sum index 2e5ab4a73..0258b2107 100644 --- a/go.sum +++ b/go.sum @@ -9,10 +9,10 @@ github.com/golang-jwt/jwt/v4 v4.4.2 h1:rcc4lwaZgFMCZ5jxF9ABolDcIHdBytAFgqFPbSJQA github.com/golang-jwt/jwt/v4 v4.4.2/go.mod h1:m21LjoU+eqJr34lmDMbreY2eSTRJ1cv77w39/MY0Ch0= github.com/inconshreveable/mousetrap v1.0.0 h1:Z8tu5sraLXCXIcARxBp/8cbvlwVa7Z1NHg9XEKhtSvM= github.com/inconshreveable/mousetrap v1.0.0/go.mod h1:PxqpIevigyE2G7u3NXJIT2ANytuPF1OarO4DADm73n8= -github.com/notaryproject/notation-core-go v0.0.0-20220809210532-f0a54093ba32 h1:dMZIRt5CMjl9eLJFywlBDDps3AWjgyy6axFnYONak8g= -github.com/notaryproject/notation-core-go v0.0.0-20220809210532-f0a54093ba32/go.mod h1:n+UjcUoYhvawO/JW5JfZerUUsGbHYTd4wH8ndGeeyas= -github.com/notaryproject/notation-go v0.9.0-alpha.1.0.20220816013743-c350ef73e5f0 h1:YQS5UhcYc0O7vVoIE2kdeXbZKGVoxEiLJwnm6C8PgQo= -github.com/notaryproject/notation-go v0.9.0-alpha.1.0.20220816013743-c350ef73e5f0/go.mod h1:crBca+qGBV39lmSnmyJM0L/2gAa/XlEWrID3rXYENXo= +github.com/notaryproject/notation-core-go v0.1.0-alpha.3 h1:gzB+h5TGzuocWiJxuYZgE/FwUIbJyKAHfk2hWSBbCGg= +github.com/notaryproject/notation-core-go v0.1.0-alpha.3/go.mod h1:Wfyh5SrQ718JegKPhTs7y74rXg86tWd5NfOx2uHK1nI= +github.com/notaryproject/notation-go v0.10.0-alpha.3 h1:jDIwUzGHsxwXuIFYLwQ1pPzpO5GFcoaA1X78EixIBo4= +github.com/notaryproject/notation-go v0.10.0-alpha.3/go.mod h1:PQuu7OZweVU5erEyqriguCvK7CCGF+X5psDj63iEvGk= github.com/opencontainers/distribution-spec/specs-go v0.0.0-20220620172159-4ab4752c3b86 h1:Oumw+lPnO8qNLTY2mrqPJZMoGExLi/0h/DdikoLTXVU= github.com/opencontainers/distribution-spec/specs-go v0.0.0-20220620172159-4ab4752c3b86/go.mod h1:aA4vdXRS8E1TG7pLZOz85InHi3BiPdErh8IpJN6E0x4= github.com/opencontainers/go-digest v1.0.0 h1:apOUWs51W5PlhuyGyz9FCeeBIOUDA/6nW8Oi/yOhh5U= @@ -37,5 +37,5 @@ golang.org/x/sys v0.0.0-20220731174439-a90be440212d/go.mod h1:oPkhp1MJrh7nUepCBc gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI= gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ= -oras.land/oras-go/v2 v2.0.0-rc.1.0.20220727034506-eb13fdfeefa6 h1:fbJtzJbpZCtdaAvjPvjlTf8CGsUE1+mClxyh/MPne6I= -oras.land/oras-go/v2 v2.0.0-rc.1.0.20220727034506-eb13fdfeefa6/go.mod h1:IZRIoIJqkAH6x0pL3tVnpyPUyZgthjSyPcH2kgJvBMo= +oras.land/oras-go/v2 v2.0.0-rc.2 h1:dks9BxPg6HQOxn5+jVNuTFl45FuYvHfLQ6wcP7hVRdE= +oras.land/oras-go/v2 v2.0.0-rc.2/go.mod h1:IZRIoIJqkAH6x0pL3tVnpyPUyZgthjSyPcH2kgJvBMo= From 4754adba82834d3ce0ddafcbded1601a5d254a5e Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Tue, 8 Nov 2022 12:20:00 +0800 Subject: [PATCH 04/13] spec: update sign cli spec for tag to digest Signed-off-by: Yi Zha --- specs/commandline/sign.md | 95 +++++++++++++++++++++++++++++---------- 1 file changed, 72 insertions(+), 23 deletions(-) diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index 995ce60b6..b687e4367 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 that is stored in a registry. Always use a `digest` to identify an artifact. `Tags` are mutable, but `digests` uniquely and immutably identify artifacts. 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 +Sign succeeded. Signature has been attached to /@. +``` + +If a `tag` is used to identify the OCI artifact, the output message is as following: + +```test +Warning: Tag is used. Always use digest to identify the reference uniquely and immutably. +Resolve tag "" to digest "" +Sign succeeded. Signature has been attached to /@. +``` ## Outline @@ -15,6 +29,7 @@ Usage: notation sign [flags] Flags: + -d, --debug print out debug output -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. @@ -27,37 +42,38 @@ Flags: ## Usage -### Sign a container image +### Sign an OCI artifact stored in a registry using a remote key ```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 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. -# Sign a container image using the default signing key -notation sign /: +# 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 -# 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 using a remote key notation sign /@ ``` -### Sign a container image using a remote key +An example for a successful signing: ```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. +$ notation sign localhost:5000/net-monitor@sha256:1111111111111111111111111111111111111111111111111111111111111111 +Sign succeeded. Signature has been attached to localhost:5000/net-monitor@sha2561111111111111111111111111111111111111111111111111111111111111111 +``` -# 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 +### Sign an OCI artifact using COSE signature format -# sign a container image using a remote key -notation sign /: +```shell +# Prerequisites: +# A default signing key is configured using CLI "notation key" + +# 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 +83,51 @@ 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: + +```shell +$ notation sign localhost:5000/net-monitor:v1 +Warning: Tag is used. Always use digest to identify the reference uniquely and immutably. +Resolve tag "v1" to digest "sha256:1111111111111111111111111111111111111111111111111111111111111111" +Sign succeeded. Signature has been attached to localhost:5000/net-monitor@sha256:1111111111111111111111111111111111111111111111111111111111111111 +``` + +### Sign an OCI artifact with debug option + +```shell +notation sign --debug /@ +``` + +An example for a successful signing: + +```shell +$ notation sign --debug localhost:5000/net-monitor@sha256:1111111111111111111111111111111111111111111111111111111111111111 +Use signature format jws. +Sign succeeded. Signature has been attached to localhost:5000/net-monitor@sha2561111111111111111111111111111111111111111111111111111111111111111 ``` From ec8782b9ea1fa4e7b8b61271204a6ae074069bb4 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Tue, 8 Nov 2022 17:32:49 +0800 Subject: [PATCH 05/13] spec: update digest value Signed-off-by: Yi Zha --- specs/commandline/sign.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index b687e4367..a73c6b040 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -59,8 +59,8 @@ notation sign /@ An example for a successful signing: ```shell -$ notation sign localhost:5000/net-monitor@sha256:1111111111111111111111111111111111111111111111111111111111111111 -Sign succeeded. Signature has been attached to localhost:5000/net-monitor@sha2561111111111111111111111111111111111111111111111111111111111111111 +$ notation sign localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 +Sign succeeded. Signature has been attached to localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 ``` ### Sign an OCI artifact using COSE signature format @@ -70,7 +70,7 @@ Sign succeeded. Signature has been attached to localhost:5000/net-monitor@sha256 # A default signing key is configured using CLI "notation key" # Use option "--signature-format" to set the signature format to COSE. -notation sign --signature-format cose /@ +$ notation sign --signature-format cose /@ ``` ### Sign an OCI artifact stored in a registry using the default signing key @@ -80,7 +80,7 @@ notation sign --signature-format cose /@ # A default signing key is configured using CLI "notation key" # Use a digest that uniquely and immutably identifies an OCI artifact. -notation sign /@ +$ notation sign /@ ``` ### Sign an OCI artifact stored in a registry and specify the signature expiry duration, for example 24 hours @@ -93,10 +93,10 @@ notation sign --expiry 24h /@ ```shell # List signing keys to get the key name -notation key list +$ 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 @@ -106,7 +106,7 @@ notation sign --key /@ # A default signing key is configured using CLI "notation key" # Use a tag to identify a container image -notation sign /: +$ notation sign /: ``` An example for a successful signing: @@ -114,8 +114,8 @@ An example for a successful signing: ```shell $ notation sign localhost:5000/net-monitor:v1 Warning: Tag is used. Always use digest to identify the reference uniquely and immutably. -Resolve tag "v1" to digest "sha256:1111111111111111111111111111111111111111111111111111111111111111" -Sign succeeded. Signature has been attached to localhost:5000/net-monitor@sha256:1111111111111111111111111111111111111111111111111111111111111111 +Resolve tag "v1" to digest "sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9" +Sign succeeded. Signature has been attached to localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 ``` ### Sign an OCI artifact with debug option @@ -127,7 +127,7 @@ notation sign --debug /@ An example for a successful signing: ```shell -$ notation sign --debug localhost:5000/net-monitor@sha256:1111111111111111111111111111111111111111111111111111111111111111 +$ notation sign --debug localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 Use signature format jws. -Sign succeeded. Signature has been attached to localhost:5000/net-monitor@sha2561111111111111111111111111111111111111111111111111111111111111111 +Sign succeeded. Signature has been attached to localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 ``` From 783c34319b65ccbd9514f69d441a87cee0ea3e2a Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Tue, 8 Nov 2022 17:48:03 +0800 Subject: [PATCH 06/13] spec: update debug description Signed-off-by: Yi Zha --- specs/commandline/sign.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index a73c6b040..ec7caf6b2 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -29,7 +29,7 @@ Usage: notation sign [flags] Flags: - -d, --debug print out debug output + -d, --debug enable verbose output -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. From 98c95033db4b403257468e6132bc699436d50fa1 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Mon, 14 Nov 2022 14:50:57 +0800 Subject: [PATCH 07/13] spec: update according to review comments Signed-off-by: Yi Zha --- specs/commandline/sign.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index ec7caf6b2..b3db43828 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -9,15 +9,15 @@ Signs an OCI artifact that is stored in a registry. Always use a `digest` to ide 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 -Sign succeeded. Signature has been attached to /@. +Signing of artifact succeeded and the signature is attached to /@. ``` If a `tag` is used to identify the OCI artifact, the output message is as following: ```test -Warning: Tag is used. Always use digest to identify the reference uniquely and immutably. -Resolve tag "" to digest "" -Sign succeeded. Signature has been attached to /@. +Warning: A tag is used to identify the artifact for signing. Artifact tags are mutable. Use digests to uniquely identify artifacts and avoid mutability. +Resolving artifact tag '' to digest '' before signing. +Signing of artifact succeeded and the signature is attached to /@. ``` ## Outline @@ -60,7 +60,7 @@ An example for a successful signing: ```shell $ notation sign localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 -Sign succeeded. Signature has been attached to localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 +Signing of artifact succeeded and the signature is attached to localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9. ``` ### Sign an OCI artifact using COSE signature format @@ -113,9 +113,9 @@ An example for a successful signing: ```shell $ notation sign localhost:5000/net-monitor:v1 -Warning: Tag is used. Always use digest to identify the reference uniquely and immutably. -Resolve tag "v1" to digest "sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9" -Sign succeeded. Signature has been attached to localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 +Warning: A tag is used to identify the artifact for signing. Artifact tags are mutable. Use digests to uniquely identify artifacts and avoid mutability. +Resolving artifact tag 'v1' to digest 'sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9' before signing. +Signing of artifact succeeded and the signature is attached to localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9. ``` ### Sign an OCI artifact with debug option @@ -129,5 +129,5 @@ An example for a successful signing: ```shell $ notation sign --debug localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 Use signature format jws. -Sign succeeded. Signature has been attached to localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 +Signing of artifact succeeded and the signature is attached to localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9. ``` From 3d5a8875a15b3b8faff39e9f9b190f5f21b6c020 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Fri, 18 Nov 2022 13:53:08 +0800 Subject: [PATCH 08/13] spec: remove the changes for debug option Signed-off-by: Yi Zha --- specs/commandline/sign.md | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index b3db43828..28885421d 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -29,7 +29,6 @@ Usage: notation sign [flags] Flags: - -d, --debug enable verbose output -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. @@ -118,16 +117,3 @@ Resolving artifact tag 'v1' to digest 'sha256:b94d27b9934d3e08a52e52d7da7dabfac4 Signing of artifact succeeded and the signature is attached to localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9. ``` -### Sign an OCI artifact with debug option - -```shell -notation sign --debug /@ -``` - -An example for a successful signing: - -```shell -$ notation sign --debug localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 -Use signature format jws. -Signing of artifact succeeded and the signature is attached to localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9. -``` From e52a8bffa75d962addff4e491da0f52dd286d24d Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Mon, 21 Nov 2022 13:10:43 +0800 Subject: [PATCH 09/13] spec: update according to comments Signed-off-by: Yi Zha --- specs/commandline/sign.md | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index 28885421d..12742629e 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -4,20 +4,20 @@ Use `notation sign` to sign artifacts. -Signs an OCI artifact that is stored in a registry. Always use a `digest` to identify an artifact. `Tags` are mutable, but `digests` uniquely and immutably identify artifacts. If a tag is used, notation resolves the tag to the `digest` before signing. +Signs an OCI artifact stored in the registry. Always sign artifact using digest(`@sha256:...`) rather than a tag(`:latest`) 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 -Signing of artifact succeeded and the signature is attached to /@. +Successfully signed /@. ``` If a `tag` is used to identify the OCI artifact, the output message is as following: ```test -Warning: A tag is used to identify the artifact for signing. Artifact tags are mutable. Use digests to uniquely identify artifacts and avoid mutability. +Warning: Always sign the artifact using digest(`@sha256:...`) rather than a tag(`:latest`) because tags are mutable and a tag reference can point to a different artifact than the one signed. Resolving artifact tag '' to digest '' before signing. -Signing of artifact succeeded and the signature is attached to /@. +Successfully signed /@ ``` ## Outline @@ -41,17 +41,17 @@ Flags: ## Usage -### Sign an OCI artifact stored in a registry using a remote key +### Sign an OCI artifact ```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. +# - 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. -# Add a default signing key referencing the key identifier for the remote key, and the plugin associated with it. +# Add a default signing key referencing the remote key identifier, and the plugin associated with it. notation key add --default --name --plugin --id -# sign an artifact stored in a registry using a remote key +# sign an artifact stored in a registry notation sign /@ ``` @@ -59,7 +59,7 @@ An example for a successful signing: ```shell $ notation sign localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 -Signing of artifact succeeded and the signature is attached to localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9. +Successfully signed localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9. ``` ### Sign an OCI artifact using COSE signature format @@ -112,8 +112,7 @@ An example for a successful signing: ```shell $ notation sign localhost:5000/net-monitor:v1 -Warning: A tag is used to identify the artifact for signing. Artifact tags are mutable. Use digests to uniquely identify artifacts and avoid mutability. +Warning: Always sign the artifact using digest(`@sha256:...`) rather than a tag(`:latest`) because tags are mutable and a tag reference can point to a different artifact than the one signed. Resolving artifact tag 'v1' to digest 'sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9' before signing. -Signing of artifact succeeded and the signature is attached to localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9. +Successfully signed localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 ``` - From 997c8dc16ec3580d0b730e2c884aa5edc1484572 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Thu, 24 Nov 2022 11:33:53 +0800 Subject: [PATCH 10/13] update typos Signed-off-by: Yi Zha --- specs/commandline/sign.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index 12742629e..8483604a8 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -16,7 +16,7 @@ If a `tag` is used to identify the OCI artifact, the output message is as follow ```test Warning: Always sign the artifact using digest(`@sha256:...`) rather than a tag(`:latest`) because tags are mutable and a tag reference can point to a different artifact than the one signed. -Resolving artifact tag '' to digest '' before signing. +Resolved artifact tag '' to digest '' before signing. Successfully signed /@ ``` @@ -113,6 +113,6 @@ An example for a successful signing: ```shell $ notation sign localhost:5000/net-monitor:v1 Warning: Always sign the artifact using digest(`@sha256:...`) rather than a tag(`:latest`) because tags are mutable and a tag reference can point to a different artifact than the one signed. -Resolving artifact tag 'v1' to digest 'sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9' before signing. +Resolved artifact tag 'v1' to digest 'sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9' before signing. Successfully signed localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 ``` From 8809288faa5a4a183bd2a27f9ef7ab4a7846047e Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Mon, 28 Nov 2022 13:46:21 +0800 Subject: [PATCH 11/13] update per comments Signed-off-by: Yi Zha --- specs/commandline/sign.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index 8483604a8..222faaedc 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -4,7 +4,7 @@ Use `notation sign` to sign artifacts. -Signs an OCI artifact stored in the registry. Always sign artifact using digest(`@sha256:...`) rather than a tag(`:latest`) 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. +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: @@ -15,7 +15,7 @@ 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(`:latest`) because tags are mutable and a tag reference can point to a different artifact than the one signed. +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 '' to digest '' before signing. Successfully signed /@ ``` @@ -57,7 +57,7 @@ notation sign /@ An example for a successful signing: -```shell +```console $ notation sign localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 Successfully signed localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9. ``` @@ -69,7 +69,7 @@ Successfully signed localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da # A default signing key is configured using CLI "notation key" # Use option "--signature-format" to set the signature format to COSE. -$ notation sign --signature-format cose /@ +notation sign --signature-format cose /@ ``` ### Sign an OCI artifact stored in a registry using the default signing key @@ -79,7 +79,7 @@ $ notation sign --signature-format cose /@ # A default signing key is configured using CLI "notation key" # Use a digest that uniquely and immutably identifies an OCI artifact. -$ notation sign /@ +notation sign /@ ``` ### Sign an OCI artifact stored in a registry and specify the signature expiry duration, for example 24 hours @@ -92,10 +92,10 @@ notation sign --expiry 24h /@ ```shell # List signing keys to get the key name -$ notation key list +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 @@ -105,14 +105,14 @@ $ notation sign --key /@ # A default signing key is configured using CLI "notation key" # Use a tag to identify a container image -$ notation sign /: +notation sign /: ``` An example for a successful signing: -```shell +```console $ notation sign localhost:5000/net-monitor:v1 -Warning: Always sign the artifact using digest(`@sha256:...`) rather than a tag(`:latest`) because tags are mutable and a tag reference can point to a different artifact than the one signed. +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 ``` From 5b18a557a6db682ac02b03c1becfb237fa98e0c0 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Thu, 1 Dec 2022 16:56:39 +0800 Subject: [PATCH 12/13] update according to comments Signed-off-by: Yi Zha --- specs/commandline/sign.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index 222faaedc..98b2c36e6 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -9,13 +9,13 @@ Signs an OCI artifact stored in the registry. Always sign artifact using digest( 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 /@. +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(`:v1`) because tags are mutable and a tag reference can point to a different artifact than the one signed. +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 /@ ``` @@ -59,7 +59,7 @@ An example for a successful signing: ```console $ notation sign localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 -Successfully signed localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9. +Successfully signed localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 ``` ### Sign an OCI artifact using COSE signature format From 5b9e582edd96227e7742263c27bd5c264ae6b87a Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Thu, 1 Dec 2022 21:47:17 +0800 Subject: [PATCH 13/13] update according to comments Signed-off-by: Yi Zha --- specs/commandline/sign.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index 98b2c36e6..a40bb8825 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -16,7 +16,7 @@ If a `tag` is used to identify the OCI artifact, the output message is as follow ```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. +Resolved artifact tag `` to digest `` before signing. Successfully signed /@ ``` @@ -113,6 +113,6 @@ 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. +Resolved artifact tag `v1` to digest `sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9` before signing. Successfully signed localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 ```