SoFunction
Updated on 2025-04-08

Nginx SSL configuration error problem and solution

Detailed explanation of Nginx SSL configuration errors

In today's Internet environment, SSL (Secure Sockets Layer) and its successor TLS (Transport Layer Security) have become important protocols to ensure the security of web applications. As a high-performance web server, Nginx is widely used in the configuration and management of HTTPS (i.e. HTTP over SSL/TLS) protocol. Configure SSL/TLS to encrypt communication between clients and servers, ensuring data confidentiality, integrity, and authentication.

However, in actual use, Nginx's SSL configuration may encounter various errors that can cause the website to fail to enable HTTPS or make the connection unsafe. Therefore, understanding common causes of SSL configuration errors and how to troubleshoot and resolve these issues is essential to ensuring the security of your web applications.

1. Basic requirements for Nginx SSL configuration

Before discussing common SSL configuration errors, let’s review the basic steps required for Nginx to properly configure SSL.

1.1 Installing SSL Certificate

In order to enable SSL, you first need to obtain a valid SSL certificate. This certificate can be obtained in the following ways:

  • Purchase a commercial certificate from a trusted certificate authority (CA).
  • Generate free certificates using free certificate authorities such as Let’s Encrypt.

An SSL certificate is usually composed of the following parts:

  • Certificate File (): Contains the public key and information about the certificate.
  • Private key file (): The private key paired with the public key must be kept confidential.
  • Certificate chain (): Contains intermediate certificates and root certificates to verify the credibility of the certificate.

1.2 Configuring Nginx to use SSL

Once the SSL certificate and private key file are obtained, SSL can be enabled in the Nginx configuration.

A basic SSL configuration looks like this:

server {
    listen 443 ssl;
    server_name ;

    ssl_certificate /etc/nginx/ssl/;
    ssl_certificate_key /etc/nginx/ssl/;
    ssl_trusted_certificate /etc/nginx/ssl/;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256';
    ssl_prefer_server_ciphers on;

    location / {
        root /var/www/html;
        index ;
    }
}
  • listen 443 ssl;: Specify Nginx listens to port 443 and enable SSL.
  • ssl_certificate: Specify the path to the certificate file.
  • ssl_certificate_key: Specify the path to the private key file.
  • ssl_protocols: Specifies the allowed SSL/TLS protocol version.
  • ssl_ciphers: Specify the supported encryption suite.

2. Common Nginx SSL configuration errors and solutions

When actually configuring SSL for Nginx, you may encounter various errors. Here are some common Nginx SSL configuration errors and their solutions:

2.1 SSL certificate and private key mismatch

Error description:

When Nginx starts, the following error message may appear:

nginx: [emerg] PEM_read_bio_X509_AUX("/etc/nginx/ssl/") failed
nginx: [emerg] SSL_CTX_use_certificate_chain_file("/etc/nginx/ssl/") failed

This error is usually caused by the SSL certificate and private key file that does not match, causing Nginx to fail to load the certificate.

Solution:

Make sure that you specify in the Nginx configurationssl_certificateandssl_certificate_keyThe files are paired and do contain the correct certificate and private key.

For example,It's a certificate file,It is the private key file to pair with it.

1. Check whether the certificate file and the private key file match:

Use the following command to check if the certificate and private key match:

openssl x509 -noout -modulus -in /etc/nginx/ssl/ | openssl md5
openssl rsa -noout -modulus -in /etc/nginx/ssl/ | openssl md5

If the output of these two commands is different, it means that the certificate and private key do not match.

2. Make sure that the private key and certificate belong to the same pair. If they do not match, you need to regenerate the certificate and private key, or contact the certificate authority to obtain the correct pairing file.

2.2 Protocol version error in SSL configuration

Error description:

Nginx has SSL configured, but the following error occurs:

SSL routines:ssl3_get_record:wrong version number

This error is usually due to the incompatible version of the SSL/TLS protocol configured by Nginx or the disable certain protocols.

Solution:

examinessl_protocolsConfiguration Items to ensure that the appropriate protocol version is enabled. TLS 1.2 and TLS 1.3 are recommended because they provide greater security.

ssl_protocols TLSv1.2 TLSv1.3;

Enabling older SSL/TLS protocol versions such as SSLv3 and TLSv1.0 is not recommended because they have been considered insecure.

2.3 Intermediate certificate (Chain) not configured

Error description:

If the certificate chain is not configured correctly, the browser may experience the following error:

ERR_SSL_PROTOCOL_ERROR

or:

SSL certificate problem: unable to get local issuer certificate

This error usually indicates that the Nginx-configured SSL certificate chain is incomplete, causing the client to be unable to verify the credibility of the certificate.

Solution:

Ensure the certificate chain file (ssl_certificateandssl_trusted_certificate) Correct configuration. The certificate chain file should contain all intermediate certificates and root certificates and together with the main certificate form a complete certificate chain.

ssl_certificate /etc/nginx/ssl/;
ssl_certificate_key /etc/nginx/ssl/;
ssl_trusted_certificate /etc/nginx/ssl/;
  • ssl_certificate: Specify the server certificate (main certificate).
  • ssl_trusted_certificate: Specify the certificate chain file, including intermediate certificates and root certificates.

If there is no separate certificate chain file, you can merge the certificate and chain into one file, asssl_certificatepath.

2.4 Incorrect encryption suite configuration

Error description:

When configuring SSL, the following error occurs:

nginx: [emerg] invalid cipher suite "ECDHE-RSA-AES128-GCM-SHA256"

This error usually occurs when an invalid encryption suite is configured, or if Nginx does not support the specified encryption algorithm.

Solution:

make suressl_ciphersThe encryption suite in the configuration item complies with modern encryption standards and is an encryption suite supported by Nginx. For example:

ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256';

You can refer to modern encryption kit recommendations, such asMozilla SSL Configuration Generatorto generate a secure encryption suite.

2.5 Insecure SSL configuration

Error description:

Nginx is configured with SSL, but there may still be security vulnerabilities due to improper configuration.

For example, using an insecure encryption suite or not supporting the latest protocol version makes SSL/TLS connections vulnerable.

Solution:

Here are some recommended SSL configurations to enhance Nginx security:

ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256';
ssl_prefer_server_ciphers on;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 10m;
  • ssl_protocols: Only modern TLS protocol versions are enabled.
  • ssl_ciphers: Use a secure encryption suite.
  • ssl_prefer_server_ciphers: Prioritize the use of server encryption suite.
  • ssl_session_cache: Enable SSL session caching to improve performance.
  • ssl_session_timeout: Set the session timeout time.

In addition, enableHTTP Strict Transport Security (HSTS)It is also an effective way to improve safety:

add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;

2.6 Prevent malicious SSL attacks (such as POODLE, BEAST)

To prevent known SSL/TLS attacks (such as POODLE, BEAST, etc.), ensure that outdated protocols and encryption algorithms are disabled.

The following configurations prevent these attacks:

ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers on;
ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256';
  • Disable SSLv3 and TLSv1.0.
  • Enable the latest TLS version and strong encryption suite.

3. SSL configuration optimization and performance

In addition to ensuring that SSL is configured correctly, performance optimization is required to avoid excessive latency caused by the SSL handshake. Here are some common optimization strategies:

3.1 Enable OCSP Stapling

OCSP Stapling (Online Certificate Status Protocol) reduces SSL handshake time and improves performance.

When OCSP Stapling is enabled, Nginx "pin" the certificate's status information (provided by the certificate authority) to the certificate, thus avoiding status queries every time you shake hands.

ssl_stapling on;
ssl_stapling_verify on;

3.2 Enable Session Resumption

Enable session recovery can reduce the overhead of repeated SSL handshakes. Through session recovery, clients and servers can reuse already established SSL sessions, reducing handshake time.

ssl_session_cache shared:SSL:10m;
ssl_session_timeout 10m;

4. Summary

Nginx's SSL configuration can cause errors for a number of reasons, from a certificate that does not match the private key to a protocol version configuration error. By understanding common configuration errors and their solutions, developers and operation staff can better configure Nginx's SSL, so that web applications can provide better performance while ensuring security.

Ensure that SSL/TLS configurations comply with modern security standards and avoid outdated protocols and weak encryption algorithms. Nginx's SSL performance can be significantly improved by placing the encryption suite rationally, enabling OCSP Stapling, and session recovery.

The above is personal experience. I hope you can give you a reference and I hope you can support me more.