From ba28208524ccbe359a19553a913939bdf024a54b Mon Sep 17 00:00:00 2001 From: Rakesh Gariganti <5878554+rgnote@users.noreply.github.com> Date: Fri, 8 Mar 2024 11:51:00 -0800 Subject: [PATCH] docs: spec updates for arbitrary blob signing (#811) CLI Spec updated for Arbitrary blob signing. Proposal https://hackmd.io/ewbJr2ZnT4a8U1ObDVXcSw?view#CLI-Spec and https://hackmd.io/@-KPyDkW6QfGA-pldFa13pA/ByuHffALa Signing Scheme and trust policy updates : https://github.com/notaryproject/specifications/pull/283 Signed-off-by: rgnote <5878554+rgnote@users.noreply.github.com> --------- Signed-off-by: rgnote <5878554+rgnote@users.noreply.github.com> Signed-off-by: Patrick Zheng Signed-off-by: Feynman Zhou Signed-off-by: dependabot[bot] Signed-off-by: Cameron Rozean Signed-off-by: Yi Zha Signed-off-by: Rakesh Gariganti <5878554+rgnote@users.noreply.github.com> Signed-off-by: Junjie Gao Signed-off-by: Toddy Mladenov Co-authored-by: Patrick Zheng Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Feynman Zhou Co-authored-by: Cameron Rozean Co-authored-by: Yi Zha Co-authored-by: Shiwei Zhang Co-authored-by: Milind Gokarn Co-authored-by: Junjie Gao Co-authored-by: Toddy Mladenov Co-authored-by: Pritesh Bandi --- specs/commandline/blob.md | 500 +++++++++++++++++++++++++++++++++++ specs/commandline/inspect.md | 7 +- specs/commandline/list.md | 4 +- specs/commandline/policy.md | 36 +-- specs/commandline/sign.md | 4 +- specs/commandline/verify.md | 7 +- specs/notation-cli.md | 30 ++- 7 files changed, 550 insertions(+), 38 deletions(-) create mode 100644 specs/commandline/blob.md diff --git a/specs/commandline/blob.md b/specs/commandline/blob.md new file mode 100644 index 000000000..1fdb76ec6 --- /dev/null +++ b/specs/commandline/blob.md @@ -0,0 +1,500 @@ +# notation blob + +## Description + +Use `notation blob` command to sign, verify, and inspect signatures associated with arbitrary blobs. Notation can sign and verify any arbitrary bag of bits like zip files, documents, executables, etc. When a user signs a blob, `notation` produces a detached signature, which the user can transport/distribute using any medium that the user prefers along with the original blob. On the verification side, Notation can verify the blob's signature and assert that the blob has not been tampered with during its transmission. + +Users can use `notation blob policy` command to manage trust policies for verifying a blob signature. The `notation blob policy` command provides a user-friendly way to manage trust policies for signed blobs. It allows users to show trust policy configuration, import/export a trust policy configuration file from/to a JSON file. For more details, see [blob trust policy specification and examples](https://github.com/notaryproject/specifications/blob/main/specs/trust-store-trust-policy.md#blob-trust-policy). + +The sample trust policy file (`trustpolicy.blob.json`) for verifying signed blobs is shown below. This sample trust policy file, contains three different statements for different usecases: + +- The Policy named "wabbit-networks-policy" is for verifying blob artifacts signed by Wabbit Networks. +- Policy named "skip-verification-policy" is for skipping verification on blob artifacts. +- Policy "global-verification-policy" is for auditing verification results when user does not provide `--policy-name` argument in `notation blob verify` command. + +```jsonc +{ + "version": "1.0", + "trustPolicies": [ + { + "name": "wabbit-networks-policy", + "signatureVerification": { + "level": "strict" + }, + "trustStores": [ + "ca:wabbit-networks", + ], + "trustedIdentities": [ + "x509.subject: C=US, ST=WA, L=Seattle, O=wabbit-networks.io, OU=Security Tools" + ] + }, + { + "name": "skip-verification-policy", + "signatureVerification": { + "level" : "skip" + } + }, + { + "name": "global-verification-policy", + "globalPolicy": true, + "signatureVerification": { + "level" : "audit" + }, + "trustStores": ["ca:acme-rockets"], + "trustedIdentities": ["*"] + } + ] +} +``` + +## Outline + +### notation blob command + +```text +Sign, inspect, and verify signatures and configure trust policies. + +Usage: + notation blob [command] + +Available Commands: + inspect inspect a signature associated with a blob + policy manage trust policy configuration for signed blobs + sign produce a detached signature for a given blob + verify verify a signature associated with a blob + +Flags: + -h, --help help for blob +``` + +### notation blob sign + +```text +Produce a signature for a given blob. A detached signature file will be written to the currently working directory with blob file name + ".sig" + signature format as the file extension. For example, signature file name for "myBlob.bin" will be "myBlob.bin.sig.jws" for JWS signature format or "myBlob.bin.sig.cose" for COSE signature format. + +Usage: + notation blob sign [flags] + +Flags: + --signature-directory string optional path where the blob signature needs to be placed (default: currently working directory) + --media-type string optional media type of the blob (default: "application/octet-stream") + -e, --expiry duration optional expiry that provides a "best by use" time for the blob. The duration is specified in minutes(m) and/or hours(h). For example: 12h, 30m, 3h20m + --id string key id (required if --plugin is set). This is mutually exclusive with the --key flag + -k, --key string signing key name, for a key previously added to notation's key list. This is mutually exclusive with the --id and --plugin flags + --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-format string signature envelope format, options: "jws", "cose" (default "jws") + -m, --user-metadata stringArray {key}={value} pairs that are added to the signature payload + -d, --debug debug mode + -v, --verbose verbose mode + -h, --help help for sign +``` + +### notation blob inspect + +```text +Inspect a signature associated with a blob + +Usage: + notation blob inspect [flags] + +Flags: + -o, --output string output format, options: 'json', 'text' (default "text") + -d, --debug debug mode + -v, --verbose verbose mode + -h, --help help for inspect +``` + +### notation blob policy + +```text +Manage trust policy configuration for arbitrary blob signature verification. + +Usage: + notation blob policy [command] + +Available Commands: + import import trust policy configuration from a JSON file + show show trust policy configuration + +Flags: + -h, --help help for policy +``` + +### notation blob policy import + +```text +Import blob trust policy configuration from a JSON file + +Usage: + notation blob policy import [flags] + +Flags: + --force override the existing trust policy configuration, never prompt + -h, --help help for import +``` + +### notation blob policy show + +```text +Show blob trust policy configuration + +Usage: + notation blob policy show [flags] + +Flags: + -h, --help help for show +``` + +### notation blob verify + +```text +Verify a signature associated with a blob + +Usage: + notation blob verify [flags] --signature + +Flags: + --signature string location of the blob signature file + --media-type string optional media type of the blob to verify + --policy-name string optional policy name to verify against. If not provided, notation verifies against the global policy if it exists. + -m, --user-metadata stringArray user defined {key}={value} pairs that must be present in the signature for successful verification if provided + --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 + -o, --output string output format, options: 'json', 'text' (default "text") + -d, --debug debug mode + -v, --verbose verbose mode + -h, --help help for inspect +``` + +## Usage + +## Produce blob signatures + +### Sign a blob by adding a new key + +```shell +# Prerequisites: +# - A signing plugin is installed. See plugin documentation (https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md) for more details. +# - Configure the signing plugin as instructed by plugin vendor. + +# Add a default signing key referencing the remote key identifier, and the plugin associated with it. +notation key add --default --name --plugin --id + +# sign a blob +notation blob sign /tmp/my-blob.bin +``` + +An example for a successful signing: + +```console +$ notation blob sign /tmp/my-blob.bin +Successfully signed /tmp/my-blob.bin +Signature file written to /absolute/path/to/cwd/my-blob.bin.sig.jws +``` + +### Sign a blob by generating the signature in a particular directory +```console +$ notation blob sign --signature-directory /tmp/xyz/sigs /tmp/my-blob.bin +Successfully signed /tmp/my-blob.bin +Signature file written to /tmp/xyz/sigs/my-blob.bin.sig.jws +``` + +### Sign a blob using a relative path +```console +$ notation blob sign ./relative/path/my-blob.bin +Successfully signed ./relative/path/my-blob.bin +Signature file written to /absolute/path/to/cwd/my-blob.bin.sig.jws +``` + +### Sign a blob with a plugin + +```shell +notation blob sign --plugin --id /tmp/my-blob.bin +``` + +### Sign a blob using COSE signature format + +```console +# Prerequisites: +# A default signing key is configured using CLI "notation key" + +# Use option "--signature-format" to set the signature format to COSE. +$ notation blob sign --signature-format cose /tmp/my-blob.bin +Successfully signed /tmp/my-blob.bin +Signature file written to /absolute/path/to/cwd/my-blob.bin.sig.cose +``` + +### Sign a blob using the default signing key + +```shell +# Prerequisites: +# A default signing key is configured using CLI "notation key" + +notation blob sign /tmp/my-blob.bin +``` + +### Sign a blob with user metadata + +```shell +# Prerequisites: +# A default signing key is configured using CLI "notation key" + +# sign a blob and add user-metadata io.wabbit-networks.buildId=123 to the payload +notation blob sign --user-metadata io.wabbit-networks.buildId=123 /tmp/my-blob.bin + +# sign a blob and add user-metadata io.wabbit-networks.buildId=123 and io.wabbit-networks.buildTime=1672944615 to the payload +notation blob sign --user-metadata io.wabbit-networks.buildId=123 --user-metadata io.wabbit-networks.buildTime=1672944615 /tmp/my-blob.bin +``` + +### Sign a blob and specify the media type for the blob + +```shell +notation blob sign --media-type /tmp/my-blob.bin +``` + +### Sign a blob and specify the signature expiry duration, for example 24 hours + +```shell +notation blob sign --expiry 24h /tmp/my-blob.bin +``` + +### Sign a blob using a specified signing key + +```shell +# List signing keys to get the key name +notation key list + +# Sign a container image using the specified key name +notation blob sign --key /tmp/my-blob.bin +``` + +## Inspect blob signatures + +### Display details of the given blob signature and its associated certificate properties + + +```text +notation blob inspect [flags] /tmp/my-blob.bin.sig.jws +``` + +### Inspect the given blob signature + +```shell +# Prerequisites: Signatures is produced by notation blob sign command +notation blob inspect /tmp/my-blob.bin.sig.jws +``` + +An example output: +```shell +/tmp/my-blob.bin.sig.jws + ├── signature algorithm: RSASSA-PSS-SHA-256 + ├── signature envelope type: jws + ├── signed attributes + │ ├── content type: application/vnd.cncf.notary.payload.v1+json + │ ├── signing scheme: notary.signingAuthority.x509 + │ ├── signing time: Fri Jun 23 22:04:01 2023 + │ ├── expiry: Sat Jun 29 22:04:01 2024 + │ └── io.cncf.notary.verificationPlugin: com.example.nv2plugin + ├── unsigned attributes + │ ├── io.cncf.notary.timestampSignature: + │ └── io.cncf.notary.signingAgent: notation/1.0.0 + ├── certificates + │ ├── SHA256 fingerprint: b13a843be16b1f461f08d61c14f3eab7d87c073570da077217541a7eb31c084d + │ │ ├── issued to: wabbit-com Software + │ │ ├── issued by: wabbit-com Software Root Certificate Authority + │ │ └── expiry: Sun Jul 06 20:50:17 2025 + │ ├── SHA256 fingerprint: 4b9fa61d5aed0fabbc7cb8fe2efd049da57957ed44f2b98f7863ce18effd3b89 + │ │ ├── issued to: wabbit-com Software Code Signing PCA 2010 + │ │ ├── issued by: wabbit-com Software Root Certificate Authority + │ │ └── expiry: Sun Jul 06 20:50:17 2025 + │ └── SHA256 fingerprint: ea3939548ad0c0a86f164ab8b97858854238c797f30bddeba6cb28688f3f6536 + │ ├── issued to: wabbit-com Software Root Certificate Authority + │ ├── issued by: wabbit-com Software Root Certificate Authority + │ └── expiry: Sat Jun 23 22:04:01 2035 + └── signed artifact + ├── media type: application/octet-stream + ├── digest: sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa + └── size: 16724 +``` + +### Inspect the given blob signature with JSON Output + +```shell +notation blob inspect -o json /tmp/my-blob.bin.sig.jws +``` + +## Import/Export trust policy configuration files + +### Import blob trust policy configuration from a JSON file + +An example of import trust policy configuration from a JSON file: + +```shell +notation blob policy import ./my_policy.json +``` + +The trust policy configuration in the JSON file should be validated according to [trust policy properties](https://github.com/notaryproject/notaryproject/specs/trust-store-trust-policy.md#blob-trust-policy). A successful message should be printed out if trust policy configuration are imported successfully. Error logs including the reason should be printed out if the importing fails. + +If there is an existing trust policy configuration, prompt for users to confirm whether discarding existing configuration or not. Users can use `--force` flag to discard existing trust policy configuration without prompt. + +### Show blob trust policies + +Use the following command to show trust policy configuration: + +```shell +notation blob policy show +``` + +Upon successful execution, the trust policy configuration is printed out to standard output. If trust policy is not configured or is malformed, users should receive an error message via standard error output, and a tip to import trust policy configuration from a JSON file. + +### Export blob trust policy configuration into a JSON file + +Users can redirect the output of command `notation blob policy show` to a JSON file. + +```shell +notation blob policy show > ./blob_trust_policy.json +``` + +### Update trust policy configuration + +The steps to update blob trust policy configuration: + +1. Export trust policy configuration into a JSON file. + + ```shell + notation blob policy show > ./blob_trust_policy.json + ``` + +2. Edit the exported JSON file "blob_trust_policy.json", update trust policy configuration and save the file. +3. Import trust policy configuration from the file. + + ```shell + notation blob policy import ./blob_trust_policy.json + ``` + +## Verify blob signatures +The `notation blob verify` command can be used to verify blob signatures. In order to verify signatures, user will need to setup a trust policy file `trustpolicy.blob.json` with Policies for blobs. Below are two examples of how a policy configuration file can be setup for verifying blob signatures. + +- The Policy named "wabbit-networks-policy" is for verifying blob artifacts signed by Wabbit Networks. +- Policy named "global-verification-policy" is for auditing verification results when user doesn't not provide `--policy-name` argument in `notation blob verify` command. + +```jsonc +{ + "version": "1.0", + "trustPolicies": [ + { + "name": "wabbit-networks-policy", + "signatureVerification": { + "level": "strict" + }, + "trustStores": [ + "ca:wabbit-networks", + ], + "trustedIdentities": [ + "x509.subject: C=US, ST=WA, L=Seattle, O=wabbit-networks.io, OU=Security Tools" + ] + }, + { + "name": "global-verification-policy", + "globalPolicy": true, + "signatureVerification": { + "level" : "audit" + }, + "trustStores": ["ca:acme-rockets"], + "trustedIdentities": ["*"] + } + ] +} +``` + +### Verify the signature of a blob + +Configure trust store and trust policy properly before using `notation blob verify` command. + +```shell + +# Prerequisites: Blob and its associated signature is present on the filesystem. +# 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 + +# Setup the trust policy in a JSON file named "trustpolicy.blob.json" under directory "{NOTATION_CONFIG}". + +# Verify the blob signature +notation blob verify --signature /tmp/my-blob.bin.sig.jws /tmp/my-blob.bin +``` + +An example of output messages for a successful verification: + +```text +Successfully verified signature /tmp/my-blob.bin.sig.jws +``` + +### Verify the signature with user metadata + +Use the `--user-metadata` flag to verify that provided key-value pairs are present in the payload of the valid signature. + +```shell +# Verify the signature and verify that io.wabbit-networks.buildId=123 is present in the signed payload +notation blob verify --user-metadata io.wabbit-networks.buildId=123 --signature /tmp/my-blob.bin.sig.jws /tmp/my-blob.bin +``` + +An example of output messages for a successful verification: + +```text +Successfully verified signature /tmp/my-blob.bin.sig.jws + +The signature contains the following user metadata: + +KEY VALUE +io.wabbit-networks.buildId 123 +``` + +An example of output messages for an unsuccessful verification: + +```text +Error: signature verification failed: unable to find specified metadata in the given signature +``` + +### Verify the signature with media type + +Use the `--media-type` flag to verify that signature is for the provided media-type. + +```shell +# Verify the signature and verify that application/my-media-octet-stream is the media type +notation blob verify --media-type application/my-media-octet-stream --signature /tmp/my-blob.bin.sig.jws /tmp/my-blob.bin +``` + +An example of output messages for a successful verification: + +```text +Successfully verified signature /tmp/my-blob.bin.sig.jws + +The blob is of media type `application/my-media-octet-stream`. + +``` + +An example of output messages for an unsuccessful verification: + +```text +Error: Signature verification failed due to a mismatch in the blob's media type 'application/xyz' and the expected type 'application/my-media-octet-stream'. +``` + +### Verify the signature using a policy name + +Use the `--policy-name` flag to select a policy to verify the signature against. + +```shell +notation blob verify --policy-name wabbit-networks-policy --signature ./sigs/my-blob.bin.sig.jws ./blobs/my-blob.bin +``` + +An example of output messages for a successful verification: + +```text +Successfully verified signature ./sigs/my-blob.bin.sig.jws using policy `wabbit-networks-policy` + +``` +An example of output messages for an unsuccessful verification: + +```text +Error: signature verification failed for policy `wabbit-networks-policy` +``` \ No newline at end of file diff --git a/specs/commandline/inspect.md b/specs/commandline/inspect.md index 33db06563..5dc9b334d 100644 --- a/specs/commandline/inspect.md +++ b/specs/commandline/inspect.md @@ -2,7 +2,7 @@ ## Description -Use `notation inspect` command to inspect all the signatures associated with signed artifact in a human readable format. +Use `notation inspect` command to inspect all the signatures associated with artifacts stored in OCI compliant registries in a human readable format. Upon successful execution, both the digest of the signed artifact and the digests of signatures manifest along with their properties associated with the signed artifact are printed in the following format: @@ -24,10 +24,13 @@ Upon successful execution, both the digest of the signed artifact and the digest └── ``` +> [!NOTE] +> This command is for inspecting signatures associated with OCI artifacts only. Use `notation blob inspect` command for inspecting signatures associated with arbitrary blobs. + ## Outline ```text -Inspect all signatures associated with the signed artifact. +Inspect all signatures associated with a signed OCI artifact. Usage: notation inspect [flags] diff --git a/specs/commandline/list.md b/specs/commandline/list.md index 075a80250..d73be9758 100644 --- a/specs/commandline/list.md +++ b/specs/commandline/list.md @@ -2,7 +2,7 @@ ## Description -Use `notation list` to list all the signatures associated with signed artifact. +Use `notation list` to list all the signatures associated with a signed OCI artifact. `Tags` are mutable, but `Digests` uniquely and immutably identify an artifact. If a tag is used to identify a signed artifact, notation resolves the tag to the `digest` first. @@ -18,7 +18,7 @@ Upon successful execution, both the digest of the signed artifact and the digest ## Outline ```text -List all the signatures associated with signed artifact +List all the signatures associated with a signed OCI artifact Usage: notation list [flags] diff --git a/specs/commandline/policy.md b/specs/commandline/policy.md index 56abd236a..f31361757 100644 --- a/specs/commandline/policy.md +++ b/specs/commandline/policy.md @@ -2,14 +2,16 @@ ## Description -As part of signature verification workflow, users need to configure the trust policy configuration file to specify trusted identities that signed the artifacts, the level of signature verification to use and other settings. For more details, see [trust policy specification and examples](https://github.com/notaryproject/notaryproject/blob/v1.0.0-rc.2/specs/trust-store-trust-policy.md#trust-policy). +As part of signature verification workflow of signed OCI artifacts, users need to configure trust policy configuration file to specify trusted identities that signed the artifacts, the level of signature verification to use and other settings. For more details, see [OCI trust policy specification and examples](https://github.com/notaryproject/specifications/blob/main/specs/trust-store-trust-policy.md#oci-trust-policy). -The `notation policy` command provides a user-friendly way to manage trust policies. It allows users to show trust policy configuration, import/export a trust policy configuration file from/to a JSON file. To get started user can refer to the following trust policy configuration sample. In this sample, there are four policies configured for different requirements: +The `notation policy` command provides a user-friendly way to manage trust policies for signed OCI images. It allows users to show trust policy configuration, import/export a trust policy configuration file from/to a JSON file. Users who want to manage trust policies for signed arbitrary blobs, please refer to `notation blob policy` command. -- The Policy named "wabbit-networks-images" is for verifying images signed by Wabbit Networks and stored in two repositories `registry.acme-rockets.io/software/net-monitor` and `registry.acme-rockets.io/software/net-logger`. -- Policy named "unsigned-image" is for skipping the verification on unsigned images stored in repository `registry.acme-rockets.io/software/unsigned/net-utils`. -- Policy "allow-expired-images" is for logging instead of failing expired images stored in repository `registry.acme-rockets.io/software/legacy/metrics`. -- Policy "global-policy-for-all-other-images" is for verifying any other images that signed by the ACME Rockets. +To get started, user can refer to the following trust policy configuration sample `trustpolicy.json` that is applicable for verifying signed OCI artifacts using `notation verify` command. In this sample, there are four policies configured for different requirements: + +- The Policy named "wabbit-networks-images" is for verifying OCI artifacts signed by Wabbit Networks and stored in two repositories `registry.acme-rockets.io/software/net-monitor` and `registry.acme-rockets.io/software/net-logger`. +- Policy named "unsigned-image" is for skipping the verification on unsigned OCI artifacts stored in repository `registry.acme-rockets.io/software/unsigned/net-utils`. +- Policy "allow-expired-images" is for logging instead of failing expired OCI artifacts stored in repository `registry.acme-rockets.io/software/legacy/metrics`. +- Policy "global-policy-for-all-other-images" is for verifying any other OCI artifacts that signed by the ACME Rockets. ```jsonc { @@ -72,7 +74,7 @@ The `notation policy` command provides a user-friendly way to manage trust polic ### notation policy command ```text -Manage trust policy configuration for signature verification. +Manage trust policy configuration for OCI artifact signature verification. Usage: notation policy [command] @@ -88,7 +90,7 @@ Flags: ### notation policy import ```text -Import trust policy configuration from a JSON file +Import OCI trust policy configuration from a JSON file Usage: notation policy import [flags] @@ -101,7 +103,7 @@ Flags: ### notation policy show ```text -Show trust policy configuration +Show OCI trust policy configuration Usage: notation policy show [flags] @@ -120,7 +122,7 @@ An example of import trust policy configuration from a JSON file: notation policy import ./my_policy.json ``` -The trust policy configuration in the JSON file should be validated according to [trust policy properties](https://github.com/notaryproject/notaryproject/blob/v1.0.0-rc.2/specs/trust-store-trust-policy.md#trust-policy-properties). A successful message should be printed out if trust policy configuration are imported successfully. Error logs including the reason should be printed out if the importing fails. +The trust policy configuration in the JSON file should be validated according to [trust policy properties](https://github.com/notaryproject/notaryproject/specs/trust-store-trust-policy.md#trust-policy-properties). A successful message should be printed out if trust policy configuration are imported successfully. Error logs including the reason should be printed out if the importing fails. If there is an existing trust policy configuration, prompt for users to confirm whether discarding existing configuration or not. Users can use `--force` flag to discard existing trust policy configuration without prompt. @@ -132,29 +134,29 @@ Use the following command to show trust policy configuration: notation policy show ``` -Upon successful execution, the trust policy configuration are printed out to standard output. If trust policy is not configured or is malformed, users should receive an error message via standard error output, and a tip to import trust policy configuration from a JSON file. +Upon successful execution, the trust policy configuration is printed out to standard output. If trust policy is not configured or is malformed, users should receive an error message via standard error output, and a tip to import trust policy configuration from a JSON file. -### Export trust policy configuration into a JSON file +### Export OCI trust policy configuration into a JSON file Users can redirect the output of command `notation policy show` to a JSON file. ```shell -notation policy show > ./trust_policy.json +notation policy show > ./oci_trust_policy.json ``` ### Update trust policy configuration -The steps to update trust policy configuration: +The steps to update OCI trust policy configuration: 1. Export trust policy configuration into a JSON file. ```shell - notation policy show > ./trust_policy.json + notation policy show > ./oci_trust_policy.json ``` -2. Edit the exported JSON file "trust_policy.json", update trust policy configuration and save the file. +2. Edit the exported JSON file "oci_trust_policy.json", update trust policy configuration and save the file. 3. Import trust policy configuration from the file. ```shell - notation policy import ./trust_policy.json + notation policy import ./oci_trust_policy.json ``` diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index ce0de903a..1bb445797 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -2,7 +2,7 @@ ## Description -Use `notation sign` to sign artifacts. +Use `notation sign` to sign artifacts stored in OCI compliant registries. 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. @@ -19,6 +19,8 @@ Warning: Always sign the artifact using digest(`@sha256:...`) rather than a tag( Successfully signed /@ ``` +NOTE: This command is for signing OCI artifacts only. Use `notation blob sign` command for signing arbitrary blobs. + ## Outline ```text diff --git a/specs/commandline/verify.md b/specs/commandline/verify.md index e529bac37..943e7bcd3 100644 --- a/specs/commandline/verify.md +++ b/specs/commandline/verify.md @@ -2,7 +2,7 @@ ## 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. Upon successful verification, the output message is printed out as follows: +Use `notation verify` command to verify signatures associated with artifacts stored in OCI compliant registries. 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 signature for /@ @@ -25,6 +25,9 @@ The artifact was signed with the following user metadata. KEY VALUE ``` +> [!NOTE] +> This command is for verifying OCI artifacts only. Use `notation blob verify` command for verifying arbitrary blobs. + ## Outline @@ -59,7 +62,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://notaryproject.dev/docs/user-guides/how-to/directory-structure/) 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` or `trustpolicy.oci.json` under `{NOTATION_CONFIG}`. See [Notation Directory Structure](https://notaryproject.dev/docs/user-guides/how-to/directory-structure/) for `{NOTATION_CONFIG}`. An example of `trustpolicy.json`: diff --git a/specs/notation-cli.md b/specs/notation-cli.md index dcb03352e..24e83f12a 100644 --- a/specs/notation-cli.md +++ b/specs/notation-cli.md @@ -6,16 +6,17 @@ This spec contains reference information on using notation commands. Each comman | Command | Description | | ------------------------------------------- | ---------------------------------------------------------------------- | +| [blob](./commandline/blob.md) | Sign, verify and inspect singatures associated with blobs | | [certificate](./commandline/certificate.md) | Manage certificates in trust store | -| [inspect](./commandline/inspect.md) | Inspect signatures | +| [inspect](./commandline/inspect.md) | Inspect OCI signatures | | [key](./commandline/key.md) | Manage keys used for signing | -| [list](./commandline/list.md) | List signatures of the signed artifact | -| [login](./commandline/login.md) | Login to registries | -| [logout](./commandline/logout.md) | Log out from the logged in registries | +| [list](./commandline/list.md) | List signatures of a signed OCI artifact | +| [login](./commandline/login.md) | Log into OCI registries | +| [logout](./commandline/logout.md) | Log out from the logged in OCI registries | | [plugin](./commandline/plugin.md) | Manage plugins | -| [policy](./commandline/policy.md) | Manage trust policy configuration for signature verification | -| [sign](./commandline/sign.md) | Sign artifacts | -| [verify](./commandline/verify.md) | Verify artifacts | +| [policy](./commandline/policy.md) | Manage trust policy configuration for OCI signature verification | +| [sign](./commandline/sign.md) | Sign OCI artifacts | +| [verify](./commandline/verify.md) | Verify OCI artifacts | | [version](./commandline/version.md) | Print the version of notation CLI | ## Notation Outline @@ -27,16 +28,17 @@ Usage: notation [command] Available Commands: + blob Sign, verify and inspect signatures associated with blobs certificate Manage certificates in trust store - inspect Inspect all signatures associated with the signed artifact + inspect Inspect all signatures associated with a signed OCI artifact key Manage keys used for signing - list List signatures of the signed artifact - login Login to registry - logout Log out from the logged in registries + list List signatures of a signed OCI artifact + login Log into OCI registries + logout Log out from the logged in OCI registries plugin Manage plugins - policy Manage trust policy configuration for signature verification - sign Sign artifacts - verify Verify artifacts + policy Manage trust policy configuration for OCI signature verification + sign Sign OCI artifacts + verify Verify OCI artifacts version Show the notation version information Flags: