<!-- review: finished -->

<a id="http-ssl"></a>

# SSL

Provides the necessary support for HTTPS.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild),
this module isn't built by default;
it should be enabled with the
`‑‑with‑http_ssl_module`
[build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure).

In packages and images from [our repos](https://en.angie.software//angie/docs/installation/index.md#install-packages),
the module is included in the build.

#### NOTE
This module requires the OpenSSL library.

<a id="configuration-example-42"></a>

## Configuration Example

To reduce the processor load it is recommended to

* set the number of [worker processes](https://en.angie.software//angie/docs/configuration/modules/core.md#worker-processes) equal to the number of processors,
* enable [keep-alive](https://en.angie.software//angie/docs/configuration/modules/http/index.md#keepalive-timeout) connections,
* enable the [shared](#ssl-session-cache) session cache,
* disable the [built-in](#ssl-session-cache) session cache,
* and possibly increase the session [lifetime](#ssl-session-timeout) (by default, 5 minutes):

```nginx
worker_processes auto;

http {

    # ...

    server {
        listen              443 ssl;
        keepalive_timeout   70;

        ssl_protocols       TLSv1.2 TLSv1.3;
        ssl_ciphers         AES128-SHA:AES256-SHA:RC4-SHA:DES-CBC3-SHA:RC4-MD5;
        ssl_certificate     /usr/local/angie/conf/cert.pem;
        ssl_certificate_key /usr/local/angie/conf/cert.key;
        ssl_session_cache   shared:SSL:10m;
        ssl_session_timeout 10m;

        # ...
    }
```

<a id="directives-45"></a>

## Directives

<a id="index-0"></a>

<a id="ssl-buffer-size"></a>

### ssl_buffer_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_buffer_size` size;   |
|------------------------------------------------------------------------------------------|---------------------------|
| Default                                                                                  | `ssl_buffer_size 16k;`    |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server              |

Sets the size of the buffer used for sending data.

By default, the buffer size is 16k, which corresponds to minimal overhead when sending big responses. To minimize Time To First Byte it may be beneficial to use smaller values, for example:

```nginx
ssl_buffer_size 4k;
```

<a id="index-1"></a>

<a id="ssl-certificate"></a>

### ssl_certificate

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_certificate` file;   |
|------------------------------------------------------------------------------------------|---------------------------|
| Default                                                                                  | —                         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server              |

Specifies a file with the certificate in the PEM format for the given virtual server. If intermediate certificates should be specified in addition to a primary certificate, they should be specified in the same file in the following order: the primary certificate comes first, then the intermediate certificates. A secret key in the PEM format may be placed in the same file.

This directive can be specified multiple times to load certificates of different types, for example, RSA and ECDSA:

```nginx
server {
    listen              443 ssl;
    server_name         example.com;

    ssl_certificate     example.com.rsa.crt;
    ssl_certificate_key example.com.rsa.key;

    ssl_certificate     example.com.ecdsa.crt;
    ssl_certificate_key example.com.ecdsa.key;

    # ...
}
```

Only OpenSSL 1.0.2 or higher supports separate certificate chains for different certificates. With older versions, only one certificate chain can be used.

#### NOTE
Variables can be used in the file name when using OpenSSL 1.0.2 or higher:

```nginx
ssl_certificate     $ssl_server_name.crt;
ssl_certificate_key $ssl_server_name.key;
```

Note that using variables implies that a certificate will be loaded for each SSL handshake, and this may have a negative impact on performance.

The value `data:$variable` can be specified instead of the file, which loads a certificate from a variable without using intermediate files. Note that inappropriate use of this syntax may have its security implications, such as writing secret key data to [error log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log).

#### NOTE
> It should be kept in mind that due to the HTTPS protocol limitations for maximum interoperability virtual servers should listen on [different IP addresses](https://en.angie.software//angie/docs/configuration/ssl.md#https-separate-ips).

If [ssl_ntls](#ssl-ntls) is enabled, the directive can accept two arguments
(the signature and the encryption parts of the certificate)
instead of one:

```nginx
listen ... ssl;

ssl_ntls  on;

# dual NTLS certificate
ssl_certificate      sign.crt enc.crt;
ssl_certificate_key  sign.key enc.key;

# can be used together with a regular RSA certificate
ssl_certificate  rsa.crt;
ssl_certificate_key rsa.key;
```

<a id="index-2"></a>

<a id="ssl-certificate-cache"></a>

### ssl_certificate_cache

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_certificate_cache` `off`;<br/><br/>`ssl_certificate_cache` `max=`N [`inactive=`time] [`valid=`time];   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `ssl_certificate_cache off;`                                                                                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                                                                                                |

Defines a cache that stores [SSL certificates](#ssl-certificate) and [secret keys](#ssl-certificate-key) specified using variables.

The directive supports the following parameters:

- `max` — sets the maximum number of elements in the cache. When the cache
  overflows, the least recently used (LRU) elements are removed.
- `inactive` — defines the time after which an element is removed if it
  has not been accessed. The default is 10 seconds.
- `valid` — defines the time during which a cached element is considered
  valid and can be reused. The default is 60 seconds. After this period,
  certificates are reloaded or revalidated.
- `off` — disables the cache.

Example:

```nginx
ssl_certificate       $ssl_server_name.crt;
ssl_certificate_key   $ssl_server_name.key;
ssl_certificate_cache max=1000 inactive=20s valid=1m;
```

<a id="index-3"></a>

<a id="ssl-certificate-compression"></a>

### ssl_certificate_compression

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_certificate_compression` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-----------------------------------------------|
| Default                                                                                  | `ssl_certificate_compression off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                                  |

Enables TLS 1.3 [compression](https://datatracker.ietf.org/doc/html/rfc8879) of server certificates.

#### NOTE
The directive is supported when using OpenSSL 3.2 or higher; the list of supported compression algorithms is provided by the library.

#### NOTE
The directive is supported when using [BoringSSL](https://boringssl.googlesource.com/boringssl/); the list of supported compression algorithms includes `zlib`.

If [ssl_stapling](#ssl-stapling) is enabled, certificate compression is disabled.

<a id="index-4"></a>

<a id="ssl-certificate-key"></a>

### ssl_certificate_key

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_certificate_key` file;   |
|------------------------------------------------------------------------------------------|-------------------------------|
| Default                                                                                  | —                             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                  |

Specifies a file with the secret key in the PEM format for the given virtual server.

#### NOTE
Variables can be used in the file name when using OpenSSL 1.0.2 or higher.

The value `engine:name:id` can be specified instead of the file, which loads a secret key with a specified id from the OpenSSL engine name.

The value `store:scheme:id` can be specified instead of the file, which is used to load a secret key with a specified id and OpenSSL provider registered URI scheme, such as [pkcs11](https://datatracker.ietf.org/doc/html/rfc7512).

The value `data:$variable` can be specified instead of the file, which loads a secret key from a variable without using intermediate files. Note that inappropriate use of this syntax may have its security implications, such as writing secret key data to [error log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log).

> If [ssl_ntls](#ssl-ntls) is enabled, the directive can accept two arguments
> (the signature and the encryption parts of the key)
> instead of one:

> ```nginx
> listen ... ssl;

> ssl_ntls  on;

> # dual NTLS certificate
> ssl_certificate      sign.crt enc.crt;
> ssl_certificate_key  sign.key enc.key;

> # can be used together with a regular RSA certificate
> ssl_certificate  rsa.crt;
> ssl_certificate_key rsa.key;
> ```

<a id="index-5"></a>

<a id="ssl-ciphers"></a>

### ssl_ciphers

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ciphers` ciphers;          |
|------------------------------------------------------------------------------------------|---------------------------------|
| Default                                                                                  | `ssl_ciphers HIGH:!aNULL:!MD5;` |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                    |

Specifies the enabled ciphers. The ciphers are specified in the format understood by the OpenSSL library, for example:

```nginx
ssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;
```

The list of ciphers depends on the version of OpenSSL installed.
The full list can be viewed using the `openssl ciphers` command.

#### WARNING
The `ssl_ciphers` directive does *not* configure ciphers for TLS
1.3 when using OpenSSL. To configure TLS 1.3 ciphers with OpenSSL, use the
[ssl_conf_command](#ssl-conf-command) directive, which was added to support advanced
SSL configuration.

- In LibreSSL, TLS 1.3 ciphers *can* be configured using
  `ssl_ciphers`.
- In BoringSSL, TLS 1.3 ciphers cannot be configured at all.

<a id="index-6"></a>

<a id="ssl-client-certificate"></a>

### ssl_client_certificate

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_client_certificate` file;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | —                                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                     |

Specifies a file with trusted CA certificates in the PEM format used to
[verify](#ssl-verify-client) client certificates and OCSP responses if
[ssl_stapling](#ssl-stapling) is enabled.

The list of certificates will be sent to clients. If this is not desired, the [ssl_trusted_certificate](#ssl-trusted-certificate) directive can be used.

<a id="index-7"></a>

<a id="ssl-conf-command"></a>

### ssl_conf_command

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_conf_command` name value;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | —                                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                     |

Sets arbitrary OpenSSL [configuration commands](https://docs.openssl.org/master/man3/SSL_CONF_cmd/).

#### NOTE
The directive is supported when using OpenSSL 1.0.2 or higher.
To configure TLS 1.3 ciphers with OpenSSL, use the `Ciphersuites` command.

Several ssl_conf_command directives can be specified on the same level:

```nginx
ssl_conf_command Options PrioritizeChaCha;
ssl_conf_command Ciphersuites TLS_CHACHA20_POLY1305_SHA256;
```

These directives are inherited from the previous configuration level if and only if there are no ssl_conf_command directives defined on the current level.

#### WARNING
Note that configuring OpenSSL directly might result in unexpected behavior.

<a id="index-8"></a>

<a id="ssl-crl"></a>

### ssl_crl

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_crl` file;   |
|------------------------------------------------------------------------------------------|-------------------|
| Default                                                                                  | —                 |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server      |

Specifies a file with revoked certificates (CRL) in the PEM format used to [verify](#ssl-verify-client) client certificates.

<a id="index-9"></a>

<a id="ssl-dhparam"></a>

### ssl_dhparam

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_dhparam` file;   |
|------------------------------------------------------------------------------------------|-----------------------|
| Default                                                                                  | —                     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server          |

Specifies a file with DH parameters for DHE ciphers.

#### WARNING
By default no parameters are set, and therefore DHE ciphers will not be used.

<a id="index-10"></a>

<a id="ssl-early-data"></a>

### ssl_early_data

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_early_data` `on` | `off`;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | `ssl_early_data off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                     |

Enables or disables TLS 1.3 [early data](https://datatracker.ietf.org/doc/html/rfc8446#section-2.3).

Requests sent within early data are subject to [replay attacks](https://datatracker.ietf.org/doc/html/rfc8470). To protect against such attacks at the application layer, the [$ssl_early_data](#v-ssl-early-data) variable should be used.

```nginx
proxy_set_header Early-Data $ssl_early_data;
```

#### NOTE
The directive is supported when using OpenSSL 1.1.1 or higher or [BoringSSL](https://boringssl.googlesource.com/boringssl/).

<a id="index-11"></a>

<a id="ssl-encrypted-hello-key"></a>

### ssl_encrypted_hello_key

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_encrypted_hello_key` file;   |
|------------------------------------------------------------------------------------------|-----------------------------------|
| Default                                                                                  | —                                 |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                      |

Specifies a file with an ECH private key and ECHConfigList in PEM format.
The directive can be specified multiple times.
Requires an OpenSSL or BoringSSL build with Encrypted Client Hello (ECH)
support; otherwise it is not supported.

<a id="index-12"></a>

<a id="ssl-ecdh-curve"></a>

### ssl_ecdh_curve

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ecdh_curve` curve;   |
|------------------------------------------------------------------------------------------|---------------------------|
| Default                                                                                  | `ssl_ecdh_curve auto;`    |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server              |

Specifies a curve for ECDHE ciphers.

#### NOTE
When using OpenSSL 1.0.2 or higher, it is possible to specify multiple curves, for example:

```nginx
ssl_ecdh_curve prime256v1:secp384r1;
```

The special value `auto` corresponds to the list of curves built into the OpenSSL library for OpenSSL 1.0.2 or higher, or prime256v1 for older versions.

#### NOTE
When using OpenSSL 1.0.2 or higher, this directive sets the list of curves supported by the server. Thus, in order for ECDSA certificates to work, it is important to include the curves used in the certificates.

<a id="index-13"></a>

<a id="ssl-ntls"></a>

### ssl_ntls

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ntls` `on` | `off`;   |
|------------------------------------------------------------------------------------------|----------------------------|
| Default                                                                                  | `ssl_ntls off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server               |

Enables server-side support for NTLS when using the [TongSuo](https://github.com/Tongsuo-Project/Tongsuo) TLS library.

```nginx
listen ... ssl;
ssl_ntls  on;
```

#### NOTE
Angie must be built with the `--with-ntls` configuration parameter, with the corresponding SSL library with NTLS support

```default
./configure --with-openssl=../Tongsuo-8.3.0 \
            --with-openssl-opt=enable-ntls  \
            --with-ntls
```

<a id="index-14"></a>

<a id="ssl-ocsp"></a>

### ssl_ocsp

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ocsp` `on` | `off` | `leaf`;   |
|------------------------------------------------------------------------------------------|-------------------------------------|
| Default                                                                                  | `ssl_ocsp off;`                     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                        |

Enables OCSP validation of the client certificate chain. The `leaf` parameter enables validation of the client certificate only.

For the OCSP validation to work, the [ssl_verify_client](#ssl-verify-client) directive should be set to `on` or `optional`.

To resolve the OCSP responder hostname, the [resolver](https://en.angie.software//angie/docs/configuration/modules/http/index.md#resolver) directive should also be specified.

Example:

```nginx
ssl_verify_client on;
ssl_ocsp          on;
resolver          127.0.0.53;
```

<a id="index-15"></a>

<a id="ssl-ocsp-cache"></a>

### ssl_ocsp_cache

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ocsp_cache` `off` | [shared:name:size];   |
|------------------------------------------------------------------------------------------|------------------------------------------------|
| Default                                                                                  | `ssl_ocsp_cache off;`                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                                   |

Sets the name and size of the cache that stores client certificate status for OCSP validation. The cache is shared between all worker processes. A cache with the same name can be used in several virtual servers.

The `off` parameter prohibits the use of the cache.

<a id="index-16"></a>

<a id="ssl-ocsp-responder"></a>

### ssl_ocsp_responder

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ocsp_responder` uri;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| Default                                                                                  | —                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                |

Overrides the URI of the OCSP responder specified in the ["Authority Information Access"](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.2.1) certificate extension for [validation](#ssl-ocsp) of client certificates.

Only `http://` OCSP responders are supported:

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

<a id="index-17"></a>

<a id="ssl-password-file"></a>

### ssl_password_file

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_password_file` file;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| Default                                                                                  | —                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                |

Specifies a file with passphrases for [secret keys](#ssl-certificate-key) where each passphrase is specified on a separate line. Passphrases are tried in turn when loading the key.

Example:

```nginx
http {
    ssl_password_file /etc/keys/global.pass;
    ...

    server {
        server_name www1.example.com;
        ssl_certificate_key /etc/keys/first.key;
    }

    server {
        server_name www2.example.com;

        # named pipe can also be used instead of a file
        ssl_password_file /etc/keys/fifo;
        ssl_certificate_key /etc/keys/second.key;
    }
}
```

<a id="index-18"></a>

<a id="ssl-prefer-server-ciphers"></a>

### ssl_prefer_server_ciphers

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_prefer_server_ciphers` `on` | `off`;   |
|------------------------------------------------------------------------------------------|---------------------------------------------|
| Default                                                                                  | `ssl_prefer_server_ciphers off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                                |

Specifies that server ciphers should be preferred over client ciphers when using the SSLv3 and TLS protocols.

<a id="index-19"></a>

<a id="ssl-protocols"></a>

### ssl_protocols

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_protocols` [`SSLv2`] [`SSLv3`] [`TLSv1`] [`TLSv1.1`] [`TLSv1.2`] [`TLSv1.3`];   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
| Default                                                                                  | `ssl_protocols TLSv1.2 TLSv1.3;`                                                     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                                                                         |

#### Versionchanged
Changed in version 1.2.0: The `TLSv1.3` parameter was added to the default set.

Enables the specified protocols.

#### NOTE
The TLSv1.1 and TLSv1.2 parameters work only when OpenSSL 1.0.1 or higher is used.

The TLSv1.3 parameter works only when OpenSSL 1.1.1 or higher is used.

<a id="index-20"></a>

<a id="ssl-reject-handshake"></a>

### ssl_reject_handshake

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_reject_handshake` `on` | `off`;   |
|------------------------------------------------------------------------------------------|----------------------------------------|
| Default                                                                                  | `ssl_reject_handshake off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                           |

If enabled, SSL handshakes in the [server](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server) block will be rejected.

For example, in the following configuration, SSL handshakes with server names other than example.com are rejected:

```nginx
server {
    listen               443 ssl default_server;
    ssl_reject_handshake on;
}

server {
    listen              443 ssl;
    server_name         example.com;
    ssl_certificate     example.com.crt;
    ssl_certificate_key example.com.key;
}
```

<a id="index-21"></a>

<a id="ssl-session-cache"></a>

### ssl_session_cache

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_session_cache` `off` | `none` | [builtin[:size]] [shared:name:size];   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| Default                                                                                  | `ssl_session_cache none;`                                                   |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                                                                |

Sets the types and sizes of caches that store session parameters. A cache can be of any of the following types:

| `off`     | the use of a session cache is strictly prohibited: Angie explicitly tells a client that sessions may not be reused.                                                                                                                                                                                                                                                                                                                                      |
|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `none`    | the use of a session cache is gently disallowed: Angie tells a client that sessions may be reused, but does not actually store session parameters in the cache.                                                                                                                                                                                                                                                                                          |
| `builtin` | a cache built in OpenSSL; used by one worker process only. The cache size is specified in sessions. If size is not given, it is equal to 20480 sessions. Use of the built-in cache can cause memory fragmentation.                                                                                                                                                                                                                                       |
| `shared`  | a cache shared between all worker processes. The cache size is specified in bytes; one megabyte can store about 4000 sessions. Each shared cache should have an arbitrary name. A cache with the same name can be used in several virtual servers. It is also used to automatically generate, store, and periodically rotate TLS session ticket keys unless configured explicitly using the [ssl_session_ticket_key](#ssl-session-ticket-key) directive. |

Both cache types can be used simultaneously, for example:

```nginx
ssl_session_cache builtin:1000 shared:SSL:10m;
```

but using only shared cache without the built-in cache should be more efficient.

<a id="index-22"></a>

<a id="ssl-session-ticket-key"></a>

### ssl_session_ticket_key

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_session_ticket_key` file;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | —                                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                     |

Sets a file with the secret key used to encrypt and decrypt TLS session tickets. The directive is necessary if the same key needs to be shared between multiple servers. By default, a randomly generated key is used.

If several keys are specified, only the first key is used to encrypt TLS session tickets. This allows configuring key rotation, for example:

```nginx
ssl_session_ticket_key current.key;
ssl_session_ticket_key previous.key;
```

The file must contain 80 or 48 bytes of random data and can be created using the following command:

```console
openssl rand 80 > ticket.key
```

Depending on the file size, either AES256 (for 80-byte keys) or AES128 (for 48-byte keys) will be used for encryption.

<a id="index-23"></a>

<a id="ssl-session-tickets"></a>

### ssl_session_tickets

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_session_tickets` `on` | `off`;   |
|------------------------------------------------------------------------------------------|---------------------------------------|
| Default                                                                                  | `ssl_session_tickets on;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                          |

Enables or disables session resumption through [TLS session tickets](https://datatracker.ietf.org/doc/html/rfc5077).

<a id="index-24"></a>

<a id="ssl-session-timeout"></a>

### ssl_session_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_session_timeout` time;   |
|------------------------------------------------------------------------------------------|-------------------------------|
| Default                                                                                  | `ssl_session_timeout 5m;`     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                  |

Specifies a time during which a client may reuse the session parameters.

<a id="index-25"></a>

<a id="ssl-stapling"></a>

### ssl_stapling

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_stapling` `on` | `off`;   |
|------------------------------------------------------------------------------------------|--------------------------------|
| Default                                                                                  | `ssl_stapling off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                   |

Enables or disables [stapling of OCSP responses](https://datatracker.ietf.org/doc/html/rfc6066#section-8) by the server. Example:

```nginx
ssl_stapling on;
resolver 127.0.0.53;
```

For OCSP stapling to work, the certificate of the server certificate issuer should be known. If the [ssl_certificate](#ssl-certificate) file does not contain intermediate certificates, the certificate of the server certificate issuer should be present in the file specified by the [ssl_trusted_certificate](#ssl-trusted-certificate) directive.

#### WARNING
For a resolution of the OCSP responder hostname, the [resolver](https://en.angie.software//angie/docs/configuration/modules/http/index.md#resolver) directive should also be specified.

<a id="index-26"></a>

<a id="ssl-stapling-file"></a>

### ssl_stapling_file

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_stapling_file` file;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| Default                                                                                  | —                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                |

When set, the stapled OCSP response will be taken from the specified file instead of querying the OCSP responder specified in the server certificate.

The file should be in the DER format as produced by the `openssl ocsp` command.

<a id="index-27"></a>

<a id="ssl-stapling-responder"></a>

### ssl_stapling_responder

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_stapling_responder` `uri`;   |
|------------------------------------------------------------------------------------------|-----------------------------------|
| Default                                                                                  | —                                 |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                      |

Overrides the URI of the OCSP responder specified in the ["Authority Information Access"](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.2.1) certificate extension.

Only `http://` OCSP responders are supported:

```nginx
ssl_stapling_responder http://ocsp.example.com/;
```

<a id="index-28"></a>

<a id="ssl-stapling-verify"></a>

### ssl_stapling_verify

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_stapling_verify` `on` | `off`;   |
|------------------------------------------------------------------------------------------|---------------------------------------|
| Default                                                                                  | `ssl_stapling_verify off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                          |

Enables or disables verification of OCSP responses by the server.

For verification to work, the certificate of the server certificate issuer, the root certificate, and all intermediate certificates should be configured as trusted using the [ssl_trusted_certificate](#ssl-trusted-certificate) directive.

<a id="index-29"></a>

<a id="ssl-trusted-certificate"></a>

### ssl_trusted_certificate

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_trusted_certificate` file;   |
|------------------------------------------------------------------------------------------|-----------------------------------|
| Default                                                                                  | —                                 |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                      |

Specifies a file with trusted CA certificates in the PEM format used to [verify](#ssl-verify-client) client certificates and OCSP responses if [ssl_stapling](#ssl-stapling) is enabled.

In contrast to the certificate set by [ssl_client_certificate](#ssl-client-certificate), the list of these certificates will not be sent to clients.

<a id="index-30"></a>

<a id="ssl-verify-client"></a>

### ssl_verify_client

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_verify_client` `on` | `off` | `optional` | `optional_no_ca`;   |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------|
| Default                                                                                  | `ssl_verify_client off;`                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                                                        |

Enables verification of client certificates. The verification result is stored in the [$ssl_client_verify](#v-ssl-client-verify) variable.

| `optional`       | requests the client certificate and verifies it if the certificate is present.                                                                                                                                             |
|------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `optional_no_ca` | requests the client certificate but does not require it to be signed by a trusted CA certificate. This is intended for use in cases when a service that is external to Angie performs the actual certificate verification. |

<a id="index-31"></a>

<a id="ssl-verify-depth"></a>

### ssl_verify_depth

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_verify_depth` number;   |
|------------------------------------------------------------------------------------------|------------------------------|
| Default                                                                                  | `ssl_verify_depth 1;`        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                 |

Sets the verification depth in the client certificates chain.

<a id="ssl-error-codes"></a>

## Error Processing

The `http_ssl` module supports several non-standard error codes that can be used for redirects using the [error_page](https://en.angie.software//angie/docs/configuration/modules/http/index.md#error-page) directive:

| `495`   | an error has occurred during the client certificate verification;   |
|---------|---------------------------------------------------------------------|
| `496`   | a client has not presented the required certificate;                |
| `497`   | a regular request has been sent to the HTTPS port.                  |

The redirection happens after the request is fully parsed and the variables, such as [$request_uri](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-request-uri), [$uri](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-uri), [$args](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-args) and others, are available.

<a id="built-in-variables-12"></a>

## Built-in Variables

The http_ssl module supports built-in variables:

<a id="v-ssl-alpn-protocol"></a>

### `$ssl_alpn_protocol`

returns the protocol selected by ALPN during the SSL handshake, or an empty string otherwise.

<a id="v-ssl-cipher"></a>

### `$ssl_cipher`

returns the name of the cipher used for an established SSL connection.

<a id="v-ssl-ciphers"></a>

### `$ssl_ciphers`

returns the list of ciphers supported by the client. Known ciphers are listed by names, unknown are shown in hexadecimal, for example:

> AES128-SHA:AES256-SHA:0x00ff

#### NOTE
The variable is fully supported only when using OpenSSL version 1.0.2 or higher. With older versions, the variable is available only for new sessions and lists only known ciphers.

<a id="v-ssl-client-escaped-cert"></a>

### `$ssl_client_escaped_cert`

returns the client certificate in the PEM format (urlencoded) for an established SSL connection.

<a id="v-ssl-client-fingerprint"></a>

### `$ssl_client_fingerprint`

returns the SHA1 fingerprint of the client certificate for an established SSL connection.

<a id="v-ssl-client-i-dn"></a>

### `$ssl_client_i_dn`

returns the "issuer DN" string of the client certificate for an established SSL connection according to [RFC 2253](https://datatracker.ietf.org/doc/html/rfc2253).

<a id="v-ssl-client-i-dn-legacy"></a>

### `$ssl_client_i_dn_legacy`

returns the "issuer DN" string of the client certificate for an established SSL connection.

<a id="v-ssl-client-raw-cert"></a>

### `$ssl_client_raw_cert`

returns the client certificate in the PEM format for an established SSL connection.

<a id="v-ssl-client-s-dn"></a>

### `$ssl_client_s_dn`

returns the "subject DN" string of the client certificate for an established SSL connection according to [RFC 2253](https://datatracker.ietf.org/doc/html/rfc2253).

<a id="v-ssl-client-s-dn-legacy"></a>

### `$ssl_client_s_dn_legacy`

returns the "subject DN" string of the client certificate for an established SSL connection.

<a id="v-ssl-client-serial"></a>

### `$ssl_client_serial`

returns the serial number of the client certificate for an established SSL connection.

<a id="v-ssl-client-sigalg"></a>

### `$ssl_client_sigalg`

returns the [signature algorithm](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-16) for the client certificate for an established SSL connection.

#### NOTE
The variable is supported only when using OpenSSL version 3.5 or higher. With older versions, the variable value will be an empty string.

#### NOTE
The variable is available only for new sessions.

<a id="v-ssl-client-v-end"></a>

### `$ssl_client_v_end`

returns the end date of the client certificate.

<a id="v-ssl-client-v-remain"></a>

### `$ssl_client_v_remain`

returns the number of days until the client certificate expires.

<a id="v-ssl-client-v-start"></a>

### `$ssl_client_v_start`

returns the start date of the client certificate.

<a id="v-ssl-client-verify"></a>

### `$ssl_client_verify`

returns the result of client certificate verification: `SUCCESS`, `FAILED:reason`, and `NONE` if a certificate was not present.

<a id="v-ssl-curve"></a>

### `$ssl_curve`

returns the negotiated curve used for key exchange during the SSL handshake. Known curves are listed by names, unknown are shown in hexadecimal, for example:

> prime256v1

#### NOTE
The variable is supported only when using OpenSSL version 3.0 or higher. With older versions, the variable value will be an empty string.

<a id="v-ssl-curves"></a>

### `$ssl_curves`

returns the list of curves supported by the client. Known curves are listed by names, unknown are shown in hexadecimal, for example:

> 0x001d:prime256v1:secp521r1:secp384r1

#### NOTE
The variable is supported only when using OpenSSL version 1.0.2 or higher. With older versions, the variable value will be an empty string.

The variable is available only for new sessions.

<a id="v-ssl-early-data"></a>

### `$ssl_early_data`

returns "1" if TLS 1.3 [early data](#ssl-early-data) is used and the handshake is not complete, otherwise "".

<a id="v-ssl-encrypted-hello"></a>

### `$ssl_encrypted_hello`

returns "1" if Encrypted Client Hello (ECH) is used, otherwise "".

<a id="v-ssl-protocol"></a>

### `$ssl_protocol`

returns the protocol of an established SSL connection.

<a id="v-ssl-server-cert-type"></a>

### `$ssl_server_cert_type`

takes the values `RSA`, `DSA`, `ECDSA`, `ED448`,
`ED25519`, `SM2`, `RSA-PSS`, or `unknown` depending
on the type of server certificate and key.

<a id="v-ssl-server-name"></a>

### `$ssl_server_name`

returns the server name requested through [SNI](http://en.wikipedia.org/wiki/Server_Name_Indication).

<a id="v-ssl-session-id"></a>

### `$ssl_session_id`

returns the session identifier of an established SSL connection.

<a id="v-ssl-session-reused"></a>

### `$ssl_session_reused`

returns "r" if an SSL session was reused, or "." otherwise.

<a id="v-ssl-sigalg"></a>

### `$ssl_sigalg`

returns the [signature algorithm](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-16) for the server certificate for an established SSL connection.

#### NOTE
The variable is supported only when using OpenSSL version 3.5 or higher. With older versions, the variable value will be an empty string.

#### NOTE
The variable is available only for new sessions.