doc: update spec for feature sign/verify local images

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 <registry>/<repository>:<tag>
 ```
 
@@ -48,6 +49,31 @@ 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
+NOTATION_EXPERIMENTAL=1 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
+```
+
+An example output:
+
+```shell
+hello-world@sha256:a08753c0c7bcdaaf5c2fdb375f68e860c34bffb146368982c201d41769e1763c
+└── application/vnd.cncf.notary.signature
+    ├── sha256:647039638efb22a021f59675c9449dd09956c981a44b82c1ff074513c2c9f273
+    └── sha256:6bfb3c4fd485d6810f9656ddd4fb603f0c414c5f0b175ef90eeb4090ebd9bfa1
 ```

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 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
@@ -162,10 +163,43 @@ 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
+NOTATION_EXPERIMENTAL=1 notation sign --signature-manifest artifact <registry>/<repository>@<digest>
+```
+
+### [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
+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 sign --signature-manifest artifact <registry>/<repository>@<digest>
+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
 [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

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 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                [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
@@ -168,3 +170,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
 ```
+
+### [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 in OCI layout",
+    "registryScopes": [ "localhost:5000/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
+NOTATION_EXPERIMENTAL=1 notation verify --oci-layout --scope "localhost:5000/hello-world" hello-world:v1
+```