From 4c33528ff6a9c95ba498cf8fac0a7145743d338f Mon Sep 17 00:00:00 2001 From: Junjie Gao Date: Fri, 16 Aug 2024 03:17:38 +0000 Subject: [PATCH 1/4] docs: remove blob signing docs Signed-off-by: Junjie Gao --- specs/commandline/inspect.md | 8 ++------ specs/commandline/policy.md | 24 ++++++++++++------------ specs/commandline/sign.md | 2 -- specs/commandline/verify.md | 29 ++++++++++++++++++++++++----- specs/error-handling-guideline.md | 2 +- specs/notation-cli.md | 4 +--- 6 files changed, 40 insertions(+), 29 deletions(-) diff --git a/specs/commandline/inspect.md b/specs/commandline/inspect.md index 5dc9b334d..a637ab55f 100644 --- a/specs/commandline/inspect.md +++ b/specs/commandline/inspect.md @@ -24,19 +24,15 @@ 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 a signed OCI artifact. +Inspect all signatures associated with the signed artifact. Usage: notation inspect [flags] Flags: - --allow-referrers-api [Experimental] use the Referrers API to inspect signatures, if not supported (returns 404), fallback to the Referrers tag schema -d, --debug debug mode -h, --help help for inspect --insecure-registry use HTTP protocol while connecting to registries. Should be used only for testing @@ -270,7 +266,7 @@ An example output: "expiry": "2023-02-06T20:50:17Z", "io.cncf.notary.verificationPlugin": "com.example.nv2plugin" }, - "unsignedAttributes": { + "unsignedAttributes": { "io.cncf.notary.timestampSignature": "", "io.cncf.notary.signingAgent": "notation/1.0.0" }, diff --git a/specs/commandline/policy.md b/specs/commandline/policy.md index f31361757..85d63e79e 100644 --- a/specs/commandline/policy.md +++ b/specs/commandline/policy.md @@ -2,9 +2,9 @@ ## Description -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). +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 [trust policy specification and examples](https://github.com/notaryproject/specifications/blob/v1.0.0/specs/trust-store-trust-policy.md#trust-policy). -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 `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. 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: @@ -74,7 +74,7 @@ To get started, user can refer to the following trust policy configuration sampl ### notation policy command ```text -Manage trust policy configuration for OCI artifact signature verification. +Manage trust policy configuration for signature verification. Usage: notation policy [command] @@ -90,7 +90,7 @@ Flags: ### notation policy import ```text -Import OCI trust policy configuration from a JSON file +Import trust policy configuration from a JSON file Usage: notation policy import [flags] @@ -103,7 +103,7 @@ Flags: ### notation policy show ```text -Show OCI trust policy configuration +Show trust policy configuration Usage: notation policy show [flags] @@ -122,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/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/specifications/blob/v1.0.0/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. @@ -136,27 +136,27 @@ notation 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 OCI trust policy configuration into a JSON file +### Export 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 > ./oci_trust_policy.json +notation policy show > ./trustpolicy.json ``` ### Update trust policy configuration -The steps to update OCI trust policy configuration: +The steps to update trust policy configuration: 1. Export trust policy configuration into a JSON file. ```shell - notation policy show > ./oci_trust_policy.json + notation policy show > ./trustpolicy.json ``` -2. Edit the exported JSON file "oci_trust_policy.json", update trust policy configuration and save the file. +2. Edit the exported JSON file "trustpolicy.json", update trust policy configuration and save the file. 3. Import trust policy configuration from the file. ```shell - notation policy import ./oci_trust_policy.json + notation policy import ./trustpolicy.json ``` diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index 1bb445797..225f917c9 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -19,8 +19,6 @@ 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 943e7bcd3..4ad6a09ed 100644 --- a/specs/commandline/verify.md +++ b/specs/commandline/verify.md @@ -25,9 +25,6 @@ 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 @@ -62,7 +59,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` or `trustpolicy.oci.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` 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`: @@ -78,7 +75,29 @@ An example of `trustpolicy.json`: "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. + "trustedIdentities": [ // Identities that are trusted to sign the artifact. It only includes identities of `ca` and `signingAuthority`. + "x509.subject: C=US, ST=WA, L=Seattle, O=wabbit-networks.io, OU=Finance, CN=SecureBuilder" + ] + } + ] +} +``` + +An example of `trustpolicy.json` with RFC 3161 timestamp verification support: + +```jsonc +{ + "version": "1.0", + "trustPolicies": [ + { + "name": "wabbit-networks-images", + "registryScopes": [ "localhost:5000/net-monitor" ], + "signatureVerification": { + "level": "strict", + "verifyTimestamp": "afterCertExpiry" // Only verify timestamp countersignatures if any code signing certificate has expired. DEFAULT: `always` + }, + "trustStores": [ "ca:wabbit-networks", "tsa:wabbit-networks-timestamp" ], // To enable timestamp verification, trust store type `tsa` MUST be configured. + "trustedIdentities": [ "x509.subject: C=US, ST=WA, L=Seattle, O=wabbit-networks.io, OU=Finance, CN=SecureBuilder" ] } diff --git a/specs/error-handling-guideline.md b/specs/error-handling-guideline.md index ef06ddcc5..d937ea608 100644 --- a/specs/error-handling-guideline.md +++ b/specs/error-handling-guideline.md @@ -32,7 +32,7 @@ Last, error logs can also be useful for post-mortem debugging and can also be wr - Provide specific and actionable prompt message with argument suggestion or show the example usage for reference. (e.g, Instead of showing flag or argument options is missing, please provide available argument options and guide users to `--help` to view more examples). - If the actionable prompt message is too long to show in the CLI output, consider guide users to Notation user manual or troubleshooting guide with the versioned permanent link. - If the error message is not enough for troubleshooting, guide users to use `--verbose` to print much more detailed logs. -- If server returns an error without any [message or detail](https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc.3/spec.md#error-codes), consider providing customized error logs to make it clearer. The original server logs can be displayed in debug mode. +- If server returns an error without any [message or detail](https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md#error-codes), consider providing customized error logs to make it clearer. The original server logs can be displayed in debug mode. - As a security tool, `notation` SHOULD prompt users to stop upon verification errors. ### Don'Ts diff --git a/specs/notation-cli.md b/specs/notation-cli.md index 24e83f12a..971ef5d09 100644 --- a/specs/notation-cli.md +++ b/specs/notation-cli.md @@ -5,8 +5,7 @@ This spec contains reference information on using notation commands. Each comman ## Notation Commands | 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 OCI signatures | | [key](./commandline/key.md) | Manage keys used for signing | @@ -28,7 +27,6 @@ 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 a signed OCI artifact key Manage keys used for signing From efddf58b01bea2e1c232c4f370010c9a03fdf594 Mon Sep 17 00:00:00 2001 From: Junjie Gao Date: Fri, 16 Aug 2024 03:26:17 +0000 Subject: [PATCH 2/4] fix: update Signed-off-by: Junjie Gao --- specs/commandline/blob.md | 500 ------------------------------ specs/commandline/inspect.md | 3 +- specs/commandline/verify.md | 22 -- specs/error-handling-guideline.md | 2 +- 4 files changed, 3 insertions(+), 524 deletions(-) delete mode 100644 specs/commandline/blob.md diff --git a/specs/commandline/blob.md b/specs/commandline/blob.md deleted file mode 100644 index 1fdb76ec6..000000000 --- a/specs/commandline/blob.md +++ /dev/null @@ -1,500 +0,0 @@ -# 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 a637ab55f..484272f0d 100644 --- a/specs/commandline/inspect.md +++ b/specs/commandline/inspect.md @@ -33,6 +33,7 @@ Usage: notation inspect [flags] Flags: + --allow-referrers-api [Experimental] use the Referrers API to inspect signatures, if not supported (returns 404), fallback to the Referrers tag schema -d, --debug debug mode -h, --help help for inspect --insecure-registry use HTTP protocol while connecting to registries. Should be used only for testing @@ -266,7 +267,7 @@ An example output: "expiry": "2023-02-06T20:50:17Z", "io.cncf.notary.verificationPlugin": "com.example.nv2plugin" }, - "unsignedAttributes": { + "unsignedAttributes": { "io.cncf.notary.timestampSignature": "", "io.cncf.notary.signingAgent": "notation/1.0.0" }, diff --git a/specs/commandline/verify.md b/specs/commandline/verify.md index 4ad6a09ed..c38e15d21 100644 --- a/specs/commandline/verify.md +++ b/specs/commandline/verify.md @@ -83,28 +83,6 @@ An example of `trustpolicy.json`: } ``` -An example of `trustpolicy.json` with RFC 3161 timestamp verification support: - -```jsonc -{ - "version": "1.0", - "trustPolicies": [ - { - "name": "wabbit-networks-images", - "registryScopes": [ "localhost:5000/net-monitor" ], - "signatureVerification": { - "level": "strict", - "verifyTimestamp": "afterCertExpiry" // Only verify timestamp countersignatures if any code signing certificate has expired. DEFAULT: `always` - }, - "trustStores": [ "ca:wabbit-networks", "tsa:wabbit-networks-timestamp" ], // To enable timestamp verification, trust store type `tsa` MUST be configured. - "trustedIdentities": [ - "x509.subject: C=US, ST=WA, L=Seattle, O=wabbit-networks.io, OU=Finance, CN=SecureBuilder" - ] - } - ] -} -``` - For a Linux user, store file `trustpolicy.json` under directory `${HOME}/.config/notation/`. For a MacOS user, store file `trustpolicy.json` under directory `${HOME}/Library/Application Support/notation/`. diff --git a/specs/error-handling-guideline.md b/specs/error-handling-guideline.md index d937ea608..ef06ddcc5 100644 --- a/specs/error-handling-guideline.md +++ b/specs/error-handling-guideline.md @@ -32,7 +32,7 @@ Last, error logs can also be useful for post-mortem debugging and can also be wr - Provide specific and actionable prompt message with argument suggestion or show the example usage for reference. (e.g, Instead of showing flag or argument options is missing, please provide available argument options and guide users to `--help` to view more examples). - If the actionable prompt message is too long to show in the CLI output, consider guide users to Notation user manual or troubleshooting guide with the versioned permanent link. - If the error message is not enough for troubleshooting, guide users to use `--verbose` to print much more detailed logs. -- If server returns an error without any [message or detail](https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md#error-codes), consider providing customized error logs to make it clearer. The original server logs can be displayed in debug mode. +- If server returns an error without any [message or detail](https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc.3/spec.md#error-codes), consider providing customized error logs to make it clearer. The original server logs can be displayed in debug mode. - As a security tool, `notation` SHOULD prompt users to stop upon verification errors. ### Don'Ts From 86012d44ecfe60c451e3ec99baef74a7a41b7b0d Mon Sep 17 00:00:00 2001 From: Junjie Gao Date: Fri, 16 Aug 2024 03:27:30 +0000 Subject: [PATCH 3/4] fix: update Signed-off-by: Junjie Gao --- specs/commandline/inspect.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/commandline/inspect.md b/specs/commandline/inspect.md index 484272f0d..338116f40 100644 --- a/specs/commandline/inspect.md +++ b/specs/commandline/inspect.md @@ -33,7 +33,7 @@ Usage: notation inspect [flags] Flags: - --allow-referrers-api [Experimental] use the Referrers API to inspect signatures, if not supported (returns 404), fallback to the Referrers tag schema + --allow-referrers-api [Experimental] use the Referrers API to inspect signatures, if not supported (returns 404), fallback to the Referrers tag schema -d, --debug debug mode -h, --help help for inspect --insecure-registry use HTTP protocol while connecting to registries. Should be used only for testing @@ -267,7 +267,7 @@ An example output: "expiry": "2023-02-06T20:50:17Z", "io.cncf.notary.verificationPlugin": "com.example.nv2plugin" }, - "unsignedAttributes": { + "unsignedAttributes": { "io.cncf.notary.timestampSignature": "", "io.cncf.notary.signingAgent": "notation/1.0.0" }, From 786562d0207d9b250576fc5682aa80fce6a436bb Mon Sep 17 00:00:00 2001 From: Junjie Gao Date: Fri, 16 Aug 2024 04:13:51 +0000 Subject: [PATCH 4/4] fix: update Signed-off-by: Junjie Gao --- specs/commandline/inspect.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/commandline/inspect.md b/specs/commandline/inspect.md index 338116f40..e3843579e 100644 --- a/specs/commandline/inspect.md +++ b/specs/commandline/inspect.md @@ -267,7 +267,7 @@ An example output: "expiry": "2023-02-06T20:50:17Z", "io.cncf.notary.verificationPlugin": "com.example.nv2plugin" }, - "unsignedAttributes": { + "unsignedAttributes": { "io.cncf.notary.timestampSignature": "", "io.cncf.notary.signingAgent": "notation/1.0.0" },