<!-- review: finished -->

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

# SSL

Обеспечивает необходимую поддержку для работы прокси-сервера по протоколу SSL/TLS.

При [сборке из исходного кода](https://angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) модуль не собирается по умолчанию; его необходимо
включить с помощью [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#configure)
`‑‑with‑stream_ssl_module`.

В пакетах и образах из
[наших репозиториев](https://angie.software//angie/docs/installation/index.md#install-packages)
модуль включен в сборку.

#### NOTE
Для этого модуля нужна библиотека OpenSSL.

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

## Пример конфигурации

Для уменьшения загрузки процессора рекомендуется

* установить число [рабочих процессов](https://angie.software//angie/docs/configuration/modules/core.md#worker-processes) равным числу процессоров,
* включить [разделяемый кэш](#s-ssl-session-cache) сессий,
* выключить [встроенный кэш](#s-ssl-session-cache) сессий
* и, возможно, увеличить [время жизни](#s-ssl-session-timeout) сессии (по умолчанию 5 минут):

```nginx
worker_processes auto;

stream {

    #...

    server {
        listen              12345 ssl;

        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-80"></a>

## Директивы

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

<a id="s-ssl-alpn"></a>

### ssl_alpn

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_alpn` протокол ...;   |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию                                                                             | —                          |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server             |

Задает список поддерживаемых протоколов [ALPN](https://datatracker.ietf.org/doc/html/rfc7301). Один из протоколов должен быть [согласован](#v-s-ssl-alpn-protocol), если клиент использует ALPN:

```nginx
map $ssl_alpn_protocol $proxy {
    h2                 127.0.0.1:8001;
    http/1.1           127.0.0.1:8002;
}

server {
    listen      12346;
    proxy_pass  $proxy;
    ssl_alpn    h2 http/1.1;
}
```

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

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

### ssl_certificate

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_certificate` файл;   |
|------------------------------------------------------------------------------------------|---------------------------|
| По умолчанию                                                                             | —                         |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server            |

Указывает файл с сертификатом в формате PEM для данного сервера. Если вместе с основным сертификатом нужно указать промежуточные, то они должны находиться в этом же файле в следующем порядке — сначала основной сертификат, а затем промежуточные. В этом же файле может находиться секретный ключ в формате PEM.

Директива может быть указана несколько раз для загрузки сертификатов разных типов, например RSA и ECDSA:

```nginx
server {
    listen              12345 ssl;

    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;

#    ...
}
```

Возможность задавать отдельные цепочки сертификатов для разных сертификатов есть только в OpenSSL 1.0.2 и выше. Для более старых версий следует указывать только одну цепочку сертификатов.

#### NOTE
В имени файла можно использовать переменные при использовании OpenSSL 1.0.2 и выше:

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

При использовании переменных сертификат загружается при каждой операции SSL-рукопожатия, что может отрицательно влиять на производительность.

Вместо `файла` можно указать значение "data:$переменная", при котором
сертификат загружается из переменной без использования промежуточных файлов.

Ненадлежащее использование подобного синтаксиса может быть небезопасно, например данные секретного ключа могут попасть в [лог ошибок](https://angie.software//angie/docs/configuration/modules/core.md#error-log).

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

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

### ssl_certificate_compression

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_certificate_compression` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-----------------------------------------------|
| По умолчанию                                                                             | `ssl_certificate_compression off;`            |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server                                |

Разрешает сжатие TLS 1.3 [сертификатов сервера](https://datatracker.ietf.org/doc/html/rfc8879).

#### NOTE
Директива поддерживается при использовании OpenSSL версии 3.2 и выше; список поддерживаемых алгоритмов сжатия предоставляется библиотекой.

#### NOTE
Директива поддерживается при использовании [BoringSSL](https://boringssl.googlesource.com/boringssl/); список поддерживаемых алгоритмов сжатия включает `zlib`.

Если включен [ssl_stapling](#s-ssl-stapling), сжатие сертификатов отключается.

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

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

### ssl_certificate_key

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_certificate_key` файл;   |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию                                                                             | —                             |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server                |

Указывает файл с секретным ключом в формате PEM для данного виртуального сервера.

#### NOTE
В имени файла можно использовать переменные при использовании OpenSSL 1.0.2 и выше.

Вместо `файла` можно указать значение "engine:имя:id", которое загружает
ключ с указанным id из OpenSSL engine с заданным именем.

Вместо `файла` можно указать значение "store:scheme:id", которое
используется для загрузки ключа с указанным id и URI-схемой scheme,
зарегистрированной в OpenSSL provider, например [pkcs11](https://datatracker.ietf.org/doc/html/rfc7512).

Вместо `файла` также можно указать значение "data:$переменная", при
котором секретный ключ загружается из переменной без использования промежуточных
файлов. При этом следует учитывать, что ненадлежащее использование подобного
синтаксиса может быть небезопасно, например данные секретного ключа могут
попасть в [лог ошибок](https://angie.software//angie/docs/configuration/modules/core.md#error-log).

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

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

### ssl_ciphers

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ciphers` шифры;            |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию                                                                             | `ssl_ciphers HIGH:!aNULL:!MD5;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server                  |

Описывает разрешенные шифры. Шифры задаются в формате, поддерживаемом библиотекой OpenSSL, например:

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

Список шифров зависит от установленной версии OpenSSL.
Полный список можно посмотреть с помощью команды `openssl ciphers`.

#### WARNING
Директива `ssl_ciphers`  *не* настраивает шифры для TLS 1.3 при
использовании OpenSSL. Для настройки шифров TLS 1.3 в OpenSSL используйте
директиву [ssl_conf_command](#s-ssl-conf-command), добавленную для расширенной
конфигурации SSL.

- В LibreSSL шифры TLS 1.3  *можно* настраивать с помощью
  `ssl_ciphers`.
- В BoringSSL шифры TLS 1.3 настроить невозможно.

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

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

### ssl_client_certificate

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_client_certificate` файл;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию                                                                             | —                                |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server                   |

Задает файл с доверенными сертификатами CA в формате PEM, которые используются
для [проверки](#s-ssl-verify-client) клиентских сертификатов и ответов
OCSP, если включен [ssl_stapling](#s-ssl-stapling).

Список сертификатов будет отправляться клиентам. Если это нежелательно, можно воспользоваться директивой [ssl_trusted_certificate](#s-ssl-trusted-certificate).

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

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

### ssl_conf_command

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_conf_command` имя значение;   |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию                                                                             | —                                  |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server                     |

Задает произвольные [конфигурационные команды](https://docs.openssl.org/master/man3/SSL_CONF_cmd/) OpenSSL.

#### NOTE
Директива поддерживается при использовании OpenSSL 1.0.2 и выше.
Чтобы настроить шифры TLS 1.3 в OpenSSL, используйте команду `ciphersuites`.

На одном уровне может быть указано несколько директив ssl_conf_command:

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

Директивы наследуются с предыдущего уровня конфигурации при условии, что на данном уровне не описаны свои директивы ssl_conf_command.

#### WARNING
Изменение настроек OpenSSL напрямую может привести к неожиданному поведению.

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

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

### ssl_crl

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_crl` файл;   |
|------------------------------------------------------------------------------------------|-------------------|
| По умолчанию                                                                             | —                 |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server    |

Указывает файл с отозванными сертификатами (CRL) в формате PEM, используемыми для [проверки](#s-ssl-verify-client) клиентских сертификатов.

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

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

### ssl_dhparam

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_dhparam` файл;   |
|------------------------------------------------------------------------------------------|-----------------------|
| По умолчанию                                                                             | —                     |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server        |

Указывает файл с параметрами для DHE-шифров.

#### WARNING
По умолчанию параметры не заданы, и соответственно DHE-шифры не будут использоваться.

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

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

### ssl_early_data

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_early_data` `on` | `off`;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию                                                                             | `ssl_early_data off;`            |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server                   |

Разрешает или запрещает TLS 1.3 [early data](https://datatracker.ietf.org/doc/html/rfc8446#section-2.3).

#### NOTE
Директива поддерживается при использовании OpenSSL 1.1.1 и выше или [BoringSSL](https://boringssl.googlesource.com/boringssl/).

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

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

### ssl_encrypted_hello_key

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_encrypted_hello_key` файл;   |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию                                                                             | —                                 |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server                    |

Указывает файл с приватным ключом ECH и списком ECHConfigList в формате PEM.
Директива может быть указана несколько раз.
Требуется сборка OpenSSL или BoringSSL с поддержкой Encrypted Client Hello (ECH),
иначе директива не поддерживается.

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

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

### ssl_ecdh_curve

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ecdh_curve` кривая;   |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию                                                                             | `ssl_ecdh_curve auto;`     |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server             |

Задает кривую для ECDHE-шифров.

#### NOTE
При использовании OpenSSL 1.0.2 и выше можно указывать несколько кривых, например:

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

Специальное значение `auto` соответствует встроенному в библиотеку OpenSSL списку кривых для OpenSSL 1.0.2 и выше, или prime256v1 для более старых версий.

#### NOTE
При использовании OpenSSL 1.0.2 и выше директива задает список кривых, поддерживаемых сервером. Поэтому для работы ECDSA-сертификатов важно, чтобы список включал кривые, используемые в сертификатах.

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

<a id="s-ssl-handshake-timeout"></a>

### ssl_handshake_timeout

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_handshake_timeout` время;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию                                                                             | `ssl_handshake_timeout 60s;`     |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server                   |

Задает таймаут для завершения операции SSL-рукопожатия.

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

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

### ssl_ocsp

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ocsp` `on` | `off` | `leaf`;   |
|------------------------------------------------------------------------------------------|-------------------------------------|
| По умолчанию                                                                             | `ssl_ocsp off;`                     |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | http, server                        |

Включает проверку OCSP для цепочки клиентских сертификатов. Параметр
`leaf` включает проверку только клиентского сертификата.

Для работы проверки OCSP необходимо дополнительно установить значение директивы
[ssl_verify_client](#s-ssl-verify-client) в `on` или `optional`.

Для преобразования имени хоста OCSP-респондера в адрес необходимо дополнительно
задать директиву [resolver](https://angie.software//angie/docs/configuration/modules/stream/index.md#s-resolver).

Пример:

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

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

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

### ssl_ocsp_cache

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ocsp_cache` `off` | [shared:имя:размер];   |
|------------------------------------------------------------------------------------------|-------------------------------------------------|
| По умолчанию                                                                             | `ssl_ocsp_cache off;`                           |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | http, server                                    |

Задает имя и размер кэша, который хранит статус клиентских сертификатов для
проверки OCSP-ответов. Кэш разделяется между всеми рабочими процессами. Кэш с
одинаковым названием может использоваться в нескольких виртуальных серверах.

Параметр `off` запрещает использование кэша.

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

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

### ssl_ocsp_responder

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ocsp_responder` uri;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию                                                                             | —                           |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | http, server                |

Переопределяет URI OCSP-респондера, указанный в расширении сертификата
["Authority Information Access"](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.2.1) для
[проверки](#s-ssl-ocsp) клиентских сертификатов.

Поддерживаются только OCSP-респондеры на основе `http://`:

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

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

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

### ssl_ntls

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ntls` `on` | `off`;   |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию                                                                             | `ssl_ntls off;`            |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server             |

Включает серверную поддержку NTLS при использовании TLS библиотеки [TongSuo](https://github.com/Tongsuo-Project/Tongsuo)

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

#### NOTE
Angie необходимо собрать с использованием параметра конфигурации `--with-ntls`, с соответствующей SSL библиотекой с поддержкой NTLS

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

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

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

### ssl_password_file

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_password_file` файл;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию                                                                             | —                           |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server              |

Задает файл с паролями от [секретных ключей](#s-ssl-certificate-key), где каждый пароль указан на отдельной строке. Пароли применяются по очереди в момент загрузки ключа.

Пример:

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

    server {
        listen 127.0.0.1:12345;
        ssl_certificate_key /etc/keys/first.key;
    }

    server {
        listen 127.0.0.1:12346;

        # вместо файла можно указать именованный канал
        ssl_password_file /etc/keys/fifo;
        ssl_certificate_key /etc/keys/second.key;
    }
}
```

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

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

### ssl_prefer_server_ciphers

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_prefer_server_ciphers` `on` | `off`;   |
|------------------------------------------------------------------------------------------|---------------------------------------------|
| По умолчанию                                                                             | `ssl_prefer_server_ciphers off;`            |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server                              |

При использовании протоколов SSLv3 и TLS устанавливает приоритет серверных шифров над клиентскими.

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

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

### ssl_protocols

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_protocols` [`SSLv2`] [`SSLv3`] [`TLSv1`] [`TLSv1.1`] [`TLSv1.2`] [`TLSv1.3`];   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
| По умолчанию                                                                             | `ssl_protocols TLSv1.2 TLSv1.3;`                                                     |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server                                                                       |

#### Versionchanged
Изменено в версии 1.2.0: Параметр `TLSv1.3` добавлен к используемым по умолчанию.

Разрешает указанные протоколы.

#### NOTE
Параметры TLSv1.1 и TLSv1.2 работают только при использовании OpenSSL 1.0.1 и выше.

Параметр TLSv1.3 работает только при использовании OpenSSL 1.1.1 и выше.

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

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

### ssl_session_cache

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_session_cache` `off` | `none` | [builtin[:размер]] [shared:название:размер];   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------|
| По умолчанию                                                                             | `ssl_session_cache none;`                                                           |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server                                                                      |

Задает тип и размеры кэшей для хранения параметров сессий. Тип кэша может быть следующим:

| `off`     | жесткое запрещение использования кэша сессий: Angie явно сообщает клиенту, что сессии не могут использоваться повторно.                                                                                                                                                                                                                                                                                                                                                                            |
|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `none`    | мягкое запрещение использования кэша сессий: Angie сообщает клиенту, что сессии могут использоваться повторно, но на самом деле не хранит параметры сессии в кэше.                                                                                                                                                                                                                                                                                                                                 |
| `builtin` | встроенный в OpenSSL кэш, используется в рамках только одного рабочего процесса. Размер кэша задается в сессиях. Если размер не задан, то он равен 20480 сессиям. Использование встроенного кэша может вести к фрагментации памяти.                                                                                                                                                                                                                                                                |
| `shared`  | кэш, разделяемый между всеми рабочими процессами. Размер кэша задается в байтах, в 1 мегабайт может поместиться около 4000 сессий. У каждого разделяемого кэша должно быть произвольное название. Кэш с одинаковым названием может использоваться в нескольких серверах. Также он используется для автоматического создания, хранения и периодического обновления ключей сессионных билетов TLS, если они не указаны явно с помощью директивы [ssl_session_ticket_key](#s-ssl-session-ticket-key). |

Можно использовать одновременно оба типа кэша, например:

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

однако использование только разделяемого кэша без встроенного должно быть более эффективным.

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

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

### ssl_session_ticket_key

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_session_ticket_key` файл;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию                                                                             | —                                |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server                   |

Задает файл с секретным ключом, применяемым при шифровании и расшифровке сессионных билетов TLS. Директива необходима, если один и тот же ключ нужно использовать на нескольких серверах. По умолчанию используется случайно сгенерированный ключ.

Если указано несколько ключей, то только первый ключ используется для шифрования сессионных билетов TLS. Это позволяет настроить ротацию ключей, например:

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

Файл должен содержать 80 или 48 байт случайных данных и может быть создан следующей командой:

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

В зависимости от размера файла для шифрования будет использоваться либо AES256 (для 80-байтных ключей), либо AES128 (для 48-байтных ключей).

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

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

### ssl_session_tickets

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_session_tickets` `on` | `off`;   |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию                                                                             | `ssl_session_tickets on;`             |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server                        |

Разрешает или запрещает возобновление сессий при помощи [сессионных билетов TLS](https://datatracker.ietf.org/doc/html/rfc5077).

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

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

### ssl_session_timeout

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_session_timeout` время;   |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию                                                                             | `ssl_session_timeout 5m;`      |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server                 |

Задает время, в течение которого клиент может повторно использовать параметры сессии.

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

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

### ssl_stapling

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_stapling` `on` | `off`;   |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию                                                                             | `ssl_stapling off;`            |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | http, server                   |

Разрешает или запрещает [прикрепление OCSP-ответов](https://datatracker.ietf.org/doc/html/rfc6066#section-8) сервером. Пример:

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

Для работы OCSP-прикрепления должен быть известен сертификат издателя
сертификата сервера. Если в заданном директивой [ssl_certificate](#s-ssl-certificate) файле не
содержится промежуточных сертификатов, то сертификат издателя сертификата
сервера следует поместить в файл, заданный директивой
[ssl_trusted_certificate](#s-ssl-trusted-certificate).

#### WARNING
Для преобразования имени хоста OCSP-респондера в адрес необходимо
дополнительно задать директиву [resolver](https://angie.software//angie/docs/configuration/modules/stream/index.md#s-resolver).

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

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

### ssl_stapling_file

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_stapling_file` файл;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию                                                                             | —                           |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | http, server                |

Если значение задано, то вместо опроса OCSP-респондера, указанного в сертификате
сервера, ответ берется из указанного файла.

Ответ должен быть в формате DER и может быть сгенерирован командой
`openssl ocsp`.

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

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

### ssl_stapling_responder

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_stapling_responder` `uri`;   |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию                                                                             | —                                 |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | http, server                      |

Переопределяет URI OCSP-респондера, указанный в расширении сертификата
["Authority Information Access"](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.2.1).

Поддерживаются только OCSP-респондеры на основе `http://`:

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

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

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

### ssl_stapling_verify

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_stapling_verify` `on` | `off`;   |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию                                                                             | `ssl_stapling_verify off;`            |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | http, server                          |

Разрешает или запрещает проверку ответов OCSP сервером.

Для работоспособности проверки сертификат издателя сертификата сервера, корневой
сертификат и все промежуточные сертификаты должны быть указаны как доверенные с
помощью директивы [ssl_trusted_certificate](#s-ssl-trusted-certificate).

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

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

### ssl_trusted_certificate

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_trusted_certificate` файл;   |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию                                                                             | —                                 |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server                    |

Задает файл с доверенными сертификатами CA в формате PEM, которые используются для [проверки](#s-ssl-verify-client) клиентских сертификатов.

В отличие от [ssl_client_certificate](#s-ssl-client-certificate), список этих сертификатов не будет отправляться клиентам.

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

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

### ssl_verify_client

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_verify_client` `on` | `off` | `optional` | `optional_no_ca`;   |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------|
| По умолчанию                                                                             | `ssl_verify_client off;`                                            |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server                                                      |

Разрешает проверку клиентских сертификатов. Результат проверки доступен через переменную [$ssl_client_verify](#v-s-ssl-client-verify). Если при проверке клиентского сертификата произошла ошибка или клиент не предоставил требуемый сертификат, соединение закрывается.

| `optional`       | запрашивает клиентский сертификат, и если сертификат был предоставлен, проверяет его                                                                                                                                         |
|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `optional_no_ca` | запрашивает сертификат клиента, но не требует, чтобы он был подписан доверенным сертификатом CA. Это предназначено для случаев, когда фактическая проверка сертификата осуществляется внешним по отношению к Angie сервисом. |

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

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

### ssl_verify_depth

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_verify_depth` число;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию                                                                             | `ssl_verify_depth 1;`       |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | stream, server              |

Устанавливает глубину проверки в цепочке клиентских сертификатов.

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

## Встроенные переменные

Модуль stream_ssl поддерживает встроенные переменные:

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

### `$ssl_alpn_protocol`

возвращает протокол, выбранный при помощи ALPN во время SSL-рукопожатия, либо пустую строку.

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

### `$ssl_cipher`

возвращает название используемого шифра для установленного SSL-соединения.

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

### `$ssl_ciphers`

возвращает список шифров, поддерживаемых клиентом. Известные шифры указаны по имени, неизвестные указаны в шестнадцатеричном виде, например:

> AES128-SHA:AES256-SHA:0x00ff

#### NOTE
Переменная полностью поддерживается при использовании OpenSSL версии 1.0.2 и выше. При использовании более старых версий переменная доступна только для новых сессий и может содержать только известные шифры.

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

### `$ssl_client_cert`

возвращает клиентский сертификат для установленного SSL-соединения в формате PEM перед каждой строкой которого, кроме первой, вставляется символ табуляции.

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

### `$ssl_client_fingerprint`

возвращает SHA1-отпечаток клиентского сертификата для установленного SSL-соединения.

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

### `$ssl_client_i_dn`

возвращает строку "issuer DN" клиентского сертификата для установленного SSL-соединения согласно [RFC 2253](https://datatracker.ietf.org/doc/html/rfc2253).

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

### `$ssl_client_raw_cert`

возвращает клиентский сертификат для установленного SSL-соединения в формате PEM.

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

### `$ssl_client_s_dn`

возвращает строку "subject DN" клиентского сертификата для установленного SSL-соединения согласно [RFC 2253](https://datatracker.ietf.org/doc/html/rfc2253).

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

### `$ssl_client_serial`

возвращает серийный номер клиентского сертификата для установленного SSL-соединения.

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

### `$ssl_client_sigalg`

возвращает [алгоритм подписи](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-16) для сертификата клиента в установленном SSL-соединении.

#### NOTE
Переменная поддерживается только при использовании OpenSSL версии 3.5 и выше. При использовании более старых версий значением переменной будет пустая строка.

#### NOTE
Переменная доступна только для новых сессий.

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

### `$ssl_client_v_end`

возвращает дату окончания срока действия клиентского сертификата.

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

### `$ssl_client_v_remain`

возвращает число дней, оставшихся до истечения срока действия клиентского сертификата.

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

### `$ssl_client_v_start`

возвращает дату начала срока действия клиентского сертификата.

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

### `$ssl_client_verify`

возвращает результат проверки клиентского сертификата: `SUCCESS`, `FAILED:reason` и, если сертификат не был предоставлен, `NONE`.

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

### `$ssl_curve`

возвращает согласованную кривую, использованную для обмена ключами во время SSL-рукопожатия. Известные кривые указаны по имени, неизвестные указаны в шестнадцатеричном виде, например:

> prime256v1

#### NOTE
Переменная поддерживается при использовании OpenSSL версии 3.0 и выше. При использовании более старых версий значением переменной будет пустая строка.

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

### `$ssl_curves`

возвращает список кривых, поддерживаемых клиентом. Известные кривые указаны по имени, неизвестные указаны в шестнадцатеричном виде, например:

> 0x001d:prime256v1:secp521r1:secp384r1

#### NOTE
Переменная поддерживается при использовании OpenSSL версии 1.0.2 и выше. При использовании более старых версий значением переменной будет пустая строка.

Переменная доступна только для новых сессий.

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

### `$ssl_early_data`

возвращает `1`, если используется TLS 1.3 [early data](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-early-data) и операция SSL-рукопожатия не завершена, иначе "".

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

### `$ssl_encrypted_hello`

возвращает `1`, если используется Encrypted Client Hello (ECH), иначе "".

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

### `$ssl_protocol`

возвращает протокол установленного SSL-соединения.

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

### `$ssl_server_cert_type`

принимает значения `RSA`, `DSA`, `ECDSA`, `ED448`,
`ED25519`, `SM2`, `RSA-PSS` или `unknown` в зависимости
от типа сертификата и ключа сервера.

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

### `$ssl_server_name`

возвращает имя сервера, запрошенное через [SNI](http://en.wikipedia.org/wiki/Server_Name_Indication).

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

### `$ssl_session_id`

возвращает идентификатор сессии установленного SSL-соединения.

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

### `$ssl_session_reused`

возвращает `r`, если сессия была использована повторно, иначе ".".

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

### `$ssl_sigalg`

возвращает [алгоритм подписи](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-16) для сертификата сервера в установленном SSL-соединении.

#### NOTE
Переменная поддерживается только при использовании OpenSSL версии 3.5 и выше. При использовании более старых версий значением переменной будет пустая строка.

#### NOTE
Переменная доступна только для новых сессий.