diff --git a/specs/commandline/list.md b/specs/commandline/list.md index 4b1b39f23..8f86bfa1a 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 + --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) @@ -39,7 +40,7 @@ Flags: ### List all the signatures of the signed container image -```text +```shell notation list /: ``` @@ -48,6 +49,35 @@ An example output: ```shell localhost:5000/net-monitor:v1 └── application/vnd.cncf.notary.signature - ├── sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa - └── sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb + ├── sha256:647039638efb22a021f59675c9449dd09956c981a44b82c1ff074513c2c9f273 + └── sha256:6bfb3c4fd485d6810f9656ddd4fb603f0c414c5f0b175ef90eeb4090ebd9bfa1 +``` + +### [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=1`. + +Reference an image in OCI layout directory using tags: + +```shell +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 +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: + +```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..7e083a276 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 + --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 @@ -162,10 +163,48 @@ 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=1`. + ```shell +export NOTATION_EXPERIMENTAL=1 notation sign --signature-manifest artifact /@ ``` +### [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`. + +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 +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, 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 `--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 +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 +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 [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..7cb4e9526 100644 --- a/specs/commandline/verify.md +++ b/specs/commandline/verify.md @@ -37,9 +37,11 @@ Usage: Flags: -d, --debug debug mode -h, --help help for verify + --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, 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 @@ -168,3 +170,28 @@ 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 ``` + +### [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`: + +```jsonc +{ + "name": "images stored as OCI layout", + "registryScopes": [ "local/hello-world" ], + "signatureVerification": { + "level" : "strict" + }, + "trustStores": [ "ca:hello-world" ], + "trustedIdentities": ["*"] +} +``` + +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 +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 +```