Skip to content

Actualizing SSL Termination for NGINX Plus #666

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Jun 13, 2025
Merged

Actualizing SSL Termination for NGINX Plus #666

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
7321788
Removed HTML.
y82 Jun 11, 2025
71e8fa2
Directive formatting added.
y82 Jun 11, 2025
bbbb18a
Updated values in ssl_protocols.
y82 Jun 11, 2025
5a69422
Updated Compatibility Notes.
y82 Jun 11, 2025
32ec881
Updated info about browser SNI support.
y82 Jun 11, 2025
5abe85f
Update content/nginx/admin-guide/security-controls/terminating-ssl-ht…
y82 Jun 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
81 changes: 43 additions & 38 deletions content/nginx/admin-guide/security-controls/terminating-ssl-http.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,9 @@ type:

This section describes how to configure an HTTPS server on NGINX and F5 NGINX Plus.

<span id="setup"></span>
## Setting up an HTTPS Server
## Setting up an HTTPS Server {#setup}

To set up an HTTPS server, in your **nginx.conf** file include the `ssl` parameter to the [listen](https://nginx.org/en/docs/http/ngx_http_core_module.html#listen) directive in the [server](https://nginx.org/en/docs/http/ngx_http_core_module.html#server) block, then specify the locations of the server certificate and private key files:
To set up an HTTPS server, in your **nginx.conf** file include the `ssl` parameter to the [`listen`](https://nginx.org/en/docs/http/ngx_http_core_module.html#listen) directive in the [`server`](https://nginx.org/en/docs/http/ngx_http_core_module.html#server) block, then specify the locations of the server certificate and private key files:

```nginx
server {
Expand All @@ -28,7 +27,7 @@ server {
}
```

The server certificate is a public entity. It is sent to every client that connects to the NGINX or NGINX Plus server. The private key is a secure entity and should be stored in a file with restricted access. However, the NGINX master process must be able to read this file. Alternatively, the private key can be stored in the same file as the certificate:
The server certificate is a public entity. It is sent to every client that connects to the NGINX or NGINX Plus server. The private key is a secure entity and should be stored in a file with restricted access. However, the NGINX master process must be able to read this file. Alternatively, the private key can be stored in the same file as the certificate:

```nginx
ssl_certificate www.example.com.cert;
Expand All @@ -37,28 +36,27 @@ ssl_certificate_key www.example.com.cert;

In this case it is important to restrict access to the file. Note that although the certificate and the key are stored in one file in this case, only the certificate is sent to clients.

The [ssl_protocols](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_protocols) and [ssl_ciphers](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_ciphers ) directives can be used to require that clients use only the strong versions and ciphers of SSL/TLS when establishing connections.
The [`ssl_protocols`](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_protocols) and [`ssl_ciphers`](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_ciphers ) directives can be used to require that clients use only the strong versions and ciphers of SSL/TLS when establishing connections.

Since version 1.23.4, NGINX uses these defaults:

```nginx
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers HIGH:!aNULL:!MD5;
ssl_ciphers HIGH:!aNULL:!MD5;
```

Vulnerabilities are sometimes found in the design of older ciphers, and we recommend disabling them in a modern NGINX configuration (unfortunately, the default configuration cannot easily be changed because of backward compatibility for existing NGINX deployments). Please note that CBC-mode ciphers might be vulnerable to a number of attacks (the BEAST attack in particular as described in [CVE-2011-3389](https://nvd.nist.gov/vuln/detail/CVE-2011-3389)), and we recommend not using SSLv3 due to the [POODLE](https://nvd.nist.gov/vuln/detail/CVE-2014-3566) attack, unless you need to support legacy clients.


<span id="setup_ocsp"></span>
### OCSP Validation of Client Certificates
### OCSP Validation of Client Certificates {#setup_ocsp}

NGINX can be configured to use Online Certificate Status Protocol (OCSP) to check the validity of X.509 client certificates as they are presented. An OCSP request for the client certificate status is sent to an OCSP responder which checks the certificate validity and returns the response with the certificate status:

- `Good` - the certificate is not revoked
- `Revoked` - the certificate is revoked
- `Unknown` - no information is available about the client certificate

To enable OCSP validation of SSL client certificates, specify the [ssl_ocsp](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_ocsp) directive along with the [ssl_verify_client](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_verify_client) directive, which enables certificate verification:
To enable OCSP validation of SSL client certificates, specify the [`ssl_ocsp`](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_ocsp) directive along with the [`ssl_verify_client`](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_verify_client) directive, which enables certificate verification:

```nginx
server {
Expand All @@ -75,15 +73,15 @@ server {
}
```

NGINX sends the OCSP request to the OCSP URI embedded in the client certificate unless a different URI is defined with the [ssl_ocsp_responder](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_ocsp_responder) directive. `Only http://` OCSP responders are supported:
NGINX sends the OCSP request to the OCSP URI embedded in the client certificate unless a different URI is defined with the [`ssl_ocsp_responder`](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_ocsp_responder) directive. Only `http://` OCSP responders are supported:

```nginx
#...
ssl_ocsp_responder http://ocsp.example.com/;
#...
```

To cache OCSP responses in a single memory zone shared by all worker processes, specify the [ssl_ocsp_cache](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_ocsp_cache) directive to define the name and size of the zone. Responses are cached for `1` hour unless the `nextUpdate`value in the OCSP response specifies a different value:
To cache OCSP responses in a single memory zone shared by all worker processes, specify the [`ssl_ocsp_cache`](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_ocsp_cache) directive to define the name and size of the zone. Responses are cached for `1` hour unless the `nextUpdate`value in the OCSP response specifies a different value:

```nginx
#...
Expand All @@ -94,15 +92,14 @@ ssl_ocsp_cache shared:one:10m;
The result of the client certificate validation is available in the [`$ssl_client_verify`](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#var_ssl_client_verify) variable, including the reason for OCSP failure.


<span id="optimize"></span>
## HTTPS Server Optimization
## HTTPS Server Optimization {#optimize}

SSL operations consume extra CPU resources. The most CPU-intensive operation is the SSL handshake. There are two ways to minimize the number of these operations per client:

- Enabling keepalive connections to send several requests via one connection
- Reusing SSL session parameters to avoid SSL handshakes for parallel and subsequent connections

Sessions are stored in the SSL session cache shared between worker processes and configured by the [ssl_session_cache](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_session_cache) directive. One megabyte of cache contains about 4000 sessions. The default cache timeout is 5 minutes. This timeout can be increased using the [ssl_session_timeout](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_session_timeout) directive. Below is a sample configuration optimized for a multi-core system with 10 megabyte shared session cache:
Sessions are stored in the SSL session cache shared between worker processes and configured by the [`ssl_session_cache`](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_session_cache) directive. One megabyte of cache contains about 4000 sessions. The default cache timeout is `5` minutes. This timeout can be increased using the [`ssl_session_timeout`](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_session_timeout) directive. Below is a sample configuration optimized for a multi-core system with 10 megabyte shared session cache:

```nginx
worker_processes auto;
Expand All @@ -125,16 +122,15 @@ http {
}
```

<span id="cert_chains"></span>
## SSL Certificate Chains
## SSL Certificate Chains {#cert_chains}

Some browsers may complain about a certificate signed by a well-known certificate authority, while other browsers may accept the certificate without issues. This occurs because the issuing authority has signed the server certificate using an intermediate certificate that is not present in the base of well-known trusted certificate authorities which is distributed in a particular browser. In this case the authority provides a bundle of chained certificates that should be concatenated to the signed server certificate. The server certificate must appear before the chained certificates in the combined file:

```shell
cat www.example.com.crt bundle.crt > www.example.com.chained.crt
```

The resulting file should be used in the [ssl_certificate](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_certificate) directive:
The resulting file should be used in the [`ssl_certificate`](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_certificate) directive:

```nginx
server {
Expand Down Expand Up @@ -184,12 +180,11 @@ Certificate chain
...
```

In this example the subject (“`s`”) of the `www.GoDaddy.com` server certificate `#0` is signed by an issuer (`“i”`) which itself is the subject of certificate #1. Certificate #1 is signed by an issuer which itself is the subject of certificate #2. This certificate, however, is signed by the well‑known issuer `ValiCert, Inc.` whose certificate is stored in the browsers themselves.
In this example the subject (“`s`”) of the `www.GoDaddy.com` server certificate `#0` is signed by an issuer (`“i”`) which itself is the subject of certificate #1. Certificate #1 is signed by an issuer which itself is the subject of certificate #2. This certificate, however, is signed by the well‑known issuer `ValiCert, Inc.` whose certificate is stored in the browsers themselves.

If a certificate bundle has not been added, only the server certificate (#0) is shown.
If a certificate bundle has not been added, only the server certificate (#0) is shown.

<span id="single"></span>
## A Single HTTP/HTTPS Server
## A Single HTTP/HTTPS Server {#single}

It is possible to configure a single server that handles both HTTP and HTTPS requests by placing one `listen` directive with the `ssl` parameter and one without in the same virtual server:

Expand All @@ -204,10 +199,10 @@ server {
}
```

In NGINX version 0.7.13 and earlier, SSL cannot be enabled selectively for individual listening sockets, as shown above. SSL can only be enabled for the entire server using the [ssl](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl) directive, making it impossible to set up a single HTTP/HTTPS server. The `ssl` parameter to the [listen](https://nginx.org/en/docs/http/ngx_http_core_module.html#listen) directive was added to solve this issue. The [ssl](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl) directive therefore is deprecated in version 0.7.14 and later.
In NGINX version 0.7.13 and earlier, SSL cannot be enabled selectively for individual listening sockets, as shown above. SSL can only be enabled for the entire server using the [ssl](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl) directive, making it impossible to set up a single HTTP/HTTPS server. The `ssl` parameter to the [listen](https://nginx.org/en/docs/http/ngx_http_core_module.html#listen) directive was added to solve this issue. The [ssl](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl) directive therefore is deprecated in version 0.7.14 and later.

<span id="name"></span>
## Name-Based HTTPS Servers

## Name-Based HTTPS Servers {#name}

A common issue arises when two or more HTTPS servers are configured to listen on a single IP address:

Expand Down Expand Up @@ -247,7 +242,7 @@ server {
}
```

Note that there are also some specific proxy settings for HTTPS upstreams ([proxy_ssl_ciphers](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_ssl_ciphers), [proxy_ssl_protocols](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_ssl_protocols), and [proxy_ssl_session_reuse](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_ssl_session_reuse)) which can be used for fine‑tuning SSL between NGINX and upstream servers. You can read more about these in the [HTTP proxy module documentation](https://nginx.org/en/docs/http/ngx_http_proxy_module.html).
Note that there are also some specific proxy settings for HTTPS upstreams ([`proxy_ssl_ciphers`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_ssl_ciphers), [`proxy_ssl_protocols`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_ssl_protocols), and [`proxy_ssl_session_reuse`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_ssl_session_reuse)) which can be used for fine‑tuning SSL between NGINX and upstream servers. You can read more about these in the [HTTP proxy module documentation](https://nginx.org/en/docs/http/ngx_http_proxy_module.html).

### An SSL Certificate With Several Names

Expand Down Expand Up @@ -276,17 +271,17 @@ server {

### Server Name Indication

A more generic solution for running several HTTPS servers on a single IP address is the [TLS Server Name Indication](https://en.wikipedia.org/wiki/Server_Name_Indication) (SNI) extension ([RFC 6066](https://tools.ietf.org/html/rfc6066)), which allows a browser to pass a requested server name during the SSL handshake. With this solution, the server will know which certificate it should use for the connection. However, SNI has limited browser support. Currently it is supported starting with the following browser versions:
A more generic solution for running several HTTPS servers on a single IP address is the [TLS Server Name Indication](https://en.wikipedia.org/wiki/Server_Name_Indication) (SNI) extension ([RFC 6066](https://tools.ietf.org/html/rfc6066)), which allows a browser to pass a requested server name during the SSL handshake. With this solution, the server will know which certificate it should use for the connection. Although SNI is widely supported by modern browsers, some old browsers may still not include support for it. Major browsers support SNI starting with the following versions:

- Opera 8.0
- MSIE 7.0 (but only on Windows Vista or higher)
- Chrome 105 (Windows version supports SNI on Vista or higher, too)
- Firefox 2.0 and other browsers using Mozilla Platform rv:1.8.1
- Microsoft Internet Explorer 7.0 (but only on Windows Vista or higher)
- Opera 8.0
- Safari 3.2.1 (Windows version supports SNI on Vista or higher)
- Chrome (Windows version supports SNI on Vista or higher, too)

Only domain names can be passed in SNI. However, some browsers will pass the IP address of the server as its name if a request includes a literal IP address. It is best not to rely on this.

In order to use SNI in NGINX, it must be supported in both the OpenSSL library with which the NGINX binary has been built, as well as the library with which it is being dynamically linked at runtime. OpenSSL supports SNI since the version 0.9.8f if it was built with configuration `option --enable-tlsext`. Since OpenSSL version 0.9.8j, this option is enabled by default. If NGINX was built with SNI support, NGINX shows the following when run with the <span style="white-space: nowrap;">`-V`</span> switch:
In order to use SNI in NGINX, it must be supported in both the OpenSSL library with which the NGINX binary has been built, as well as the library with which it is being dynamically linked at runtime. OpenSSL supports SNI since the version 0.9.8f if it was built with configuration `option --enable-tlsext`. Since OpenSSL version 0.9.8j, this option is enabled by default. If NGINX was built with SNI support, NGINX shows the following when run with the `-V` switch:

```shell
nginx -V
Expand All @@ -305,21 +300,31 @@ therefore SNI is not available

## Compatibility Notes

- The SNI support status has been shown by the <span style="white-space: nowrap;">`-V`</span> switch since versions 0.8.21 and 0.7.62.
- The SNI support status has been shown by the `-V` switch since versions 0.8.21 and 0.7.62.

- The `ssl` parameter of the [`listen`](https://nginx.org/en/docs/http/ngx_http_core_module.html#listen) directive has been supported since version 0.7.14. Prior to version 0.8.21 it could only be specified along with the `default` parameter.

- SNI has been supported since version 0.5.23.

- The `ssl` parameter to the [listen](https://nginx.org/en/docs/http/ngx_http_core_module.html#listen) directive has been supported since version 0.7.14. Prior to version 0.8.21 it could only be specified along with the `default` parameter.
- The shared SSL session cache has been supported since version 0.5.6.

- SNI has been supported since version 0.5.23.
- The shared SSL session cache has been supported since version 0.5.6.
### SSL protocols

- Version 1.27.3 and later: the default SSL protocols are `TLSv1.2` and `TLSv1.3` (if supported by the OpenSSL library). Otherwise, when OpenSSL 1.0.0 or older is used, the default SSL protocols are `TLSv1` and `TLSv1.1`.

- Version 1.23.4 and later: the default SSL protocols are `TLSv1`, `TLSv1.1`, `TLSv1.2`, and `TLSv1.3` (if supported by the OpenSSL library).

- Version 1.9.1 and later: the default SSL protocols are `TLSv1`, `TLSv1.1`, and `TLSv1.2` (if supported by the OpenSSL library).
- From versions 0.7.65 and 0.8.19 and later, the default SSL protocols are `SSLv3`, `TLSv1`, `TLSv1.1`, and `TLSv1.2` (if supported by the OpenSSL library).

- In versions 0.7.64 and 0.8.18 and earlier, the default SSL protocols are `SSLv2`, `SSLv3`, and `TLSv1`.
- From versions 0.7.65 and 0.8.19 and later, the default SSL protocols are `SSLv3`, `TLSv1`, `TLSv1.1`, and `TLSv1.2` (if supported by the OpenSSL library).

- In versions 0.7.64 and 0.8.18 and earlier, the default SSL protocols are `SSLv2`, `SSLv3`, and `TLSv1`.

### SSL ciphers

- In version 1.0.5 and later, the default SSL ciphers are `HIGH:!aNULL:!MD5`.
- In version 1.0.5 and later, the default SSL ciphers are `HIGH:!aNULL:!MD5`.

- In versions 0.7.65 and 0.8.20 and later, the default SSL ciphers are `HIGH:!ADH:!MD5`.
- In versions 0.7.65 and 0.8.20 and later, the default SSL ciphers are `HIGH:!ADH:!MD5`.

- From version 0.8.19 the default SSL ciphers are `ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM`.

Expand Down
Loading