Docker Content Trust

Docker Content Trust is a feature in the Docker containerization platform that enables remote registry content to be digitally signed, ensuring that the content is unaltered and is the most current available version when users access it. It works via cryptographic keys. Docker Content Trust was introduced in Docker Engine with version 1.8.

Docker Content Trust adds security controls that verify the integrity of container images -- the container files that hold application components and content -- stored in a registry, such as Docker Hub. Enterprise developers and other users can push or pull (upload or download) container images to a registry. Docker Content Trust addresses two concerns with registries. Users might upload a container image infiltrated with malware, and the users accessing it from that remote repository cannot determine its integrity. And secondly, users can put outdated containers on a registry, which creates interoperability, compatibility or performance problems for the business. In Docker parlance, a repository is a collection of container images with the same name, distinguished by tags, placed in the registry.

When a publisher pushes a container image to a remote registry, Docker Engine applies a cryptographic signature to the container image, using the publisher's cryptographic key. The signed image can be pulled from the registry by users, at which point Docker Engine uses the original publisher's public key to verify it is the same. This key check only verifies that the image is the original file, unaltered. Docker Content Trust does not certify the suitability or performance of a container for any particular task. It is possible to pull a verified container image, only for that container to generate errors or perform poorly because it is not production-ready. A user can still upload a malicious container image, and Docker Content Trust will sign the image. Public registry and repository users still bear the responsibility to test and vet a container image.

Docker Content Trust setup
Figure 1. This diagram shows how Docker Content Trust is set up.

Key features of Docker Content Trust

Docker Content Trust uses two cryptographic keys that are created as trust is established. The first time an image publisher pushes their content to the registry, DCT produces an offline key and a tagging key. The tagging key, also known as a repository key, is applied to the publisher's repository and is the shared key used by anyone who needs to sign content for the repository. The offline key is the private or root trust key for the repository. The term offline key indicates that this key's holder should keep it offline, where it is safe from some types of attacks. Container publishers should protect and back up their cryptographic keys.

Docker Content Trust automatically generates a timestamp key for the uploaded container file, ensuring the image version is authentically the latest upload presented in the repository.

Using these keys, Docker Content Trust can check the cryptographic signature when a user attempts to pull a container. If the keys match, the content is deemed authentic. If not, the user is warned but allowed to proceed if they choose.

TUF in Docker Content Trust
Figure 2. TUF enables Docker Content Trust to follow a schema of digital signatures to verify content is unaltered.

Docker Content Trust is based on Docker Notary tool to publish and manage trusted content and The Update Framework (TUF), which is a framework to secure software update systems. The Notary project provides a client-server foundation for establishing trust to verify and work with content collections. Notary is integrated into Docker Content Trust to enable publishers to sign content using offline keys and post trusted content to a trusted collection on public servers. Users can securely obtain the publisher's public key, and then use it to verify the content. Notary relies on TUF for secure software distribution and update operations.

Docker Content Trust security advantages

The verification system helps guard against man-in-the-middle attacks, as it prevents an attacker from secretly forging or tampering with content. DCT also prevents replay attacks, wherein valid actions are copied and replayed by attackers to fool a system. For example, DCT timestamps prevent attackers from passing off older (typically compromised) images from being passed off as most recent. The TUF framework and use of multiple keys allow DCT to guard the system against tagging key compromise, and allow publishers to change tagging keys on demand, without disrupting users.

Docker designed the Content Trust feature to be unobtrusive for developers that upload images and the people who use this content. Content publishers do not have to learn new commands, or change workflows, but they do need to create and manage keys. Users are completely insulated from the digital signage system, and can use the same push, pull, build, run and other commands as they would without Docker Content Trust.

Docker Content Trust diagram
Figure 3. This diagram shows how the Docker command-line interface tool interacts with the Content Trust server.

The version of Content Trust released in Docker Engine 1.8 is opt-in, disabled by default. Publishers and users must deliberately enable it. Once Docker Content Trust is enabled, all registry operations will demand the use of signed and verified images.

To increase security, organizations can also use private image registries with Docker, certified container images from trusted software vendors, and secrets management and security scanning on the Docker platform.

This was last updated in December 2017

Continue Reading About Docker Content Trust

Dig Deeper on Containers and virtualization