ACME#

Обеспечивает автоматическое получение сертификатов с использованием протокола ACME.

При сборке из исходного кода модуль не собирается по умолчанию; его необходимо включить с помощью параметра сборки --with-http_acme_module.

В пакетах и образах из наших репозиториев модуль включен в сборку.

Связанные руководства

Настройка ACME: все методы проверки и миграция с Certbot.
Первые шаги: первый сертификат без внешнего клиента.

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

В этом примере ACME-клиент с именем example автоматически получает и обновляет сертификат для example.com и www.example.com, используя HTTP-проверку по умолчанию:

http {

    acme_client example https://acme-v02.api.letsencrypt.org/directory;

    server {

        listen 80; # Необязательно, если нет сервера,
                   # слушающего порт HTTP‑проверки
                   # (см. директиву 'acme_http_port')

        listen 443 ssl;

        server_name example.com www.example.com;
        acme example;

        ssl_certificate $acme_cert_example;
        ssl_certificate_key $acme_cert_key_example;
    }
}

Другие методы проверки (DNS, ALPN, с помощью хуков) и подробные инструкции по настройке см. в разделе Настройка ACME.

Директивы#

acme#

Синтаксис	`acme` имя;
По умолчанию	—
Контекст	server

Указывает клиент ACME, который получает сертификат для допустимых идентификаторов сертификата этого блока server. Единый сертификат охватывает все допустимые доменные имена и IP-адреса, указанные в директивах server_name всех блоков server, которые ссылаются на клиент с именем имя; если изменится конфигурация server_name, сертификат обновляется для учета изменений.

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

Примечание

Эта директива определяет только то, какие допустимые идентификаторы сертификата включаются в запросы; она не влияет на то, где можно использовать сертификат. Любой блок server может ссылаться на сертификат через переменную $acme_cert_<имя>, независимо от того, содержит ли блок директиву acme. Удаление acme из блока server просто исключает значения server_name этого блока из последующих запросов сертификатов, но не запрещает блоку использовать сертификат.

Примечание

Сейчас домены, заданные через регулярные выражения, не поддерживаются и будут пропускаться.

Домены со звездочкой поддерживаются только в режиме challenge=dns в acme_client.

Адреса IPv4 и IPv6 поддерживаются, если клиент не использует challenge=dns. При выборе DNS-проверки IP-адреса пропускаются.

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

server {

    listen 443 ssl;
    server_name example.com www.example.com;

    ssl_certificate $acme_cert_rsa;
    ssl_certificate_key $acme_cert_key_rsa;

    ssl_certificate $acme_cert_ecdsa;
    ssl_certificate_key $acme_cert_key_ecdsa;

    acme rsa;
    acme ecdsa;
}

acme_client#

Синтаксис	`acme_client` имя uri [`enabled=on` \| `off`] [`key_type=`тип] [`key_bits=`число] [`email=`email] [`max_cert_size=`размер] [`max_key_auth_size=`размер] [`renew_before_expiry=`время] [`renew_on_load`] [`retry_after_error=`off\|время] [`challenge=dns` \| `http` \| `alpn`] [`profile=`имя] [`account_key=`файл] [`eab=`id[:alg]:key];
По умолчанию	—
Контекст	http

Определяет клиент ACME с глобально уникальным именем. Оно должно быть допустимым для каталога, представляет собой строку с переменными и будет использоваться без учета регистра.

Каждый клиент управляет одним сертификатом; чтобы получить отдельные сертификаты, настройте несколько блоков acme_client (см. Отдельные сертификаты для разных доменов).

Совет

Задаваемое здесь имя клиента идентифицирует его в конфигурации Angie, позволяя сопоставить между собой директивы acme_client, acme и переменные модуля, использующие это имя; не следует путать его с именем вашего домена или сервера.

Вторым обязательным параметром является uri каталога ACME. Например, URI каталога Let's Encrypt ACME указан как https://acme-v02.api.letsencrypt.org/directory.

Примечание

Модуль ACME добавляет в контекст client именованный location @acme, который можно использовать для настройки запросов к каталогу ACME; По умолчанию в этом location задана директива proxy_pass с uri каталога, к которой можно добавить другие настройки из модуля Proxy.

Клиент определяет адрес каталога по его имени через resolver, который по умолчанию обращается к DNS-серверам из /etc/resolv.conf.

Примечание

Для тестирования удостоверяющие центры обычно предоставляют отдельные тестовые среды. Например, среда тестирования Let's Encrypt — https://acme-staging-v02.api.letsencrypt.org/directory.

`enabled`	Включает или отключает обновление сертификатов для клиента; это полезно, например, для временной приостановки без удаления клиента из конфигурации. По умолчанию: `on`.
`key_type`	Тип алгоритма закрытого ключа для сертификата. Допустимые значения: `rsa`, `ecdsa`. По умолчанию: `ecdsa`.
`key_bits`	Количество битов в ключе сертификата. По умолчанию: 256 для `ecdsa`, 2048 для `rsa`.
`email`	Необязательный адрес электронной почты для обратной связи; используется при создании учетной записи на сервере CA.
`max_cert_size`	Задает максимальный допустимый размер файла нового сертификата, чтобы зарезервировать место для нового сертификата в разделяемой памяти; чем больше число доменов, для которых запрашивается сертификат, тем больше требуется места. Размер задается в байтах; также допустимы суффиксы `k` и `m`. Этот параметр не ограничивает размер ответа ACME‑сервера; для этого используется acme_max_response_size. Если параметр не задан, Angie вычисляет приблизительный размер на основе списка доменов и использует его при выделении разделяемой памяти. Если в момент запуска сертификат уже существует, но его размер превышает значение `max_cert_size`, значение `max_cert_size` динамически увеличивается до размера существующего файла сертификата. Если размер сертификата, полученного при обновлении, превышает `max_cert_size`, процесс обновления завершится с ошибкой. По умолчанию: вычисляется автоматически.
`max_key_auth_size`	Ограничивает размер строки авторизации ключа, которую Angie хранит в разделяемой памяти для ACME-проверки. Если ACME-сервер возвращает строку авторизации ключа большего размера, запрос завершается ошибкой с рекомендацией увеличить `max_key_auth_size`. Хотя параметр задается в строке `acme_client`, это единая настройка, общая для всех клиентов в блоке `http`. По умолчанию: `2k`.
`renew_before_expiry`	Время до истечения срока действия сертификата, когда должно начаться его обновление. По умолчанию: `30d`.
`renew_on_load`	Указывает, что сертификат следует принудительно обновлять при каждой загрузке конфигурации.
`retry_after_error`	Время до повторной попытки, если получить сертификат не удалось. Если задано значение `off`, клиент не будет снова пытаться получить сертификат после ошибки. По умолчанию: `2h`. Эта задержка действует, пока Angie работает; перезагрузка конфигурации сразу же повторно запрашивает сертификат.
`challenge`	Задает тип верификации для ACME-клиента. Допустимые значения: `dns`, `http`, `alpn`. Значение `alpn` включает проверку TLS-ALPN-01 и требует, чтобы Angie был собран с OpenSSL с поддержкой ALPN (не поддерживается сборками с BoringSSL и AWS-LC). По умолчанию: `http`.
`profile`	Запрашивает у удостоверяющего центра определенный ACME-профиль. Профиль — это заданный удостоверяющим центром вариант настроек сертификата и проверки, например срок действия сертификата или типы идентификаторов, которые можно запрашивать. Так, доступные профили Let's Encrypt описаны в документации по профилям. ACME-сервер должен объявлять этот профиль в метаданных своего каталога; иначе клиент не сможет получить сертификат.
`account_key`	Указывает полный путь к файлу, содержащему ключ в формате PEM. Это удобно, если вы хотите использовать существующий ключ аккаунта вместо автоматической генерации, или если вам нужно использовать один ключ для нескольких ACME-клиентов. Поддерживаемые типы ключей: RSA-ключи с длиной, кратной 8, в диапазоне от 2048 до 8192 бит. ECDSA-ключи с длиной 256, 384 или 521 бит. При указании параметра `account_key` следует убедиться, что файл ключа действительно существует. Если файл отсутствует, Angie попытается создать его по указанному пути. Следует учитывать, что ключи для ACME-клиентов создаются в том порядке, в каком соответствующие клиенты упомянуты в конфигурации в директивах acme_client, acme или acme_hook. Поэтому, если один клиент должен использовать ключ, созданный для другого, этот другой клиент должен стоять в конфигурации раньше. Кроме того, ключи создаются только для клиентов, у которых задан параметр `enabled=on`.
`eab`	Настраивает External Account Binding (EAB) — привязку учетной записи ACME к уже существующей учетной записи на стороне удостоверяющего центра (CA). Значение имеет вид `eab=`id[:alg]:key: id — идентификатор ключа, выданный CA. alg — алгоритм HMAC, используемый для вычисления подписи привязки: `HS256` (по умолчанию), `HS384` или `HS512`. key — Base64URL-кодированный MAC-ключ, связанный с id на стороне CA. Если CA требует привязки к внешней учетной записи, а параметр не задан, клиент сообщает об ошибке и не создает учетную запись ACME. Данные EAB передаются только при регистрации новой учетной записи ACME; существующая учетная запись ACME используется как есть.

acme_client_path#

Синтаксис	`acme_client_path` путь;
По умолчанию	—
Контекст	http

Переопределяет путь к каталогу для хранения сертификатов и ключей, заданному при сборке с помощью параметра сборки --http-acme-client-path.

acme_dns_port#

Синтаксис	`acme_dns_port` порт \| ip[:порт] \| [ip6][:порт];
Значение по умолчанию	`acme_dns_port 53;`
Контекст	http

Указывает порт, который модуль использует для обработки DNS-запросов от ACME-сервера по UDP. Номер порта должен быть в диапазоне от 1 до 65535.

Также поддерживается указание IP-адреса вместе с опциональным портом. Могут быть использованы как IPv4-адреса в виде ip:порт, так и IPv6-адреса в виде [ip6]:порт:

acme_dns_port 8053;
acme_dns_port 127.0.0.1;
acme_dns_port [::1];

Чтобы использовать номер порта 1024 или ниже, мастер-процесс Angie должен работать с привилегиями суперпользователя.

acme_dns_ttl#

Добавлено в версии 1.12.0.

Синтаксис	`acme_dns_ttl` число;
По умолчанию	`acme_dns_ttl 1;`
Контекст	http

Задает время жизни (TTL, в секундах) TXT-записей, которые модуль возвращает в ответах на запросы DNS-проверки от ACME-серверов. Допустимые значения — от 0 до 2147483647, согласно RFC 2181.

Увеличьте значение, если проверка не завершается: некоторые DNS-провайдеры отфильтровывают ответы с таким низким TTL, как значение по умолчанию.

acme_hook#

Синтаксис	`acme_hook` имя [uri];
По умолчанию	—
Контекст	location

Включает проверку домена с помощью хуков для ACME-клиента, заданного параметром имя. Когда для выпуска или обновления сертификата требуется проверка домена, Angie формирует внутренний запрос к именованному location, в котором размещена эта директива. Способ обработки запроса полностью зависит от других директив, заданных в том же location, таких как fastcgi_pass, proxy_pass или любого другого обработчика запросов.

имя

Имя ACME-клиента, для которого этот хук обрабатывает проверку домена.

uri

Строка с переменными; задает URI запроса для вызовов хука.

По умолчанию: /.

Например, следующая конфигурация передает значения переменных хука в приложение FastCGI через URI запроса:

acme_hook example uri=/acme_hook/$acme_hook_name?domain=$acme_hook_domain&key=$acme_hook_keyauth;
fastcgi_param REQUEST_URI $request_uri;
fastcgi_pass ...;

acme_http_port#

Добавлено в версии 1.11.0.

Синтаксис	`acme_http_port` порт \| ip[:порт] \| [ip6][:порт];
Значение по умолчанию	`acme_http_port 80;`
Контекст	http

Указывает порт, который модуль использует для обработки HTTP‑проверок ACME. Номер порта должен быть в диапазоне от 1 до 65535.

Также поддерживается указание IP-адреса вместе с опциональным портом. Могут быть использованы как IPv4-адреса в виде ip:порт, так и IPv6-адреса в виде [ip6]:порт:

acme_http_port 8080;
acme_http_port 127.0.0.1;
acme_http_port [::1];

Если ни один сервер не слушает указанный адрес и порт, модуль создаст отдельный слушающий сокет для HTTP‑проверок.

Чтобы использовать номер порта 1024 или ниже, мастер-процесс Angie должен работать с привилегиями суперпользователя.

acme_max_response_size#

Добавлено в версии 1.11.0.

Синтаксис	`acme_max_response_size` размер;
По умолчанию	`acme_max_response_size 32k;`
Контекст	http

Ограничивает максимальный размер тела ответа ACME‑сервера. Если ответ превышает это значение, запрос завершится ошибкой. Увеличьте значение, если появляются ошибки вида too big subrequest response while sending to client.

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

`$acme_cert_<имя>`#

Содержимое последнего файла сертификата (если он есть), полученного клиентом с этим именем.

`$acme_cert_key_<имя>`#

Содержимое файла ключа сертификата, используемого клиентом с этим именем.

Примечание

Файл сертификата доступен, только если клиент ACME получил хотя бы один сертификат, а вот файл ключа доступен сразу после запуска.

`$acme_hook_challenge`#

Тип проверки. Возможные значения: dns, http, alpn.

`$acme_hook_client`#

Имя ACME-клиента, инициирующего запрос.

`$acme_hook_domain`#

Проверяемый домен. Если это wildcard-домен, он будет передан без префикса *..

`$acme_hook_keyauth`#

Строка авторизации:

При DNS-проверке используется как значение TXT-записи, имя которой формируется как _acme-challenge. + $acme_hook_domain + ..
При HTTP-проверке эта строка должна использоваться в качестве содержимого ответа, запрашиваемого ACME-сервером.

`$acme_hook_name`#

Имя хука. Для разных типов проверки оно может иметь разные значения и смысл:

Значение	Смысл при DNS-проверке	Смысл при HTTP-проверке
`add` (добавление хука)	Необходимо добавить соответствующую TXT-запись в конфигурацию DNS.	Необходимо подготовить ответ на соответствующий HTTP-запрос.
`remove` (удаление хука)	Можно удалить TXT-запись из конфигурации DNS.	Данный HTTP-запрос более не актуален; можно удалить ранее созданный файл со строкой авторизации.

`$acme_hook_token`#

Токен для проверки. При HTTP-проверке используется как имя запрашиваемого файла: /.well-known/acme-challenge/ + $acme_hook_token.

ACME#

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

Директивы#

acme#

acme_client#

acme_client_path#

acme_dns_port#

acme_dns_ttl#

acme_hook#

acme_http_port#

acme_max_response_size#

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

$acme_cert_<имя>#

$acme_cert_key_<имя>#

$acme_hook_challenge#

$acme_hook_client#

$acme_hook_domain#

$acme_hook_keyauth#

$acme_hook_name#

$acme_hook_token#

`$acme_cert_<имя>`#

`$acme_cert_key_<имя>`#

`$acme_hook_challenge`#

`$acme_hook_client`#

`$acme_hook_domain`#

`$acme_hook_keyauth`#

`$acme_hook_name`#

`$acme_hook_token`#