Docker Content Trust

When transferring data among networked systems, trust is a central concern. In particular, when communicating over an untrusted medium such as the internet, it is critical to ensure the integrity and the publisher of all the data a system operates on. You use Docker Engine to push and pull images to a public or private registry. Docker Content Trust (DCT) gives you the ability to verify both the integrity and the publisher of all the data received from a registry over any channel.

Docker Content Trust provides the ability to use digital signatures for data sent to and received from remote Docker registries. These signatures allow client-side or runtime verification of the integrity and publisher of specific image tags.

Through DCT, image publishers can sign their images and image consumers can verify the signatures of the images they pull. Publishers could be individuals or organizations manually signing their content or automated software supply chains signing content as part of their release process.

Image tags and DCT

An individual image record has the following identifier:

[REGISTRY_HOST[:REGISTRY_PORT]/]REPOSITORY[:TAG]

A particular image REPOSITORY can have multiple tags. For example, latest and 3.1.2 are both tags on the mongo image. An image publisher can build an image and tag combination many times changing the image with each build.

DCT is associated with the TAG portion of an image. Each image repository has a set of keys that image publishers use to sign an image tag. Image publishers have discretion on which tags they sign.

An image repository can contain an image with one tag that is signed and another tag that is not. For example, consider the Mongo image repository. The latest tag could be unsigned while the 3.1.6 tag could be signed. It is the responsibility of the image publisher to decide if an image tag is signed or not. In this representation, some image tags are signed, others are not:

../_images/tag_signing.png

Publishers can choose to sign a specific tag or not. As a result, the content of an unsigned tag and that of a signed tag with the same name may not match. For example, a publisher can push a tagged image someimage:latest and sign it. Later, the same publisher can push an unsigned someimage:latest image. This second push replaces the last unsigned tag latest but does not affect the signed latest version. The ability to choose which tags they can sign allows publishers to iterate over the unsigned version of an image before officially signing it.

Image consumers can enable DCT to ensure that images they use are signed. If a consumer enables DCT, they can only pull, run, or build with trusted images. Enabling DCT is a bit like applying a “filter” to your registry. Consumers “see” only signed image tags while the less desirable, unsigned image tags are “invisible” to them.

../_images/trust_view.png

To the consumer who has not enabled DCT, nothing changes with regard to how they work with Docker images. Every image is visible regardless of whether it is signed or not.

Docker Content Trust Keys

Trust for an image tag is managed through the use of signing keys. A key set is created when an operation using DCT is first invoked. A key set consists of the following classes of keys:

  • an offline key that is the root of DCT for an image tag

  • repository or tagging keys that sign tags

  • server-managed keys such as the timestamp key, which provides freshness security guarantees for your repository

The following image depicts the various signing keys and their relationships:

../_images/trust_components.png

Warning

Once lost, the root key is not recoverable.

You should back up the root key somewhere safe. Given that it is only required to create new repositories, you should store it offline in hardware. For details on securing, and backing up your keys, make sure you read Manage keys for content trust.