Add documentation for signature access protocols

This is primarily the only documentation of the sigstore layout;
in addition it comments on the OpenShift API master REST API and the
OpenShift docker/distribution API extension.

Signed-off-by: Miloslav Trmač <mitr@redhat.com>

Author: mtrmac

docs/signature-protocols.md

@@ -0,0 +1,115 @@
+# Signature access protocols
+
+The `github.com/containers/image` library supports signatures implemented as blobs “attached to” an image.
+Some image transports (local storage formats and remote procotocols) implement these signatures natively
+or trivially; for others, the protocol extensions described below are necessary.
+
+## docker/distribution registries—separate storage
+
+### Usage
+
+Any existing docker/distribution registry, whether or not it natively supports signatures,
+can be augmented with separate signature storage by configuring a signature storage URL in [`registries.d`](registries.d.md).
+`registries.d` can be configured to use one storage URL for a whole docker/distribution server,
+or also separate URLs for smaller namespaces or individual repositories within the server
+(which e.g. allows image authors to manage their own signature storage while publishing
+the images on the public `docker.io` server).
+
+The signature storage URL defines a root of a path hierarchy.
+It can be either a `file:///…` URL, pointing to a local directory structure,
+or a `http`/`https` URL, pointing to a remote server.
+`file:///` signature storage can be both read and written, `http`/`https` only supports reading.
+
+The same path hierarchy is used in both cases, so the HTTP/HTTPS server can be
+a simple static web server serving a directory structure created by writing to a `file:///` signature storage.
+(This of course does not prevent other server implementations,
+e.g. a HTTP server reading signatures from a database.)
+
+The usual workflow for producing and distributing images using the separate storage mechanism
+is to configure the repository in `registries.d` with `sigstore-staging` URL pointing to a private
+`file:///` staging area, and a `sigstore` URL pointing to a public web server.
+To publish an image, the image author would sign the image as necessary (e.g. using `skopeo copy`),
+and then copy the created directory structure from the `file:///` staging area
+to a subdirectory of a webroot of the public web server so that they are accessible using the public `sigstore` URL.
+The author would also instruct consumers of the image to, or provide a `registries.d` configuration file to,
+set up a `sigstore` URL pointing to the public web server.
+
+### Path structure
+
+Given a _base_ signature storage URL configured in `registries.d` as mentioned above,
+and a container image stored in a docker/distribution registry using the _fully-expanded_ name
+_hostname_`/`_namespaces_`/`_name_{`@`_digest_,`:`_tag_} (e.g. for `docker.io/library/busybox:latest`,
+_namespaces_ is `library`, even if the user refers to the image using the shorter syntax as `busybox:latest`),
+signatures are accessed using URLs of the form
+> _base_`/`_namespaces_`/`_name_`@`_digest-algo_`=`_digest-value_`/signature-`_index_
+
+where _digest-algo_`:`_digest-value_ is a manifest digest usable for referencing the relevant image manifest
+(i.e. even if the user referenced the image using a tag,
+the signature storage is always disambiguated using digest references).
+Note that in the URLs used for signatures,
+_digest-algo_ and _digest-value_ are separated using the `=` character,
+not `:` like when acessing the manifest using the docker/distribution API.
+
+Within the URL, _index_ is a decimal integer (in the canonical form), starting with 1.
+Signatures are stored at URLs with successive _index_ values; to read all of them, start with _index_=1,
+and continue reading signatures and increasing _index_ as long as signatures with these _index_ values exist.
+Similarly, to add one more signature to an image, find the first _index_ which does not exist, and
+then store the new signature using that _index_ value.
+
+There is no way to list existing signatures other than iterating through the successive _index_ values,
+and no way to download all of the signatures at once.
+
+### Examples
+
+For a docker/distribution image available as `busybox@sha256:817a12c32a39bbe394944ba49de563e085f1d3c5266eb8e9723256bc4448680e`
+(or as `busybox:latest` if the `latest` tag points to to a manifest with the same digest),
+and with a `registries.d` configuration specifying a `sigstore` URL `https://example.com/sigstore` for the same image,
+the following URLs would be accessed to download all signatures:
+> - `https://example.com/sigstore/library/busybox@sha256=817a12c32a39bbe394944ba49de563e085f1d3c5266eb8e9723256bc4448680e/signature-1`
+> - `https://example.com/sigstore/library/busybox@sha256=817a12c32a39bbe394944ba49de563e085f1d3c5266eb8e9723256bc4448680e/signature-2`
+> - …
+
+For a docker/distribution image available as `example.com/ns1/ns2/ns3/repo@somedigest:digestvalue` and the same
+`sigstore` URL, the signatures would be available at
+> `https://example.com/sigstore/ns1/ns2/ns3/repo@somedigest=digestvalue/signature-1`
+
+and so on.
+
+## OpenShift-embedded registries
+
+The OpenShift-embedded registry implements the ordinary docker/distribution API,
+and it also exposes images through the OpenShift REST API (available through the “API master” servers).
+
+As of https://github.com/openshift/origin/pull/9181,
+signatures are exposed through the OpenShift API
+(i.e. to access the complete image, it is necessary to use both APIs,
+in particular to know the URLs for both the docker/distribution and the OpenShift API master endpoints).
+
+To read the signature, any user with access to an image can use the `imagestreamimages` namespaced
+resource to read an `Image` object and its `Signatures` array.  Use only the `ImageSignature` objects
+which have `Type` equal to `atomic`, and read the signature from `Content`; ignore the other fields of
+the `ImageSignature` object.
+
+To add or remove signatures, use the cluster-wide (non-namespaced) `imagesignatures` resource,
+with `Type` set to `atomic` and `Content` set to the signature.  Signature names must have the form
+_digest_`@`_per-image-name_, where _digest_ is an image manifest digest (OpenShift “image name”),
+and _per-image-name_ is any unique identifier.
+
+Note that because signatures are stored within the cluster-wide image objects,
+i.e. different namespaces can not associate different sets of signatures to the same image,
+updating signatures requires a cluster-wide access to the `imagesignatures` resource
+(by default available to the `system:image-signer` role),
+and deleting signatures is strongly discouraged
+(it deletes the signature from all namespaces which contain the same image).
+
+## (OpenShift) docker/distribution API extension
+
+As of https://github.com/openshift/origin/pull/12504/ , the OpenShift-embedded registry also provides
+an extension of the docker/distribution API which allows simpler access to the signatures,
+using only the docker/distribution API endpoint.
+
+This API is not inherently OpenShift-specific (e.g. the client does not need to know the OpenShift API endpoint,
+and credentials sufficient to access the docker/distribution API server are sufficient to access signatures as well),
+and in the future it will be the preferred way to implement signature storage in registries.
+
+More detailed documentation of this API will be added later (after `github.com/containers/image` implements it).