Signing Images with Docker Content Trust¶

Within the Docker CLI, you can sign and push a container image with the $ docker trust command syntax. This is built on top of the Notary feature set, more information for which can be found in the Notary Github Repository.

A prerequisite for signing an image is a container image Registry with a Notary server attached, such as a Mirantis Secure Registry or Docker Hub. Instructions for standing up a self-hosted environment can be found in the Docker official documentation, Deploy Notary Server with Compose.

A delegation key pair is required to sign a container image. These keys can be generated locally using $ docker trust key generate or generated by a certificate authority. If you are using Mirantis Kubernetes Engine, the Client Bundle provides adequate keys for a delegation.

To sign images with Docker Content Trust:

Add the delegation private key to the local Docker trust repository, which by default is stored in ~/.docker/trust/.

If you are generating delegation keys with $ docker trust key generate, the private key is automatically added to the local trust store.

If you are importing a separate key, such as one from a MKE Client Bundle, you must use the $ docker trust key load command:

$ docker trust key generate jeff
Generating key for jeff...
Enter passphrase for new jeff key with ID 9deed25:
Repeat passphrase for new jeff key with ID 9deed25:
Successfully generated and loaded private key. Corresponding public key
available: /home/ubuntu/Documents/mytrustdir/jeff.pub

If you have an existing key, run the following command:

$ docker trust key load key.pem --name jeff
Loading key from "key.pem"...
Enter passphrase for new jeff key with ID 8ae710e:
Repeat passphrase for new jeff key with ID 8ae710e:
Successfully imported key from key.pem

Add the delegation public key to the Notary server. Each delegation key in Notary is specific to a particular image repository. If this is the first time you are adding a delegation to that repository, this command will also initiate the repository, using a local Notary canonical root key. To understand more about initiating a repository, and the role of delegations, refer to the official Docker documentation, Delegations for content trust.
```
$ docker trust signer add --key cert.pem jeff msr.example.com/admin/demo
Adding signer "jeff" to msr.example.com/admin/demo...
Enter passphrase for new repository key with ID 10b5e94:
```

Use the delegation private key to sign a particular tag and push the signature up to the registry.

$ docker trust sign msr.example.com/admin/demo:1
Signing and pushing trust data for local image msr.example.com/admin/demo:1, may overwrite remote trust data
The push refers to repository [msr.example.com/admin/demo]
7bff100f35cb: Pushed
1: digest: sha256:3d2e482b82608d153a374df3357c0291589a61cc194ec4a9ca2381073a17f58e size: 528
Signing and pushing trust metadata
Enter passphrase for signer key with ID 8ae710e:
Successfully signed msr.example.com/admin/demo:1

Alternatively, once the keys have been imported an image can be pushed with the $ docker push command:

$ export DOCKER_CONTENT_TRUST=1

$ docker push msr.example.com/admin/demo:1
The push refers to repository [msr.example.com/admin/demo:1]
7bff100f35cb: Pushed
1: digest: sha256:3d2e482b82608d153a374df3357c0291589a61cc194ec4a9ca2381073a17f58e size: 528
Signing and pushing trust metadata
Enter passphrase for signer key with ID 8ae710e:
Successfully signed msr.example.com/admin/demo:1

To view remote trust data for a tag or repository:

Run the $ docker trust inspect command to view remote trust data for a tag or a repository:

$ docker trust inspect --pretty msr.example.com/admin/demo:1

Signatures for msr.example.com/admin/demo:1

SIGNED TAG          DIGEST                                                             SIGNERS
1                   3d2e482b82608d153a374df3357c0291589a61cc194ec4a9ca2381073a17f58e   jeff

List of signers and their keys for msr.example.com/admin/demo:1

SIGNER              KEYS
jeff                8ae710e3ba82

Administrative keys for msr.example.com/admin/demo:1

  Repository Key:    10b5e94c916a0977471cc08fa56c1a5679819b2005ba6a257aa78ce76d3a1e27
  Root Key:  84ca6e4416416d78c4597e754f38517bea95ab427e5f95871f90d460573071fc

To remove remote trust data for a tag:

Run the $ docker trust revoke command to remove remote trust data for a tag:

$ docker trust revoke msr.example.com/admin/demo:1
Enter passphrase for signer key with ID 8ae710e:
Successfully deleted signature for msr.example.com/admin/demo:1