Welcome to from-docker-to-kubernetes

Docker Content Trust 2.0

Next-generation supply chain security with Notary v2 integration, enhanced signature verification, and automated policy enforcement for secure container deployments

H A R S H H A A
@NotHarshhaa

Introduction to Docker Content Trust 2.0

Enhanced Signature Verification

Cryptographically validate image authenticity and provenance

Notary v2 Integration

Next-generation trusted content framework with improved performance

Hardware Security Module Support

Enterprise-grade key management and protection

Automated Policy Enforcement

Enforce security requirements across development pipelines

This guide explores the architecture, implementation strategies, and best practices for deploying Docker Content Trust 2.0 to create secure software supply chains for containerized applications.

Content Trust 2.0 Architecture

Security Model

Docker Content Trust 2.0 builds upon the original DCT framework while introducing significant architectural improvements:

┌─────────────────────────────────────────────────────────────────────────┐
│                                                                         │
│                     Docker Content Trust 2.0                            │
│                                                                         │
│  ┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐  │
│  │                 │      │                 │      │                 │  │
│  │  Signature      │      │  Policy         │      │  Verification   │  │
│  │  Generation     │◄────►│  Management     │◄────►│  Engine         │  │
│  │                 │      │                 │      │                 │  │
│  └────────┬────────┘      └────────┬────────┘      └────────┬────────┘  │
│           │                        │                        │           │
│           │                        │                        │           │
│           ▼                        ▼                        ▼           │
│  ┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐  │
│  │                 │      │                 │      │                 │  │
│  │  Key            │      │  Notary v2      │      │  Registry       │  │
│  │  Management     │◄────►│  Service        │◄────►│  Integration    │  │
│  │                 │      │                 │      │                 │  │
│  └─────────────────┘      └─────────────────┘      └─────────────────┘  │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

Core Components

The framework consists of several integrated components:

  • Signature Generation: Creates cryptographic signatures for image content

  • Policy Management: Defines and enforces rules for image signing and verification

  • Verification Engine: Validates signatures and enforces policies at runtime

  • Key Management: Secures signing keys with robust access controls

  • Notary v2 Service: Next-generation trusted content service

  • Registry Integration: Connects with Docker Hub and private registries

Notary v2 Architecture

Enhanced performance: Optimized for large-scale container environments

Simplified key management: Improved user experience for key operations

OCI compatibility: Direct integration with OCI distribution specification

Transparency logs: Immutable audit trails for signature operations

Getting Started with Content Trust 2.0

Prerequisites

Enabling Content Trust 2.0

Enable Content Trust 2.0 for your Docker environment:

Global Configuration
Persistent Setup
# Enable Content Trust globally
export DOCKER_CONTENT_TRUST=1
export DOCKER_CONTENT_TRUST_VERSION=2

# Configure Content Trust 2.0 specific settings
docker trust config --version=2

Initializing Trust for a Repository

Before pushing signed images, initialize trust for your repository:

# Initialize trust for a repository
docker trust init --version=2 myregistry.example.com/myorg/myapp

# Generate and add signing keys
docker trust signer add --key key.pem developer myregistry.example.com/myorg/myapp

Image Signing and Verification

Signing Images

Sign container images to establish their provenance and authenticity:

# Build and sign an image in one step
docker build -t myregistry.example.com/myorg/myapp:v1.0 .
docker push myregistry.example.com/myorg/myapp:v1.0

# Sign an existing image
docker trust sign myregistry.example.com/myorg/myapp:v1.0

Verification Process

When Content Trust 2.0 is enabled, Docker automatically verifies images during pulls:

# Pull a signed image with verification
docker pull myregistry.example.com/myorg/myapp:v1.0

# Explicitly verify an image's signatures
docker trust inspect --pretty myregistry.example.com/myorg/myapp:v1.0

Example verification output:

Signatures for myregistry.example.com/myorg/myapp:v1.0

SIGNED TAG          DIGEST                                                             SIGNERS
v1.0                394b5fe637171d7221c3145b9f3493825e6745ef9bcf35068cb63f35b113f180   developer

Administrative keys for myregistry.example.com/myorg/myapp:v1.0

  Repository Key:   8f87059c69514475a3c2f9093d8a9b194f30fd7e292e1e6732d30d53fca9949f
  Root Key:         cb8642898d4e29aa83b5ecf3ebbb4b9f18ce8641c9ae7b3c2309cd5e692b7b32

Working with Multiple Signers

Implement multiple signers for enhanced security and separation of duties:

# Add multiple signers to a repository
docker trust signer add --key dev.pem developer myregistry.example.com/myorg/myapp
docker trust signer add --key qa.pem qa-team myregistry.example.com/myorg/myapp
docker trust signer add --key security.pem security-team myregistry.example.com/myorg/myapp

# Sign with a specific key
docker trust sign --key dev.pem myregistry.example.com/myorg/myapp:v1.0

Advanced Trust Configurations

Hardware Security Modules

Integrate hardware security modules (HSMs) for enterprise-grade key protection:

# Configure Docker to use a PKCS#11 HSM
export DOCKER_CONTENT_TRUST_HSM=1
export DOCKER_CONTENT_TRUST_HSM_PROVIDER=pkcs11
export DOCKER_CONTENT_TRUST_HSM_MODULE=/usr/lib/libsofthsm2.so
export DOCKER_CONTENT_TRUST_HSM_TOKEN_LABEL="Docker Content Trust"
export DOCKER_CONTENT_TRUST_HSM_PIN=1234

# Generate keys on HSM
docker trust key generate --hsm my-key

Delegation Hierarchies

Create sophisticated delegation hierarchies for complex organizational requirements:

# Create a delegation hierarchy
docker trust delegation add --key targets/releases.key releases myregistry.example.com/myorg/myapp
docker trust delegation add --key targets/releases/qa.key qa myregistry.example.com/myorg/myapp --path "v*.0"
docker trust delegation add --key targets/releases/prod.key production myregistry.example.com/myorg/myapp --path "v*.*"

Threshold Signatures

Configure threshold signatures requiring multiple approvals:

# Set up threshold signatures (requires 2 of 3 signers)
docker trust delegation add --key key1.pem --key key2.pem --key key3.pem --threshold 2 release-managers myregistry.example.com/myorg/myapp

Policy Management

Creating Trust Policies

Define comprehensive trust policies to enforce security requirements:

version: "2.0"
trust:
  repositories:
    "myregistry.example.com/myorg/*":
      requireSignatures: true
      signers:
        - role: security-team
          required: true
        - role: developer
          required: true
      thresholds:
        release-managers: 2
      allow:
        paths:
          - "v*.*.*"
        expires: 15d

Enforcing Policies with Docker

Integrate policies with Docker clients and servers:

# Apply a trust policy
docker trust policy apply --file policy.yaml

# Validate an image against policies
docker trust policy validate myregistry.example.com/myorg/myapp:v1.0

CI/CD Integration

Incorporate Content Trust 2.0 into your CI/CD pipelines:

# Example GitHub Actions workflow
name: Build and Sign Container

on:
  push:
    branches: [ main ]

jobs:
  build-and-sign:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v2
      
      - name: Login to registry
        uses: docker/login-action@v2
        with:
          registry: myregistry.example.com
          username: ${{ secrets.REGISTRY_USERNAME }}
          password: ${{ secrets.REGISTRY_PASSWORD }}
      
      - name: Import signing keys
        run: |
          echo "${{ secrets.DOCKER_CONTENT_TRUST_PRIVATE_KEY }}" > signing-key.pem
          echo "${{ secrets.DOCKER_CONTENT_TRUST_PRIVATE_KEY_PASSPHRASE }}" > passphrase.txt
      
      - name: Build and sign image
        env:
          DOCKER_CONTENT_TRUST: 1
          DOCKER_CONTENT_TRUST_VERSION: 2
        run: |
          export DOCKER_CONTENT_TRUST_PRIVATE_KEY="$(pwd)/signing-key.pem"
          export DOCKER_CONTENT_TRUST_PASSPHRASE="$(cat passphrase.txt)"
          docker build -t myregistry.example.com/myorg/myapp:${{ github.sha }} .
          docker push myregistry.example.com/myorg/myapp:${{ github.sha }}

Notary v2 Integration

Setting Up Notary v2

Deploy a Notary v2 server for enhanced signature management:

# Run Notary v2 server
docker run -d --name notary-v2 \
  -p 4443:4443 \
  -v notary-data:/var/lib/notary \
  docker/notary-server-v2:latest

# Configure Docker to use custom Notary v2 server
export DOCKER_CONTENT_TRUST_SERVER=https://notary-v2.example.com:4443

Custom Certificate Authorities

Configure custom certificate authorities for Notary v2:

# Add custom CA certificate
mkdir -p ~/.docker/tls/notary-v2.example.com
cp ca.crt ~/.docker/tls/notary-v2.example.com/ca.crt

# Use custom CA for verification
docker trust inspect --tls-ca-cert ~/.docker/tls/ca.crt myregistry.example.com/myorg/myapp:v1.0

Automating Security Scanning

Integrating Vulnerability Scanning

Combine Content Trust 2.0 with vulnerability scanning for comprehensive security:

# Scan and sign workflow
docker scan myregistry.example.com/myorg/myapp:v1.0 --severity high
if [ $? -eq 0 ]; then
  docker trust sign myregistry.example.com/myorg/myapp:v1.0
else
  echo "Vulnerabilities found, image will not be signed"
  exit 1
fi

Automated Policy Enforcement

Implement automated policy enforcement in deployment pipelines:

# Example Kubernetes admission controller configuration
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
  name: image-verification-webhook
webhooks:
  - name: verify.images.example.com
    clientConfig:
      service:
        name: image-verifier
        namespace: security
        path: "/validate"
      caBundle: "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0t..."
    rules:
      - apiGroups: [""]
        apiVersions: ["v1"]
        operations: ["CREATE", "UPDATE"]
        resources: ["pods"]
    failurePolicy: Fail
    sideEffects: None

Security Considerations

Key Rotation

Implement regular key rotation for enhanced security:

# Generate new repository keys
docker trust key generate new-repo-key

# Rotate keys for a repository
docker trust key rotate --repository myregistry.example.com/myorg/myapp

Compromised Key Handling

Establish procedures for handling compromised keys:

# Revoke a compromised signer key
docker trust signer remove compromised-signer myregistry.example.com/myorg/myapp

# Rotate the repository key after a compromise
docker trust key rotate --repository myregistry.example.com/myorg/myapp

Offline Root Keys

Manage root keys in an offline environment for maximum security:

# Export root key for offline storage
docker trust key export --root

# Store the key material in a secure offline location
# (e.g., HSM, offline secure storage, etc.)

Operational Best Practices

Monitoring and Auditing

Implement comprehensive monitoring and auditing for Content Trust operations:

  1. Signature logs: Track all signature creation and verification events
  2. Policy enforcement: Monitor policy violations and enforcement actions
  3. Key usage: Audit key operations for abnormal patterns
  4. Trust metadata: Regularly review trust metadata for inconsistencies

CI/CD Pipeline Integration

Integrate Content Trust 2.0 seamlessly into CI/CD workflows:

  1. Automated signing: Sign images automatically after successful builds
  2. Verification gates: Block deployments of unsigned or improperly signed images
  3. Policy checks: Validate images against organizational policies before deployment
  4. Transparency logs: Record all signature operations in immutable audit logs

Disaster Recovery

Establish robust disaster recovery procedures:

  1. Key backup: Securely back up all signing keys
  2. Recovery procedures: Document step-by-step recovery processes
  3. Testing: Regularly test key recovery procedures
  4. Emergency access: Implement break-glass procedures for emergencies

Enterprise Implementation Strategies

Phased Rollout Approach

Implement Content Trust 2.0 using a phased approach:

  1. Discovery phase: Identify critical images and repositories
  2. Pilot implementation: Start with non-critical systems
  3. Policy development: Create tailored policies for your organization
  4. Training and documentation: Prepare teams for the new processes
  5. Production rollout: Gradually expand to production systems
  6. Continuous improvement: Refine policies and procedures based on feedback

Organizational Policies

Develop comprehensive organizational policies:

  1. Signing requirements: Define which images require signatures
  2. Signer roles: Establish clear roles and responsibilities
  3. Key management: Document procedures for key lifecycle management
  4. Verification requirements: Specify when and how images must be verified
  5. Exception handling: Create processes for handling exceptions

Conclusion

Docker Content Trust 2.0 represents a significant advancement in container supply chain security. By implementing robust signature verification, integrating with Notary v2, and supporting advanced features like hardware security modules and policy enforcement, organizations can create secure, compliant container ecosystems.

Enhanced Security Posture

Cryptographic verification of image authenticity

Supply Chain Integrity

Protection against tampering and unauthorized modifications

Regulatory Compliance

Support for stringent security requirements

Operational Resilience

Robust key management and disaster recovery

Integration Flexibility

Seamless incorporation into existing workflows

Edit this page
Docker GPU Acceleration Framework
Comprehensive guide to Docker's GPU acceleration capabilities for high-performance computing, AI/ML workloads, and multi-vendor hardware support
Docker Cache Management
Understanding and optimizing Docker's cache system for faster builds