Technical Analysis and Solutions for SSL Self-Signed Certificate Chain Error in Docker Containers

Problem Phenomenon and Initial Analysis

In Linux-based Docker container environments, attempting to access HTTPS endpoints using curl often results in the following error message:

curl: (60) SSL certificate problem: self signed certificate in certificate chain

This error is not specific to particular websites (such as Google) but affects all HTTPS connections. The core issue lies in SSL/TLS certificate verification failure, specifically the presence of self-signed certificates in the certificate chain.

Certificate Chain Validation Mechanism

Modern TLS/SSL connections rely on certificate chain validation mechanisms to ensure communication security. When a client (such as curl) connects to an HTTPS server, the server provides its digital certificate along with intermediate certificates forming the trust chain. The client must verify:

1. Whether the certificate is issued by a trusted Certificate Authority (CA)
2. Whether the certificate chain is complete and valid
3. Whether the certificate is within its validity period
4. Whether the domain name in the certificate matches the accessed domain

Analyzing the certificate chain using openssl reveals the nature of the problem:

openssl s_client -showcerts -connect www.google.com:443

The output shows that the certificate chain includes corporate custom CA certificates (such as MyCompanyServer in the example), indicating the presence of man-in-the-middle proxies in the network for monitoring or decrypting TLS traffic. This configuration is common in enterprise environments but requires clients to trust the corporate CA certificates.

Root Cause Identification

The fundamental cause of the error is the lack of proper CA certificate configuration in Docker containers. Specific manifestations include:

• Container images may not contain complete CA certificate bundles
• Corporate custom CA certificates are not correctly installed in the container's trust store
• Certificate update mechanisms fail in container environments

When curl attempts to verify the server certificate, it finds self-signed certificates (corporate CA certificates) in the certificate chain that are not in the container's trusted CA list, causing verification failure.

Solution 1: Certificate Installation Within Container

For containers that need to run long-term, it is recommended to install complete CA certificate bundles within the container. Specific steps are as follows:

1. Install the ca-certificates package (package name may vary depending on Linux distribution)
2. Copy corporate CA certificates to the system certificate directory
3. Update the system CA certificate cache

Taking Debian/Ubuntu systems as an example:

# Install CA certificate package
apt-get update && apt-get install -y ca-certificates

# Copy corporate CA certificate to specified directory
cp company-ca.crt /usr/local/share/ca-certificates/

# Update system CA certificates
update-ca-certificates

After executing the update-ca-certificates command, the system regenerates the CA certificate bundle, including all certificates in the /usr/local/share/ca-certificates/ directory.

Solution 2: Host Certificate Mounting

If the host operating system has correctly configured CA certificates (including corporate CA certificates), they can be shared with containers through Docker volume mounting. This approach avoids repeated certificate installation in each container, improving deployment efficiency.

docker run \
  -v /etc/ssl/certs/ca-certificates.crt:/etc/ssl/certs/ca-certificates.crt \
  your-image

CA certificate file paths vary across different Linux distributions:

• Debian/Ubuntu/Gentoo: /etc/ssl/certs/ca-certificates.crt
• Fedora/RHEL 6: /etc/pki/tls/certs/ca-bundle.crt
• OpenSUSE: /etc/ssl/ca-bundle.pem
• OpenELEC: /etc/pki/tls/cacert.pem
• CentOS/RHEL 7: /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem

Select the correct certificate file path for mounting based on the specific distribution of the host system.

Technical Details of Certificate Verification Process

Understanding the certificate verification process helps in better diagnosing and solving similar problems. When establishing TLS connections, curl performs the following verification steps:

1. Receive certificate chain from server
2. Check validity of end-entity certificate
3. Verify upward along the certificate chain until a trusted root certificate is found
4. If the chain contains self-signed certificates not in the trust list, report an error

Error code 19 (self signed certificate in certificate chain) indicates that the verification process encountered self-signed certificates in the certificate chain that are not trusted by the system. In corporate proxy environments, these self-signed certificates are typically corporate CA certificates that need to be explicitly added to the trust store.

Security Considerations and Best Practices

When implementing solutions, the following security best practices should be considered:

• Only trust legitimate corporate CA certificates, avoid adding certificates from unknown sources
• Regularly update CA certificate bundles to ensure inclusion of the latest root and intermediate certificates
• Explicitly document certificate installation steps in Dockerfile to improve maintainability
• Consider using certificate pinning to enhance security for critical connections

For production environments, it is recommended to create custom base images that already include necessary CA certificate configurations, simplifying deployment and management of subsequent containers.

Troubleshooting and Verification

After implementing solutions, verify whether the configuration is effective using the following methods:

1. Test HTTPS connections using curl: curl https://google.com
2. Check detailed curl output: curl -v https://google.com
3. Verify certificate chain using openssl: openssl s_client -connect www.google.com:443
4. Check if verification return code is 0 (indicating successful verification)

If the problem persists, check:

• Whether certificate file permissions are correct
• Whether certificate format is PEM
• Whether system time is accurate (affects certificate validity verification)
• Whether other network proxy configurations interfere

Conclusion

SSL certificate verification errors in Docker containers typically stem from incomplete CA certificate configurations, especially in corporate network environments. By understanding certificate chain validation mechanisms and TLS handshake processes, the root cause of problems can be accurately diagnosed. The two main solutions—certificate installation within containers and host certificate mounting—each have applicable scenarios and can be selected based on specific needs. Properly configuring CA certificates not only resolves connection issues but also ensures the security and reliability of TLS communications.