How to install a certificate in nginx

Before you start

• Your server certificate (the leaf certificate) and the CA’s intermediate certificate or certificates, in PEM format.
• The private key you created with the CSR. It never leaves the server; never paste it into a website.
• Root access, and port 443 open in the firewall.
• If you use Let’s Encrypt, certbot can write these files and the configuration for you.

Why it matters: nginx sends exactly the certificates you give it. Leave out the intermediate and most browsers still work, but curl on Linux, Java, Python, Node.js and many phones fail.

Steps

1. Build the full chain file

nginx wants the leaf first, then the intermediates, in one file. The nginx documentation says “the primary certificate comes first, then the intermediate certificates”. Leave the root out: clients must already have it. See how to build the full chain file.

sudo mkdir -p /etc/ssl/example
cat www.example.com.crt intermediate.crt | sudo tee /etc/ssl/example/fullchain.pem > /dev/null
sudo install -m 600 -o root -g root www.example.com.key /etc/ssl/example/privkey.pem

Check the order. Each certificate’s issuer must be the subject of the next one:

openssl crl2pkcs7 -nocrl -certfile /etc/ssl/example/fullchain.pem | openssl pkcs7 -print_certs -noout

subject=CN = intranet.example.com
issuer=C = BE, O = Example Corp, CN = Example Corp Issuing CA 1

subject=C = BE, O = Example Corp, CN = Example Corp Issuing CA 1
issuer=C = BE, O = Example Corp, CN = Example Corp Root CA

2. Check that the key matches the certificate

The two hashes must be identical (key and certificate match):

openssl x509 -in /etc/ssl/example/fullchain.pem -noout -pubkey | openssl sha256
sudo openssl pkey -in /etc/ssl/example/privkey.pem -pubout | openssl sha256

SHA2-256(stdin)= 4831d810716492fe84b3e7885848156700dce2d6c52325f917f7dec47de8ba1c
SHA2-256(stdin)= 4831d810716492fe84b3e7885848156700dce2d6c52325f917f7dec47de8ba1c

openssl x509 reads only the first certificate in the file, which is why the leaf must come first.

3. Configure the server block

On Debian and Ubuntu, create /etc/nginx/sites-available/example.com and link it into sites-enabled; on other systems, use a file in /etc/nginx/conf.d/:

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    server_name www.example.com example.com;

    ssl_certificate     /etc/ssl/example/fullchain.pem;
    ssl_certificate_key /etc/ssl/example/privkey.pem;
    ssl_protocols       TLSv1.2 TLSv1.3;

    root /var/www/example;
}

server {
    listen 80;
    listen [::]:80;
    server_name www.example.com example.com;
    return 301 https://$host$request_uri;
}

ssl_protocols TLSv1.2 TLSv1.3 is the default since nginx 1.27.3, but older packages still enable TLS 1.0 and 1.1: Ubuntu 24.04’s /etc/nginx/nginx.conf contains ssl_protocols TLSv1 TLSv1.1 TLSv1.2 TLSv1.3;. Change that line too, so every server block agrees. For HTTP/2, add http2 on; (nginx 1.25.1 and later) or listen 443 ssl http2; on older versions. Ciphers, HSTS and the rest are in How to configure TLS securely.

To serve an ECDSA and an RSA certificate side by side, repeat the ssl_certificate and ssl_certificate_key pair; nginx has supported that since 1.11.0. A key with a passphrase needs ssl_password_file.

4. Test the configuration and reload

sudo nginx -t

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

sudo systemctl reload nginx

A reload loads the new files without dropping connections. nginx reads certificates only at start and reload, so every renewal needs one; certbot and similar clients do it with a deploy hook.

Check it worked

Look at what the server actually sends, from another machine if you can:

openssl s_client -connect www.example.com:443 -servername www.example.com </dev/null 2>/dev/null | grep -E '^ [0-9] s:|^   i:|Verify return code'

On our test server (nginx 1.24 on Ubuntu 24.04, private test CA, so we added -CAfile corp-root.crt):

 0 s:CN = intranet.example.com
   i:C = BE, O = Example Corp, CN = Example Corp Issuing CA 1
 1 s:C = BE, O = Example Corp, CN = Example Corp Issuing CA 1
   i:C = BE, O = Example Corp, CN = Example Corp Root CA
Verify return code: 0 (ok)

Two certificates, leaf first, and code 0. Then a plain request:

curl -sS -o /dev/null -w '%{http_code}\n' https://www.example.com/

Paste the -showcerts output into the chain checker to see the same verdict, explained:

Try it: Chain checkerOpen the full tool

Runs in your browser. Nothing you paste is sent anywhere.

Paste the chain

Try a sampleChoose a sample…A complete chain: leaf, intermediate and rootA server that forgets its intermediateA chain in the wrong orderA self-signed root CA

-----BEGIN CERTIFICATE----- MIIC1zCCAnygAwIBAgIQWTTOzqWiPshGdQhNb6kmNjAKBggqhkjOPQQDAjB+MQsw CQYDVQQGEwJCRTEZMBcGA1UEChMQUEtJIFplcm8gdG8gSGVybzEnMCUGA1UECxMe U2FtcGxlcyAtIG5vdCBwdWJsaWNseSB0cnVzdGVkMSswKQYDVQQDEyJQS0kgWmVy byB0byBIZXJvIFNhbXBsZSBJc3N1aW5nIENBMB4XDTI2MTAwMTAwMDAwMFoXDTM2 MTAwMTAwMDAwMFowGjEYMBYGA1UEAxMPd3d3LmV4YW1wbGUuY29tMFkwEwYHKoZI zj0CAQYIKoZIzj0DAQcDQgAEw4og6Y/SOr+WrqSv+ng7tOBEsc5N3A3yZRk+9hsR XzPQvB9672aHZHTYFNlSY93RWVcTRieE+8XnIbWIYfwxIqOCAT4wggE6MAwGA1Ud EwEB/wQCMAAwDgYDVR0PAQH/BAQDAgeAMBMGA1UdJQQMMAoGCCsGAQUFBwMBMCcG A1UdEQQgMB6CD3d3dy5leGFtcGxlLmNvbYILZXhhbXBsZS5jb20wHQYDVR0OBBYE FALMipe4vcXJTpwO926S15Y/bobzMB8GA1UdIwQYMBaAFN+ph37v40SN23r6Fg/z OvSNjJqeMEgGCCsGAQUFBwEBBDwwOjA4BggrBgEFBQcwAoYsaHR0cDovL3BraS5l eGFtcGxlLmNvbS9zYW1wbGUtaXNzdWluZy1jYS5jcnQwPQYDVR0fBDYwNDAyoDCg LoYsaHR0cDovL3BraS5leGFtcGxlLmNvbS9zYW1wbGUtaXNzdWluZy1jYS5jcmww EwYDVR0gBAwwCjAIBgZngQwBAgEwCgYIKoZIzj0EAwIDSQAwRgIhAM5dJUPhL+qV artvWtQinfnykhVflJTjMXe8M6PnqQfaAiEAhOLGj1hSEkNxQoMrYNXRaIe69nq6 2unibVFSVw1AC80= -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- MIIE2TCCAsGgAwIBAgIQPh9PeiGf4STnEQriHxExjDANBgkqhkiG9w0BAQsFADB7 MQswCQYDVQQGEwJCRTEZMBcGA1UEChMQUEtJIFplcm8gdG8gSGVybzEnMCUGA1UE CxMeU2FtcGxlcyAtIG5vdCBwdWJsaWNseSB0cnVzdGVkMSgwJgYDVQQDEx9QS0kg WmVybyB0byBIZXJvIFNhbXBsZSBSb290IENBMB4XDTI1MDEwMTAwMDAwMFoXDTQw MDEwMTAwMDAwMFowfjELMAkGA1UEBhMCQkUxGTAXBgNVBAoTEFBLSSBaZXJvIHRv IEhlcm8xJzAlBgNVBAsTHlNhbXBsZXMgLSBub3QgcHVibGljbHkgdHJ1c3RlZDEr MCkGA1UEAxMiUEtJIFplcm8gdG8gSGVybyBTYW1wbGUgSXNzdWluZyBDQTBZMBMG ByqGSM49AgEGCCqGSM49AwEHA0IABBFqObJ/j93aHrAuebO5+KWnj0xRFzUS8/Jh Idj6jR/p4zqaNT8+gOqxZ+zhpNO/weIpz/nzXjQ7RJS+EebYRNijggEfMIIBGzAS BgNVHRMBAf8ECDAGAQH/AgEAMA4GA1UdDwEB/wQEAwIBhjAdBgNVHSUEFjAUBggr BgEFBQcDAQYIKwYBBQUHAwIwHQYDVR0OBBYEFN+ph37v40SN23r6Fg/zOvSNjJqe MB8GA1UdIwQYMBaAFIVx1Hy1TuED0pMkxEcdM+DWWPGiMEUGCCsGAQUFBwEBBDkw NzA1BggrBgEFBQcwAoYpaHR0cDovL3BraS5leGFtcGxlLmNvbS9zYW1wbGUtcm9v dC1jYS5jcnQwOgYDVR0fBDMwMTAvoC2gK4YpaHR0cDovL3BraS5leGFtcGxlLmNv bS9zYW1wbGUtcm9vdC1jYS5jcmwwEwYDVR0gBAwwCjAIBgZngQwBAgEwDQYJKoZI hvcNAQELBQADggIBAFa8c1kEzTTPW2aPDRPb3+OQc8GTgwpZV0pWNR3e6X8mJi7A D/RGrz4t354IwGzTts+tX23sY3fORKST3/BkqeHZwAZHvGNWi0+Co342eo2BySxo bcyy31AJBSSHOC2b7KJ11coMX++bvaHgtwOloy6DnHRDYIFwWRHg91wo1MKJGNVb OQH0vmqn6YPDLZ4BYL8VHOVtlRddBwd6bKyyp3Lw0MEMgfmg87Yd/U0yRZFaLKNb b5vgDg7n+J1ozFwvumQlN6WVEyPsQdvI73K5bgMHkUeeUQ6j9KOeDMZMjbqQSC8x 1khcyT/qhqZLDJIHvmWS11FcYaLQUuvQiAzQieTNIuOM8WJw95LlxYSNIkZeOuLf f+JboiuT1cmqmvdbngAXtBIWRJ+Byeqdq2Z0d8Xfln6gWhHmm93+DO5uTaTxBwTr DayFTdTFxBZydXs48S+I/rVQvQtwkRh3rOcZpwTMsGzfoiCsOhEaiBOFk0C5FEKi um55SDXCMR6yXDhWqFPBIdle4izj5g2YmuZ3YD4G3PlcX5okW7aKTNU3RGWEOMk3 Ob9bkPnCsY7Ei4OqDqTBt/8HH/2kA4om4RzKGLw5Zc/Y+KhpbFhT52gtL7WDEEVZ NqFHgi6fdHgsczFNpCKhC8vM+mAM/gBiVR8hYIpt5lPFyXpFJO5Wn5BcEkv3 -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- MIIFxDCCA6ygAwIBAgIQV3/H8mpwNp5raCafwOtSezANBgkqhkiG9w0BAQsFADB7 MQswCQYDVQQGEwJCRTEZMBcGA1UEChMQUEtJIFplcm8gdG8gSGVybzEnMCUGA1UE CxMeU2FtcGxlcyAtIG5vdCBwdWJsaWNseSB0cnVzdGVkMSgwJgYDVQQDEx9QS0kg WmVybyB0byBIZXJvIFNhbXBsZSBSb290IENBMCAXDTI1MDEwMTAwMDAwMFoYDzIw NTAwMTAxMDAwMDAwWjB7MQswCQYDVQQGEwJCRTEZMBcGA1UEChMQUEtJIFplcm8g dG8gSGVybzEnMCUGA1UECxMeU2FtcGxlcyAtIG5vdCBwdWJsaWNseSB0cnVzdGVk MSgwJgYDVQQDEx9QS0kgWmVybyB0byBIZXJvIFNhbXBsZSBSb290IENBMIICIjAN BgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAnYTGHkYMca54QPkZcZENin3BHB3t uKdHkDZeKZvJHWqpfXpcZfusLvtJFeTrwWlEDBJuV20vmhaLeV29QeYKaIkm1Ul2 qCkrLUpWn/W9CPosfVqMd1nOrd+Ka9iPSeKlW3YX1P5WqQEjieJhBzT9comdj8qN /PynceTDcLa2mgYw7QhU8trBoLzhYqIJFfoUBk+7lahae8b9G5wKCbDicRM8/ATt 0dO9jCxi6RxJpkKl24ULgNOuFP9gG4nubWA8+BaMeM0LU64wNciFofgM2g/3iHHn zmcoe1z80C7WN+GuzNkWkN8D/tcqrbua0O5fREKKw6PyyxwQsjeMghpxLb0h1KeA ihpQMVgpWbhRkkpvF5odkF9vTJP89Z2y+8cgnUMyTpXATrt8KgC5LdWo5mlTNXC/ MvbCUb1Vz9bvcEx2y29tUeLIAUmyBzhF7zgMUPAOtDbLLCuxgR78T2TWaXB/8WBT XL44Wk5rOe7U+KuBr/t12AcZjaq0AGiNsvfd1P+IFbRivElegpdrM+S3arjOjptP M9sUl9Hc+cszaTpEVcQFFxcIyvq5HVjTlZr4vLKdqlhSkQB9hZUFuWNpnUZEYEnA 1vn/GkHNTJ6pv8XxdNXkFeRaUv3ajCn7CQ3UP/EXJqzBw5fl6aa9lqKTS5kF9rgw EIhwNaSd2O557KUCAwEAAaNCMEAwDwYDVR0TAQH/BAUwAwEB/zAOBgNVHQ8BAf8E BAMCAQYwHQYDVR0OBBYEFIVx1Hy1TuED0pMkxEcdM+DWWPGiMA0GCSqGSIb3DQEB CwUAA4ICAQBMdaOOM84aoItvumQ/sNzOhXvmLwboTb3oe67wda9TvPMSf2aP3JtP UWsR/9UbZgNE9M41p2+XZlVpsGP1BLEvi5ZwfMWmR876Mw1Zkt8ouY3DWN08egnm IdV2vKwDHhDE93IQ12fjNc8iuMCasoYiXTsmXx3R/+PkNbeBAupZEk6EwTr75PCY IJ2cheL7jQ06xeCCZv815rG+63jGk3tys7A+nUXKqOp9oN/dkEhi+YWiHG9UJ2w/ BDZCFUUoJBia7C3+hcXZAVxtWwTy0A5T/plEsqGcdfCMFA4cOFstthyS/Wnnuw8y cpSiXdUAQbLkJ+CGavr6MXVmDicmnV9p3Pv9EbpGPV8UlxwvoQMf+ajEE4EAaJkN Gc85wOC7Y7wwWkBnzjiyLztqRqOFdHEdM13V+2Gw2545Jk8o2gRizBQ6Ey6rlt2u YdYFqFFQhe2H+VqvJiLKefkN1mVQhvhfAvuoxZWIsDtyJWGs12L06xMj3wG98kne mUJjPzze3swZU39eiaC1MBs6U0oLZE6ZqubmjJd/ppmGyK+7o2SMi0juouvw6rcA J9eUJQLNpiVKmiwzKvPejASpunK5B5JO3Y7NAb4SVU22ItR73bBiRAugPwVajlBN RGcjMkDSiW07/dhN6GgjsNAzXHcTR7/nbILOAWbhBstNFK1mgejlbQ== -----END CERTIFICATE-----

Every certificate the server sends, leaf first. The output of openssl s_client -showcerts -connect example.com:443 works as it is: we ignore the text around the certificates.

Check the chainClearChoose a file

If something goes wrong

• nginx -t passes, but clients say unable to verify the first certificate or unable to get local issuer certificate. The intermediate is missing. nginx -t does not check the chain: with the leaf alone our test passed nginx -t, then openssl s_client showed one certificate and Verify return code: 21 (unable to verify the first certificate), and curl failed. Rebuild fullchain.pem (step 1).

• key values mismatch. nginx refuses to start:

  [emerg] SSL_CTX_use_PrivateKey("/etc/ssl/example/privkey.pem") failed (SSL: error:05800074:x509 certificate routines::key values mismatch)

  Either the key belongs to another certificate, or the chain file starts with the intermediate. We got the same message both ways. Check the order and the key (steps 1 and 2).

• cannot load certificate … BIO_new_file() failed. The path is wrong or the file is missing.

• The browser shows the old certificate. You did not reload, or another server block answers for that name. Run sudo nginx -T | grep -E 'server_name|ssl_certificate' to see the configuration nginx actually loaded.

• NET::ERR_CERT_COMMON_NAME_INVALID. The certificate’s Subject Alternative Name does not cover the name in the address bar. Check it with the hostname matcher.

• NET::ERR_CERT_DATE_INVALID. The certificate has expired or is not yet valid, or the client’s clock is wrong.

Why this works

During the TLS handshake, nginx sends the certificates from ssl_certificate in file order, and signs the handshake with the matching private key to prove it holds that key. The client then builds a certificate chain from the leaf through the intermediate to a root in its own store. If the intermediate is missing, the client cannot complete the chain unless it fetches or caches the intermediate itself, which browsers often do and other clients do not. See Certificate chains and path validation, The TLS 1.3 handshake and Anatomy of an X.509 certificate.

Go deeper

• nginx: ngx_http_ssl_module: every TLS directive, with defaults and versions.
• nginx: configuring HTTPS servers: chains, name-based HTTPS servers and SNI.
• RFC 9846, section 4.5.1: TLS 1.3’s rule that “the sender’s certificate MUST come in the first CertificateEntry”, and why the root may be left out.