ACME#

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

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

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

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

http {

    resolver 127.0.0.53; # требуется для директивы 'acme_client'

    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#

Изменено в версии 1.11.0.

Изменено в версии 1.12.0.

Синтаксис

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.

Примечание

Для тестирования удостоверяющие центры обычно предоставляют отдельные тестовые среды. Например, среда тестирования 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

Задает максимальный допустимый размер файла нового сертификата в байтах, чтобы зарезервировать место для нового сертификата в разделяемой памяти; чем больше число доменов, для которых запрашивается сертификат, тем больше требуется места. Этот параметр не ограничивает размер ответа 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.

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.

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.

Изменено в версии 1.11.1.

Синтаксис

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.