From 6a88890a01628f45c09a705e8bf6fe91cbacd23c Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Tue, 7 Feb 2023 15:27:17 +0800 Subject: [PATCH 1/5] doc: update sign.md for OCI image manifest support Signed-off-by: Yi Zha --- specs/commandline/sign.md | 42 ++++++++++++++++----------------------- 1 file changed, 17 insertions(+), 25 deletions(-) diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index 8abf0de85..a8ffdd7bd 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -28,27 +28,29 @@ Usage: notation sign [flags] Flags: - -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 - -h, --help help for sign - --image-spec string manifest type for signatures. options: v1.1-artifact, v1.1-image (default: v1.1-artifact) - -k, --key string signing key name, for a key previously added to notation's key list. - -p, --password string password for registry operations (default to $NOTATION_PASSWORD if not specified) - --plain-http registry access via plain HTTP - --plugin-config strings {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") - -u, --username string username for registry operations (default to $NOTATION_USERNAME if not specified) - -m, --user-metadata strings {key}={value} pairs that are added to the signature payload + -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 + -h, --help help for sign + -k, --key string signing key name, for a key previously added to notation's key list. + -p, --password string password for registry operations (default to $NOTATION_PASSWORD if not specified) + --plain-http registry access via plain HTTP + --plugin-config strings {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") + --signature-manifest string manifest type for signatures. options: "image", "artifact" (default "artifact") + -u, --username string username for registry operations (default to $NOTATION_USERNAME if not specified) + -m, --user-metadata strings {key}={value} pairs that are added to the signature payload ``` ## Use OCI image manifest to store signatures -By default, Notation uses [OCI artifact manifest][oci-artifact-manifest] to store signatures in registries. For backward compatibility, Notation supports using `OCI image manifest` to store signatures in registries that partially implement the [OCI Image specification v1.1][oci-image-spec]. Use flag `--image-spec v1.1-image` to force Notation to store the signatures using OCI image manifest. +By default, Notation uses [OCI artifact manifest][oci-artifact-manifest] to store signatures in registries. For registries that don't support `OCI artifact` or [Referrers API][oci-referers-api] is not enabled in registries, users can use flag `--signature-manifest image` to force Notation to store the signatures using [OCI image manifest][oci-image-spec]. -Registries MAY not implement or enable the `Referrers API`, which is used by clients to fetch referrers. In the context of Notation, the referrers are signatures. Notation follows the fallback procedure defined in [OCI distribution spec][oci-backward-compatibility] if `Referrers API` is unavailable. +Note that there is no deterministic way to determine whether a registry supports `OCI artifact` or not. The following response status contained in error messages MAY indicate that the registry doesn't support `OCI artifact`. + +- Response status `400 BAD Request` with error code `MANIFEST_INVALID` or `UNSUPPORTED` ### Set config property for OCI image manifest -OCI image manifest requires additional property `config` of type `descriptor`, which is not required by OCI artifact manifest. Notation creates a default config descriptor for the user if flag `--image-spec v1.1-image` is used. +OCI image manifest requires additional property `config` of type `descriptor`, which is not required by OCI artifact manifest. Notation creates a default config descriptor for the user if flag `--signature-manifest image` is used. Notation uses empty JSON object `{}` as the default configuration content, and thus the default `config` property is fixed, as following: @@ -60,14 +62,6 @@ Notation uses empty JSON object `{}` as the default configuration content, and t } ``` -### When to use OCI image manifest - -[Registry support][registry-support] lists registries with different compatibilities. For registries not supporting `OCI artifact manifest`, users can use flag `--image-spec v1.1-image` to sign artifacts stored in those registries. - -For registries not listed in the page, users can consider using flag `--image-spec v1.1-image` by checking the error message. Note that there is no deterministic way to determine whether a registry supports `OCI artifact manifest` or not. The error message is just for reference. The following response status contained in error messages MAY indicate that the registry doesn't support `OCI artifact manifest`: - -- Response status `400 BAD Request` with error code `MANIFEST_INVALID` or `UNSUPPORTED` - ## Usage ### Sign an OCI artifact @@ -161,11 +155,9 @@ Successfully signed localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da ### Sign an artifact and store the signature using OCI image manifest ```shell -notation sign --image-spec v1.1-image /@ +notation sign --signature-manifest image /@ ``` [oci-artifact-manifest]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/artifact.md [oci-image-spec]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/spec.md -[oci-backward-compatibility]: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#backwards-compatibility -[registry-support]: https://notaryproject.dev/docs/registrysupport/ -[oras-land]: https://oras.land/ +[oci-referers-api]: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#listing-referrers From 457837bca1160414b37f0232f74411753606b322 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Tue, 7 Feb 2023 15:32:04 +0800 Subject: [PATCH 2/5] doc: fix wording Signed-off-by: Yi Zha --- specs/commandline/sign.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index a8ffdd7bd..671c13d08 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -35,14 +35,14 @@ Flags: --plain-http registry access via plain HTTP --plugin-config strings {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") - --signature-manifest string manifest type for signatures. options: "image", "artifact" (default "artifact") + --signature-manifest string manifest type for signatures, options: "image", "artifact" (default "artifact") -u, --username string username for registry operations (default to $NOTATION_USERNAME if not specified) -m, --user-metadata strings {key}={value} pairs that are added to the signature payload ``` ## Use OCI image manifest to store signatures -By default, Notation uses [OCI artifact manifest][oci-artifact-manifest] to store signatures in registries. For registries that don't support `OCI artifact` or [Referrers API][oci-referers-api] is not enabled in registries, users can use flag `--signature-manifest image` to force Notation to store the signatures using [OCI image manifest][oci-image-spec]. +By default, Notation uses [OCI artifact manifest][oci-artifact-manifest] to store signatures in registries. For registries that don't support `OCI artifact` or [Referrers API][oci-referers-api] is not enabled in registries, users should use flag `--signature-manifest image` to force Notation to store the signatures using [OCI image manifest][oci-image-spec]. Note that there is no deterministic way to determine whether a registry supports `OCI artifact` or not. The following response status contained in error messages MAY indicate that the registry doesn't support `OCI artifact`. From 1f7ae992cfecdfc4f64b58edbb98e20ce9412e41 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Wed, 8 Feb 2023 16:11:19 +0800 Subject: [PATCH 3/5] doc: update per comments Signed-off-by: Yi Zha --- 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 671c13d08..154b004ec 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -42,7 +42,7 @@ Flags: ## Use OCI image manifest to store signatures -By default, Notation uses [OCI artifact manifest][oci-artifact-manifest] to store signatures in registries. For registries that don't support `OCI artifact` or [Referrers API][oci-referers-api] is not enabled in registries, users should use flag `--signature-manifest image` to force Notation to store the signatures using [OCI image manifest][oci-image-spec]. +By default, Notation uses [OCI artifact manifest][oci-artifact-manifest] to store signatures in registries. For registries that don't support `OCI artifact` or [Referrers API][oci-referers-api] is not enabled, users SHOULD use flag `--signature-manifest image` to force Notation to store the signatures using [OCI image manifest][oci-image-spec]. Note that there is no deterministic way to determine whether a registry supports `OCI artifact` or not. The following response status contained in error messages MAY indicate that the registry doesn't support `OCI artifact`. From 50a9bb5611f0d648ccbce1ad0e3838bc0be1860f Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Thu, 9 Feb 2023 11:27:56 +0800 Subject: [PATCH 4/5] doc: update per comments Signed-off-by: Yi Zha --- 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 154b004ec..81e96901f 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -35,7 +35,7 @@ Flags: --plain-http registry access via plain HTTP --plugin-config strings {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") - --signature-manifest string manifest type for signatures, options: "image", "artifact" (default "artifact") + --signature-manifest string manifest type for signature, options: "image", "artifact" (default "artifact") -u, --username string username for registry operations (default to $NOTATION_USERNAME if not specified) -m, --user-metadata strings {key}={value} pairs that are added to the signature payload ``` From 1e213724f1b0865f87c4c743a9a2efab3fa1de83 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Thu, 9 Feb 2023 12:41:16 +0800 Subject: [PATCH 5/5] doc: fix duplicates Signed-off-by: Yi Zha --- specs/commandline/sign.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index c1e88fdcf..70aa13e44 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -52,7 +52,6 @@ Note that there is no deterministic way to determine whether a registry supports ### Set config property for OCI image manifest -OCI image manifest requires additional property `config` of type `descriptor`, which is not required by OCI artifact manifest. Notation creates a default config descriptor for the user if flag `--signature-manifest image` is used. OCI image manifest requires additional property `config` of type `descriptor`, which is not required by OCI artifact manifest. Notation creates a default config descriptor for the user if flag `--signature-manifest image` is used. Notation uses empty JSON object `{}` as the default configuration content, and thus the default `config` property is fixed, as following: @@ -159,7 +158,6 @@ Successfully signed localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da ```shell notation sign --signature-manifest image /@ -notation sign --signature-manifest image /@ ``` [oci-artifact-manifest]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/artifact.md