From eee90cd49a8e47d6165afd88524a20401d659b43 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Tue, 8 Nov 2022 17:26:42 +0800 Subject: [PATCH 01/11] spec: update cli verify spec for UX improvement Signed-off-by: Yi Zha --- specs/commandline/verify.md | 102 ++++++++++++++++++++++++++++++++---- 1 file changed, 91 insertions(+), 11 deletions(-) diff --git a/specs/commandline/verify.md b/specs/commandline/verify.md index f5e9b5c3b..09eb1e21c 100644 --- a/specs/commandline/verify.md +++ b/specs/commandline/verify.md @@ -13,6 +13,7 @@ Usage: notation verify [flags] Flags: + -d, --debug print out debug output -h, --help help for verify -p, --password string password for registry operations (default to $NOTATION_PASSWORD if not specified) --plain-http registry access via plain HTTP @@ -54,26 +55,28 @@ 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. +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/specs/trust-store-trust-policy.md#trust-policy) for details. -### Verify signatures on a container image stored in a registry (Neither trust store nor trust policy is configured yet) +### Verify signatures on an OCI artifact stored in a registry + +Configure trust store and trust policy properly before using `notation verify` command. ```shell -# Prerequisites: Signatures are stored in a registry referencing the signed container image +# Prerequisites: Signatures are stored in a registry referencing the signed OCI artifact # 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 +$ 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/notation/trustpolicy.json +$ cat < $HOME/.config/notation/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. + "registryScopes": [ "localhost:5000/net-monitor" ], // The registry artifacts to which the policy applies. "signatureVerification": { // The level of verification - strict, permissive, audit, skip. "level" : "strict" }, @@ -86,15 +89,92 @@ cat < $HOME/.config/notation/trustpolicy.json } EOF -# Verify signatures on a container image -notation verify registry.wabbit-networks.io/software/net-monitor:v1 +# Verify signatures on the supplied OCI artifact identified by the digest +$ notation verify localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 +``` + +An example of output messages for a successful verification: + +```text +Verify succeeded for localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 ``` -### Verify signatures on an OCI artifact stored in a registry (Trust store and trust policy are configured properly) +### Verify signatures on an OCI artifact identified by a tag + +A tag is resolved to a digest first before verification. ```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 +# Verify signatures on an OCI artifact identified by the tag +$ notation verify localhost:5000/net-monitor:v1 +``` + +An example of output messages for a successful verification: + +```text +Warning: Tag is used. Always use digest to identify the reference uniquely and immutably. + +Resolve tag `v1` to digest `sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9` +Verify succeeded for localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 +``` + +### Verify succeeded using "--debug" flag + +```shell +$ notation verify --debug localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 +Use trust policy: +Use certificate: // +Signature verification level: [strict/permissive/audit/skip] + +Verify succeeded on signature ${signature-digest} for localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 +``` + +### Verify succeeded with conditions using "--debug" flag + +```shell +$ notation verify --debug localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 +Use trust policy: +Use certificate: // +Signature verification level: [strict/permissive/audit/skip] + +Error: +signature verification failure +${signature-digest}: ${error message} + +Warning: +signature verification failure, but only logged the error +${signature-digest}: ${error message} + +Verify succeeded on signature ${signature-digest} for localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 +``` + +### Verify failed for all signatures without using "--debug" flag + +Trust policy and trust store are configured properly. + +```shell +$ notation verify localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 +Verify failed for all the 2 signature(s) associated with localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 +``` + +### Verify failed for all signatures using "--debug" flag + +Trust policy and trust store are configured properly. + +```shell +$ notation verify --debug localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 +Use trust policy: +Use certificate: // +Signature verification level: [strict/permissive/audit/skip] + +Error: +signature verification failed +${signature-digest}: ${error message} + +Error: +signature verification failed +${signature-digest}: ${error message} + +Verify failed for all the 2 signature(s) associated with localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 ``` From ef64d6ab0f28bd1833b93bf904ac1d086e735847 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Tue, 8 Nov 2022 17:48:40 +0800 Subject: [PATCH 02/11] spec: update debug description Signed-off-by: Yi Zha --- specs/commandline/verify.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/commandline/verify.md b/specs/commandline/verify.md index 09eb1e21c..7c5b49087 100644 --- a/specs/commandline/verify.md +++ b/specs/commandline/verify.md @@ -13,7 +13,7 @@ Usage: notation verify [flags] Flags: - -d, --debug print out debug output + -d, --debug enable verbose output -h, --help help for verify -p, --password string password for registry operations (default to $NOTATION_PASSWORD if not specified) --plain-http registry access via plain HTTP From 331321b06472e2617fe9cd13102c66d9bbeb4b3b Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Fri, 18 Nov 2022 14:16:10 +0800 Subject: [PATCH 03/11] spec: remove updates for debug option Signed-off-by: Yi Zha --- specs/commandline/verify.md | 80 ++++++++----------------------------- 1 file changed, 16 insertions(+), 64 deletions(-) diff --git a/specs/commandline/verify.md b/specs/commandline/verify.md index 7c5b49087..ecda399dc 100644 --- a/specs/commandline/verify.md +++ b/specs/commandline/verify.md @@ -4,6 +4,20 @@ 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. +Upon successful verifying, the output message is printed out as following: + +```text +Verify succeeded for /@. +``` + +If a `tag` is used to identify the OCI artifact, the output message is as following: + +```text +Warning: A tag is used to identify the artifact for verifying. Artifact tags are mutable. Use digests to uniquely identify artifacts and avoid mutability. +Resolving artifact tag '' to digest '' before verifying. +Verify succeeded for /@. +``` + ## Outline ```text @@ -13,7 +27,6 @@ Usage: notation verify [flags] Flags: - -d, --debug enable verbose output -h, --help help for verify -p, --password string password for registry operations (default to $NOTATION_PASSWORD if not specified) --plain-http registry access via plain HTTP @@ -113,68 +126,7 @@ $ notation verify localhost:5000/net-monitor:v1 An example of output messages for a successful verification: ```text -Warning: Tag is used. Always use digest to identify the reference uniquely and immutably. - -Resolve tag `v1` to digest `sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9` +Warning: A tag is used to identify the artifact for verifying. Artifact tags are mutable. Use digests to uniquely identify artifacts and avoid mutability. +Resolving artifact tag `v1` to digest `sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9` before verifying. Verify succeeded for localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 ``` - -### Verify succeeded using "--debug" flag - -```shell -$ notation verify --debug localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 -Use trust policy: -Use certificate: // -Signature verification level: [strict/permissive/audit/skip] - -Verify succeeded on signature ${signature-digest} for localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 -``` - -### Verify succeeded with conditions using "--debug" flag - -```shell -$ notation verify --debug localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 -Use trust policy: -Use certificate: // -Signature verification level: [strict/permissive/audit/skip] - -Error: -signature verification failure -${signature-digest}: ${error message} - -Warning: -signature verification failure, but only logged the error -${signature-digest}: ${error message} - -Verify succeeded on signature ${signature-digest} for localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 -``` - -### Verify failed for all signatures without using "--debug" flag - -Trust policy and trust store are configured properly. - -```shell -$ notation verify localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 -Verify failed for all the 2 signature(s) associated with localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 -``` - -### Verify failed for all signatures using "--debug" flag - -Trust policy and trust store are configured properly. - -```shell -$ notation verify --debug localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 -Use trust policy: -Use certificate: // -Signature verification level: [strict/permissive/audit/skip] - -Error: -signature verification failed -${signature-digest}: ${error message} - -Error: -signature verification failed -${signature-digest}: ${error message} - -Verify failed for all the 2 signature(s) associated with localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 -``` From 831cfcd62c152005dfba511c6b8e4c1e92706785 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Mon, 21 Nov 2022 12:53:05 +0800 Subject: [PATCH 04/11] spec: update according to comments Signed-off-by: Yi Zha --- specs/commandline/verify.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/specs/commandline/verify.md b/specs/commandline/verify.md index ecda399dc..02f6371ee 100644 --- a/specs/commandline/verify.md +++ b/specs/commandline/verify.md @@ -2,20 +2,20 @@ ## Description -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. +Use `notation verify` command to verify signatures associated with the artifact. Signature verification succeeds if verification succeeds for at least one of the signatures associated with the artifact. Always verify 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 that was verified. Upon successful verifying, the output message is printed out as following: ```text -Verify succeeded for /@. +Successfully verified for /@ ``` If a `tag` is used to identify the OCI artifact, the output message is as following: ```text -Warning: A tag is used to identify the artifact for verifying. Artifact tags are mutable. Use digests to uniquely identify artifacts and avoid mutability. -Resolving artifact tag '' to digest '' before verifying. -Verify succeeded for /@. +Warning: Always verify 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 verified. +Resolved artifact tag '' to digest '' before verification. +Successfully verified for /@ ``` ## Outline @@ -109,7 +109,7 @@ $ notation verify localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7d An example of output messages for a successful verification: ```text -Verify succeeded for localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 +Successfully verified for localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 ``` ### Verify signatures on an OCI artifact identified by a tag @@ -126,7 +126,7 @@ $ notation verify localhost:5000/net-monitor:v1 An example of output messages for a successful verification: ```text -Warning: A tag is used to identify the artifact for verifying. Artifact tags are mutable. Use digests to uniquely identify artifacts and avoid mutability. -Resolving artifact tag `v1` to digest `sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9` before verifying. -Verify succeeded for localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 +Warning: Always verify 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 verified. +Resolved artifact tag `v1` to digest `sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9` before verification. +Successfully verified for localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 ``` From eb2662c19a83b9fbd58f1d0b5383d8940363c5e7 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Wed, 23 Nov 2022 16:41:43 +0800 Subject: [PATCH 05/11] spec: adding a table for trust policy properties Signed-off-by: Yi Zha --- specs/commandline/verify.md | 55 +++++++++++++++++++------------------ 1 file changed, 29 insertions(+), 26 deletions(-) diff --git a/specs/commandline/verify.md b/specs/commandline/verify.md index 02f6371ee..60255eae0 100644 --- a/specs/commandline/verify.md +++ b/specs/commandline/verify.md @@ -55,7 +55,7 @@ An example of `trustpolicy.json`: { // 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. + "registryScopes": [ "localhost:5000/net-monitor" ], // The registry artifacts to which the policy applies. "signatureVerification": { // The level of verification - strict, permissive, audit, skip. "level": "strict" }, @@ -68,7 +68,30 @@ 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/specs/trust-store-trust-policy.md#trust-policy) for details. +For a Linux user, store file `trustpolicy.json` under directory `$HOME/.config/notation/`. + +For a Mac user, store file `trustpolicy.json` under directory `$HOME/Library/Application Support/notation/`. + +For a Window user, store file `trustpolicy.json` under directory `C:\Users\\AppData\Roaming\notation\`. + +Example values on trust policy properties: + +| Property name | Value | Meaning | +| --|--|--| +| name | "wabbit-networks-images" | The name of the policy is "wabbit-networks-images". | +| registryScopes | "localhost:5000/net-monitor" | The policy only applies to artifacts stored in repository `localhost:5000/net-monitor`. | +| registryScopes | "localhost:5000/net-monitor", "localhost:5000/nginx" | The policy applies to artifacts stored in two repositories: `localhost:5000/net-monitor` and `localhost:5000/nginx`. | +| registryScopes | "*" | The policy applies to all the artifacts stored in any repositories. | +| signatureVerification | "level": "strict" | Signature verification is performed at strict level, which enforces all validations: `integrity`, `authenticity`, `authentic timestamp`, `expiry` and `revocation`.| +| signatureVerification | "level": "permissive" | The permissive level enforces most validations, but will only logs failures for `revocation` and `expiry`. | +| signatureVerification | "level": "audit" | The audit level only enforces signature `integrity` if a signature is present. Failure of all other validations are only logged. | +| signatureVerification | "level": "skip" | The skip level does not fetch signatures for artifacts and does not perform any signature verification. | +| trustStores | "ca:wabbit-networks" | Verify signatures using certificates stored in one trust store. The type of trust store is `ca` and the name is `wabbit-networks`, which are configured using `notation certificate add` command.| +| trustStores | "ca:wabbit-networks", "ca:rocket-networks" | Verify signatures using certificates stored in two trust stores. | +| trustedIdentities | "x509.subject: C=US, ST=WA, L=Seattle, O=wabbit-networks.io, OU=Finance, CN=SecureBuilder" | Use only trusts the identity with specific subject. User can use `notation certificate show` command to get the subject info. | +| trustedIdentities | "*" | User trusts any identity (signing certificate) issued by the CA(s) in trustStore. | + +User can configure multiple trust policies for different scenarios. See [Trust Policy Schema and properties](https://github.com/notaryproject/notaryproject/blob/main/specs/trust-store-trust-policy.md#trust-policy) for details. ### Verify signatures on an OCI artifact stored in a registry @@ -77,33 +100,13 @@ Configure trust store and trust policy properly before using `notation verify` c ```shell # Prerequisites: Signatures are stored in a registry referencing the signed OCI artifact - # 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 +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/notation/trustpolicy.json -{ - "version": "1.0", - "trustPolicies": [ - { - "name": "wabbit-networks-images", // Name of the policy. - "registryScopes": [ "localhost:5000/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 +# Create a JSON file named "trustpolicy.json" under directory "{NOTATION_CONFIG}". # Verify signatures on the supplied OCI artifact identified by the digest -$ notation verify localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 +notation verify localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 ``` An example of output messages for a successful verification: @@ -120,7 +123,7 @@ A tag is resolved to a digest first before verification. # Prerequisites: Signatures are stored in a registry referencing the signed OCI artifact # Verify signatures on an OCI artifact identified by the tag -$ notation verify localhost:5000/net-monitor:v1 +notation verify localhost:5000/net-monitor:v1 ``` An example of output messages for a successful verification: From d339f0e7c3397855839c46dcdab98ecb71129688 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Wed, 23 Nov 2022 16:49:31 +0800 Subject: [PATCH 06/11] spec: fix typos 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 60255eae0..c75525677 100644 --- a/specs/commandline/verify.md +++ b/specs/commandline/verify.md @@ -88,8 +88,8 @@ Example values on trust policy properties: | signatureVerification | "level": "skip" | The skip level does not fetch signatures for artifacts and does not perform any signature verification. | | trustStores | "ca:wabbit-networks" | Verify signatures using certificates stored in one trust store. The type of trust store is `ca` and the name is `wabbit-networks`, which are configured using `notation certificate add` command.| | trustStores | "ca:wabbit-networks", "ca:rocket-networks" | Verify signatures using certificates stored in two trust stores. | -| trustedIdentities | "x509.subject: C=US, ST=WA, L=Seattle, O=wabbit-networks.io, OU=Finance, CN=SecureBuilder" | Use only trusts the identity with specific subject. User can use `notation certificate show` command to get the subject info. | -| trustedIdentities | "*" | User trusts any identity (signing certificate) issued by the CA(s) in trustStore. | +| trustedIdentities | "x509.subject: C=US, ST=WA, L=Seattle, O=wabbit-networks.io, OU=Finance, CN=SecureBuilder" | User only trusts the identity with specific subject. User can use `notation certificate show` command to get the `subject` info. | +| trustedIdentities | "*" | User trusts any identity (signing certificate) issued by the CA(s) in trust stores. | User can configure multiple trust policies for different scenarios. See [Trust Policy Schema and properties](https://github.com/notaryproject/notaryproject/blob/main/specs/trust-store-trust-policy.md#trust-policy) for details. From 3078025b272093a679ee459dc350f4a1b46a3c3b Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Mon, 28 Nov 2022 15:20:06 +0800 Subject: [PATCH 07/11] update per comments Signed-off-by: Yi Zha --- specs/commandline/verify.md | 54 ++++++++++++++++++------------------- 1 file changed, 26 insertions(+), 28 deletions(-) diff --git a/specs/commandline/verify.md b/specs/commandline/verify.md index c75525677..4f51b839c 100644 --- a/specs/commandline/verify.md +++ b/specs/commandline/verify.md @@ -2,19 +2,17 @@ ## Description -Use `notation verify` command to verify signatures associated with the artifact. Signature verification succeeds if verification succeeds for at least one of the signatures associated with the artifact. Always verify 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 that was verified. - -Upon successful verifying, the output message is printed out as following: +Use `notation verify` command to verify signatures associated with the artifact. Signature verification succeeds if verification succeeds for at least one of the signatures associated with the artifact. Upon successful verification, the output message is printed out as follows: ```text Successfully verified for /@ ``` -If a `tag` is used to identify the OCI artifact, the output message is as following: +Tags are mutable and a tag reference can point to a different artifact than that was signed referred by the same tag. If a `tag` is used to identify the OCI artifact, the output message is as follows: ```text -Warning: Always verify 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 verified. Resolved artifact tag '' to digest '' before verification. +Warning: The resolved digest may not point to the same signed artifact, since tags are mutable. Successfully verified for /@ ``` @@ -44,7 +42,7 @@ 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}`. +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://notaryproject.dev/docs/tutorials/directory-structure/) for `{NOTATION_CONFIG}`. An example of `trustpolicy.json`: @@ -54,13 +52,13 @@ An example of `trustpolicy.json`: "trustPolicies": [ { // Policy for all artifacts, from any registry location. - "name": "wabbit-networks-images", // Name of the policy. - "registryScopes": [ "localhost:5000/net-monitor" ], // The registry artifacts to which the policy applies. - "signatureVerification": { // The level of verification - strict, permissive, audit, skip. + "name": "wabbit-networks-images", // Name of the policy. + "registryScopes": [ "localhost:5000/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. + "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" ] } @@ -68,28 +66,28 @@ An example of `trustpolicy.json`: } ``` -For a Linux user, store file `trustpolicy.json` under directory `$HOME/.config/notation/`. +For a Linux user, store file `trustpolicy.json` under directory `${HOME}/.config/notation/`. -For a Mac user, store file `trustpolicy.json` under directory `$HOME/Library/Application Support/notation/`. +For a MacOS user, store file `trustpolicy.json` under directory `${HOME}/Library/Application Support/notation/`. -For a Window user, store file `trustpolicy.json` under directory `C:\Users\\AppData\Roaming\notation\`. +For a Window user, store file `trustpolicy.json` under directory `%USERPROFILE%\AppData\Roaming\notation\`. Example values on trust policy properties: | Property name | Value | Meaning | -| --|--|--| -| name | "wabbit-networks-images" | The name of the policy is "wabbit-networks-images". | -| registryScopes | "localhost:5000/net-monitor" | The policy only applies to artifacts stored in repository `localhost:5000/net-monitor`. | -| registryScopes | "localhost:5000/net-monitor", "localhost:5000/nginx" | The policy applies to artifacts stored in two repositories: `localhost:5000/net-monitor` and `localhost:5000/nginx`. | -| registryScopes | "*" | The policy applies to all the artifacts stored in any repositories. | -| signatureVerification | "level": "strict" | Signature verification is performed at strict level, which enforces all validations: `integrity`, `authenticity`, `authentic timestamp`, `expiry` and `revocation`.| -| signatureVerification | "level": "permissive" | The permissive level enforces most validations, but will only logs failures for `revocation` and `expiry`. | -| signatureVerification | "level": "audit" | The audit level only enforces signature `integrity` if a signature is present. Failure of all other validations are only logged. | -| signatureVerification | "level": "skip" | The skip level does not fetch signatures for artifacts and does not perform any signature verification. | -| trustStores | "ca:wabbit-networks" | Verify signatures using certificates stored in one trust store. The type of trust store is `ca` and the name is `wabbit-networks`, which are configured using `notation certificate add` command.| -| trustStores | "ca:wabbit-networks", "ca:rocket-networks" | Verify signatures using certificates stored in two trust stores. | -| trustedIdentities | "x509.subject: C=US, ST=WA, L=Seattle, O=wabbit-networks.io, OU=Finance, CN=SecureBuilder" | User only trusts the identity with specific subject. User can use `notation certificate show` command to get the `subject` info. | -| trustedIdentities | "*" | User trusts any identity (signing certificate) issued by the CA(s) in trust stores. | +| ----------------------|--------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| name | "wabbit-networks-images" | The name of the policy is "wabbit-networks-images". | +| registryScopes | "localhost:5000/net-monitor" | The policy only applies to artifacts stored in repository `localhost:5000/net-monitor`. | +| registryScopes | "localhost:5000/net-monitor", "localhost:5000/nginx" | The policy applies to artifacts stored in two repositories: `localhost:5000/net-monitor` and `localhost:5000/nginx`. | +| registryScopes | "*" | The policy applies to all the artifacts stored in any repositories. | +| signatureVerification | "level": "strict" | Signature verification is performed at strict level, which enforces all validations: `integrity`, `authenticity`, `authentic timestamp`, `expiry` and `revocation`.| +| signatureVerification | "level": "permissive" | The permissive level enforces most validations, but will only logs failures for `revocation` and `expiry`. | +| signatureVerification | "level": "audit" | The audit level only enforces signature `integrity` if a signature is present. Failure of all other validations are only logged. | +| signatureVerification | "level": "skip" | The skip level does not fetch signatures for artifacts and does not perform any signature verification. | +| trustStores | "ca:wabbit-networks" | Specify the trust store that uses the format {trust-store-type}:{named-store}. The trust store is added using `notation certificate add` command. | +| trustStores | "ca:wabbit-networks", "ca:rocket-networks" | Specify two trust stores, each of which contains the trusted roots against which signatures are verified. | +| trustedIdentities | "x509.subject: C=US, ST=WA, L=Seattle, O=wabbit-networks.io, OU=Finance, CN=SecureBuilder" | User only trusts the identity with specific subject. User can use `notation certificate show` command to get the `subject` info. | +| trustedIdentities | "*" | User trusts any identity (signing certificate) issued by the CA(s) in trust stores. | User can configure multiple trust policies for different scenarios. See [Trust Policy Schema and properties](https://github.com/notaryproject/notaryproject/blob/main/specs/trust-store-trust-policy.md#trust-policy) for details. @@ -129,7 +127,7 @@ notation verify localhost:5000/net-monitor:v1 An example of output messages for a successful verification: ```text -Warning: Always verify 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 verified. Resolved artifact tag `v1` to digest `sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9` before verification. +Warning: The resolved digest may not point to the same signed artifact, since tags are mutable. Successfully verified for localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 ``` From e611ce6db4a1e6cb2d2be5788f68ab4772d451a3 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Mon, 28 Nov 2022 15:22:03 +0800 Subject: [PATCH 08/11] update per comments Signed-off-by: Yi Zha --- specs/commandline/verify.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/commandline/verify.md b/specs/commandline/verify.md index 4f51b839c..eeb8ea59f 100644 --- a/specs/commandline/verify.md +++ b/specs/commandline/verify.md @@ -74,7 +74,7 @@ For a Window user, store file `trustpolicy.json` under directory `%USERPROFILE%\ Example values on trust policy properties: -| Property name | Value | Meaning | +| Property name | Value | Meaning | | ----------------------|--------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | name | "wabbit-networks-images" | The name of the policy is "wabbit-networks-images". | | registryScopes | "localhost:5000/net-monitor" | The policy only applies to artifacts stored in repository `localhost:5000/net-monitor`. | From 7ed1b7091f87caa7aec4123df4e0ffbc14569405 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Mon, 28 Nov 2022 15:26:19 +0800 Subject: [PATCH 09/11] update per comments Signed-off-by: Yi Zha --- specs/commandline/verify.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/commandline/verify.md b/specs/commandline/verify.md index eeb8ea59f..277afd8e1 100644 --- a/specs/commandline/verify.md +++ b/specs/commandline/verify.md @@ -70,7 +70,7 @@ For a Linux user, store file `trustpolicy.json` under directory `${HOME}/.config For a MacOS user, store file `trustpolicy.json` under directory `${HOME}/Library/Application Support/notation/`. -For a Window user, store file `trustpolicy.json` under directory `%USERPROFILE%\AppData\Roaming\notation\`. +For a Windows user, store file `trustpolicy.json` under directory `%USERPROFILE%\AppData\Roaming\notation\`. Example values on trust policy properties: From fe944a5bbdd85c7a907817910aa36f262bcc30ce Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Tue, 29 Nov 2022 09:34:50 +0800 Subject: [PATCH 10/11] update per comments Signed-off-by: Yi Zha --- specs/commandline/verify.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/specs/commandline/verify.md b/specs/commandline/verify.md index 277afd8e1..4e57b1e1b 100644 --- a/specs/commandline/verify.md +++ b/specs/commandline/verify.md @@ -5,7 +5,7 @@ Use `notation verify` command to verify signatures associated with the artifact. Signature verification succeeds if verification succeeds for at least one of the signatures associated with the artifact. Upon successful verification, the output message is printed out as follows: ```text -Successfully verified for /@ +Successfully verified signature for /@ ``` Tags are mutable and a tag reference can point to a different artifact than that was signed referred by the same tag. If a `tag` is used to identify the OCI artifact, the output message is as follows: @@ -13,7 +13,7 @@ Tags are mutable and a tag reference can point to a different artifact than that ```text Resolved artifact tag '' to digest '' before verification. Warning: The resolved digest may not point to the same signed artifact, since tags are mutable. -Successfully verified for /@ +Successfully verified signature for /@ ``` ## Outline @@ -110,7 +110,7 @@ notation verify localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dab An example of output messages for a successful verification: ```text -Successfully verified for localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 +Successfully verified signature for localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 ``` ### Verify signatures on an OCI artifact identified by a tag @@ -129,5 +129,5 @@ An example of output messages for a successful verification: ```text Resolved artifact tag `v1` to digest `sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9` before verification. Warning: The resolved digest may not point to the same signed artifact, since tags are mutable. -Successfully verified for localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 +Successfully verified signature for localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 ``` From c0de48542c3679a5bf3d5cede4e21792db6d453f Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Thu, 1 Dec 2022 21:46:00 +0800 Subject: [PATCH 11/11] update according to comments Signed-off-by: Yi Zha --- specs/commandline/verify.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/commandline/verify.md b/specs/commandline/verify.md index 4e57b1e1b..b154caac9 100644 --- a/specs/commandline/verify.md +++ b/specs/commandline/verify.md @@ -11,7 +11,7 @@ Successfully verified signature for /@ Tags are mutable and a tag reference can point to a different artifact than that was signed referred by the same tag. If a `tag` is used to identify the OCI artifact, the output message is as follows: ```text -Resolved artifact tag '' to digest '' before verification. +Resolved artifact tag `` to digest `` before verification. Warning: The resolved digest may not point to the same signed artifact, since tags are mutable. Successfully verified signature for /@ ```