From 6fbe842aee3e059afdbbf39e94546959623fa7c3 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Sat, 25 Mar 2023 22:12:23 +0800 Subject: [PATCH 01/11] doc: update spec for sign/verify local images Signed-off-by: Yi Zha --- specs/commandline/list.md | 28 +++++++++++++++++++++++++++- specs/commandline/sign.md | 32 ++++++++++++++++++++++++++++++++ specs/commandline/verify.md | 23 +++++++++++++++++++++++ 3 files changed, 82 insertions(+), 1 deletion(-) diff --git a/specs/commandline/list.md b/specs/commandline/list.md index 4b1b39f23..2e4b37950 100644 --- a/specs/commandline/list.md +++ b/specs/commandline/list.md @@ -29,6 +29,7 @@ Aliases: Flags: -d, --debug debug mode -h, --help help for list + --local-artifact [Preview] if set, list signatures associated with the image in OCI layout directory -p, --password string password for registry operations (default to $NOTATION_PASSWORD if not specified) --plain-http registry access via plain HTTP -u, --username string username for registry operations (default to $NOTATION_USERNAME if not specified) @@ -39,7 +40,7 @@ Flags: ### List all the signatures of the signed container image -```text +```shell notation list /: ``` @@ -51,3 +52,28 @@ localhost:5000/net-monitor:v1 ├── sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa └── sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb ``` + +### [Preview] List all the signatures associated with the image in OCI layout directory + +The following example lists the signatures associated with the image in OCI layout directory named `hello-world`. + +Reference an image in OCI layout directory using tags: + +```shell +notation list --local-artifact ./hello-world:v1 +``` + +Reference an image in OCI layout directory using exact digest: + +```shell +notation list --local-artifact ./hello-world@sha256:xxx +``` + +An example output: + +```shell +./hello-world@sha256:a08753c0c7bcdaaf5c2fdb375f68e860c34bffb146368982c201d41769e1763c +└── application/vnd.cncf.notary.signature + ├── sha256:647039638efb22a021f59675c9449dd09956c981a44b82c1ff074513c2c9f273 + └── sha256:6bfb3c4fd485d6810f9656ddd4fb603f0c414c5f0b175ef90eeb4090ebd9bfa1 +``` diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index 5cb19f4ba..6087a4864 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -33,6 +33,7 @@ Flags: -h, --help help for sign --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 + --local-artifact [Preview] if set, sign artifacts on local disk -p, --password string password for registry operations (default to $NOTATION_PASSWORD if not specified) --plain-http registry access via plain HTTP --plugin string signing plugin name. This is mutually exclusive with the --key flag @@ -166,6 +167,37 @@ Successfully signed localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da notation sign --signature-manifest artifact /@ ``` +### [Preview] Sign local OCI image + +A local OCI image means an OCI image Layout on local disk. OCI image layout is defined by spec [OCI image layout][oci-image-layout]. It is a directory structure that contains files and folders. Users can reference an image in the layout using either tags, or the exact digest. The OCI image layout could be a tarball or a directory. Notation only supports signing OCI layout directory. + +Tools like `docker buildx` support building an OCI image layout on local disk. The following example creates a tarball named `hello-world.tar` with tag `v1`, which is an OCI layout tarball on local disk. Please note that the digest can be found in the output messages. + +```shell +docker buildx create --use +docker buildx build . -f Dockerfile -o type=oci,dest=hello-world.tar -t hello-world:v1 +``` + +Users need to extract the tarball into a directory first. The following command creates the OCI layout directory, and the image can be referred by `./hello-world:v1` or `./hello-world@sha256:xxx`. + +```shell +mkdir hello-world +tar -xf ./hello-world.tar -C hello-world +``` + +Use flag `--local-artifact` for signing local OCI images. The signatures are stored in the layout directory and associated with the image. For example: + +```shell +notation sign --local-artifact ./hello-world@sha256:xxx +``` + +Upon successful signing, use the `notation list` command to list the signatures, for example: + +```shell +notation list ./hello-world@sha256:xxx +``` + [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-referers-api]: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#listing-referrers +[oci-image-layout]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/image-layout.md diff --git a/specs/commandline/verify.md b/specs/commandline/verify.md index 3741cb966..9a3b98ad9 100644 --- a/specs/commandline/verify.md +++ b/specs/commandline/verify.md @@ -40,6 +40,7 @@ Flags: -p, --password string password for registry operations (default to $NOTATION_PASSWORD if not specified) --plain-http registry access via plain HTTP --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 [Preview] trust policy scope for local artifact verification. -u, --username string username for registry operations (default to $NOTATION_USERNAME if not specified) -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 @@ -168,3 +169,25 @@ An example of output messages for a successful verification: Warning: Always verify the artifact using digest(@sha256:...) rather than a tag(:v1) because resolved digest may not point to the same signed artifact, as tags are mutable. Successfully verified signature for localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 ``` + +### [Preview] Verify local OCI image + +Users should configure trust policy properly before verifying local OCI image. According to trust policy specification, `registryScopes` property determines which trust policy is applicable for the given artifact. For an image stored in a remote registry, the reference is like "localhost:5000/net-monitor:v1", and the value of `registryScopes` should be set to "localhost:5000/net-monitor", which is the repository URL of the image. Local OCI image is in the form of OCI layout directory, the reference is like "./hello-world:v1", the registry scope cannot be extracted from the reference. Users need to specify which `registryScopes` is used to verify the local image using flag `--scope`. Here is an example of trust policy configured for local image `./hello-world:v1`: + +```jsonc +{ + "name": "local-images", + "registryScopes": [ "local/hello-world" ], + "signatureVerification": { + "level" : "strict" + }, + "trustStores": [ "ca:hello-world" ], + "trustedIdentities": ["*"] +} +``` + +Please note that the value of `registryScopes` should be a fully qualified URL for both local and remote images. To verify local image `./hello-world:v1`, use the following command: + +```shell +notation verify --scope "local/hello-world" ./hello-world:v1 +``` From 390a997380e90234ceb5f27fc250ac54f4c0c4f9 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Sat, 25 Mar 2023 22:25:02 +0800 Subject: [PATCH 02/11] doc: update spec for sign/verify local images Signed-off-by: Yi Zha --- specs/commandline/sign.md | 10 +++++----- specs/commandline/verify.md | 6 ++++-- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index 6087a4864..87ba820e2 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -169,29 +169,29 @@ notation sign --signature-manifest artifact /@ ### [Preview] Sign local OCI image -A local OCI image means an OCI image Layout on local disk. OCI image layout is defined by spec [OCI image layout][oci-image-layout]. It is a directory structure that contains files and folders. Users can reference an image in the layout using either tags, or the exact digest. The OCI image layout could be a tarball or a directory. Notation only supports signing OCI layout directory. +A local OCI image means an OCI image Layout on local disk. OCI image layout is defined by spec [OCI image layout][oci-image-layout]. It is a directory structure that contains files and folders. Users can reference an image in the layout using either tags, or the exact digest. The OCI image layout could be a tarball or a directory. Notation only supports signing OCI layout directory for now. -Tools like `docker buildx` support building an OCI image layout on local disk. The following example creates a tarball named `hello-world.tar` with tag `v1`, which is an OCI layout tarball on local disk. Please note that the digest can be found in the output messages. +Tools like `docker buildx` support building an OCI image layout on local disk. The following example creates a tarball named `hello-world.tar` with tag `v1`, which is an OCI layout tarball on local disk. Please note that the digest can be found in the output messages of `docker buildx build`. ```shell docker buildx create --use docker buildx build . -f Dockerfile -o type=oci,dest=hello-world.tar -t hello-world:v1 ``` -Users need to extract the tarball into a directory first. The following command creates the OCI layout directory, and the image can be referred by `./hello-world:v1` or `./hello-world@sha256:xxx`. +Users need to extract the tarball into a directory first. The following command creates the OCI layout directory, and the image can be referenced by `./hello-world:v1` or `./hello-world@sha256:xxx`. ```shell mkdir hello-world tar -xf ./hello-world.tar -C hello-world ``` -Use flag `--local-artifact` for signing local OCI images. The signatures are stored in the layout directory and associated with the image. For example: +Use flag `--local-artifact` for signing local OCI images. For example: ```shell notation sign --local-artifact ./hello-world@sha256:xxx ``` -Upon successful signing, use the `notation list` command to list the signatures, for example: +Upon successful signing, the signature is stored in the same layout directory and associated with the image. Use `notation list` command to list the signatures, for example: ```shell notation list ./hello-world@sha256:xxx diff --git a/specs/commandline/verify.md b/specs/commandline/verify.md index 9a3b98ad9..2734122f3 100644 --- a/specs/commandline/verify.md +++ b/specs/commandline/verify.md @@ -172,7 +172,7 @@ Successfully verified signature for localhost:5000/net-monitor@sha256:b94d27b993 ### [Preview] Verify local OCI image -Users should configure trust policy properly before verifying local OCI image. According to trust policy specification, `registryScopes` property determines which trust policy is applicable for the given artifact. For an image stored in a remote registry, the reference is like "localhost:5000/net-monitor:v1", and the value of `registryScopes` should be set to "localhost:5000/net-monitor", which is the repository URL of the image. Local OCI image is in the form of OCI layout directory, the reference is like "./hello-world:v1", the registry scope cannot be extracted from the reference. Users need to specify which `registryScopes` is used to verify the local image using flag `--scope`. Here is an example of trust policy configured for local image `./hello-world:v1`: +Users should configure trust policy properly before verifying local OCI image. According to trust policy specification, `registryScopes` property determines which trust policy is applicable for the given artifact. For example, a remote image is referenced by "localhost:5000/net-monitor:v1", thus the value of `registryScopes` should contain "localhost:5000/net-monitor", which is the repository URL of the image. Local OCI image is in the form of OCI layout directory, the reference is different from a remote image, for example "./hello-world:v1". Users need to specify which `registryScopes` is used to verify the local image using flag `--scope`. Here is an example of trust policy configured for local image `./hello-world:v1`: ```jsonc { @@ -186,7 +186,9 @@ Users should configure trust policy properly before verifying local OCI image. A } ``` -Please note that the value of `registryScopes` should be a fully qualified URL for both local and remote images. To verify local image `./hello-world:v1`, use the following command: +Please note that the value of `registryScopes` should be a fully qualified URL for both local and remote images. + +To verify local image `./hello-world:v1`, use the following command: ```shell notation verify --scope "local/hello-world" ./hello-world:v1 From 8f59b9cdc2592bef1c0e9a0ed762c6eee5002b8c Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Sat, 25 Mar 2023 22:27:30 +0800 Subject: [PATCH 03/11] doc: update spec for sign/verify local images Signed-off-by: Yi Zha --- specs/commandline/verify.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/specs/commandline/verify.md b/specs/commandline/verify.md index 2734122f3..c6eea55b4 100644 --- a/specs/commandline/verify.md +++ b/specs/commandline/verify.md @@ -172,7 +172,7 @@ Successfully verified signature for localhost:5000/net-monitor@sha256:b94d27b993 ### [Preview] Verify local OCI image -Users should configure trust policy properly before verifying local OCI image. According to trust policy specification, `registryScopes` property determines which trust policy is applicable for the given artifact. For example, a remote image is referenced by "localhost:5000/net-monitor:v1", thus the value of `registryScopes` should contain "localhost:5000/net-monitor", which is the repository URL of the image. Local OCI image is in the form of OCI layout directory, the reference is different from a remote image, for example "./hello-world:v1". Users need to specify which `registryScopes` is used to verify the local image using flag `--scope`. Here is an example of trust policy configured for local image `./hello-world:v1`: +Users should configure trust policy properly before verifying local OCI image. According to trust policy specification, `registryScopes` property determines which trust policy is applicable for the given artifact. The value of `registryScopes` should be a fully qualified URL for both local and remote images. For example, a remote image is referenced by "localhost:5000/net-monitor:v1", thus the value of `registryScopes` should contain "localhost:5000/net-monitor", which is the repository URL of the image. Local OCI image is in the form of OCI layout directory, the reference is different from a remote image, for example "./hello-world:v1". Users need to specify which `registryScopes` is used to verify the local image using flag `--scope`. Here is an example of trust policy configured for local image `./hello-world:v1`: ```jsonc { @@ -186,8 +186,6 @@ Users should configure trust policy properly before verifying local OCI image. A } ``` -Please note that the value of `registryScopes` should be a fully qualified URL for both local and remote images. - To verify local image `./hello-world:v1`, use the following command: ```shell From 3fea2b2ceff7a65a9b3eb5d7e1e58b2871b0fa84 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Mon, 27 Mar 2023 14:35:30 +0800 Subject: [PATCH 04/11] doc: update per comments Signed-off-by: Yi Zha --- specs/commandline/list.md | 2 +- specs/commandline/sign.md | 2 +- specs/commandline/verify.md | 5 +++-- 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/specs/commandline/list.md b/specs/commandline/list.md index 2e4b37950..62881f951 100644 --- a/specs/commandline/list.md +++ b/specs/commandline/list.md @@ -29,7 +29,7 @@ Aliases: Flags: -d, --debug debug mode -h, --help help for list - --local-artifact [Preview] if set, list signatures associated with the image in OCI layout directory + --local-artifact [Preview] list signatures associated with the artifact in OCI layout directory -p, --password string password for registry operations (default to $NOTATION_PASSWORD if not specified) --plain-http registry access via plain HTTP -u, --username string username for registry operations (default to $NOTATION_USERNAME if not specified) diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index 87ba820e2..d09bc1f74 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -33,7 +33,7 @@ Flags: -h, --help help for sign --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 - --local-artifact [Preview] if set, sign artifacts on local disk + --local-artifact [Preview] sign artifact on local disk -p, --password string password for registry operations (default to $NOTATION_PASSWORD if not specified) --plain-http registry access via plain HTTP --plugin string signing plugin name. This is mutually exclusive with the --key flag diff --git a/specs/commandline/verify.md b/specs/commandline/verify.md index c6eea55b4..b0ebda17e 100644 --- a/specs/commandline/verify.md +++ b/specs/commandline/verify.md @@ -37,6 +37,7 @@ Usage: Flags: -d, --debug debug mode -h, --help help for verify + --local-artifact [Preview] verify artifact on local disk -p, --password string password for registry operations (default to $NOTATION_PASSWORD if not specified) --plain-http registry access via plain HTTP --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 @@ -172,7 +173,7 @@ Successfully verified signature for localhost:5000/net-monitor@sha256:b94d27b993 ### [Preview] Verify local OCI image -Users should configure trust policy properly before verifying local OCI image. According to trust policy specification, `registryScopes` property determines which trust policy is applicable for the given artifact. The value of `registryScopes` should be a fully qualified URL for both local and remote images. For example, a remote image is referenced by "localhost:5000/net-monitor:v1", thus the value of `registryScopes` should contain "localhost:5000/net-monitor", which is the repository URL of the image. Local OCI image is in the form of OCI layout directory, the reference is different from a remote image, for example "./hello-world:v1". Users need to specify which `registryScopes` is used to verify the local image using flag `--scope`. Here is an example of trust policy configured for local image `./hello-world:v1`: +Users should configure trust policy properly before verifying local OCI image. According to trust policy specification, `registryScopes` property determines which trust policy is applicable for the given artifact. The value of `registryScopes` should be a fully qualified URL for both local and remote images. For example, a remote image is referenced by "localhost:5000/net-monitor:v1", thus the value of `registryScopes` should contain "localhost:5000/net-monitor", which is the repository URL of the image. Local OCI image is in the form of OCI layout directory, the reference is different from a remote image, for example "./hello-world:v1". Besides flag `--local-artifact`, users need to specify which `registryScopes` is used to verify the local image using flag `--scope`. Here is an example of trust policy configured for local image `./hello-world:v1`: ```jsonc { @@ -189,5 +190,5 @@ Users should configure trust policy properly before verifying local OCI image. A To verify local image `./hello-world:v1`, use the following command: ```shell -notation verify --scope "local/hello-world" ./hello-world:v1 +notation verify --local-artifact --scope "local/hello-world" ./hello-world:v1 ``` From ea2563ee8d473cc576de1b34057674a277420d6f Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Thu, 30 Mar 2023 21:06:20 +0800 Subject: [PATCH 05/11] doc: update per comments Signed-off-by: Yi Zha --- specs/commandline/list.md | 8 ++++---- specs/commandline/sign.md | 16 ++++++++-------- specs/commandline/verify.md | 14 +++++++------- 3 files changed, 19 insertions(+), 19 deletions(-) diff --git a/specs/commandline/list.md b/specs/commandline/list.md index 62881f951..e43d62134 100644 --- a/specs/commandline/list.md +++ b/specs/commandline/list.md @@ -29,7 +29,7 @@ Aliases: Flags: -d, --debug debug mode -h, --help help for list - --local-artifact [Preview] list signatures associated with the artifact in OCI layout directory + --oci-layout [Preview] whether the artifact is OCI image layout -p, --password string password for registry operations (default to $NOTATION_PASSWORD if not specified) --plain-http registry access via plain HTTP -u, --username string username for registry operations (default to $NOTATION_USERNAME if not specified) @@ -53,20 +53,20 @@ localhost:5000/net-monitor:v1 └── sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb ``` -### [Preview] List all the signatures associated with the image in OCI layout directory +### [Preview] List all the signatures associated with the image in OCI layout directory on disk The following example lists the signatures associated with the image in OCI layout directory named `hello-world`. Reference an image in OCI layout directory using tags: ```shell -notation list --local-artifact ./hello-world:v1 +notation list --oci-layout ./hello-world:v1 ``` Reference an image in OCI layout directory using exact digest: ```shell -notation list --local-artifact ./hello-world@sha256:xxx +notation list --oci-layout ./hello-world@sha256:xxx ``` An example output: diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index d09bc1f74..21c084640 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -33,7 +33,7 @@ Flags: -h, --help help for sign --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 - --local-artifact [Preview] sign artifact on local disk + --oci-layout [Preview] whether the artifact is OCI image layout -p, --password string password for registry operations (default to $NOTATION_PASSWORD if not specified) --plain-http registry access via plain HTTP --plugin string signing plugin name. This is mutually exclusive with the --key flag @@ -167,34 +167,34 @@ Successfully signed localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da notation sign --signature-manifest artifact /@ ``` -### [Preview] Sign local OCI image +### [Preview] Sign artifacts in OCI layout directory on disk -A local OCI image means an OCI image Layout on local disk. OCI image layout is defined by spec [OCI image layout][oci-image-layout]. It is a directory structure that contains files and folders. Users can reference an image in the layout using either tags, or the exact digest. The OCI image layout could be a tarball or a directory. Notation only supports signing OCI layout directory for now. +Artifacts can be stored on disk in the form of 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 OCI layout directory for now. Users can reference an artifact in the layout using either tags, or the exact digest. For example, use `hello-world:v1` or `hello-world@sha256xxx` to reference the container image in OCI layout directory named `hello-world`. -Tools like `docker buildx` support building an OCI image layout on local disk. The following example creates a tarball named `hello-world.tar` with tag `v1`, which is an OCI layout tarball on local disk. Please note that the digest can be found in the output messages of `docker buildx build`. +Tools like `docker buildx` support building an OCI image layout on disk. The following example creates a tarball named `hello-world.tar` with tag `v1`. Please note that the digest can be retrieved in the output messages of `docker buildx build`. ```shell docker buildx create --use docker buildx build . -f Dockerfile -o type=oci,dest=hello-world.tar -t hello-world:v1 ``` -Users need to extract the tarball into a directory first. The following command creates the OCI layout directory, and the image can be referenced by `./hello-world:v1` or `./hello-world@sha256:xxx`. +Users need to extract the tarball into a directory first, since Notation only support OCI layout directory for now. The following command creates the OCI layout directory. ```shell mkdir hello-world tar -xf ./hello-world.tar -C hello-world ``` -Use flag `--local-artifact` for signing local OCI images. For example: +Use flag `--oci-layout` to sign the image in OCI layout directory referenced by `hello-world@sha256xxx`. For example: ```shell -notation sign --local-artifact ./hello-world@sha256:xxx +notation sign --oci-layout ./hello-world@sha256:xxx ``` Upon successful signing, the signature is stored in the same layout directory and associated with the image. Use `notation list` command to list the signatures, for example: ```shell -notation list ./hello-world@sha256:xxx +notation list --oci-layout ./hello-world@sha256:xxx ``` [oci-artifact-manifest]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/artifact.md diff --git a/specs/commandline/verify.md b/specs/commandline/verify.md index b0ebda17e..bfa4cf5ed 100644 --- a/specs/commandline/verify.md +++ b/specs/commandline/verify.md @@ -37,11 +37,11 @@ Usage: Flags: -d, --debug debug mode -h, --help help for verify - --local-artifact [Preview] verify artifact on local disk + --oci-layout [Preview] whether artifact is OCI image layout -p, --password string password for registry operations (default to $NOTATION_PASSWORD if not specified) --plain-http registry access via plain HTTP --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 [Preview] trust policy scope for local artifact verification. + --scope string [Preview] set trust policy scope for artifact verification, only use it with flag "--oci-layout" -u, --username string username for registry operations (default to $NOTATION_USERNAME if not specified) -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 @@ -171,14 +171,14 @@ Warning: Always verify the artifact using digest(@sha256:...) rather than a tag Successfully verified signature for localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 ``` -### [Preview] Verify local OCI image +### [Preview] Verify artifacts in OCI layout directory on disk -Users should configure trust policy properly before verifying local OCI image. According to trust policy specification, `registryScopes` property determines which trust policy is applicable for the given artifact. The value of `registryScopes` should be a fully qualified URL for both local and remote images. For example, a remote image is referenced by "localhost:5000/net-monitor:v1", thus the value of `registryScopes` should contain "localhost:5000/net-monitor", which is the repository URL of the image. Local OCI image is in the form of OCI layout directory, the reference is different from a remote image, for example "./hello-world:v1". Besides flag `--local-artifact`, users need to specify which `registryScopes` is used to verify the local image using flag `--scope`. Here is an example of trust policy configured for local image `./hello-world:v1`: +Users should configure trust policy properly before verifying artifacts in OCI layout directory on disk. 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 artifacts in OCI layout directory doesn't contain repository URL information. Users can set `registryScopes` to the URL that the artifact 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 local image `./hello-world:v1`: ```jsonc { "name": "local-images", - "registryScopes": [ "local/hello-world" ], + "registryScopes": [ "localhost:5000/hello-world" ], "signatureVerification": { "level" : "strict" }, @@ -187,8 +187,8 @@ Users should configure trust policy properly before verifying local OCI image. A } ``` -To verify local image `./hello-world:v1`, use the following command: +To verify local image `./hello-world:v1`, user should use flag `--oci-layout` and `--scope` together, for example: ```shell -notation verify --local-artifact --scope "local/hello-world" ./hello-world:v1 +notation verify --oci-layout --scope "localhost:5000/hello-world" ./hello-world:v1 ``` From 3c0fa9486dddf80f98955d2c3531591989e6d3c4 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Fri, 31 Mar 2023 18:45:53 +0800 Subject: [PATCH 06/11] doc: update per comments Signed-off-by: Yi Zha --- specs/commandline/list.md | 12 ++++++------ specs/commandline/sign.md | 10 +++++----- specs/commandline/verify.md | 10 +++++----- 3 files changed, 16 insertions(+), 16 deletions(-) diff --git a/specs/commandline/list.md b/specs/commandline/list.md index e43d62134..b6b3a94f8 100644 --- a/specs/commandline/list.md +++ b/specs/commandline/list.md @@ -29,7 +29,7 @@ Aliases: Flags: -d, --debug debug mode -h, --help help for list - --oci-layout [Preview] whether the artifact is OCI image layout + --oci-layout [Preview] list signatures stored in OCI image layout -p, --password string password for registry operations (default to $NOTATION_PASSWORD if not specified) --plain-http registry access via plain HTTP -u, --username string username for registry operations (default to $NOTATION_USERNAME if not specified) @@ -49,24 +49,24 @@ An example output: ```shell localhost:5000/net-monitor:v1 └── application/vnd.cncf.notary.signature - ├── sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa - └── sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb + ├── sha256:647039638efb22a021f59675c9449dd09956c981a44b82c1ff074513c2c9f273 + └── sha256:6bfb3c4fd485d6810f9656ddd4fb603f0c414c5f0b175ef90eeb4090ebd9bfa1 ``` -### [Preview] List all the signatures associated with the image in OCI layout directory on disk +### [Preview] List all the signatures associated with the image in OCI layout directory The following example lists the signatures associated with the image in OCI layout directory named `hello-world`. Reference an image in OCI layout directory using tags: ```shell -notation list --oci-layout ./hello-world:v1 +notation list --oci-layout hello-world:v1 ``` Reference an image in OCI layout directory using exact digest: ```shell -notation list --oci-layout ./hello-world@sha256:xxx +notation list --oci-layout hello-world@sha256:xxx ``` An example output: diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index 21c084640..40641f75c 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -33,7 +33,7 @@ Flags: -h, --help help for sign --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 - --oci-layout [Preview] whether the artifact is OCI image layout + --oci-layout [Preview] sign the artifact stored in OCI image layout -p, --password string password for registry operations (default to $NOTATION_PASSWORD if not specified) --plain-http registry access via plain HTTP --plugin string signing plugin name. This is mutually exclusive with the --key flag @@ -167,11 +167,11 @@ Successfully signed localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da notation sign --signature-manifest artifact /@ ``` -### [Preview] Sign artifacts in OCI layout directory on disk +### [Preview] Sign container images stored in OCI layout directory -Artifacts can be stored on disk in the form of 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 OCI layout directory for now. Users can reference an artifact in the layout using either tags, or the exact digest. For example, use `hello-world:v1` or `hello-world@sha256xxx` to reference the container image in OCI layout directory named `hello-world`. +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`. -Tools like `docker buildx` support building an OCI image layout on disk. The following example creates a tarball named `hello-world.tar` with tag `v1`. Please note that the digest can be retrieved in the output messages of `docker buildx build`. +Tools like `docker buildx` support building images stored in OCI image layout. The following example creates a tarball named `hello-world.tar` with tag `v1`. Please note that the digest can be retrieved in the output messages of `docker buildx build`. ```shell docker buildx create --use @@ -185,7 +185,7 @@ mkdir hello-world tar -xf ./hello-world.tar -C hello-world ``` -Use flag `--oci-layout` to sign the image in OCI layout directory referenced by `hello-world@sha256xxx`. For example: +Use flag `--oci-layout` to sign the image stored in OCI layout directory referenced by `hello-world@sha256xxx`. For example: ```shell notation sign --oci-layout ./hello-world@sha256:xxx diff --git a/specs/commandline/verify.md b/specs/commandline/verify.md index bfa4cf5ed..cdfe22894 100644 --- a/specs/commandline/verify.md +++ b/specs/commandline/verify.md @@ -37,7 +37,7 @@ Usage: Flags: -d, --debug debug mode -h, --help help for verify - --oci-layout [Preview] whether artifact is OCI image layout + --oci-layout [Preview] verify the artifact stored in OCI image layout -p, --password string password for registry operations (default to $NOTATION_PASSWORD if not specified) --plain-http registry access via plain HTTP --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 @@ -171,13 +171,13 @@ Warning: Always verify the artifact using digest(@sha256:...) rather than a tag Successfully verified signature for localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 ``` -### [Preview] Verify artifacts in OCI layout directory on disk +### [Preview] Verify container images in OCI layout directory -Users should configure trust policy properly before verifying artifacts in OCI layout directory on disk. 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 artifacts in OCI layout directory doesn't contain repository URL information. Users can set `registryScopes` to the URL that the artifact 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 local image `./hello-world:v1`: +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`: ```jsonc { - "name": "local-images", + "name": "images stored in OCI layout", "registryScopes": [ "localhost:5000/hello-world" ], "signatureVerification": { "level" : "strict" @@ -187,7 +187,7 @@ Users should configure trust policy properly before verifying artifacts in OCI l } ``` -To verify local image `./hello-world:v1`, user should use flag `--oci-layout` and `--scope` together, for example: +To verify image `./hello-world:v1`, user should use flag `--oci-layout` and `--scope` together, for example: ```shell notation verify --oci-layout --scope "localhost:5000/hello-world" ./hello-world:v1 From 184dcf1bc69b9891b46312c2513678d76a456bf7 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Fri, 31 Mar 2023 20:56:39 +0800 Subject: [PATCH 07/11] doc: update per comments Signed-off-by: Yi Zha --- specs/commandline/list.md | 2 +- specs/commandline/sign.md | 6 +++--- specs/commandline/verify.md | 6 +++--- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/specs/commandline/list.md b/specs/commandline/list.md index b6b3a94f8..bc071a348 100644 --- a/specs/commandline/list.md +++ b/specs/commandline/list.md @@ -72,7 +72,7 @@ notation list --oci-layout hello-world@sha256:xxx An example output: ```shell -./hello-world@sha256:a08753c0c7bcdaaf5c2fdb375f68e860c34bffb146368982c201d41769e1763c +hello-world@sha256:a08753c0c7bcdaaf5c2fdb375f68e860c34bffb146368982c201d41769e1763c └── application/vnd.cncf.notary.signature ├── sha256:647039638efb22a021f59675c9449dd09956c981a44b82c1ff074513c2c9f273 └── sha256:6bfb3c4fd485d6810f9656ddd4fb603f0c414c5f0b175ef90eeb4090ebd9bfa1 diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index 40641f75c..412794ef7 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -182,19 +182,19 @@ Users need to extract the tarball into a directory first, since Notation only su ```shell mkdir hello-world -tar -xf ./hello-world.tar -C hello-world +tar -xf hello-world.tar -C hello-world ``` Use flag `--oci-layout` to sign the image stored in OCI layout directory referenced by `hello-world@sha256xxx`. For example: ```shell -notation sign --oci-layout ./hello-world@sha256:xxx +notation sign --oci-layout hello-world@sha256:xxx ``` Upon successful signing, the signature is stored in the same layout directory and associated with the image. Use `notation list` command to list the signatures, for example: ```shell -notation list --oci-layout ./hello-world@sha256:xxx +notation list --oci-layout hello-world@sha256:xxx ``` [oci-artifact-manifest]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/artifact.md diff --git a/specs/commandline/verify.md b/specs/commandline/verify.md index cdfe22894..4a9767f36 100644 --- a/specs/commandline/verify.md +++ b/specs/commandline/verify.md @@ -173,7 +173,7 @@ Successfully verified signature for localhost:5000/net-monitor@sha256:b94d27b993 ### [Preview] 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`: +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`: ```jsonc { @@ -187,8 +187,8 @@ Users should configure trust policy properly before verifying artifacts in OCI l } ``` -To verify image `./hello-world:v1`, user should use flag `--oci-layout` and `--scope` together, for example: +To verify image `hello-world:v1`, user should use flag `--oci-layout` and `--scope` together, for example: ```shell -notation verify --oci-layout --scope "localhost:5000/hello-world" ./hello-world:v1 +notation verify --oci-layout --scope "localhost:5000/hello-world" hello-world:v1 ``` From cea38f619cfb933508b86240cbe48bd04f1aa7d2 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Sat, 1 Apr 2023 10:03:05 +0800 Subject: [PATCH 08/11] doc: update per comments Signed-off-by: Yi Zha --- specs/commandline/verify.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/commandline/verify.md b/specs/commandline/verify.md index 4a9767f36..aa2028bc8 100644 --- a/specs/commandline/verify.md +++ b/specs/commandline/verify.md @@ -41,7 +41,7 @@ Flags: -p, --password string password for registry operations (default to $NOTATION_PASSWORD if not specified) --plain-http registry access via plain HTTP --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 [Preview] set trust policy scope for artifact verification, only use it with flag "--oci-layout" + --scope string [Preview] set trust policy scope for artifact verification, required to be used with flag "--oci-layout" -u, --username string username for registry operations (default to $NOTATION_USERNAME if not specified) -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 @@ -187,7 +187,7 @@ Users should configure trust policy properly before verifying artifacts in OCI l } ``` -To verify image `hello-world:v1`, user should use flag `--oci-layout` and `--scope` together, for example: +To verify image `hello-world:v1`, user should use flags `--oci-layout` and `--scope` together, for example: ```shell notation verify --oci-layout --scope "localhost:5000/hello-world" hello-world:v1 From 32234f330713282853d8b76c3bd7cd5ac2c30055 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Mon, 10 Apr 2023 15:23:01 +0800 Subject: [PATCH 09/11] doc: update to using experimental flag Signed-off-by: Yi Zha --- specs/commandline/list.md | 10 +++++----- specs/commandline/sign.md | 14 ++++++++------ specs/commandline/verify.md | 10 +++++----- 3 files changed, 18 insertions(+), 16 deletions(-) diff --git a/specs/commandline/list.md b/specs/commandline/list.md index bc071a348..5a421da0d 100644 --- a/specs/commandline/list.md +++ b/specs/commandline/list.md @@ -29,7 +29,7 @@ Aliases: Flags: -d, --debug debug mode -h, --help help for list - --oci-layout [Preview] list signatures stored in OCI image layout + --oci-layout [Experimental] list signatures stored in OCI image layout -p, --password string password for registry operations (default to $NOTATION_PASSWORD if not specified) --plain-http registry access via plain HTTP -u, --username string username for registry operations (default to $NOTATION_USERNAME if not specified) @@ -53,20 +53,20 @@ localhost:5000/net-monitor:v1 └── sha256:6bfb3c4fd485d6810f9656ddd4fb603f0c414c5f0b175ef90eeb4090ebd9bfa1 ``` -### [Preview] List all the signatures associated with the image in OCI layout directory +### [Experimental] List all the signatures associated with the image in OCI layout directory -The following example lists the signatures associated with the image in OCI layout directory named `hello-world`. +The following example lists the signatures associated with the image in OCI layout directory named `hello-world`. To access this flag `--oci-layout` set the environment variable `NOTATION_EXPERIMENTAL`. Reference an image in OCI layout directory using tags: ```shell -notation list --oci-layout hello-world:v1 +NOTATION_EXPERIMENTAL=1 notation list --oci-layout hello-world:v1 ``` Reference an image in OCI layout directory using exact digest: ```shell -notation list --oci-layout hello-world@sha256:xxx +NOTATION_EXPERIMENTAL=1 notation list --oci-layout hello-world@sha256:xxx ``` An example output: diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index 412794ef7..bf3677441 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -33,7 +33,7 @@ Flags: -h, --help help for sign --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 - --oci-layout [Preview] sign the artifact stored in OCI image layout + --oci-layout [Experimental] sign the artifact stored in OCI image layout -p, --password string password for registry operations (default to $NOTATION_PASSWORD if not specified) --plain-http registry access via plain HTTP --plugin string signing plugin name. This is mutually exclusive with the --key flag @@ -163,11 +163,13 @@ Successfully signed localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da ### [Experimental] Sign an artifact and store the signature using OCI artifact manifest +To access this flag `--signature-manifest` set the environment variable `NOTATION_EXPERIMENTAL`. + ```shell -notation sign --signature-manifest artifact /@ +NOTATION_EXPERIMENTAL=1 notation sign --signature-manifest artifact /@ ``` -### [Preview] Sign container images stored in OCI layout directory +### [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`. @@ -185,16 +187,16 @@ mkdir hello-world tar -xf hello-world.tar -C hello-world ``` -Use flag `--oci-layout` to sign the image stored in OCI layout directory referenced by `hello-world@sha256xxx`. For example: +Use flag `--oci-layout` to sign the image stored in OCI layout directory referenced by `hello-world@sha256xxx`. To access this flag `--oci-layout` set the environment variable `NOTATION_EXPERIMENTAL`. For example: ```shell -notation sign --oci-layout hello-world@sha256:xxx +NOTATION_EXPERIMENTAL=1 notation sign --oci-layout hello-world@sha256:xxx ``` Upon successful signing, the signature is stored in the same layout directory and associated with the image. Use `notation list` command to list the signatures, for example: ```shell -notation list --oci-layout hello-world@sha256:xxx +NOTATION_EXPERIMENTAL=1 notation list --oci-layout hello-world@sha256:xxx ``` [oci-artifact-manifest]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/artifact.md diff --git a/specs/commandline/verify.md b/specs/commandline/verify.md index aa2028bc8..7ab38f494 100644 --- a/specs/commandline/verify.md +++ b/specs/commandline/verify.md @@ -37,11 +37,11 @@ Usage: Flags: -d, --debug debug mode -h, --help help for verify - --oci-layout [Preview] verify the artifact stored in OCI image layout + --oci-layout [Experimental] verify the artifact stored in OCI image layout -p, --password string password for registry operations (default to $NOTATION_PASSWORD if not specified) --plain-http registry access via plain HTTP --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 [Preview] set trust policy scope for artifact verification, required to be used with flag "--oci-layout" + --scope string [Experimental] set trust policy scope for artifact verification, required to be used with flag "--oci-layout" -u, --username string username for registry operations (default to $NOTATION_USERNAME if not specified) -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 @@ -171,7 +171,7 @@ Warning: Always verify the artifact using digest(@sha256:...) rather than a tag Successfully verified signature for localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 ``` -### [Preview] Verify container images in OCI layout directory +### [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`: @@ -187,8 +187,8 @@ Users should configure trust policy properly before verifying artifacts in OCI l } ``` -To verify image `hello-world:v1`, user should use flags `--oci-layout` and `--scope` together, for example: +To verify image `hello-world:v1`, user should set the environment variable `NOTATION_EXPERIMENTAL` and use flags `--oci-layout` and `--scope` together. for example: ```shell -notation verify --oci-layout --scope "localhost:5000/hello-world" hello-world:v1 +NOTATION_EXPERIMENTAL=1 notation verify --oci-layout --scope "localhost:5000/hello-world" hello-world:v1 ``` From d73dc138ee15ec8daf8d12eda825456f4d26be8e Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Tue, 11 Apr 2023 19:57:04 +0800 Subject: [PATCH 10/11] doc: update per comments Signed-off-by: Yi Zha --- specs/commandline/list.md | 2 +- specs/commandline/sign.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/specs/commandline/list.md b/specs/commandline/list.md index 5a421da0d..40ae18042 100644 --- a/specs/commandline/list.md +++ b/specs/commandline/list.md @@ -55,7 +55,7 @@ localhost:5000/net-monitor:v1 ### [Experimental] List all the signatures associated with the image in OCI layout directory -The following example lists the signatures associated with the image in OCI layout directory named `hello-world`. To access this flag `--oci-layout` set the environment variable `NOTATION_EXPERIMENTAL`. +The following example lists the signatures associated with the image in OCI layout directory named `hello-world`. To access this flag `--oci-layout` , set the environment variable `NOTATION_EXPERIMENTAL=1`. Reference an image in OCI layout directory using tags: diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index bf3677441..4b2a9efb2 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -163,7 +163,7 @@ Successfully signed localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da ### [Experimental] Sign an artifact and store the signature using OCI artifact manifest -To access this flag `--signature-manifest` set the environment variable `NOTATION_EXPERIMENTAL`. +To access this flag `--signature-manifest`, set the environment variable `NOTATION_EXPERIMENTAL=1`. ```shell NOTATION_EXPERIMENTAL=1 notation sign --signature-manifest artifact /@ @@ -187,7 +187,7 @@ mkdir hello-world tar -xf hello-world.tar -C hello-world ``` -Use flag `--oci-layout` to sign the image stored in OCI layout directory referenced by `hello-world@sha256xxx`. To access this flag `--oci-layout` set the environment variable `NOTATION_EXPERIMENTAL`. For example: +Use flag `--oci-layout` to sign the image stored in OCI layout directory referenced by `hello-world@sha256xxx`. To access this flag `--oci-layout` , set the environment variable `NOTATION_EXPERIMENTAL=1`. For example: ```shell NOTATION_EXPERIMENTAL=1 notation sign --oci-layout hello-world@sha256:xxx From a310de7309cc2dc52ab5a59fac51075b8d9c0d04 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Mon, 17 Apr 2023 13:21:44 +0800 Subject: [PATCH 11/11] doc:update per comments Signed-off-by: Yi Zha --- specs/commandline/list.md | 8 ++++++-- specs/commandline/sign.md | 13 +++++++++---- specs/commandline/verify.md | 13 ++++++++----- 3 files changed, 23 insertions(+), 11 deletions(-) diff --git a/specs/commandline/list.md b/specs/commandline/list.md index 40ae18042..8f86bfa1a 100644 --- a/specs/commandline/list.md +++ b/specs/commandline/list.md @@ -60,13 +60,17 @@ The following example lists the signatures associated with the image in OCI layo Reference an image in OCI layout directory using tags: ```shell -NOTATION_EXPERIMENTAL=1 notation list --oci-layout hello-world:v1 +export NOTATION_EXPERIMENTAL=1 +# Assume OCI layout directory hello-world is under current path +notation list --oci-layout hello-world:v1 ``` Reference an image in OCI layout directory using exact digest: ```shell -NOTATION_EXPERIMENTAL=1 notation list --oci-layout hello-world@sha256:xxx +export NOTATION_EXPERIMENTAL=1 +# Assume OCI layout directory hello-world is under current path +notation list --oci-layout hello-world@sha256:xxx ``` An example output: diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index 4b2a9efb2..7e083a276 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -33,7 +33,7 @@ Flags: -h, --help help for sign --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 - --oci-layout [Experimental] sign the artifact stored in OCI image layout + --oci-layout [Experimental] sign the artifact stored as OCI image layout -p, --password string password for registry operations (default to $NOTATION_PASSWORD if not specified) --plain-http registry access via plain HTTP --plugin string signing plugin name. This is mutually exclusive with the --key flag @@ -166,7 +166,8 @@ Successfully signed localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da To access this flag `--signature-manifest`, set the environment variable `NOTATION_EXPERIMENTAL=1`. ```shell -NOTATION_EXPERIMENTAL=1 notation sign --signature-manifest artifact /@ +export NOTATION_EXPERIMENTAL=1 +notation sign --signature-manifest artifact /@ ``` ### [Experimental] Sign container images stored in OCI layout directory @@ -190,13 +191,17 @@ tar -xf hello-world.tar -C hello-world Use flag `--oci-layout` to sign the image stored in OCI layout directory referenced by `hello-world@sha256xxx`. To access this flag `--oci-layout` , set the environment variable `NOTATION_EXPERIMENTAL=1`. For example: ```shell -NOTATION_EXPERIMENTAL=1 notation sign --oci-layout hello-world@sha256:xxx +export NOTATION_EXPERIMENTAL=1 +# Assume OCI layout directory hello-world is under current path +notation sign --oci-layout hello-world@sha256:xxx ``` Upon successful signing, the signature is stored in the same layout directory and associated with the image. Use `notation list` command to list the signatures, for example: ```shell -NOTATION_EXPERIMENTAL=1 notation list --oci-layout hello-world@sha256:xxx +export NOTATION_EXPERIMENTAL=1 +# Assume OCI layout directory hello-world is under current path +notation list --oci-layout hello-world@sha256:xxx ``` [oci-artifact-manifest]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/artifact.md diff --git a/specs/commandline/verify.md b/specs/commandline/verify.md index 7ab38f494..7cb4e9526 100644 --- a/specs/commandline/verify.md +++ b/specs/commandline/verify.md @@ -37,11 +37,11 @@ Usage: Flags: -d, --debug debug mode -h, --help help for verify - --oci-layout [Experimental] verify the artifact stored in OCI image layout + --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) --plain-http registry access via plain HTTP --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 to be used with flag "--oci-layout" + --scope string [Experimental] set trust policy scope for artifact verification, only required if flag "--oci-layout" is set -u, --username string username for registry operations (default to $NOTATION_USERNAME if not specified) -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 @@ -177,8 +177,8 @@ Users should configure trust policy properly before verifying artifacts in OCI l ```jsonc { - "name": "images stored in OCI layout", - "registryScopes": [ "localhost:5000/hello-world" ], + "name": "images stored as OCI layout", + "registryScopes": [ "local/hello-world" ], "signatureVerification": { "level" : "strict" }, @@ -190,5 +190,8 @@ Users should configure trust policy properly before verifying artifacts in OCI l To verify image `hello-world:v1`, user should set the environment variable `NOTATION_EXPERIMENTAL` and use flags `--oci-layout` and `--scope` together. for example: ```shell -NOTATION_EXPERIMENTAL=1 notation verify --oci-layout --scope "localhost:5000/hello-world" hello-world:v1 +export NOTATION_EXPERIMENTAL=1 +# Assume OCI layout directory hello-world is under current path +# The value of --scope should be set base on the trust policy configuration +notation verify --oci-layout --scope "local/hello-world" hello-world:v1 ```