From df1e729f1bd22e1365bc746cc06dfbd738d1103e Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Thu, 18 Aug 2022 15:59:19 +0800 Subject: [PATCH 01/18] 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/18] 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/18] 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 57740f5ec925f2af28b6a56aa4e5439e37da10bf Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Tue, 20 Sep 2022 16:52:56 +0800 Subject: [PATCH 04/18] Add notation sign CLI spec Signed-off-by: Yi Zha --- specs/commandline/sign.md | 69 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 specs/commandline/sign.md diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md new file mode 100644 index 000000000..3c2d4d921 --- /dev/null +++ b/specs/commandline/sign.md @@ -0,0 +1,69 @@ +--- +title: "notation sign" +description: "The notation sign command description and usage" +keywords: "notation, sign" +--- +# notation sign +## Description +Use `notation sign` to sign artifacts. + +If the signing artifact is a container image stored in a registry, the signature is pushed to the registry by default after signing successfully, and the digest of the container image is returned. +## Outline +```console +$ notation sign --help +Sign artifacts + +Usage: + notation sign [reference] [flags] + +Flags: + --cert-file string signing certificate file + -e, --expiry duration expire duration + -h, --help help for sign + -k, --key string signing key name + --key-file string signing key file + -l, --local reference is a local file + --media-type string specify the media type of the manifest read from file or stdin (default "application/vnd.docker.distribution.manifest.v2+json") + -o, --output string write signature to a specific path + -p, --password string Password for registry operations (default from $NOTATION_PASSWORD) + -c, --pluginConfig string list of comma-separated {key}={value} pairs that are passed as is to the plugin, refer plugin documentation to set appropriate values + --push push after successful signing (default true) + -r, --reference string original reference + -u, --username string Username for registry operations (default from $NOTATION_USERNAME) + +Global Flags: + --plain-http Registry access via plain HTTP +``` +## Usage +### sign a container image with a local key and certificate +```console +notation sign --key-file --cert-file +``` +### sign a container image using a key name +```console +# Add a key with a key name referencing signing key file +notation key add -n + +# sign a container image using a key name +notation sign --key +``` +### sign a container image with key and certificate stored in a Key Vault +```console +# Pre-condition: +# - A Key Vault plugin is installed in notation +# - User creates keys and certificates in a Key vault +# Add the key with a key name referencing the key stored in Key Vault +notation key add -n --plugin --id + +# sign a container image using a key name +notation sign --key +``` +### store signature in a local file +```console +# disable auto push and store signature in a specified file +notation sign --key --push false -o +``` +### sign a local file and store signature in a specified file +```console +notation sign -l --key -o +``` \ No newline at end of file From c1d661dc196e72db328078172e22819f0c3be6c8 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Tue, 20 Sep 2022 16:52:56 +0800 Subject: [PATCH 05/18] Add notation sign CLI spec Signed-off-by: Yi Zha --- specs/commandline/sign.md | 69 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 specs/commandline/sign.md diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md new file mode 100644 index 000000000..3c2d4d921 --- /dev/null +++ b/specs/commandline/sign.md @@ -0,0 +1,69 @@ +--- +title: "notation sign" +description: "The notation sign command description and usage" +keywords: "notation, sign" +--- +# notation sign +## Description +Use `notation sign` to sign artifacts. + +If the signing artifact is a container image stored in a registry, the signature is pushed to the registry by default after signing successfully, and the digest of the container image is returned. +## Outline +```console +$ notation sign --help +Sign artifacts + +Usage: + notation sign [reference] [flags] + +Flags: + --cert-file string signing certificate file + -e, --expiry duration expire duration + -h, --help help for sign + -k, --key string signing key name + --key-file string signing key file + -l, --local reference is a local file + --media-type string specify the media type of the manifest read from file or stdin (default "application/vnd.docker.distribution.manifest.v2+json") + -o, --output string write signature to a specific path + -p, --password string Password for registry operations (default from $NOTATION_PASSWORD) + -c, --pluginConfig string list of comma-separated {key}={value} pairs that are passed as is to the plugin, refer plugin documentation to set appropriate values + --push push after successful signing (default true) + -r, --reference string original reference + -u, --username string Username for registry operations (default from $NOTATION_USERNAME) + +Global Flags: + --plain-http Registry access via plain HTTP +``` +## Usage +### sign a container image with a local key and certificate +```console +notation sign --key-file --cert-file +``` +### sign a container image using a key name +```console +# Add a key with a key name referencing signing key file +notation key add -n + +# sign a container image using a key name +notation sign --key +``` +### sign a container image with key and certificate stored in a Key Vault +```console +# Pre-condition: +# - A Key Vault plugin is installed in notation +# - User creates keys and certificates in a Key vault +# Add the key with a key name referencing the key stored in Key Vault +notation key add -n --plugin --id + +# sign a container image using a key name +notation sign --key +``` +### store signature in a local file +```console +# disable auto push and store signature in a specified file +notation sign --key --push false -o +``` +### sign a local file and store signature in a specified file +```console +notation sign -l --key -o +``` \ No newline at end of file From 0e69491cccd6db1f623f162d6cca33c8bed138d3 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Thu, 22 Sep 2022 14:47:08 +0800 Subject: [PATCH 06/18] update spec according to review comments Signed-off-by: Yi Zha --- specs/commandline/sign.md | 75 ++++++++++++++++++--------------------- 1 file changed, 35 insertions(+), 40 deletions(-) diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index 3c2d4d921..c8d317b1e 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -1,69 +1,64 @@ ---- -title: "notation sign" -description: "The notation sign command description and usage" -keywords: "notation, sign" ---- # notation sign ## Description Use `notation sign` to sign artifacts. -If the signing artifact is a container image stored in a registry, the signature is pushed to the registry by default after signing successfully, and the digest of the container image is returned. +If the container image being signed is stored in the registry, upon successful signing, the generated signature will be pushed to the registry and the digest of the container image will be returned. ## Outline ```console -$ notation sign --help Sign artifacts Usage: - notation sign [reference] [flags] + notation sign [flags] Flags: - --cert-file string signing certificate file - -e, --expiry duration expire duration - -h, --help help for sign - -k, --key string signing key name - --key-file string signing key file - -l, --local reference is a local file - --media-type string specify the media type of the manifest read from file or stdin (default "application/vnd.docker.distribution.manifest.v2+json") - -o, --output string write signature to a specific path + --cert-file string Location of file containing signing(leaf) certificate and certificate chain + -e, --expiry duration Expire duration in seconds, minutes or hours + -h, --help Help for sign + -k, --key string Signing key name + --key-file string Signing key file -p, --password string Password for registry operations (default from $NOTATION_PASSWORD) - -c, --pluginConfig string list of comma-separated {key}={value} pairs that are passed as is to the plugin, refer plugin documentation to set appropriate values - --push push after successful signing (default true) - -r, --reference string original reference + -c, --pluginConfig string List of comma-separated {key}={value} pairs that are passed as is to the plugin, refer plugin documentation to set appropriate values -u, --username string Username for registry operations (default from $NOTATION_USERNAME) Global Flags: --plain-http Registry access via plain HTTP ``` ## Usage -### sign a container image with a local key and certificate +### Sign a container image ```console -notation sign --key-file --cert-file -``` -### sign a container image using a key name -```console -# Add a key with a key name referencing signing key file -notation key add -n +# Add a key and make it a default signing key +notation key add -n --default -# sign a container image using a key name -notation sign --key +# [Optional] Change a default signing key +notation key update --default + +# Sign a container image using the default signing key +notation sign ``` -### sign a container image with key and certificate stored in a Key Vault +### Sign a container image using a remote key ```console -# Pre-condition: +# Prerequisites: # - A Key Vault plugin is installed in notation -# - User creates keys and certificates in a Key vault -# Add the key with a key name referencing the key stored in Key Vault -notation key add -n --plugin --id +# - User creates keys and certificates in a Key Vault +# Add a default signing key referencing the key stored in the Key Vault +notation key add -n --plugin --id --default -# sign a container image using a key name -notation sign --key +# sign a container image using a remote key +notation sign ``` -### store signature in a local file +### Sign a container image and specify the signature expiry duration, for example 24 hours ```console -# disable auto push and store signature in a specified file -notation sign --key --push false -o +notation sign --expiry 24h +``` +### Sign a container image using a specified signing key +```console +# List signing keys to get the key name +notation key list + +# Sign a container image using the specified key name +notation sign --key ``` -### sign a local file and store signature in a specified file +### Sign a container image using a local key and certificate which are not added in the signing key list ```console -notation sign -l --key -o +notation sign --key-file --cert-file ``` \ No newline at end of file From 3e01f49180c58a527e00b35dc491dd0a1796fe89 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Fri, 23 Sep 2022 13:15:35 +0800 Subject: [PATCH 07/18] update cli sign spec according to review comments Signed-off-by: Yi Zha --- specs/commandline/sign.md | 31 ++++++++++++++++--------------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index c8d317b1e..b79110052 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -2,7 +2,7 @@ ## Description Use `notation sign` to sign artifacts. -If the container image being signed is stored in the registry, upon successful signing, the generated signature will be pushed to the registry and the digest of the container image will be returned. +Signs a container artifact that is stored in a registry. Upon successful signing, the generated signature is pushed to the registry and the digest of the container image is returned. ## Outline ```console Sign artifacts @@ -11,12 +11,12 @@ Usage: notation sign [flags] Flags: - --cert-file string Location of file containing signing(leaf) certificate and certificate chain - -e, --expiry duration Expire duration in seconds, minutes or hours + --cert-file string Location of file containing signing(leaf) certificate and certificate chain. Use this flag with flag '--key-file' together. + -e, --expiry duration Optional expiry that provides a “best by use” time for the artifact. The duration is specified in seconds, minutes or hours. -h, --help Help for sign - -k, --key string Signing key name - --key-file string Signing key file - -p, --password string Password for registry operations (default from $NOTATION_PASSWORD) + -k, --key string Signing key name, for a key previously added to notation's key list. + --key-file string Signing key file. Use this flag with flag '--cert-file' together. + -p, --password string Password for registry operations (default to $NOTATION_PASSWORD if not specified) -c, --pluginConfig string List of comma-separated {key}={value} pairs that are passed as is to the plugin, refer plugin documentation to set appropriate values -u, --username string Username for registry operations (default from $NOTATION_USERNAME) @@ -33,22 +33,23 @@ notation key add -n --default notation key update --default # Sign a container image using the default signing key -notation sign +notation sign https:///: ``` ### Sign a container image using a remote key ```console # Prerequisites: -# - A Key Vault plugin is installed in notation -# - User creates keys and certificates in a Key Vault -# Add a default signing key referencing the key stored in the Key Vault +# - A compliant signing plugin is installed in notation. See notation plugin documentation 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 -n --plugin --id --default # sign a container image using a remote key -notation sign +notation sign https:///: ``` -### Sign a container image and specify the signature expiry duration, for example 24 hours +### Sign a container image and specify the signature expiry duration, for example 1 day ```console -notation sign --expiry 24h +notation sign https:///: --expiry 24h ``` ### Sign a container image using a specified signing key ```console @@ -56,9 +57,9 @@ notation sign --expiry 24h notation key list # Sign a container image using the specified key name -notation sign --key +notation sign https:///: --key ``` ### Sign a container image using a local key and certificate which are not added in the signing key list ```console -notation sign --key-file --cert-file +notation sign https:///: --key-file --cert-file ``` \ No newline at end of file From 17f080bcd9c199321dbb84cfcbd2ffc9c6d6e70d Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Fri, 23 Sep 2022 13:18:23 +0800 Subject: [PATCH 08/18] update cli sign spec according to review comments 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 b79110052..5866202ca 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -38,7 +38,7 @@ notation sign https:///: ### Sign a container image using a remote key ```console # Prerequisites: -# - A compliant signing plugin is installed in notation. See notation plugin documentation for more details . +# - A compliant signing plugin is installed in notation. See notation plugin documentation for more details [link](https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md). # - 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. From 5e6d1ca21f1f9ade66fbe1c5653b7662a07a3af1 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Fri, 23 Sep 2022 13:22:13 +0800 Subject: [PATCH 09/18] update cli sign spec according to review comments 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 5866202ca..ec6d4100c 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -38,7 +38,7 @@ notation sign https:///: ### Sign a container image using a remote key ```console # Prerequisites: -# - A compliant signing plugin is installed in notation. See notation plugin documentation for more details [link](https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md). +# - A compliant signing plugin is installed in notation. See notation plugin documentation for more details (https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md). # - 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. From 948c0dffb40c6b31013a72b7d69bb42476dd6916 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Fri, 23 Sep 2022 13:24:10 +0800 Subject: [PATCH 10/18] update cli sign spec according to review comments Signed-off-by: Yi Zha --- specs/commandline/sign.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index ec6d4100c..0aaa5e9a8 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -4,7 +4,7 @@ Use `notation sign` to sign artifacts. Signs a container artifact that is stored in a registry. Upon successful signing, the generated signature is pushed to the registry and the digest of the container image is returned. ## Outline -```console +``` Sign artifacts Usage: @@ -25,7 +25,7 @@ Global Flags: ``` ## Usage ### Sign a container image -```console +``` # Add a key and make it a default signing key notation key add -n --default @@ -36,7 +36,7 @@ notation key update --default notation sign https:///: ``` ### Sign a container image using a remote key -```console +``` # Prerequisites: # - A compliant signing plugin is installed in notation. See notation plugin documentation for more details (https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md). # - 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. @@ -48,11 +48,11 @@ notation key add -n --plugin --id --def notation sign https:///: ``` ### Sign a container image and specify the signature expiry duration, for example 1 day -```console +``` notation sign https:///: --expiry 24h ``` ### Sign a container image using a specified signing key -```console +``` # List signing keys to get the key name notation key list @@ -60,6 +60,6 @@ notation key list notation sign https:///: --key ``` ### Sign a container image using a local key and certificate which are not added in the signing key list -```console +``` notation sign https:///: --key-file --cert-file ``` \ No newline at end of file From 085e28f73d0f35744427671325bae31e80e8270c Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Fri, 23 Sep 2022 13:34:44 +0800 Subject: [PATCH 11/18] update cli sign spec according to review comments Signed-off-by: Yi Zha --- specs/commandline/sign.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index 0aaa5e9a8..aaa2ea974 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -17,7 +17,7 @@ Flags: -k, --key string Signing key name, for a key previously added to notation's key list. --key-file string Signing key file. Use this flag with flag '--cert-file' together. -p, --password string Password for registry operations (default to $NOTATION_PASSWORD if not specified) - -c, --pluginConfig string List of comma-separated {key}={value} pairs that are passed as is to the plugin, refer plugin documentation to set appropriate values + -c, --pluginConfig string Optional list of comma-separated {key}={value} pairs that are passed as is to a plugin, if the key (--key) is associated with a signing plugin, refer plugin documentation to set appropriate values -u, --username string Username for registry operations (default from $NOTATION_USERNAME) Global Flags: @@ -26,8 +26,8 @@ Global Flags: ## Usage ### Sign a container image ``` -# Add a key and make it a default signing key -notation key add -n --default +# Add a key which uses a local private key and certificate, and make it a default signing key +notation key add --name --default # [Optional] Change a default signing key notation key update --default @@ -42,7 +42,7 @@ notation sign https:///: # - 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 -n --plugin --id --default +notation key add --name --plugin --id --default # sign a container image using a remote key notation sign https:///: From b73e0881b4c7120cc3b020a12d769c5ccf05b5f6 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Mon, 26 Sep 2022 14:42:12 +0800 Subject: [PATCH 12/18] update cli sign spec according to review comments 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 aaa2ea974..4982c6c7f 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -18,7 +18,7 @@ Flags: --key-file string Signing key file. Use this flag with flag '--cert-file' together. -p, --password string Password for registry operations (default to $NOTATION_PASSWORD if not specified) -c, --pluginConfig string Optional list of comma-separated {key}={value} pairs that are passed as is to a plugin, if the key (--key) is associated with a signing plugin, refer plugin documentation to set appropriate values - -u, --username string Username for registry operations (default from $NOTATION_USERNAME) + -u, --username string Username for registry operations (default to $NOTATION_USERNAME if not specified) Global Flags: --plain-http Registry access via plain HTTP From 5576310642a6575f1de53283b763eb69231b7564 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Wed, 28 Sep 2022 16:14:39 +0800 Subject: [PATCH 13/18] update CLI sign spec according to review comments Signed-off-by: Yi Zha --- specs/commandline/sign.md | 39 +++++++++++++++++++++++++++------------ 1 file changed, 27 insertions(+), 12 deletions(-) diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index 4982c6c7f..24f2e0033 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -1,31 +1,38 @@ # notation sign + ## Description + Use `notation sign` to sign artifacts. Signs a container artifact that is stored in a registry. Upon successful signing, the generated signature is pushed to the registry and the digest of the container image is returned. + ## Outline -``` + +```text Sign artifacts Usage: notation sign [flags] Flags: - --cert-file string Location of file containing signing(leaf) certificate and certificate chain. Use this flag with flag '--key-file' together. - -e, --expiry duration Optional expiry that provides a “best by use” time for the artifact. The duration is specified in seconds, minutes or hours. + --cert-file string Location of file containing signing(leaf) certificate and certificate chain. Use this flag with '--key-file'. + -e, --expiry duration Optional expiry that provides a "best by use" time for the artifact. The duration is specified in minutes, hours or days. -h, --help Help for sign -k, --key string Signing key name, for a key previously added to notation's key list. - --key-file string Signing key file. Use this flag with flag '--cert-file' together. + --key-file string Location of file containing signing key file. Use this flag with '--cert-file'. -p, --password string Password for registry operations (default to $NOTATION_PASSWORD if not specified) - -c, --pluginConfig string Optional list of comma-separated {key}={value} pairs that are passed as is to a plugin, if the key (--key) is associated with a signing plugin, refer plugin documentation to set appropriate values + -c, --plugin-config string Optional, list of comma-separated {key}={value} pairs that are passed as is to a plugin, if the key (--key) is associated with a signing plugin, refer plugin documentation to set appropriate values -u, --username string Username for registry operations (default to $NOTATION_USERNAME if not specified) Global Flags: --plain-http Registry access via plain HTTP ``` + ## Usage + ### Sign a container image -``` + +```text # Add a key which uses a local private key and certificate, and make it a default signing key notation key add --name --default @@ -35,10 +42,12 @@ notation key update --default # Sign a container image using the default signing key notation sign https:///: ``` + ### Sign a container image using a remote key -``` + +```text # Prerequisites: -# - A compliant signing plugin is installed in notation. See notation plugin documentation for more details (https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md). +# - 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. @@ -47,19 +56,25 @@ notation key add --name --plugin --id - # sign a container image using a remote key notation sign https:///: ``` + ### Sign a container image and specify the signature expiry duration, for example 1 day -``` + +```text notation sign https:///: --expiry 24h ``` + ### Sign a container image using a specified signing key -``` + +```text # List signing keys to get the key name notation key list # Sign a container image using the specified key name notation sign https:///: --key ``` + ### Sign a container image using a local key and certificate which are not added in the signing key list -``` + +```text notation sign https:///: --key-file --cert-file -``` \ No newline at end of file +``` From b99f8ac65e849f1154eb526edba8e636e452660e Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Fri, 30 Sep 2022 17:10:10 +0800 Subject: [PATCH 14/18] update according to review comments Signed-off-by: Yi Zha --- specs/commandline/sign.md | 39 +++++++++++++++++++++------------------ 1 file changed, 21 insertions(+), 18 deletions(-) diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index 24f2e0033..93b539c32 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -15,13 +15,13 @@ Usage: notation sign [flags] Flags: - --cert-file string Location of file containing signing(leaf) certificate and certificate chain. Use this flag with '--key-file'. - -e, --expiry duration Optional expiry that provides a "best by use" time for the artifact. The duration is specified in minutes, hours or days. + --cert-file string Location of file containing a complete certificate chain for the signing key. Use this flag with '--key-file'. + -e, --expiry duration Optional expiry that provides a "best by use" time for the artifact. The duration is specified in minutes, hours or days. For example: 30d or 1d3h20m. -h, --help Help for sign -k, --key string Signing key name, for a key previously added to notation's key list. --key-file string Location of file containing signing key file. Use this flag with '--cert-file'. - -p, --password string Password for registry operations (default to $NOTATION_PASSWORD if not specified) - -c, --plugin-config string Optional, list of comma-separated {key}={value} pairs that are passed as is to a plugin, if the key (--key) is associated with a signing plugin, refer plugin documentation to set appropriate values + -p, --password string Password or identity token for registry operations (default to $NOTATION_PASSWORD if not specified) + --plugin-config strings List of {key}={value} pairs that are passed as is to a plugin, if the key (--key) is associated with a signing plugin, refer plugin documentation to set appropriate values -u, --username string Username for registry operations (default to $NOTATION_USERNAME if not specified) Global Flags: @@ -32,49 +32,52 @@ Global Flags: ### Sign a container image -```text +```shell # Add a key which uses a local private key and certificate, and make it a default signing key -notation key add --name --default +notation key add --name --default -# [Optional] Change a default signing key -notation key update --default +# Or change the default signing key to an existing signing key +notation key update --default # Sign a container image using the default signing key -notation sign https:///: +notation sign /: + +# Or using container image digests instead of tags. A container image digest uniquely and immutably identifies a container image. +notation sign /@ ``` ### Sign a container image using a remote key -```text +```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 --name --plugin --id --default +notation key add --name --plugin --id --default # sign a container image using a remote key -notation sign https:///: +notation sign /: ``` ### Sign a container image and specify the signature expiry duration, for example 1 day -```text -notation sign https:///: --expiry 24h +```shell +notation sign /: --expiry 1d ``` ### Sign a container image using a specified signing key -```text +```shell # List signing keys to get the key name notation key list # Sign a container image using the specified key name -notation sign https:///: --key +notation sign https:///: --key ``` ### Sign a container image using a local key and certificate which are not added in the signing key list -```text -notation sign https:///: --key-file --cert-file +```shell +notation sign https:///: --key-file --cert-file ``` From c34780b95b02c4ccd796a967a78ded3370715fb3 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Fri, 30 Sep 2022 20:04:58 +0800 Subject: [PATCH 15/18] update according to review 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 93b539c32..44cd20a3a 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -73,11 +73,11 @@ notation sign /: --expiry 1d notation key list # Sign a container image using the specified key name -notation sign https:///: --key +notation sign /: --key ``` ### Sign a container image using a local key and certificate which are not added in the signing key list ```shell -notation sign https:///: --key-file --cert-file +notation sign /: --key-file --cert-file ``` From e759ec5ff530019f05555ca5bd1318e6eaf6ecfc Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Fri, 30 Sep 2022 20:12:57 +0800 Subject: [PATCH 16/18] update according to review comments 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 44cd20a3a..a2e80861c 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -16,7 +16,7 @@ Usage: Flags: --cert-file string Location of file containing a complete certificate chain for the signing key. Use this flag with '--key-file'. - -e, --expiry duration Optional expiry that provides a "best by use" time for the artifact. The duration is specified in minutes, hours or days. For example: 30d or 1d3h20m. + -e, --expiry duration Optional expiry that provides a "best by use" time for the artifact. The duration is specified in minutes(m), hours(h) or days(d). For example: 30d, 12h, 30m, 1d3h20m -h, --help Help for sign -k, --key string Signing key name, for a key previously added to notation's key list. --key-file string Location of file containing signing key file. Use this flag with '--cert-file'. From efa92db42127d983c0a0dab2ceea49d57fc81b24 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Fri, 30 Sep 2022 22:48:05 +0800 Subject: [PATCH 17/18] update according to review comments Signed-off-by: Yi Zha --- specs/commandline/sign.md | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index a2e80861c..6bc4aed80 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -4,7 +4,7 @@ Use `notation sign` to sign artifacts. -Signs a container artifact that is stored in a registry. Upon successful signing, the generated signature is pushed to the registry and the digest of the container image is returned. +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. ## Outline @@ -21,7 +21,7 @@ Flags: -k, --key string Signing key name, for a key previously added to notation's key list. --key-file string Location of file containing signing key file. Use this flag with '--cert-file'. -p, --password string Password or identity token for registry operations (default to $NOTATION_PASSWORD if not specified) - --plugin-config strings List of {key}={value} pairs that are passed as is to a plugin, if the key (--key) is associated with a signing plugin, refer plugin documentation to set appropriate values + --plugin-config strings List of {key}={value} pairs that are passed as is to a plugin, if the key (--key) is associated with a signing plugin, refer plugin documentation to set appropriate values -u, --username string Username for registry operations (default to $NOTATION_USERNAME if not specified) Global Flags: @@ -34,10 +34,10 @@ Global Flags: ```shell # Add a key which uses a local private key and certificate, and make it a default signing key -notation key add --name --default +notation key add --default --name # Or change the default signing key to an existing signing key -notation key update --default +notation key update --default # Sign a container image using the default signing key notation sign /: @@ -54,16 +54,26 @@ notation sign /@ # - 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 --name --plugin --id --default +notation key add --default --name --plugin --id # sign a container image using a remote key notation sign /: ``` +### Sign an OCI artifact using the default signing key + +```shell +# Prerequisites: +# A default signing key is configured using CLI "notation key" + +# Use a digest that uniquely and immutably identifies an OCI artifact. +notation sign /@ +``` + ### Sign a container image and specify the signature expiry duration, for example 1 day ```shell -notation sign /: --expiry 1d +notation sign --expiry 1d /: ``` ### Sign a container image using a specified signing key From 2c4e454cf423a71fc0a52981075134ebe184cfd4 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Sat, 1 Oct 2022 21:15:41 +0800 Subject: [PATCH 18/18] update according to review 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 6bc4aed80..02280ad03 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -83,11 +83,11 @@ notation sign --expiry 1d /: notation key list # Sign a container image using the specified key name -notation sign /: --key +notation sign --key /: ``` ### Sign a container image using a local key and certificate which are not added in the signing key list ```shell -notation sign /: --key-file --cert-file +notation sign --key-file --cert-file /: ```