Sign an image¶
Two key components of the Mirantis Secure Registry are the Notary Server and the Notary Signer. These two containers provide the required components for using Docker Content Trust (DCT) out of the box. Docker Content Trust allows you to sign image tags, therefore giving consumers a way to verify the integrity of your image.
Note
If the MSR certificate authority (CA) is self-signed, you must take steps to
make the machine running the docker trust command trust the MSR
CA. You can do this by creating a folder with the name of MSR
hostname under $HOME/.docker/tls/
and placing the MSR CA file in that
folder. For example:
mkdir -p $HOME/.docker/tls/msr.example.com curl -k -o
$HOME/.docker/tls/msr.example.com/msr-ca.crt https://msr.example.com/ca
As part of MSR, both the Notary and the Registry servers are accessed through a front-end proxy, with both components sharing the MKE’s RBAC (Role-based Access Control) Engine. Therefore, you do not need additional Docker client configuration in order to use DCT.
DCT is integrated with the Docker CLI, and allows you to:
Configure repositories
Add signers
Sign images using the docker trust command
Sign images that MKE can trust¶
MKE has a feature that prevent untrusted images from being deployed
on the cluster. To use the feature, you need to sign and push images
to your MSR. To tie the signed images back to MKE, you need
to sign the images with the private keys of the MKE users.
From an MKE client bundle, use key.pem
as your private key,
and cert.pem
as your public key on an x509
certificate.
To sign images in a way that MKE can trust, you need to:
Download a client bundle for the user account you want to use for signing the images.
Add the user’s private key to your machine’s trust store.
Initialize trust metadata for the repository.
Delegate signing for that repository to the MKE user.
Sign the image.
The following example shows the nginx
image getting pulled from
Docker Hub, tagged as msr.example.com/dev/nginx:1
, pushed to MSR,
and signed in a way that is trusted by MKE.
Import an MKE user’s private key¶
After downloading and extracting an MKE client bundle into your local
directory, you need to load the private key into the local Docker trust
store (~/.docker/trust)
. To illustrate the process, we will use
jeff
as an example user.
$ docker trust key load --name jeff key.pem
Loading key from "key.pem"...
Enter passphrase for new jeff key with ID a453196:
Repeat passphrase for new jeff key with ID a453196:
Successfully imported key from key.pem
Initialize the trust metadata and add the user’s public certificate¶
Next,initiate trust metadata for an MSR repository. If you have not
already done so, navigate to the MSR web UI, and create a repository
for your image. This example uses the nginx
repository in the
prod
namespace.
As part of initiating the repository, the public key of the MKE user needs to be added to the Notary server as a signer for the repository. You will be asked for a number of passphrases to protect the keys.Make a note of these passphrases.
$ docker trust signer add --key cert.pem jeff msr.example.com/prod/nginx
Adding signer "jeff" to msr.example.com/prod/nginx...
Initializing signed repository for msr.example.com/prod/nginx...
Enter passphrase for root key with ID 4a72d81:
Enter passphrase for new repository key with ID e0d15a2:
Repeat passphrase for new repository key with ID e0d15a2:
Successfully initialized "msr.example.com/prod/nginx"
Successfully added signer: jeff to msr.example.com/prod/nginx
Inspect the trust metadata of the repository to make sure the user has been added correctly.
$ docker trust inspect --pretty msr.example.com/prod/nginx
No signatures for msr.example.com/prod/nginx
List of signers and their keys for msr.example.com/prod/nginx
SIGNER KEYS
jeff 927f30366699
Administrative keys for msr.example.com/prod/nginx
Repository Key: e0d15a24b7...540b4a2506b
Root Key: b74854cb27...a72fbdd7b9a
Sign the image¶
Finally, user jeff
can sign an image tag. The following steps
include downloading the image from Hub, tagging the image for Jeff’s MSR
repository, pushing the image to Jeff’s MSR, as well as signing the tag
with Jeff’s keys.
$ docker pull nginx:latest
$ docker tag nginx:latest msr.example.com/prod/nginx:1
$ docker trust sign msr.example.com/prod/nginx:1
Signing and pushing trust data for local image msr.example.com/prod/nginx:1, may overwrite remote trust data
The push refers to repository [msr.example.com/prod/nginx]
6b5e2ed60418: Pushed
92c15149e23b: Pushed
0a07e81f5da3: Pushed
1: digest: sha256:5b49c8e2c890fbb0a35f6050ed3c5109c5bb47b9e774264f4f3aa85bb69e2033 size: 948
Signing and pushing trust metadata
Enter passphrase for jeff key with ID 927f303:
Successfully signed msr.example.com/prod/nginx:1
Inspect the trust metadata again to make sure the image tag has been signed successfully.
$ docker trust inspect --pretty msr.example.com/prod/nginx:1
Signatures for msr.example.com/prod/nginx:1
SIGNED TAG DIGEST SIGNERS
1 5b49c8e2c8...90fbb2033 jeff
List of signers and their keys for msr.example.com/prod/nginx:1
SIGNER KEYS
jeff 927f30366699
Administrative keys for msr.example.com/prod/nginx:1
Repository Key: e0d15a24b74...96540b4a2506b
Root Key: b74854cb27c...1ea72fbdd7b9a
Alternatively, you can review the signed image from the MSR web UI.
Add delegations¶
You have the option to sign an image using multiple MKE users’ keys. For
example, an image needs to be signed by a member of the Security
team and a member of the Developers
team. Let’s assume jeff
is a
member of the Developers team. In this case, we only need to add a
member of the Security team.
To do so, first add the private key of the Security team member to the local Docker trust store.
$ docker trust key load --name ian key.pem
Loading key from "key.pem"...
Enter passphrase for new ian key with ID 5ac7d9a:
Repeat passphrase for new ian key with ID 5ac7d9a:
Successfully imported key from key.pem
Upload the user’s public key to the Notary Server and sign the image.
You will be asked for jeff
, the developer’s passphrase, as well as
the ian
user’s passphrase to sign the tag.
$ docker trust signer add --key cert.pem ian msr.example.com/prod/nginx
Adding signer "ian" to msr.example.com/prod/nginx...
Enter passphrase for repository key with ID e0d15a2:
Successfully added signer: ian to msr.example.com/prod/nginx
$ docker trust sign msr.example.com/prod/nginx:1
Signing and pushing trust metadata for msr.example.com/prod/nginx:1
Existing signatures for tag 1 digest 5b49c8e2c890fbb0a35f6050ed3c5109c5bb47b9e774264f4f3aa85bb69e2033 from:
jeff
Enter passphrase for jeff key with ID 927f303:
Enter passphrase for ian key with ID 5ac7d9a:
Successfully signed msr.example.com/prod/nginx:1
Finally, check the tag again to make sure it includes two signers.
$ docker trust inspect --pretty msr.example.com/prod/nginx:1
Signatures for msr.example.com/prod/nginx:1
SIGNED TAG DIGEST SIGNERS
1 5b49c8e2c89...5bb69e2033 jeff, ian
List of signers and their keys for msr.example.com/prod/nginx:1
SIGNER KEYS
jeff 927f30366699
ian 5ac7d9af7222
Administrative keys for msr.example.com/prod/nginx:1
Repository Key: e0d15a24b741ab049470298734397afbea539400510cb30d3b996540b4a2506b
Root Key: b74854cb27cc25220ede4b08028967d1c6e297a759a6939dfef1ea72fbdd7b9a
Delete trust data¶
If an administrator wants to delete an MSR repository that contains trust metadata, they will be prompted to delete the trust metadata first before removing the repository.
To delete trust metadata, you need to use the Notary CLI.
$ notary delete msr.example.com/prod/nginx --remote
Deleting trust data for repository msr.example.com/prod/nginx
Enter username: admin
Enter password:
Successfully deleted local and remote trust data for repository msr.example.com/prod/nginx
If you don’t include the --remote
flag, Notary deletes local cached
content but will not delete data from the Notary server.
Delete signed images¶
To delete signed images, you must first identify the roles that signed the image and then remove the trust data for each of those roles.
Identify the roles that signed an image¶
Determine the roles that are trusted to sign the image:
List the trusted roles:
notary delegation list <registry-host-name>/<namespace>/<repository>
Example output:
ROLE PATHS KEY IDS THRESHOLD ---- ----- ------- --------- targets/releases "" <all paths> c3470c45cefde5...2ea9bc8 1 targets/qa "" <all paths> c3470c45cefde5...2ea9bc8 1
In this example, the repository owner delegated trust to the
targets/releases
andtargets/qa
roles.
For each role listed in the previous step, identify whether it signed the image:
notary list <registry-host-name>/<namespace>/<repository> --roles <role-name>
Remove trust data for a role¶
Note
Only users with private keys that have the required roles can perform this operation.
For each role that signed the image, remove the trust data for that role:
notary remove <registry-host-name>/<namespace>/<repository> <tag> \
--roles <role-name> --publish
The image will display as unsigned once the trust data has been removed for all of the roles that signed the image.
Delete the image¶
To delete the image, refer to Delete images.