DockerHow-ToBeginner · 4 min read

How to Use Docker Content Trust for Secure Image Signing

Use DOCKER_CONTENT_TRUST=1 to enable Docker Content Trust, which ensures images are signed and verified before pulling or pushing. Run commands like docker pull or docker push with this environment variable set to enforce signature verification automatically.

📐

Syntax

Docker Content Trust is enabled by setting the environment variable DOCKER_CONTENT_TRUST=1. This tells Docker to verify digital signatures when pulling or pushing images.

Basic usage pattern:

DOCKER_CONTENT_TRUST=1 docker pull <image> - Pulls an image and verifies its signature.
DOCKER_CONTENT_TRUST=1 docker push <image> - Pushes an image and signs it.

bash

DOCKER_CONTENT_TRUST=1 docker pull alpine:latest
DOCKER_CONTENT_TRUST=1 docker push yourrepo/yourimage:tag

💻

Example

This example shows how to enable Docker Content Trust to pull a signed image and push a signed image to a repository.

bash

export DOCKER_CONTENT_TRUST=1

docker pull alpine:latest

docker tag alpine:latest yourrepo/alpine-signed:latest

docker push yourrepo/alpine-signed:latest

Output

Using default tag: latest latest: Pulling from library/alpine Digest: sha256:... Status: Downloaded newer image for alpine:latest The push refers to repository [docker.io/yourrepo/alpine-signed] ... Signing and pushing trust metadata

⚠️

Common Pitfalls

Common mistakes when using Docker Content Trust include:

Not setting DOCKER_CONTENT_TRUST=1, so signatures are not verified.
Trying to pull unsigned images with trust enabled, which causes errors.
Losing private keys needed to sign images, preventing pushes.
Forgetting to initialize trust keys before pushing signed images.

Always back up your trust keys and ensure images are signed before pulling with trust enabled.

bash

docker pull alpine:latest
# Without DOCKER_CONTENT_TRUST=1, no signature verification happens

DOCKER_CONTENT_TRUST=1 docker pull unsignedimage:latest
# Error: No trust data found for image

# Correct way:
export DOCKER_CONTENT_TRUST=1
docker pull signedimage:latest

📊

Quick Reference

Command	Description
DOCKER_CONTENT_TRUST=1 docker pull	Pulls image and verifies signature
DOCKER_CONTENT_TRUST=1 docker push	Pushes image and signs it
export DOCKER_CONTENT_TRUST=1	Enable trust for current shell session
docker trust key generate	Generate a new signing key
docker trust sign	Sign an existing image

✅

Key Takeaways

Enable Docker Content Trust by setting DOCKER_CONTENT_TRUST=1 to verify image signatures automatically.

You must have signing keys set up to push signed images successfully.

Pulling unsigned images with trust enabled will fail to protect you from unverified content.

Always back up your trust keys to avoid losing the ability to sign images.

Use Docker trust commands to manage keys and sign images explicitly when needed.