From b72a5655671c1475c3e9472161ec71d45a852fb8 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Fri, 13 Jan 2023 23:09:27 +0800 Subject: [PATCH] doc: update to support OCI image manifest (#502) Signed-off-by: Yi Zha --- specs/commandline/sign.md | 41 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index 33c19d9ec..b8ea9c9f4 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -31,6 +31,7 @@ Usage: 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 @@ -40,6 +41,34 @@ Flags: -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. + +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. + +### 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. + +Notation uses empty JSON object `{}` as the default configuration content, and thus the default `config` property is fixed, as following: + +```json +"config": { + "mediaType": "application/vnd.cncf.notary.signature", + "size": 2, + "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a" +} +``` + +### 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 @@ -130,3 +159,15 @@ Warning: Always sign the artifact using digest(`@sha256:...`) rather than a tag( Resolved artifact tag `v1` to digest `sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9` before signing. Successfully signed localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 ``` + +### Sign an artifact and store the signature using OCI image manifest + +```shell +notation sign --image-spec v1.1-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/