LabEx
Log InJoin Free

How to verify the SSL certificate used by a Docker registry

DockerBeginner
Practice Now

Introduction

Securing your Docker environment is crucial, and verifying the SSL certificate used by your Docker registry is an essential step in maintaining this security. This tutorial will guide you through the process of verifying SSL certificates for Docker registries, helping you ensure secure communication and troubleshoot any SSL certificate-related issues.

By the end of this lab, you will understand how Docker uses SSL certificates, be able to inspect and verify certificates used by Docker registries, and know how to handle common certificate issues.

Understanding Docker Registry SSL Certificates

Docker registries are repositories where Docker images are stored and distributed. These registries use SSL/TLS certificates to secure the communication between your Docker client and the registry server. Let's understand what these certificates are and why they matter.

What is an SSL/TLS Certificate?

An SSL/TLS certificate is a digital document that:

  • Establishes a secure connection between a client and a server
  • Encrypts data transmitted between them
  • Verifies the identity of the server

When you connect to a Docker registry, your Docker client checks the registry's SSL certificate to ensure the connection is secure and that you're connecting to the legitimate registry.

Examining Certificate Information with OpenSSL

Let's start by exploring how to check certificate information using OpenSSL, a powerful tool for working with SSL certificates.

First, let's create a directory for our lab work:

mkdir -p ~/project/ssl-lab
cd ~/project/ssl-lab

Now, let's check the SSL certificate for Docker Hub, which is a common Docker registry:

openssl s_client -connect hub.docker.com:443 -showcerts < /dev/null

This command connects to Docker Hub and displays information about its SSL certificate. You should see a lot of information in the output, including:

  • The certificate chain
  • Issuer information
  • Certificate validity dates
  • The public key

Let's extract just the certificate information in a more readable format:

echo | openssl s_client -connect hub.docker.com:443 2> /dev/null | openssl x509 -text -noout | head -20

This command shows the first 20 lines of the certificate details, which include important information like:

  • Version
  • Serial Number
  • Signature Algorithm
  • Issuer (the Certificate Authority)
  • Validity period
  • Subject (who the certificate belongs to)

Understanding this information is the first step in verifying a certificate's authenticity.

Verifying Registry SSL Certificates with Docker CLI

Now that we understand the basics of SSL certificates, let's learn how to verify certificates specifically for Docker registries using the Docker CLI.

Using docker info to Check Registry Configuration

The Docker CLI provides tools to examine registry configurations, including their certificate settings.

Let's check the current registry configurations that Docker is aware of:

docker info --format '{{json .RegistryConfig.IndexConfigs}}' | python3 -m json.tool

This command outputs the configuration details for all registries the Docker daemon knows about, formatted in a readable JSON structure. You'll notice that Docker Hub (at index.docker.io) is configured by default.

Testing a Connection to a Registry

Let's try connecting to Docker Hub to verify its certificate:

docker login

When prompted, you can press Ctrl+C to cancel the login since we're just testing the connection, not actually logging in.

The Docker client automatically verifies the registry's SSL certificate during the login process. If the certificate is valid, you'll see the login prompt. If not, Docker would display an error message.

Creating a File to Check a Specific Registry

Let's create a script to check the certificate for a specific registry more thoroughly:

cat > check_registry_cert.sh << 'EOF'
#!/bin/bash

REGISTRY=${1:-"hub.docker.com"}
PORT=${2:-"443"}

echo "Checking certificate for $REGISTRY:$PORT..."
echo | openssl s_client -connect $REGISTRY:$PORT 2>/dev/null | openssl x509 -noout -dates -issuer -subject

echo -e "\nVerifying certificate chain..."
openssl s_client -connect $REGISTRY:$PORT -showcerts </dev/null 2>/dev/null | grep -A 1 "Certificate chain"
EOF

Now make the script executable:

chmod +x check_registry_cert.sh

Let's run it to check Docker Hub's certificate:

./check_registry_cert.sh

You should see output showing:

  • When the certificate was issued and when it expires
  • Who issued the certificate
  • Who the certificate belongs to
  • Information about the certificate chain

Let's also check the certificate for another registry, Microsoft's container registry:

./check_registry_cert.sh mcr.microsoft.com

Compare the outputs to see how certificates can differ between registries.

Troubleshooting SSL Certificate Issues

Even with a proper verification process, you may encounter SSL certificate issues when working with Docker registries. Let's learn how to identify and resolve the most common problems.

Common SSL Certificate Problems

The most frequent SSL certificate issues include:

  1. Self-signed certificates
  2. Expired certificates
  3. Certificate hostname mismatches
  4. Untrusted certificate authorities

Let's create a directory to simulate and troubleshoot these problems:

mkdir -p ~/project/ssl-lab/troubleshooting
cd ~/project/ssl-lab/troubleshooting

Creating a Test Self-Signed Certificate

First, let's create a self-signed certificate to understand how to handle them:

openssl req -newkey rsa:2048 -nodes -keyout registry.key -x509 -days 365 -out registry.crt -subj "/CN=registry.example.com"

This command creates:

  • A private key (registry.key)
  • A self-signed certificate (registry.crt) valid for 365 days

Let's examine our self-signed certificate:

openssl x509 -in registry.crt -text -noout | grep -E "Issuer|Subject|Not"

Notice that in a self-signed certificate, the Issuer and Subject are the same, as the certificate signed itself.

Configuring Docker to Trust a Self-Signed Certificate

To make Docker trust a self-signed certificate, you would typically add it to the Docker certificates directory. Let's create the necessary directory structure:

sudo mkdir -p /etc/docker/certs.d/registry.example.com:5000
sudo cp registry.crt /etc/docker/certs.d/registry.example.com:5000/ca.crt

After adding a certificate, you would normally restart Docker:

## We won't actually restart Docker in this lab
echo "In a real environment, you would run: sudo systemctl restart docker"

Handling Expired Certificates

Let's simulate checking an expired certificate by creating one with a past expiration date:

openssl req -newkey rsa:2048 -nodes -keyout expired.key -x509 -days -30 -out expired.crt -subj "/CN=expired.example.com"

Now let's examine the expired certificate:

openssl x509 -in expired.crt -text -noout | grep -E "Issuer|Subject|Not"

You'll see that the "Not After" date is in the past, which means the certificate is expired.

Configuring Insecure Registries

In some cases, you might need to use registries with certificate issues. Docker allows you to mark specific registries as "insecure":

cat > daemon.json << 'EOF'
{
  "insecure-registries": [
    "registry.example.com:5000",
    "expired.example.com:5000"
  ]
}
EOF

echo "In a real environment, you would place this file at /etc/docker/daemon.json"
cat daemon.json

This configuration tells Docker to skip certificate verification for these registries, which can be useful for testing environments but should be avoided in production.

Script to Check Certificate Expiration

Let's create a useful script to check if a certificate is about to expire:

cat > check_expiration.sh << 'EOF'
#!/bin/bash

CERT_FILE=$1
DAYS_WARNING=${2:-30}

if [ ! -f "$CERT_FILE" ]; then
    echo "Certificate file not found: $CERT_FILE"
    exit 1
fi

## Get expiration date in seconds since epoch
EXPIRY=$(openssl x509 -in "$CERT_FILE" -noout -enddate | cut -d= -f2)
EXPIRY_SECONDS=$(date -d "$EXPIRY" +%s)
NOW_SECONDS=$(date +%s)
SECONDS_LEFT=$((EXPIRY_SECONDS - NOW_SECONDS))
DAYS_LEFT=$((SECONDS_LEFT / 86400))

echo "Certificate: $CERT_FILE"
echo "Expires on: $EXPIRY"
echo "Days remaining: $DAYS_LEFT"

if [ $DAYS_LEFT -lt 0 ]; then
    echo "CRITICAL: Certificate has EXPIRED!"
    exit 2
elif [ $DAYS_LEFT -lt $DAYS_WARNING ]; then
    echo "WARNING: Certificate will expire in less than $DAYS_WARNING days!"
    exit 1
else
    echo "OK: Certificate is valid for more than $DAYS_WARNING days."
    exit 0
fi
EOF

chmod +x check_expiration.sh

Let's test our script with both certificates:

./check_expiration.sh registry.crt
./check_expiration.sh expired.crt

You'll see that the script correctly identifies the valid certificate and the expired one.

Best Practices for Docker Registry SSL Certificates

Now that we understand how to verify and troubleshoot SSL certificates, let's explore best practices for managing certificates with Docker registries.

Automating Certificate Verification

It's essential to regularly verify your certificates to prevent unexpected failures. Let's create a script that can be scheduled to run periodically:

cd ~/project/ssl-lab
cat > monitor_registry_certs.sh << 'EOF'
#!/bin/bash

## List of registries to check
REGISTRIES=(
  "hub.docker.com"
  "mcr.microsoft.com"
  "registry.k8s.io"
  "quay.io"
)

echo "========================================"
echo "Docker Registry Certificate Monitor"
echo "========================================"
echo "Date: $(date)"
echo ""

for registry in "${REGISTRIES[@]}"; do
  echo "Checking $registry..."
  CERT_INFO=$(echo | openssl s_client -connect $registry:443 2>/dev/null | openssl x509 -noout -dates -issuer -subject 2>/dev/null)
  
  if [ -z "$CERT_INFO" ]; then
    echo "ERROR: Could not retrieve certificate for $registry"
  else
    echo "$CERT_INFO"
    
    ## Extract expiry date
    EXPIRY=$(echo "$CERT_INFO" | grep "notAfter" | cut -d= -f2)
    EXPIRY_SECONDS=$(date -d "$EXPIRY" +%s)
    NOW_SECONDS=$(date +%s)
    DAYS_LEFT=$(( (EXPIRY_SECONDS - NOW_SECONDS) / 86400 ))
    
    echo "Days until expiry: $DAYS_LEFT"
    
    if [ $DAYS_LEFT -lt 30 ]; then
      echo "WARNING: Certificate will expire in less than 30 days!"
    fi
  fi
  echo "----------------------------------------"
done
EOF

chmod +x monitor_registry_certs.sh

Let's run the script to see how it works:

./monitor_registry_certs.sh

This script checks multiple registries and warns you if any certificates are nearing expiration, which is crucial for preventing unexpected downtime.

Certificate Management Best Practices

Let's create a document outlining best practices for Docker registry certificate management:

cat > certificate_best_practices.md << 'EOF'
## Docker Registry Certificate Management Best Practices

### Certificate Procurement
- Use certificates from trusted Certificate Authorities for production environments
- Use appropriate certificate types (DV, OV, or EV based on needs)
- Ensure certificates match the exact domain names used to access registries
- Consider wildcard certificates for multiple subdomains
- Use appropriate key lengths (minimum 2048 bits for RSA)

### Certificate Deployment
- Store certificates securely
- Use proper file permissions (readable only by the Docker daemon)
- Back up certificates and private keys securely
- Implement proper certificate rotation procedures
- Keep certificate paths consistent across all nodes in a cluster

### Monitoring and Maintenance
- Set up alerts for certificates nearing expiration (at least 30 days in advance)
- Maintain an inventory of all certificates in use
- Document renewal procedures
- Test certificate renewals in a staging environment before production
- Automate certificate renewal where possible (using tools like certbot)

### Security Considerations
- Never use insecure registries in production environments
- Avoid using self-signed certificates in production
- Implement proper certificate revocation procedures
- Regularly audit certificate usage and permissions
- Keep the CA bundle updated on all systems
EOF

cat certificate_best_practices.md

Creating a Configuration Template for Secure Registries

Finally, let's create a template for a secure Docker registry configuration:

cat > secure_registry_config.yml << 'EOF'
version: '3'

services:
  registry:
    image: registry:2
    ports:
      - 5000:5000
    environment:
      REGISTRY_HTTP_TLS_CERTIFICATE: /certs/domain.crt
      REGISTRY_HTTP_TLS_KEY: /certs/domain.key
      ## Additional security settings
      REGISTRY_STORAGE_DELETE_ENABLED: "true"
      REGISTRY_HTTP_HEADERS_X_CONTENT_TYPE_OPTIONS: nosniff
      REGISTRY_HTTP_HEADERS_X_FRAME_OPTIONS: DENY
    volumes:
      - ./certs:/certs
      - ./data:/var/lib/registry
    restart: always
    
  ## Optional: Add a UI for your registry
  registry-ui:
    image: joxit/docker-registry-ui:latest
    ports:
      - 8080:80
    environment:
      - REGISTRY_URL=https://registry:5000
      - REGISTRY_TITLE=Secure Docker Registry
      - SINGLE_REGISTRY=true
    depends_on:
      - registry
EOF

cat secure_registry_config.yml

This configuration provides a template for running a secure Docker registry with proper SSL certificate configuration.

Summary of SSL Certificate Management Steps

Let's create a quick reference for SSL certificate management with Docker:

cat > ssl_management_summary.txt << 'EOF'
## Docker Registry SSL Certificate Management Summary

1. VERIFY a registry's certificate:
   openssl s_client -connect registry.example.com:443 -showcerts </dev/null

2. ADD a custom certificate for a registry:
   sudo mkdir -p /etc/docker/certs.d/registry.example.com:5000
   sudo cp registry.crt /etc/docker/certs.d/registry.example.com:5000/ca.crt
   sudo systemctl restart docker

3. CONFIGURE an insecure registry (development only):
   Add to /etc/docker/daemon.json:
   { "insecure-registries": ["registry.example.com:5000"] }
   sudo systemctl restart docker

4. CHECK expiration dates regularly:
   openssl x509 -in certificate.crt -noout -dates

5. AUTOMATE certificate monitoring:
   Create and schedule scripts to check certificates regularly
EOF

cat ssl_management_summary.txt

This summary serves as a quick reference for the most common operations related to Docker registry SSL certificates.

Summary

In this lab, you learned how to verify and manage SSL certificates for Docker registries. You now have the knowledge and tools to:

  • Understand what SSL certificates are and why they are essential for Docker registry security
  • Verify SSL certificates using OpenSSL and Docker CLI commands
  • Troubleshoot common certificate issues like expired certificates and self-signed certificates
  • Implement best practices for certificate management
  • Configure Docker to work with various certificate scenarios
  • Automate certificate monitoring to prevent unexpected failures

These skills are crucial for maintaining secure Docker environments, especially in production settings where security is paramount. By regularly verifying and properly managing your Docker registry SSL certificates, you can prevent security vulnerabilities and ensure smooth operations for your containerized applications.

Related Docker Courses
Docker for Beginners

Docker for Beginners

dockerdevops
Docker Practice Challenges

Docker Practice Challenges

dockerdevops
Docker Practice Labs

Docker Practice Labs

dockerdevops