The Docker Content Trust mechanism is implemented using Docker Notary (https://github.com/docker/notary), which is on The Update Framework (https://github.com/theupdateframework/tuf). TUF is a secure framework that allows us to delivery a collection of trusted content at a time. Notary allows a client and a server to form a trusted collection by making it easier to publish and verify contents. If we have a Docker image, we can sign it offline using a highly secure offline key. Then when we publish that image, we can push it to a Notary server that can be used to delivery trusted images. Notary is the way to enable Secured Software Supply Chain for the enterprise using Docker.

We demonstrate how to set up our own Notary server and use it to sign Docker image content before pushing to a Docker registry. The prerequisite is to have a recent version of Docker Compose installed.

The first step is to clone Notary (in this example we fix its version at 0.4.2):

git clone https://github.com/docker/notary.git
cd notary
git checkout v0.4.2
cd notary

Open docker-compose.yml and add the image option to specify an image name and tag for both signer and server. In this example, I used Docker Hub to store the build images. So it's chanwit/server:v042 and chanwit/signer:v042. Change this to reflect your local configuration.

Then start with

$ docker-compose up -d

We now have a Notary server up and running at https://127.0.0.1:4443. To make it possible for the Docker client to do a handshake with Notary, we need to copy the Notary Server certificate as CA of this trusted address (127.0.0.4443).

$ mkdir -p ~/.docker/tls/127.0.0.1:4443/
$ cp ./fixtures/notary-server.crt 
    ~/.docker/tls/127.0.0.1:4443/ca.crt

After that, we enable Docker Content Trust and point Docker Content Trust server to our own Notary at https://127.0.0.1:4443.

$ export DOCKER_CONTENT_TRUST=1
$ export DOCKER_CONTENT_TRUST_SERVER=https://127.0.0.1:4443  

Then we tag the image as a new one and push the image while enabling Docker Content Trust:

$ docker tag busybox chanwit/busybox:signed
$ docker push chanwit/busybox:signed

If the setup finishes correctly, we'll see the Docker client asking for the new root key and the new repository key. Then it will confirm that chanwit/busybox:signed was successfully signed.

The push refers to a repository [docker.io/chanwit/busybox]
e88b3f82283b: Layer already exists
signed: digest: 
sha256:29f5d56d12684887bdfa50dcd29fc31eea4aaf4ad3bec43daf19026a7ce69912 size: 527
Signing and pushing trust metadata
You are about to create a new root signing key passphrase. This passphrase
will be used to protect the most sensitive key in your signing system. Please
choose a long, complex passphrase and be careful to keep the password and the
key file itself secure and backed up. It is highly recommended that you use a
password manager to generate the passphrase and keep it safe. There will be no
way to recover this key. You can find the key in your config directory.
Enter passphrase for new root key with ID 1bec0c1:
Repeat passphrase for new root key with ID 1bec0c1:
Enter passphrase for new repository key with ID ee73739 (docker.io/chanwit/busybox):
Repeat passphrase for new repository key with ID ee73739 (docker.io/chanwit/busybox):
Finished initializing "docker.io/chanwit/busybox"
Successfully signed "docker.io/chanwit/busybox":signed

Now, we can try pulling the same image:

$ docker pull chanwit/busybox:signed
Pull (1 of 1): chanwit/busybox:signed@sha256:29f5d56d12684887bdfa50dcd29fc31eea4aaf4ad3bec43daf19026a7ce69912
sha256:29f5d56d12684887bdfa50dcd29fc31eea4aaf4ad3bec43daf19026a7ce69912: Pulling from chanwit/busybox
Digest: sha256:29f5d56d12684887bdfa50dcd29fc31eea4aaf4ad3bec43daf19026a7ce69912
Status: Image is up to date for chanwit/busybox@sha256:29f5d56d12684887bdfa50dcd29fc31eea4aaf4ad3bec43daf19026a7ce69912
Tagging chanwit/busybox@sha256:29f5d56d12684887bdfa50dcd29fc31eea4aaf4ad3bec43daf19026a7ce69912 as chanwit/busybox:signed

When we pull an unsigned image, and this time it will show that there is no trusted data:

$ docker pull busybox:latest
Error: remote trust data does not exist for docker.io/library/busybox: 127.0.0.1:4443 does not have trust data for docker.io/library/busybox