Using Docker Content Trust

1. Enabling Content Trust

Command	Description	Notes
docker content trust enable	Enables content trust for a repository	Requires Docker CLI 20.10 or later
DOCKER_CONTENT_TRUST=1	Environment variable to enable content trust globally	Can be set in shell profile or Docker daemon config

Example: Enabling Content Trust for a Repository

docker content trust enable myrepo/myapp

Note: Content trust ensures that only signed images are pulled from the registry.

Warning: Once enabled, content trust cannot be disabled for a repository without reinitializing the trust store.

2. Signing Images with Notary

Command	Description	Notes
docker trust sign	Signs a Docker image using the Notary server	Requires Docker Content Trust to be enabled
docker trust key generate	Generates a new signing key for image signatures	Used to create keys before signing images
docker trust key list	Lists all available signing keys	Shows keys used for image signing

Example: Signing a Docker Image

export DOCKER_CONTENT_TRUST=1
docker trust sign myapp:latest

Note: Docker Content Trust must be enabled via DOCKER_CONTENT_TRUST=1 to sign images.

Warning: Once an image is signed, it cannot be modified without invalidating the signature.

3. Managing Signing Keys

Key Type	Description	Usage
Signing Key	Private key used to sign Docker images	Required for image signing and verification
Root Key	Private key used to sign the trust root	Used for managing trust policies and root of trust
Target Key	Private key used to sign image targets	Used for signing specific image tags

Example: Generate a new signing key

docker trust key generate my-signing-key

Example: List available signing keys

docker trust key list

Example: Remove a signing key

docker trust key remove my-signing-key

Note: Signing keys must be securely stored and backed up to prevent loss of trust in signed images.

4. Verifying Image Signatures

Command	Description	Example
docker content trust verify	Verifies the signature of a Docker image	`docker content trust verify myapp:latest`
docker trust inspect	Inspects the trust information of an image	`docker trust inspect myapp:latest`

Example: Verifying an Image Signature

docker content trust verify myapp:latest

Note: Docker Content Trust must be enabled to verify image signatures. Use export DOCKER_CONTENT_TRUST=1 to enable it.

Warning: If an image is not signed, the verification will fail and display a warning.

5. Configuring Trust Policies

Policy Type	Description	Configuration Example
Notary	Enables content trust for Docker images using Notary server	`export DOCKER_CONTENT_TRUST=1`
Signature Requirements	Defines which signatures are required for image pulls	`docker trust inspect <image>`
Key Management	Manages signing keys for image trust	`docker trust key generate <key>`

Example: Setting Up Content Trust

export DOCKER_CONTENT_TRUST=1
docker pull alpine:latest

Note: Content trust requires Docker CLI version 17.06.0 or higher.

Warning: Disabling content trust with DOCKER_CONTENT_TRUST=0 bypasses image verification.

Trust Policy	Effect	Usage
Signature Required	Ensures only signed images are pulled	`docker pull <signed-image>`
Key Rotation	Allows updating signing keys for security	`docker trust key rotate <key>`
Revocation	Invalidates trust for compromised keys	`docker trust revoke <key>`

6. Rotating Signing Keys

Rotating signing keys in Docker Content Trust ensures that your images remain secure and that only authorized parties can sign them. This process involves generating a new key pair and updating the trust configuration.

Step	Description	Action
1	Generate a new signing key	`docker trust key generate my-new-key`
2	Export the public key	`docker trust key export my-new-key.pub`
3	Update the trust root with the new key	`docker trust key import my-new-key.pub`
4	Re-sign images with the new key	`docker trust sign my-image:latest`

Note: Ensure that all team members have access to the new signing key and update their local trust configurations accordingly.

7. Delegating Signing Authority

Docker Content Trust allows you to delegate signing authority to other users or teams. This ensures that only authorized individuals can sign images, maintaining the integrity and security of your container registry.

Role	Description	Permissions
Content Trust Manager	Manages the trust root and delegates signing responsibilities.	Can add/remove signers, configure trust policies, manage keys.
Image Signer	Signs images using their private key.	Can only sign images; cannot manage trust policies or keys.

Example: Adding a Signer

docker content trust signer add --key /path/to/signer-key.pem myorg/myapp

Note: The myorg/myapp image must already exist in the registry for the signer to be added.

Key Points

Content Trust supports role-based delegation for signing authority.
Only the Content Trust Manager can add or remove signers.
Signers must have their private keys available to sign images.

8. Using Root Keys Securely

Key Type	Description	Security Considerations
Root Key	Primary key used to sign Docker content trust metadata.	Must be stored securely and never exposed in code or logs. Use hardware security modules (HSMs) or secure key storage solutions when possible.
Revoke Root Key	Process to invalidate a compromised root key.	Requires immediate rotation of all content trust signatures. Use `docker content trust revoke` to invalidate the key and re-sign all images with a new root key.

Example: Revoking Root Key

docker content trust revoke --root-key /path/to/root.key

Note: Root keys should never be stored in plaintext on systems accessible to untrusted users or processes.

Warning: Revoking a root key invalidates all content trust signatures. Ensure all images are re-signed with a new root key before proceeding.

9. Managing Repository Keys

Key Type	Description	Usage
Signing Key	Private key used to sign Docker images	Generated with `docker trust key generate`
Root Key	Root of trust for content trust	Used to sign the delegation keys
Delegation Key	Keys used to delegate signing responsibilities	Used for specific roles like `targets`

Example: Generate a Signing Key

docker trust key generate my-signing-key

Example: Inspect Key Details

docker trust key inspect my-signing-key

Note: Ensure that signing keys are securely stored and backed up to prevent loss of image trust.

Workflow: Add a Key to a Repository

Generate a new key pair using docker trust key generate
Sign the repository with the new key using docker trust sign
Push the signed image to the repository

10. Recovering from Key Compromise

Note: This process involves revoking and reissuing signing keys in Docker Content Trust, which requires access to the Docker Notary server and administrative privileges.

If a signing key is compromised, it must be revoked to prevent unauthorized use. The following steps outline how to recover from a key compromise:

Action	Description	Command
Revoke the key	Remove the compromised signing key from the Notary server.	`notary key revoke --key-id <key-id>`
Generate new key	Create a new signing key for content trust.	`notary key generate`
Re-sign images	Re-sign all images that were previously signed with the compromised key.	`docker trust sign <image>`

Example: Revoking a compromised key

notary key revoke --key-id 1234567890abcdef

Example: Re-signing an image after key recovery

docker trust sign myrepo/myapp:latest

Warning: After revoking a key, all images previously signed with that key will no longer be trusted by Docker Content Trust. Ensure that new keys are properly distributed to all users and systems.

11. Integrating with CI/CD Pipelines

Example: Docker Content Trust in GitHub Actions

name: Build and Push
on:
  push:
    branches: [ main ]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
      - name: Login to DockerHub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}
      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: myapp:latest
          build-args:
            - "DOCKER_CONTENT_TRUST=1"

Configuration	Description	Value
DOCKER_CONTENT_TRUST	Enables Docker Content Trust (DCT)	`1`
DOCKER_CONTENT_TRUST_SERVER	Custom Notary server URL	`https://notary.example.com`

Note: DCT requires signed images to be pulled from a trusted registry. Ensure your CI/CD pipeline has proper credentials for signing and pushing images.

Warning: Disabling DCT in CI/CD pipelines reduces security by allowing unsigned images to be pulled and executed.

12. Troubleshooting Trust Errors

Error Message	Possible Cause	Solution
signature verification failed	Signature does not match the image	Re-pull the image or check for tampering
no valid trust data found	Image was not signed or trust data is missing	Enable content trust and re-sign the image
signature expired	Trust signature has expired	Re-sign the image with a new timestamp
key not found	Required signing key is missing from local store	Import the missing key or reconfigure trust settings

Example: Re-enable Docker Content Trust

export DOCKER_CONTENT_TRUST=1
docker pull myrepo/myapp:latest

Note: Ensure that your Docker client is updated to the latest version to avoid compatibility issues with trust data.