Skip to main content

Sign containers with Docker Notary

Docker integrates with DigiCert​​®​​ Software Trust Manager PKCS11 library to securely manage your root and delegation keys. The PKCS11 library ensures that cryptographic operations and key management are performed securely. This integrated approach delegates the responsibility of managing snapshot and timestamping keys to the notary server. The notary server ensures the authenticity and integrity of Docker images by signing and verifying them using these snapshot and timestamp keys.

Prerequisites

Docker Content Trust

Follow these steps to manage Docker Content Trust.

Tip

This is a once off action performed by the repository or collection owner

Before you begin:

  1. Configure the following environment variable:

    export DOCKER_CONTENT_TRUST=1

  2. Copy the Software Trust Manager PKCS11 library to this location:

    copy smpkcs11.so /usr/local/lib/libykcs11.so

Generate root key

The root key, also known as the "Root Signing Key" is the highest level of trust in Docker Content Trust. It is a key that signs other keys and establishes a chain of trust. The root key is used to sign the repository key and may be used to sign additional keys, such as intermediate keys or delegation keys. The root key's signature on these other keys ensures that the entire chain of trust can be verified, from the root key down to the repository key and target keys.

A root key is only required when adding new repositories or collections. Docker identifies a root key when it contains a certificate with CN=root. This action should only be performed by the repository or collection owner.

If one does not already exist, generate a new keypair that contains “CN=root”, using:

keytool -keystore NONE -storetype PKCS11 -storepass changeit -providerClass sun.security.pkcs11.SunPKCS11 -providerArg <path_of_configuration_file> -genkeypair -keyalg EC -keysize 256 -dname “CN=root” -alias docker_root_key

Note

Docker signing only supports ECDSA 256-bit keys.

Generate delegation key

The delegation key is used to sign the delegation metadata, designating the trusted party to manage the signing of specific images. This feature is particularly useful in large repositories where multiple teams or users may be responsible for different sets of images.

A delegation key with a default certificate is required for Docker to sign images. You can generate a key and default certificate in Signing Manager Controller (SMCTL) or in Software Trust Manager.

To generate the delegation key and default certificate in SMCTL:

smctl keypair generate ecdsa <Delegation Key Alias> --cert-alias=<Delegation Cert Alias> --cert-profile-id=<Certificate Profile ID> --generate-cert=true --key-type=PRODUCTION

Create repository

Follow theses steps to create a Docker repository and add a delegation role.

Download the certificate generated for the Docker delegation key:

  1. Sign in to DigiCert ONE.

  2. Navigate Manager menu icon (top right) > Software Trust.

  3. Select Certificates.

  4. Click on the certificate alias.

  5. Identify the Certificate field.

  6. Click the Download icon or copy and paste the plain text.

 

To add the certificate as a delegation on Docker, use the command:

docker trust signer add --key <keypair_delegation_certificate.cer> "digicert" digicert/hello-digicert

"DigiCert" is the name of the delegation. "digicert/hello-digicert" is the new repository or collection.

Note

You need a repository key to add or remove a delegation or signer.

Verify signer and delegation roles for the repository

To verify the signer and delegation roles associated with the repository.

docker trust inspect --pretty digicert/hello-digicert

Push the image and trust data to registry and notary

Push Docker images from your local machine or build server to the repository. These images will be stored in the registry and can be accessed by others.

To sign the tag using the delegation key and push the trust data to notary:

docker push digicert/hello-digicert

Docker Pull allows other users or systems to pull the images from the repository to use them for running container. When content trust enabled, Docker verifies the image before running it.

Related articles

Troubleshooting

: