doc: update to support OCI image manifest (notaryproject#502)

Signed-off-by: Yi Zha <[email protected]>

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 <registry>/<repository>@<digest>
+```
+
+[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/