From 855f9fe166c7906fedbe45578c8544eb35754fc5 Mon Sep 17 00:00:00 2001 From: Patrick Zheng Date: Fri, 18 Aug 2023 10:30:13 +0800 Subject: [PATCH 01/10] added spec for file sign/verify Signed-off-by: Patrick Zheng --- specs/commandline/sign.md | 30 ++++++++++++++++++- specs/commandline/verify.md | 59 +++++++++++++++++++++++++++++++++++++ 2 files changed, 88 insertions(+), 1 deletion(-) diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index 5c3569d5d..e80c72d3f 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -4,7 +4,8 @@ Use `notation sign` to sign artifacts. -Signs an OCI artifact stored in the registry. Always sign artifact using digest(`@sha256:...`) rather than a tag(`:v1`) because tags are mutable and a tag reference can point to a different artifact than the one signed. If a tag is used, notation resolves the tag to the `digest` before signing. +### Sign an OCI artifact stored in registry +Always sign artifact using digest(`@sha256:...`) rather than a tag(`:v1`) because tags are mutable and a tag reference can point to a different artifact than the one signed. If a tag is used, notation resolves the tag to the `digest` before signing. Upon successful signing, the generated signature is pushed to the registry and associated with the signed OCI artifact. The output message is printed out as following: @@ -19,6 +20,15 @@ Warning: Always sign the artifact using digest(`@sha256:...`) rather than a tag( Successfully signed /@ ``` +### Sign an arbitrary file stored in file system +The file content, i.e. the file blob, is signed. + +Upon successful signing, the generated signature is stored to user specified signature path in file system. The output message is printed out as following: + +```text +Successfully signed +``` + ## Outline ```text @@ -31,6 +41,7 @@ Flags: --allow-referrers-api [Experimental] use the Referrers API to store signatures in the registry, if not supported (returns 404), fallback to the Referrers tag schema -d, --debug debug mode -e, --expiry duration optional expiry that provides a "best by use" time for the artifact. The duration is specified in minutes(m) and/or hours(h). For example: 12h, 30m, 3h20m + --file enable signing a file located in file system, if set, the reference argument is the file path (required if --signature is set) -h, --help help for sign --id string key id (required if --plugin is set). This is mutually exclusive with the --key flag --insecure-registry use HTTP protocol while connecting to registries. Should be used only for testing @@ -39,6 +50,7 @@ Flags: -p, --password string password for registry operations (default to $NOTATION_PASSWORD if not specified) --plugin string signing plugin name. This is mutually exclusive with the --key flag --plugin-config stringArray {key}={value} pairs that are passed as it is to a plugin, refer plugin's documentation to set appropriate values. + --signature string output path of generated signature when signing a file (required if --file is set) --signature-format string signature envelope format, options: "jws", "cose" (default "jws") -u, --username string username for registry operations (default to $NOTATION_USERNAME if not specified) -m, --user-metadata stringArray {key}={value} pairs that are added to the signature payload @@ -153,6 +165,22 @@ Warning: Always sign the artifact using digest(`@sha256:...`) rather than a tag( Successfully signed localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 ``` +### Sign an arbitrary file located in file system +Notation supports signing a file located in user's file system. The file's content (blob) gets signed and the generated signature is stored in the same file system. +```shell +# Prerequisites: +# A default signing key is configured using CLI "notation key" + +# Use flag "--file" to enable signing a file +# Use flag "--signature" to specify path where the generated signature is stored +notation sign --file --signature +``` +An example of a successful signing: +```console +$ notation sign --file --signature ./mySignature.sig ./myFile.txt +Successfully signed ./myFile.txt +``` + ### [Experimental] Sign container images stored in OCI layout directory Container images can be stored in OCI image Layout defined in spec [OCI image layout][oci-image-layout]. It is a directory structure that contains files and folders. The OCI image layout could be a tarball or a directory in the filesystem. For example, a file named `hello-world.tar` or a directory named `hello-world`. Notation only supports signing images stored in OCI layout directory for now. Users can reference an image in the layout using either tags, or the exact digest. For example, use `hello-world:v1` or `hello-world@sha256xxx` to reference the image in OCI layout directory named `hello-world`. diff --git a/specs/commandline/verify.md b/specs/commandline/verify.md index 3576fbf39..10f2a6bef 100644 --- a/specs/commandline/verify.md +++ b/specs/commandline/verify.md @@ -2,6 +2,7 @@ ## Description +### Verify an OCI artifact stored in registry 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 @@ -26,6 +27,20 @@ KEY VALUE ``` +### Verify an arbitrary file stored in file system +Verify the file content (blob) against signatures stored in file system. Upon successful verification, the output message is printed out as follows: + +```text +Successfully verified signature for +``` + +### Verify an arbitrary file stored in registry +Verify the file content (blob) against signatures stored in registry. Upon successful verification, the output message is printed out as follows: + +```text +Successfully verified signature for /@ +``` + ## Outline ```text @@ -37,6 +52,7 @@ Usage: Flags: --allow-referrers-api [Experimental] use the Referrers API to verify signatures, if not supported (returns 404), fallback to the Referrers tag schema -d, --debug debug mode + --file enable verifying a file, if set, the reference argument is the file path or full URI reference of the file artifact in registry (required if --signature is set) -h, --help help for verify --insecure-registry use HTTP protocol while connecting to registries. Should be used only for testing --max-signatures int maximum number of signatures to evaluate or examine (default 100) @@ -45,6 +61,7 @@ Flags: --plugin-config stringArray {key}={value} pairs that are passed as it is to a plugin, if the verification is associated with a verification plugin, refer plugin documentation to set appropriate values --scope string [Experimental] set trust policy scope for artifact verification, required and can only be used when flag "--oci-layout" is set -u, --username string username for registry operations (default to $NOTATION_USERNAME if not specified) + --signature string path of signatures when verifying a file, required and used if and only if the target file is stored in file system -m, --user-metadata stringArray user defined {key}={value} pairs that must be present in the signature for successful verification if provided -v, --verbose verbose mode ``` @@ -173,6 +190,48 @@ Warning: Always verify the artifact using digest(@sha256:...) rather than a tag Successfully verified signature for localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 ``` +### Verify an arbitrary file located in OCI-compliant registry +A user wants to verify a file stored as an OCI artifact in an OCI-compliant registry. +```shell +# Prerequisites: Signatures are stored in a registry referencing the file artifact + +# Use flag "--file" to enable verifying a file +notation verify --file localhost:5000/myFile@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 +``` + +An example of output messages for a successful verification: + +```text +Successfully verified signature for localhost:5000/myFile@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 +``` + +### Verify an arbitrary file located in file system +A verifier wants to verify a file against its signatures located in file system. + +Trust policy to be used follows the rule below: +1. User MAY pass in a trust policy scope via `--scope` flag. The value MUST follow Notation's trust policy [spec](https://github.com/notaryproject/specifications/blob/main/specs/trust-store-trust-policy.md#registry-scopes-constraints). If the user specified trust policy does not exist in Notation's `trustpolicy.json` (use command `notation policy show` to check existence), then +the [global trust policy](https://github.com/notaryproject/specifications/blob/main/specs/trust-store-trust-policy.md#registry-scopes-constraints) is used. +2. If user ignores the `--scope` flag, then the trust policy with scope `file/` will be used as default. If this trust policy does not exist in Notation's `trustpolicy.json` (use command `notation policy show` to check existence), then +the [global trust policy](https://github.com/notaryproject/specifications/blob/main/specs/trust-store-trust-policy.md#registry-scopes-constraints) is used. +```shell +# Prerequisites: Both target file and signatures are stored in user's file system + +# Use flag "--file" to enable verifying a file +# Use flag "--signature" to speicfy path where the signatures are stored +# Trust policy with scope "file/myFile" is used, if it does not exist, the global trust policy is used +notation verify --file --signature ./mySignature1.sig --signature ./mySignature2.sig ./myFile.txt + +# Use flag "--file" to enable verifying a file +# Use flag "--signature" to speicfy path where the signatures are stored +# Trust policy with scope "example/myPolicy" is used, if it does not exist, the global trust policy is used +notation verify --file --signature ./mySignature1.sig --scope example/myPolicy ./myFile.txt +``` +An example of output messages for a successful verification: + +```text +Successfully verified signature for ./myFile.txt +``` + ### [Experimental] Verify container images in OCI layout directory Users should configure trust policy properly before verifying artifacts in OCI layout directory. According to trust policy specification, `registryScopes` property of trust policy configuration determines which trust policy is applicable for the given artifact. For example, an image stored in a remote registry is referenced by "localhost:5000/net-monitor:v1". In order to verify the image, the value of `registryScopes` should contain "localhost:5000/net-monitor", which is the repository URL of the image. However, the reference to the image stored in OCI layout directory doesn't contain repository URL information. Users can set `registryScopes` to the URL that the image is supposed to be stored in the registry, and then use flag `--scope` for `notation verify` command to determine which trust policy is used for verification. Here is an example of trust policy configured for image `hello-world:v1`: From 477f0bb3a34e06de49922c002d3787c38d0a5a31 Mon Sep 17 00:00:00 2001 From: Patrick Zheng Date: Thu, 17 Aug 2023 23:15:20 +0800 Subject: [PATCH 02/10] chore: quick fix on notation policy command print out (#764) Signed-off-by: Patrick Zheng --- cmd/notation/policy/import.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cmd/notation/policy/import.go b/cmd/notation/policy/import.go index 2ac1b9b4e..adeee4f70 100644 --- a/cmd/notation/policy/import.go +++ b/cmd/notation/policy/import.go @@ -65,7 +65,7 @@ func runImport(command *cobra.Command, opts importOpts) error { } } } else { - fmt.Fprintf(os.Stderr, "Warning: existing trust policy configuration file will be overwritten") + fmt.Fprintln(os.Stderr, "Warning: existing trust policy configuration file will be overwritten") } // read configuration From 1d00480518465308a856899b18b5e7825ca63bba Mon Sep 17 00:00:00 2001 From: Patrick Zheng Date: Fri, 18 Aug 2023 14:40:25 +0800 Subject: [PATCH 03/10] update Signed-off-by: Patrick Zheng --- specs/commandline/sign.md | 4 ++-- specs/commandline/verify.md | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index e80c72d3f..fb2408433 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -26,7 +26,7 @@ The file content, i.e. the file blob, is signed. Upon successful signing, the generated signature is stored to user specified signature path in file system. The output message is printed out as following: ```text -Successfully signed +Successfully signed , stored signature at ``` ## Outline @@ -178,7 +178,7 @@ notation sign --file --signature An example of a successful signing: ```console $ notation sign --file --signature ./mySignature.sig ./myFile.txt -Successfully signed ./myFile.txt +Successfully signed ./myFile.txt, stored signature at ./mySignature.sig ``` ### [Experimental] Sign container images stored in OCI layout directory diff --git a/specs/commandline/verify.md b/specs/commandline/verify.md index 10f2a6bef..ba9987a96 100644 --- a/specs/commandline/verify.md +++ b/specs/commandline/verify.md @@ -31,7 +31,7 @@ KEY VALUE Verify the file content (blob) against signatures stored in file system. Upon successful verification, the output message is printed out as follows: ```text -Successfully verified signature for +Successfully verified with signature ``` ### Verify an arbitrary file stored in registry @@ -224,12 +224,12 @@ notation verify --file --signature ./mySignature1.sig --signature ./mySignature2 # Use flag "--file" to enable verifying a file # Use flag "--signature" to speicfy path where the signatures are stored # Trust policy with scope "example/myPolicy" is used, if it does not exist, the global trust policy is used -notation verify --file --signature ./mySignature1.sig --scope example/myPolicy ./myFile.txt +notation verify --file --signature ./mySignature.sig --scope example/myPolicy ./myFile.txt ``` An example of output messages for a successful verification: ```text -Successfully verified signature for ./myFile.txt +Successfully verified ./myFile.txt with signature ./mySignature.sig ``` ### [Experimental] Verify container images in OCI layout directory From 6da89d6f84ee0ca196aef3c3e539529bb37b59c9 Mon Sep 17 00:00:00 2001 From: Patrick Zheng Date: Fri, 18 Aug 2023 17:15:48 +0800 Subject: [PATCH 04/10] update Signed-off-by: Patrick Zheng --- 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 ba9987a96..d457096dc 100644 --- a/specs/commandline/verify.md +++ b/specs/commandline/verify.md @@ -61,7 +61,7 @@ Flags: --plugin-config stringArray {key}={value} pairs that are passed as it is to a plugin, if the verification is associated with a verification plugin, refer plugin documentation to set appropriate values --scope string [Experimental] set trust policy scope for artifact verification, required and can only be used when flag "--oci-layout" is set -u, --username string username for registry operations (default to $NOTATION_USERNAME if not specified) - --signature string path of signatures when verifying a file, required and used if and only if the target file is stored in file system + --signature stringArray path of signatures when verifying a file, required and used if and only if the target file is stored in file system -m, --user-metadata stringArray user defined {key}={value} pairs that must be present in the signature for successful verification if provided -v, --verbose verbose mode ``` From a3c09ccc92ccf39f005a320245490ad1ac873cbd Mon Sep 17 00:00:00 2001 From: Patrick Zheng Date: Fri, 18 Aug 2023 17:30:19 +0800 Subject: [PATCH 05/10] update Signed-off-by: Patrick Zheng --- specs/commandline/verify.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specs/commandline/verify.md b/specs/commandline/verify.md index d457096dc..9ad98449a 100644 --- a/specs/commandline/verify.md +++ b/specs/commandline/verify.md @@ -59,7 +59,7 @@ Flags: --oci-layout [Experimental] verify the artifact stored as OCI image layout -p, --password string password for registry operations (default to $NOTATION_PASSWORD if not specified) --plugin-config stringArray {key}={value} pairs that are passed as it is to a plugin, if the verification is associated with a verification plugin, refer plugin documentation to set appropriate values - --scope string [Experimental] set trust policy scope for artifact verification, required and can only be used when flag "--oci-layout" is set + --scope string [Experimental] set trust policy scope for artifact verification, required when flag "--oci-layout" is set, can only be used when "--oci-layout" or "--file" is set -u, --username string username for registry operations (default to $NOTATION_USERNAME if not specified) --signature stringArray path of signatures when verifying a file, required and used if and only if the target file is stored in file system -m, --user-metadata stringArray user defined {key}={value} pairs that must be present in the signature for successful verification if provided @@ -221,6 +221,7 @@ the [global trust policy](https://github.com/notaryproject/specifications/blob/m # Trust policy with scope "file/myFile" is used, if it does not exist, the global trust policy is used notation verify --file --signature ./mySignature1.sig --signature ./mySignature2.sig ./myFile.txt +export NOTATION_EXPERIMENTAL=1 # Use flag "--file" to enable verifying a file # Use flag "--signature" to speicfy path where the signatures are stored # Trust policy with scope "example/myPolicy" is used, if it does not exist, the global trust policy is used From 88fbb4113d2614af24553762e3ee524b9af9725c Mon Sep 17 00:00:00 2001 From: Patrick Zheng Date: Mon, 21 Aug 2023 15:45:42 +0800 Subject: [PATCH 06/10] updated spec Signed-off-by: Patrick Zheng --- specs/commandline/sign.md | 12 ++++++++++-- specs/commandline/verify.md | 9 ++++----- 2 files changed, 14 insertions(+), 7 deletions(-) diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index fb2408433..98489220d 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -50,7 +50,7 @@ Flags: -p, --password string password for registry operations (default to $NOTATION_PASSWORD if not specified) --plugin string signing plugin name. This is mutually exclusive with the --key flag --plugin-config stringArray {key}={value} pairs that are passed as it is to a plugin, refer plugin's documentation to set appropriate values. - --signature string output path of generated signature when signing a file (required if --file is set) + --signature string output path of generated signature when signing a file, can only be used when --file is set --signature-format string signature envelope format, options: "jws", "cose" (default "jws") -u, --username string username for registry operations (default to $NOTATION_USERNAME if not specified) -m, --user-metadata stringArray {key}={value} pairs that are added to the signature payload @@ -171,12 +171,20 @@ Notation supports signing a file located in user's file system. The file's conte # Prerequisites: # A default signing key is configured using CLI "notation key" +# Use flag "--file" to enable signing a file +# The generated signature is saved at the same dir as the target file with name +# .sig +notation sign --file + # Use flag "--file" to enable signing a file # Use flag "--signature" to specify path where the generated signature is stored notation sign --file --signature ``` -An example of a successful signing: +Examples of successful signing: ```console +$ notation sign --file ./myFile.txt +Successfully signed ./myFile.txt, stored signature at ./myFile.sig + $ notation sign --file --signature ./mySignature.sig ./myFile.txt Successfully signed ./myFile.txt, stored signature at ./mySignature.sig ``` diff --git a/specs/commandline/verify.md b/specs/commandline/verify.md index 9ad98449a..c51585802 100644 --- a/specs/commandline/verify.md +++ b/specs/commandline/verify.md @@ -52,7 +52,7 @@ Usage: Flags: --allow-referrers-api [Experimental] use the Referrers API to verify signatures, if not supported (returns 404), fallback to the Referrers tag schema -d, --debug debug mode - --file enable verifying a file, if set, the reference argument is the file path or full URI reference of the file artifact in registry (required if --signature is set) + --file enable verifying a file, if set, the reference argument is the file path or full URI reference of the file artifact in registry (required if --signature is set) -h, --help help for verify --insecure-registry use HTTP protocol while connecting to registries. Should be used only for testing --max-signatures int maximum number of signatures to evaluate or examine (default 100) @@ -193,7 +193,7 @@ Successfully verified signature for localhost:5000/net-monitor@sha256:b94d27b993 ### Verify an arbitrary file located in OCI-compliant registry A user wants to verify a file stored as an OCI artifact in an OCI-compliant registry. ```shell -# Prerequisites: Signatures are stored in a registry referencing the file artifact +# Prerequisites: Signatures are stored in the registry referencing the file artifact # Use flag "--file" to enable verifying a file notation verify --file localhost:5000/myFile@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 @@ -211,14 +211,13 @@ A verifier wants to verify a file against its signatures located in file system. Trust policy to be used follows the rule below: 1. User MAY pass in a trust policy scope via `--scope` flag. The value MUST follow Notation's trust policy [spec](https://github.com/notaryproject/specifications/blob/main/specs/trust-store-trust-policy.md#registry-scopes-constraints). If the user specified trust policy does not exist in Notation's `trustpolicy.json` (use command `notation policy show` to check existence), then the [global trust policy](https://github.com/notaryproject/specifications/blob/main/specs/trust-store-trust-policy.md#registry-scopes-constraints) is used. -2. If user ignores the `--scope` flag, then the trust policy with scope `file/` will be used as default. If this trust policy does not exist in Notation's `trustpolicy.json` (use command `notation policy show` to check existence), then -the [global trust policy](https://github.com/notaryproject/specifications/blob/main/specs/trust-store-trust-policy.md#registry-scopes-constraints) is used. +2. If user ignores the `--scope` flag, then the [global trust policy](https://github.com/notaryproject/specifications/blob/main/specs/trust-store-trust-policy.md#registry-scopes-constraints) is used as default. ```shell # Prerequisites: Both target file and signatures are stored in user's file system # Use flag "--file" to enable verifying a file # Use flag "--signature" to speicfy path where the signatures are stored -# Trust policy with scope "file/myFile" is used, if it does not exist, the global trust policy is used +# The global trust policy is used by default notation verify --file --signature ./mySignature1.sig --signature ./mySignature2.sig ./myFile.txt export NOTATION_EXPERIMENTAL=1 From 3520ec4a62b2452943914c5c94b982a0cb5964d8 Mon Sep 17 00:00:00 2001 From: Patrick Zheng Date: Tue, 22 Aug 2023 13:32:23 +0800 Subject: [PATCH 07/10] updated per code review Signed-off-by: Patrick Zheng --- specs/commandline/sign.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index 98489220d..457dc78f6 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -26,7 +26,7 @@ The file content, i.e. the file blob, is signed. Upon successful signing, the generated signature is stored to user specified signature path in file system. The output message is printed out as following: ```text -Successfully signed , stored signature at +Successfully signed and created signature at ``` ## Outline @@ -183,10 +183,10 @@ notation sign --file --signature Examples of successful signing: ```console $ notation sign --file ./myFile.txt -Successfully signed ./myFile.txt, stored signature at ./myFile.sig +Successfully signed ./myFile.txt and created signature at ./myFile.sig $ notation sign --file --signature ./mySignature.sig ./myFile.txt -Successfully signed ./myFile.txt, stored signature at ./mySignature.sig +Successfully signed ./myFile.txt and created signature at ./mySignature.sig ``` ### [Experimental] Sign container images stored in OCI layout directory From 4d6e4346342d3121144aea39058606db8ffbac57 Mon Sep 17 00:00:00 2001 From: Patrick Zheng Date: Tue, 22 Aug 2023 15:20:49 +0800 Subject: [PATCH 08/10] update Signed-off-by: Patrick Zheng --- 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 457dc78f6..c98948e52 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -41,7 +41,7 @@ Flags: --allow-referrers-api [Experimental] use the Referrers API to store signatures in the registry, if not supported (returns 404), fallback to the Referrers tag schema -d, --debug debug mode -e, --expiry duration optional expiry that provides a "best by use" time for the artifact. The duration is specified in minutes(m) and/or hours(h). For example: 12h, 30m, 3h20m - --file enable signing a file located in file system, if set, the reference argument is the file path (required if --signature is set) + --file enable signing a file's content, if set, the reference argument is the file path in the file system (required if --signature is set) -h, --help help for sign --id string key id (required if --plugin is set). This is mutually exclusive with the --key flag --insecure-registry use HTTP protocol while connecting to registries. Should be used only for testing From 0c5c86ab9c48bed211998dff4540127d36e9f8c5 Mon Sep 17 00:00:00 2001 From: Patrick Zheng Date: Wed, 23 Aug 2023 11:09:39 +0800 Subject: [PATCH 09/10] updated per code review Signed-off-by: Patrick Zheng --- specs/commandline/sign.md | 13 ++++++++----- specs/commandline/verify.md | 11 ++++++++--- 2 files changed, 16 insertions(+), 8 deletions(-) diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index c98948e52..dd692de54 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -5,6 +5,7 @@ Use `notation sign` to sign artifacts. ### Sign an OCI artifact stored in registry + Always sign artifact using digest(`@sha256:...`) rather than a tag(`:v1`) because tags are mutable and a tag reference can point to a different artifact than the one signed. If a tag is used, notation resolves the tag to the `digest` before signing. Upon successful signing, the generated signature is pushed to the registry and associated with the signed OCI artifact. The output message is printed out as following: @@ -21,6 +22,7 @@ Successfully signed /@ ``` ### Sign an arbitrary file stored in file system + The file content, i.e. the file blob, is signed. Upon successful signing, the generated signature is stored to user specified signature path in file system. The output message is printed out as following: @@ -41,7 +43,7 @@ Flags: --allow-referrers-api [Experimental] use the Referrers API to store signatures in the registry, if not supported (returns 404), fallback to the Referrers tag schema -d, --debug debug mode -e, --expiry duration optional expiry that provides a "best by use" time for the artifact. The duration is specified in minutes(m) and/or hours(h). For example: 12h, 30m, 3h20m - --file enable signing a file's content, if set, the reference argument is the file path in the file system (required if --signature is set) + --file enable signing file content, if set, the reference argument is the file path in the file system (required if --signature is set) -h, --help help for sign --id string key id (required if --plugin is set). This is mutually exclusive with the --key flag --insecure-registry use HTTP protocol while connecting to registries. Should be used only for testing @@ -166,7 +168,8 @@ Successfully signed localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da ``` ### Sign an arbitrary file located in file system -Notation supports signing a file located in user's file system. The file's content (blob) gets signed and the generated signature is stored in the same file system. + +Notation supports signing files located in file systems. ```shell # Prerequisites: # A default signing key is configured using CLI "notation key" @@ -182,11 +185,11 @@ notation sign --file --signature ``` Examples of successful signing: ```console -$ notation sign --file ./myFile.txt -Successfully signed ./myFile.txt and created signature at ./myFile.sig +$ notation sign --file myFile.txt +Successfully signed myFile.txt and created signature at myFile.sig $ notation sign --file --signature ./mySignature.sig ./myFile.txt -Successfully signed ./myFile.txt and created signature at ./mySignature.sig +Successfully signed myFile.txt and created signature at mySignature.sig ``` ### [Experimental] Sign container images stored in OCI layout directory diff --git a/specs/commandline/verify.md b/specs/commandline/verify.md index c51585802..c02d2d13d 100644 --- a/specs/commandline/verify.md +++ b/specs/commandline/verify.md @@ -3,6 +3,7 @@ ## Description ### Verify an OCI artifact stored in registry + 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 @@ -28,6 +29,7 @@ KEY VALUE ``` ### Verify an arbitrary file stored in file system + Verify the file content (blob) against signatures stored in file system. Upon successful verification, the output message is printed out as follows: ```text @@ -35,6 +37,7 @@ Successfully verified with signature ``` ### Verify an arbitrary file stored in registry + Verify the file content (blob) against signatures stored in registry. Upon successful verification, the output message is printed out as follows: ```text @@ -61,7 +64,7 @@ Flags: --plugin-config stringArray {key}={value} pairs that are passed as it is to a plugin, if the verification is associated with a verification plugin, refer plugin documentation to set appropriate values --scope string [Experimental] set trust policy scope for artifact verification, required when flag "--oci-layout" is set, can only be used when "--oci-layout" or "--file" is set -u, --username string username for registry operations (default to $NOTATION_USERNAME if not specified) - --signature stringArray path of signatures when verifying a file, required and used if and only if the target file is stored in file system + --signature string path of signature when verifying a file, required and used if and only if the target file is stored in file system -m, --user-metadata stringArray user defined {key}={value} pairs that must be present in the signature for successful verification if provided -v, --verbose verbose mode ``` @@ -191,6 +194,7 @@ Successfully verified signature for localhost:5000/net-monitor@sha256:b94d27b993 ``` ### Verify an arbitrary file located in OCI-compliant registry + A user wants to verify a file stored as an OCI artifact in an OCI-compliant registry. ```shell # Prerequisites: Signatures are stored in the registry referencing the file artifact @@ -206,6 +210,7 @@ Successfully verified signature for localhost:5000/myFile@sha256:b94d27b9934d3e0 ``` ### Verify an arbitrary file located in file system + A verifier wants to verify a file against its signatures located in file system. Trust policy to be used follows the rule below: @@ -218,13 +223,13 @@ the [global trust policy](https://github.com/notaryproject/specifications/blob/m # Use flag "--file" to enable verifying a file # Use flag "--signature" to speicfy path where the signatures are stored # The global trust policy is used by default -notation verify --file --signature ./mySignature1.sig --signature ./mySignature2.sig ./myFile.txt +notation verify --file --signature mySignature1.sig myFile.txt export NOTATION_EXPERIMENTAL=1 # Use flag "--file" to enable verifying a file # Use flag "--signature" to speicfy path where the signatures are stored # Trust policy with scope "example/myPolicy" is used, if it does not exist, the global trust policy is used -notation verify --file --signature ./mySignature.sig --scope example/myPolicy ./myFile.txt +notation verify --file --signature mySignature.sig --scope example/myPolicy myFile.txt ``` An example of output messages for a successful verification: From 0395b6aa1875dceaa8d9e92652757980b128a583 Mon Sep 17 00:00:00 2001 From: Patrick Zheng Date: Wed, 23 Aug 2023 11:20:05 +0800 Subject: [PATCH 10/10] updated per code review Signed-off-by: Patrick Zheng --- specs/commandline/sign.md | 6 +++--- specs/commandline/verify.md | 8 ++++---- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index dd692de54..f57d7ed5b 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -186,10 +186,10 @@ notation sign --file --signature Examples of successful signing: ```console $ notation sign --file myFile.txt -Successfully signed myFile.txt and created signature at myFile.sig +Successfully signed myFile.txt and created signature at myFile.txt.sig -$ notation sign --file --signature ./mySignature.sig ./myFile.txt -Successfully signed myFile.txt and created signature at mySignature.sig +$ notation sign --file --signature mySignature.sig myFile +Successfully signed myFile and created signature at mySignature.sig ``` ### [Experimental] Sign container images stored in OCI layout directory diff --git a/specs/commandline/verify.md b/specs/commandline/verify.md index c02d2d13d..f7f240478 100644 --- a/specs/commandline/verify.md +++ b/specs/commandline/verify.md @@ -218,16 +218,16 @@ Trust policy to be used follows the rule below: the [global trust policy](https://github.com/notaryproject/specifications/blob/main/specs/trust-store-trust-policy.md#registry-scopes-constraints) is used. 2. If user ignores the `--scope` flag, then the [global trust policy](https://github.com/notaryproject/specifications/blob/main/specs/trust-store-trust-policy.md#registry-scopes-constraints) is used as default. ```shell -# Prerequisites: Both target file and signatures are stored in user's file system +# Prerequisites: Both target and signature files are stored in file system # Use flag "--file" to enable verifying a file -# Use flag "--signature" to speicfy path where the signatures are stored +# Use flag "--signature" to speicfy path where the signature is stored # The global trust policy is used by default -notation verify --file --signature mySignature1.sig myFile.txt +notation verify --file --signature mySignature.sig myFile.txt export NOTATION_EXPERIMENTAL=1 # Use flag "--file" to enable verifying a file -# Use flag "--signature" to speicfy path where the signatures are stored +# Use flag "--signature" to speicfy path where the signature is stored # Trust policy with scope "example/myPolicy" is used, if it does not exist, the global trust policy is used notation verify --file --signature mySignature.sig --scope example/myPolicy myFile.txt ```