Diogo Mónica

Introducing Docker Content Trust

Diogo Mónica

Image Signing and Verification using The Update Framework (TUF)

A common request that we’ve heard from the Docker community is the need to have strong cryptographic guarantees over what code and what versions of software are being run in your infrastructure. This is an absolute necessity for secure and auditable production deployments. To answer these needs, we are excited to announce a new feature in 1.8 called Docker Content Trust which integrates The Update Framework (TUF) into Docker using Notary, an open source tool that provides trust over any content.


Introducing Docker Content Trust

notaryDocker Content Trust is a new feature in Docker Engine 1.8 that makes it possible to verify the publisher of Docker images. Before a publisher pushes an image to a remote registry, Docker Engine signs the image locally with the publisher’s private key. When you later pull this image, Docker Engine uses the publisher’s public key to verify that the image you are about to run is exactly what the publisher created, has not been tampered with and is up to date.

A key focus for Docker is to provide the highest level of security without sacrificing usability. Once enabled, Docker Content Trust is tied into a developer’s regular Docker workflow with no additional commands to learn. Users continue to use the same docker pull, docker push, docker build, docker create, docker run, commands they always have — only now it only operates on signed content.

In this release, Docker Content Trust is available to users as an opt-in feature. With content trust enabled, all operations using a remote registry enforce the use of signed and verified images. This is a new feature that we have developed with the community and are looking forward to having you opt-in, use it and give us feedback.


Overview of Docker Content Trust

The diagram below provides an overview of how Docker Content Trust works. When images are pushed to a repository, they are signed with private keys held by the content publisher. When a user interacts with the image for the first time, they establish trust with that publisher and then all subsequent interactions require a valid signature verification from that same publisher. This is similar to the trust on first use model of SSH that developers are familiar with, except for the added security benefit of the initial trust being established over HTTPS using the corresponding public PKI.



Content Trust Key Structure

Docker Content Trust has two distinct keys, an Offline key and a Tagging key, that are generated the first time a publisher pushes an image and stored client-side. Each repository has its own unique Tagging key. The first time a user runs the command docker pull, the user establishes trust to the repository with the Offline key.

The Tagging Key is generated for each new repository the publisher owns. They can be exported and shared with any person/system that needs the ability to sign content for this repository.

The Offline Key is the most important key, since it is the root of trust for your repository. Different repositories can use the same Offline key. You will only need this key if you are creating a new repository or rotating an existing key. The Offline key should be kept offline as this is advantageous for resisting against certain classes of attacks.

Once trust is established, Docker Content Trust makes use of TUF to ensure both the integrity and freshness of the content. In order to achieve these freshness guarantees, a Timestamp key is generated and stored on a remote server. Docker manages the Timestamp key for you, reducing the hassle of having to constantly refresh the content client-side.

Keys are the critical component to sign and verify trusted content for your repositories. It is very important that you backup these keys to a safe and secure location. It is important to note that while the loss of the Tagging or Timestamp keys is recoverable, the loss of the Offline key is not. Refer to docs on how to backup these keys.


Protection Against Image Forgery

Once trust is established, one of the guarantees that Docker Content Trust provides is the ability to withstand a malicious actor with a privileged network position, aka a man-in-the-middle attack. This means that in the event a registry is compromised, the malicious actor cannot tamper with the content and successfully serve it to the user. In this situation, every docker command run by a user will hard fail with a message stating that it was not able to verify the content.



Protection Against Replay Attacks

Replay attacks are a common problem with designing secure distributed systems, where previously valid payloads are replayed to trick another system. The same problem exists in software update systems, where old versions of signed software can be presented as the most recent. If a user is fooled into installing an older version of a particular software, the malicious actor can make use of known security vulnerabilities to compromise the user’s host.

Docker Content Trust uses the Timestamp key when publishing the image, providing protection against replay attacks and ensuring the user is receiving the most up to date content.



Protection Against Key Compromise

The illustration below depicts a scenario where the Tagging key has been compromised. The online nature of the Tagging key and the fact that it is needed every time new content gets pushed to a repository makes this key inherently more exposed than the Offline key. If this were a system that attempted to ensure integrity of data by using a single key, there would be no path forward to recover from an a key compromise. Docker Content Trust utilizes TUF to separate responsibilities across a hierarchy of keys such that loss of any particular key (except the Offline role) by itself is not fatal to the security of the system.


Docker Content Trust enables the publisher to rotate the compromised key transparently to the users and effectively remove the compromised key from the system. Given the key rotation process is non-disruptive to the user, publishers can even proactively rotate this key and protect themselves from undetected key compromises.


Notary: Secure content distribution for all

Docker Content Trust is enabled through an integration of Notary into Docker Engine. Notary is a utility for securely publishing and verifying content that is distributed over any insecure network. Introduced at DockerCon as “infrastructure plumbing,” Notary can be downloaded and implemented by anyone who wants to digitally sign and verify their arbitrary collections of content. The primary objective of Notary is to leapfrog the status-quo of software distribution, and package modern security guarantees within a simple command-line utility.


The Update Framework (TUF)

Under the hood, Notary uses The Update Framework (TUF), a secure general design for the problem of software distribution and updates. TUF solves the problem of helping developers secure software update systems by providing a flexible security framework that enables applications to be secure from all known attacks on the software update process. Using TUF gives Notary and Docker Content Trust advantages around survivable key compromise, the ability to have trusted updates over untrusted mirrors, protection against replay attacks, downgrade attacks and much more.

Here are more resources to learn more about TUF:

The Update Framework Specification
​A Look in the Mirror: Attacks on Package Managers
Package Management Security
Survivable Key Compromise in Software Update Systems



Introducing Content Trust as a core part of the Docker platform is a key milestone in helping developers build secure distributed applications. Anyone can start using it today to sign and verify Docker images. We have signed all the Official repository images on Docker Hub so that you can have a base set of trusted images from which to start building your applications.

So, get signing! Try out Docker Content Trust as part of Docker Engine 1.8 and check out Notary if you want to delve deeper.

Download Docker Toolbox to start using Docker
Read more about Docker 1.8
Read the docs for Content Trust


Learn More about the Docker 1.8 Release

Join our upcoming Docker online meetups featuring Docker engineers discussing the latest features of Docker 1.8 including plugins, Docker Content Trust and Toolbox – click here to register!



 Learn More about Docker



10 thoughts on “Introducing Docker Content Trust

  1. Roy Inganta Ginting

    Could you please elaborate on “Docker Content Trust uses the Timestamp key when publishing the image, providing protection against replay attacks and ensuring the user is receiving the most up to date content.”, specifically how does “ensuring the user is receiving the most up to date content” work?

    I am under impression that it is possible for attacker to trick users to believe that they are downloading the latest image even though attacker sending previous version which is vulnerable. Here is the scenario i can think of
    1. User issued docker pull image_name
    2. Docker engine on client check latest image to registry
    3. Attacker which has been compromise the registry and has capability to do replay attack telling docker engine on the client that previous version which is vulnerable is the latest
    4. Docker engine on the client downloads the vulnerable version (assuming docker engine on client does not has it locally) and runs it locally
    5. Attacker attacks vulnerable container that running on user server and game over.

  2. After pushing on a private registry using DOCKER CONTENT TRUST some metadata files are generated(targets.json, root,json,…) in ~/.docker/trust directory. Could you please elaborate what hashes (sha256) from target.json file means? What the connection between it and the digest of the image? Thank you!

Leave a Reply