Learn how to fix “x509: certificate relies on legacy Common Name field, use SANs instead” error. Our Docker Support team is here to help you with your questions and concerns.

“x509: certificate relies on legacy Common Name field, use SANs instead” Error

Have you encountered the following error message in SSL/TLS communications?

x509: certificate relies on legacy Common Name field, use SANs instead

This indicates that Docker cannot validate the certificate due to the absence of SANs.

This error occurs when Docker or other software encounters a certificate using the deprecated Common Name (CN) field for server identification, instead of the modern and secure Subject Alternative Names (SANs).

SSL/TLS certificates are essential for secure communications over the internet.

• x509 Certificate:

  A standard format for public key infrastructure (PKI) used in SSL/TLS. It includes details about the server’s identity, public key, and the issuing Certificate Authority (CA).
• Common Name (CN):

  Historically, the CN field was used to specify the server’s fully qualified domain name (FQDN), such as `www.example.com`.
• Subject Alternative Name (SAN):

  SAN is an extension to the x509 specification that supports multiple domain names or IP addresses in a certificate, making it the modern standard for domain identification.

Why the Common Name Field Is Deprecated

Over time, the Common Name field has been deprecated for the following reasons:

• The CN field lacks the flexibility and security needed for robust server identity validation.
• Unlike CN, SAN allows specifying multiple domains (e.g., `example.com` and `www.example.com`) or IP addresses in a single certificate.

As a result, modern SSL/TLS implementations, including those in Docker, enforce using SANs for domain validation. Certificates relying solely on CN may trigger compatibility issues.

Why the Error Occurs in Docker?

This error is commonly seen in Docker environments when:

• A certificate uses only the deprecated Common Name field to identify the server.
• Docker, or its underlying SSL library, requires certificates to include SANs for proper validation.

How to Fix the Issue

To resolve the error, ensure the SSL/TLS certificates include the SAN extension. Here’s how:

1. First, generate a new certificate with SANs. We can use tools like OpenSSL to include SANs in our certificate configuration.
2. Use a Certificate Authority that supports SANs. Most modern CAs, including Let’s Encrypt, automatically include SANs in issued certificates.
3. Then, regenerate Self-Signed Certificates. If we use self-signed certificates, we can regenerate them with SANs to meet modern standards.
4. After generating or updating the certificate, confirm it includes SANs using OpenSSL:

   openssl x509 -in mydomain.crt -text -noout

   Look for the X509v3 Subject Alternative Name section in the output.
5. Next, ensure Docker uses the updated certificate by placing it in the appropriate directory. Finally, restart Docker to apply the changes.

[Need assistance with a different issue? Our team is available 24/7.]

Conclusion

The “x509 certificate relies on legacy Common Name field” error highlights the importance of modern SSL/TLS practices. By ensuring our certificates include SANs, we can avoid compatibility issues and maintain secure communications in Docker and other environments.

In brief, our Support Experts demonstrated how to fix the “x509: certificate relies on legacy Common Name field, use SANs instead” error.