Docker Content Trust: Image Signing and Verification

Docker Content Trust (DCT) ensures the integrity and publisher authenticity of Docker images through digital signatures. When enabled, Docker only pulls and runs images that have been signed by trusted publishers, preventing tampered or unauthorized images from running in your environment. This guide covers enabling DCT, signing images, and managing trust.

How DCT Works

• Image publishers sign images with private keys using The Update Framework (TUF)
• Signatures are stored in a Notary server alongside the registry
• When pulling, Docker verifies signatures before downloading image layers
• Unsigned or incorrectly signed images are rejected

Enabling Docker Content Trust

# Enable globally via environment variable
export DOCKER_CONTENT_TRUST=1

# Or per-command
DOCKER_CONTENT_TRUST=1 docker pull nginx:latest

# Disable for specific commands
DOCKER_CONTENT_TRUST=0 docker pull unsigned-image:latest

Signing Images

# First push generates signing keys
export DOCKER_CONTENT_TRUST=1

# Build and tag
docker build -t registry.example.com/myapp:v1.0 .

# Push (triggers signing)
docker push registry.example.com/myapp:v1.0
# First time: prompted to create root key and repository key
# Enter passphrases for both keys

# Subsequent pushes use existing keys
docker push registry.example.com/myapp:v1.1

Key Management

# Keys are stored in ~/.docker/trust/
# Root key: signs the top-level trust metadata (KEEP SECURE)
# Repository key: signs individual image repositories
# Delegation key: for granting signing rights to team members

# List keys
docker trust key ls

# Generate a new delegation key
docker trust key generate developer1
# Creates developer1.pub

# Add delegation key to a repository
docker trust signer add --key developer1.pub developer1 registry.example.com/myapp

# Rotate keys (if compromised)
docker trust key rotate registry.example.com/myapp snapshot

Inspecting Trust

# View signed tags for an image
docker trust inspect --pretty registry.example.com/myapp

# Output shows:
# - Signed tags with their digests
# - List of signers
# - Administrative keys

# Verify an image signature
DOCKER_CONTENT_TRUST=1 docker pull registry.example.com/myapp:v1.0
# Outputs: Tagging registry.example.com/myapp@sha256:abc123... as registry.example.com/myapp:v1.0

Cosign (Modern Alternative)

Cosign (from Sigstore) is the modern standard for container image signing, used by major projects:

# Install cosign
brew install cosign    # macOS
sudo apt install cosign # Linux (via package)

# Generate a key pair
cosign generate-key-pair

# Sign an image
cosign sign --key cosign.key registry.example.com/myapp:v1.0

# Verify an image
cosign verify --key cosign.pub registry.example.com/myapp:v1.0

# Keyless signing with OIDC (no key management needed)
cosign sign registry.example.com/myapp:v1.0
# Opens browser for OIDC authentication (GitHub, Google, etc.)

# Verify keyless signature
cosign verify --certificate-identity user@example.com --certificate-oidc-issuer https://accounts.google.com registry.example.com/myapp:v1.0

CI/CD Integration

# GitHub Actions — sign images after build
- name: Sign image with Cosign
  run: |
    cosign sign --yes --key env://COSIGN_KEY \
      ${{ env.REGISTRY }}/${{ env.IMAGE }}:${{ env.TAG }}
  env:
    COSIGN_KEY: ${{ secrets.COSIGN_PRIVATE_KEY }}
    COSIGN_PASSWORD: ${{ secrets.COSIGN_PASSWORD }}

Best Practices

• Enable DCT in all production environments — never run unsigned images
• Store root keys offline (USB drive, HSM) and use delegation keys for daily signing
• Consider Cosign for new projects — it has better CI/CD integration and keyless signing
• Rotate repository keys periodically and immediately if compromise is suspected
• Combine image signing with vulnerability scanning for comprehensive supply chain security
• Set DOCKER_CONTENT_TRUST=1 in system-wide profile on production servers