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:
- Self-signed certificates
- Expired certificates
- Certificate hostname mismatches
- 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.
