Configure image signing¶

To configure image signing, you must enable Docker Content Trust (DCT) and initiate a repository for use with DCT.

Enable DCT¶

While MSR supports DCT use by default, you must opt in to use it on the Docker client side by setting the following environment variable:

export DOCKER_CONTENT_TRUST=1

Important

Mirantis recommends that you add this environment variable to your shell login configuration, so that it is always active.

Trust MSR CA certificate¶

If your MSR instance uses a certificate that is issued by a well-known, public certificate authority (CA), then skip this section and proceed to Configure repository for signing.

If the MSR certificate authority (CA) is self-signed, you must configure the machine that runs the docker trust commands to trust the CA, as detailed in this section.

Caution

It is not possible to use DCT with a remote MSR that is set up as an insecure registry in the Docker daemon configuration. This is because DCT operations are not processed by the Docker daemon, but are instead sent directly to the back-end Notary components that handle signing. It is not possible to configure the back-end components to allow insecure operation.

To configure your machine to trust a self-signed CA:

Create a certificate directory for the MSR host in the Docker configuration directory:
```
export MSR=<registy-hostname>
mkdir -p ~/.docker/certs.d/${MSR}
```

Download the MSR CA certificate into the newly created directory:

curl -ks https://${MSR}/ca > ~/.docker/certs.d/${MSR}/ca.crt

Restart the Docker daemon.
Verify that you do not receive certificate errors when accessing MSR:
```
docker login ${MSR}
```
Create a symlink between the certs.d and tls directories. This link allows the Docker client to share the same CA trust as established for the Docker daemon in the preceding steps.
```
ln -s certs.d ~/.docker/tls
```

Configure repository for signing¶

Initialize a repository for use with DCT by pushing an image to the relevant repository. You will be prompted for both a new root key password and a new repository key password, as displayed in the example output.

docker push <registry-host-name>/<namespace>/<repository>:<tag>

Example output:

The push refers to repository [<registry-host-name>/<namespace>/<repository>]
b2d5eeeaba3a: Layer already exists
latest: digest: sha256:def822f9851ca422481ec6fee59a9966f12b351c62ccb9aca841526ffaa9f748 size: 528
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 8128255: <root-password>
Repeat passphrase for new root key with ID 8128255: <root-password>
Enter passphrase for new repository key with ID 493e995: <repository-password>
Repeat passphrase for new repository key with ID 493e995: <repository-password>
Finished initializing "<registry-host-name>/<namespace>/<repository>"
Successfully signed <registry-host-name>/<namespace>/<repository>:<tag>

The root and repository keys are kept only locally in your content trust store.