From df1e729f1bd22e1365bc746cc06dfbd738d1103e Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Thu, 18 Aug 2022 15:59:19 +0800 Subject: [PATCH 1/7] 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 2/7] 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 3/7] 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 47fdd40efbd34b6b90720c130fd5e6e0d630cdc6 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Sat, 8 Oct 2022 13:08:10 +0800 Subject: [PATCH 4/7] spec: Add spec for notation verify Signed-off-by: Yi Zha --- specs/commandline/verify.md | 98 +++++++++++++++++++++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 specs/commandline/verify.md diff --git a/specs/commandline/verify.md b/specs/commandline/verify.md new file mode 100644 index 000000000..bf34ffdb4 --- /dev/null +++ b/specs/commandline/verify.md @@ -0,0 +1,98 @@ +# notation verify + +## Description + +Use `notation verify` command to verify signatures on an artifact. Signature verification succeeds if verification succeeds for at least one signature. The digest of the supplied artifact is returned upon successful verification. + +## Outline + +Verify artifacts against signatures + +Usage: + notation verify [flags] + +Flags: + -h, --help help for verify + -p, --password string Password for registry operations (default to $NOTATION_PASSWORD if not specified) + -u, --username string Username for registry operations (default to $NOTATION_USERNAME if not specified) + +## Usage + +User needs to configure trust store and trust policy properly before using `notation verify` command. + +### Configure Trust Store + +Use `notation certificate` command to configure trust stores. + +### Configure Trust Policy + +Users who consume signed artifact from a registry use the trust policy to specify trusted identities which sign the artifacts, and level of signature verification to use. The trust policy is a JSON document. User needs to create a file named `trustpolicy.json` under `{NOTATION_CONFIG}`. See [Notation Directory Structure](https://github.com/notaryproject/notation/blob/main/specs/directory.md) for `{NOTATION_CONFIG}`. + +An example of `trustpolicy.json`: + +```text +{ + "version": "1.0", + "trustPolicies": [ + { + // Policy for all artifacts, from any registry location. + "name": "wabbit-networks-images", // Name of the policy. + "registryScopes": [ "*" ], // The registry artifacts to which the policy applies. + "signatureVerification": { // The level of verification - strict, permissive, audit, skip. + "level" : "strict" + }, + "trustStores": ["ca:wabbit-networks"], // The trust stores that contains the X.509 trusted roots. + "trustedIdentities": [ // Identities that are trusted to sign the artifact. + "x509.subject: C=US, ST=WA, L=Seattle, O=wabbit-networks.io, OU=Finance, CN=SecureBuilder" + ] + } + ] +} +``` + +In this example, only one policy is configured with the name `wabbit-networks-images`. With the value of property `registryScopes` set to `*`, this policy applies to all artifacts from any registry location. User can configure multiple trust policies for different scenarios. See [Trust Policy Schema and properties](https://github.com/notaryproject/notaryproject/blob/main/trust-store-trust-policy-specification.md#trust-policy) for details. + +### Verify signatures on a container image stored in a registry (Neither trust store nor trust policy is configured) + +```shell + +# Prerequisites: Signatures are stored in a registry referencing the signed container image + +# Configure trust store by adding a certificate file into trust store named "wabbit-network" of type "ca" +notation certificate add --type ca --store wabbit-networks wabbit-networks.crt + +# Configure trust policy by creating a JSON document named "trustpolicy.json" under directory "{NOTATION_CONFIG}" +# Example on Linux +cat < $HOME/.config/notaton/trustpolicy.json +{ + "version": "1.0", + "trustPolicies": [ + { + "name": "wabbit-networks-images", // Name of the policy. + "registryScopes": [ "registry.wabbit-networks.io/software/net-monitor" ], // The registry artifacts to which the policy applies. + "signatureVerification": { // The level of verification - strict, permissive, audit, skip. + "level" : "strict" + }, + "trustStores": ["ca:wabbit-networks"], // The trust stores that contains the X.509 trusted roots. + "trustedIdentities": [ // Identities that are trusted to sign the artifact. + "x509.subject: C=US, ST=WA, L=Seattle, O=wabbit-networks.io, OU=Finance, CN=SecureBuilder" + ] + } + ] +} +EOF + +# Verify signatures on a container image +notation verify registry.wabbit-networks.io/software/net-monitor:v1 + +``` + +### Verify signatures on an OCI artifact stored in a registry (Trust store and trust policy are configured properly) + +```shell +# Prerequisites: Signatures are stored in a registry referencing the signed OCI artifact + +# Verify signatures on an OCI artifact identified by the digest +notation verify registry.wabbit-networks.io/software/net-monitor@sha256:abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234 + +``` From dc11d5982eafbe348a1a04fe7ffa29d99d01d3ba Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Tue, 11 Oct 2022 16:56:55 +0800 Subject: [PATCH 5/7] spec: update according to review comments Signed-off-by: Yi Zha --- specs/commandline/verify.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/specs/commandline/verify.md b/specs/commandline/verify.md index bf34ffdb4..b1ac3d64b 100644 --- a/specs/commandline/verify.md +++ b/specs/commandline/verify.md @@ -2,19 +2,22 @@ ## Description -Use `notation verify` command to verify signatures on an artifact. Signature verification succeeds if verification succeeds for at least one signature. The digest of the supplied artifact is returned upon successful verification. +Use `notation verify` command to verify signatures on an artifact. Signature verification succeeds if verification succeeds for at least one of the signatures associated with the artifact. The digest of the supplied artifact is returned upon successful verification. It is recommended that this digest reference be used to pull the artifact subsequently, as registry tags may be mutable, and a tag reference can point to a different artifact that what was verified. ## Outline +```text Verify artifacts against signatures Usage: notation verify [flags] Flags: - -h, --help help for verify - -p, --password string Password for registry operations (default to $NOTATION_PASSWORD if not specified) - -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) + --plugin-config strings {key}={value} pairs that are passed as 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) +``` ## Usage @@ -30,7 +33,7 @@ Users who consume signed artifact from a registry use the trust policy to specif An example of `trustpolicy.json`: -```text +```jsonc { "version": "1.0", "trustPolicies": [ @@ -52,7 +55,7 @@ An example of `trustpolicy.json`: In this example, only one policy is configured with the name `wabbit-networks-images`. With the value of property `registryScopes` set to `*`, this policy applies to all artifacts from any registry location. User can configure multiple trust policies for different scenarios. See [Trust Policy Schema and properties](https://github.com/notaryproject/notaryproject/blob/main/trust-store-trust-policy-specification.md#trust-policy) for details. -### Verify signatures on a container image stored in a registry (Neither trust store nor trust policy is configured) +### Verify signatures on a container image stored in a registry (Neither trust store nor trust policy is configured yet) ```shell @@ -63,7 +66,7 @@ notation certificate add --type ca --store wabbit-networks wabbit-networks.crt # Configure trust policy by creating a JSON document named "trustpolicy.json" under directory "{NOTATION_CONFIG}" # Example on Linux -cat < $HOME/.config/notaton/trustpolicy.json +cat < $HOME/.config/notation/trustpolicy.json { "version": "1.0", "trustPolicies": [ From f8a0fd2ebabcd5f54bfdf6da049ab5c0d5103793 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Wed, 12 Oct 2022 19:48:15 +0800 Subject: [PATCH 6/7] spec: update according to comments Signed-off-by: Yi Zha --- specs/commandline/verify.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/commandline/verify.md b/specs/commandline/verify.md index b1ac3d64b..258b593ef 100644 --- a/specs/commandline/verify.md +++ b/specs/commandline/verify.md @@ -7,7 +7,7 @@ Use `notation verify` command to verify signatures on an artifact. Signature ver ## Outline ```text -Verify artifacts against signatures +Verify signatures associated with the artifact. Usage: notation verify [flags] @@ -21,7 +21,7 @@ Flags: ## Usage -User needs to configure trust store and trust policy properly before using `notation verify` command. +Pre-requisite: User needs to configure trust store and trust policy properly before using `notation verify` command. ### Configure Trust Store From 68489cb70d753839f90ad62de0439665f8a40c49 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Wed, 12 Oct 2022 20:34:43 +0800 Subject: [PATCH 7/7] spec: update according to comments Signed-off-by: Yi Zha --- specs/commandline/verify.md | 26 ++++++++++++-------------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/specs/commandline/verify.md b/specs/commandline/verify.md index 258b593ef..1a779e62d 100644 --- a/specs/commandline/verify.md +++ b/specs/commandline/verify.md @@ -10,7 +10,7 @@ Use `notation verify` command to verify signatures on an artifact. Signature ver Verify signatures associated with the artifact. Usage: - notation verify [flags] + notation verify [flags] Flags: -h, --help help for verify @@ -39,14 +39,14 @@ An example of `trustpolicy.json`: "trustPolicies": [ { // Policy for all artifacts, from any registry location. - "name": "wabbit-networks-images", // Name of the policy. - "registryScopes": [ "*" ], // The registry artifacts to which the policy applies. - "signatureVerification": { // The level of verification - strict, permissive, audit, skip. - "level" : "strict" + "name": "wabbit-networks-images", // Name of the policy. + "registryScopes": [ "*" ], // The registry artifacts to which the policy applies. + "signatureVerification": { // The level of verification - strict, permissive, audit, skip. + "level": "strict" }, - "trustStores": ["ca:wabbit-networks"], // The trust stores that contains the X.509 trusted roots. - "trustedIdentities": [ // Identities that are trusted to sign the artifact. - "x509.subject: C=US, ST=WA, L=Seattle, O=wabbit-networks.io, OU=Finance, CN=SecureBuilder" + "trustStores": [ "ca:wabbit-networks" ], // The trust stores that contains the X.509 trusted roots. + "trustedIdentities": [ // Identities that are trusted to sign the artifact. + "x509.subject: C=US, ST=WA, L=Seattle, O=wabbit-networks.io, OU=Finance, CN=SecureBuilder" ] } ] @@ -74,11 +74,11 @@ cat < $HOME/.config/notation/trustpolicy.json "name": "wabbit-networks-images", // Name of the policy. "registryScopes": [ "registry.wabbit-networks.io/software/net-monitor" ], // The registry artifacts to which the policy applies. "signatureVerification": { // The level of verification - strict, permissive, audit, skip. - "level" : "strict" + "level" : "strict" }, - "trustStores": ["ca:wabbit-networks"], // The trust stores that contains the X.509 trusted roots. - "trustedIdentities": [ // Identities that are trusted to sign the artifact. - "x509.subject: C=US, ST=WA, L=Seattle, O=wabbit-networks.io, OU=Finance, CN=SecureBuilder" + "trustStores": [ "ca:wabbit-networks" ], // The trust stores that contains the X.509 trusted roots. + "trustedIdentities": [ // Identities that are trusted to sign the artifact. + "x509.subject: C=US, ST=WA, L=Seattle, O=wabbit-networks.io, OU=Finance, CN=SecureBuilder" ] } ] @@ -87,7 +87,6 @@ EOF # Verify signatures on a container image notation verify registry.wabbit-networks.io/software/net-monitor:v1 - ``` ### Verify signatures on an OCI artifact stored in a registry (Trust store and trust policy are configured properly) @@ -97,5 +96,4 @@ notation verify registry.wabbit-networks.io/software/net-monitor:v1 # Verify signatures on an OCI artifact identified by the digest notation verify registry.wabbit-networks.io/software/net-monitor@sha256:abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234 - ```