ACME#
Обеспечивает автоматическое получение сертификатов с использованием протокола ACME.
При сборке из исходного кода модуль не собирается по умолчанию; его необходимо
включить с помощью параметра сборки
--with-http_acme_module
.
В пакетах и образах из
наших репозиториев
модуль включен в сборку.
Шаги для включения запроса сертификатов в конфигурации:
Настройте клиент ACME в блоке
http
с помощью директивы acme_client, задающей уникальное имя клиента и другие параметры; можно настроить несколько клиентов ACME.Укажите домены, для которых запрашиваются сертификаты: для доменных имен, перечисленных во всех директивах server_name всех блоков
server
с директивами acme, указывающими на один и тот же клиент ACME, будет выдан единый сертификат.Обеспечьте прием вызовов ACME, открыв порт 80; остальное сделает модуль. Сейчас Angie поддерживает проверку доменных имен только по HTTP, что требует ответа на специальный запрос от удостоверяющего центра (CA); это так называемый вызов ACME.
Настройте SSL с использованием полученного сертификата и ключа: Модуль делает сертификаты и ключи доступными в виде встроенных переменных, которые можно использовать в конфигурации для заполнения ssl_certificate и ssl_certificate_key.
Детали реализации#
Ключи и сертификаты клиентов хранятся
в кодировке PEM
в соответствующих подкаталогах каталога,
заданного с помощью параметра сборки
--http-acme-client-path
:
$ ls /var/lib/angie/acme/example/
account.key certificate.pem private.key
Клиенту ACME требуется учетная запись на сервере CA.
Для ее создания и управления ею клиент использует закрытый ключ
(account.key
);
если ключа у него еще нет, ключ создается при запуске.
Затем клиент использует его для регистрации учетной записи на сервере.
Примечание
Если у вас уже есть ключ учетной записи, поместите его в подкаталог клиента перед запуском для повторного использования учетной записи.
Клиент ACME также использует отдельный ключ
(private.key
) для запросов на подпись сертификата (CSR);
если нужно, этот ключ сертификата также создается автоматически при запуске.
При запуске клиент запрашивает сертификат, если его еще нет,
подписывая и отправляя CSR для всех доменов, которыми он управляет, серверу CA.
Сервер проверяет владение доменом по HTTP и выдает сертификат,
который клиент сохраняет локально (certificate.pem
).
Когда приближается завершение срока действия сертификата или изменяется список доменов, клиент подписывает и отправляет еще один CSR на сервер CA. Сервер снова проверяет владение и выдает новый сертификат, который клиент устанавливает локально, заменяя предыдущий.
Пример конфигурации#
Здесь клиент ACME с именем example
управляет доменами example.com
и www.example.com
.
Сертификат и его ключ
доступны через префиксные переменные
$acme_cert_<name> и $acme_cert_key_<name>.
Они содержат соответствующие файлы,
которые используются
с ssl_certificate и ssl_certificate_key:
http {
resolver 127.0.0.53; # требуется для директивы 'acme_client'
acme_client example https://acme-v02.api.letsencrypt.org/directory;
server {
listen 80; # Может стоять в другом блоке 'server'
# с другим списком доменов
# или даже без него
listen 443 ssl;
server_name example.com www.example.com;
acme example;
ssl_certificate $acme_cert_example;
ssl_certificate_key $acme_cert_key_example;
}
}
Как уже отмечалось, порт 80 должен быть открыт для приема вызовов ACME по HTTP. Однако, как указывает предыдущий пример, директива listen для этого порта может стоять в отдельном блоке server. Если существующего блока с такой директивой нет, можно ограничить новый блок одними только вызовами ACME:
server {
listen 80;
return 444; # Нет ответа, соединение закрыто
}
Почему это работает?
Модуль перехватывает запросы к /.well-known/acme-challenge/<TOKEN>
после чтения заголовков, но до выбора виртуального сервера
и обработки директив rewrite и location.
Такие перехваченные запросы обрабатываются, если значение TOKEN
соответствует ожидаемому для конкретного вызова.
Обращения к директории не будет; запрос полностью обрабатывается модулем.
Директивы#
acme#
Для всех доменов, указанных в директивах server_name
во всех блоках server,
которые ссылаются на клиент ACME с именем имя,
будет получен единый сертификат;
если изменится конфигурация server_name
,
сертификат будет обновлен для учета изменений.
Примечание
Сейчас домены со звездочкой и домены, заданные через регулярные выражения, не поддерживаются и будут пропущены.
Эта директива может быть указана несколько раз для загрузки сертификатов разных типов, например 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#
|
|
По умолчанию |
— |
http |
Определяет клиент ACME с глобально уникальным именем. Оно должно быть допустимым для каталога и будет использоваться без учета регистра.
Вторым обязательным параметром является uri каталога ACME. Например, URI каталога Let's Encrypt ACME указан как https://acme-v02.api.letsencrypt.org/directory.
Чтобы директива работала, в том же контексте должен быть настроен resolver.
Примечание
Для тестирования удостоверяющие центры обычно предоставляют отдельные тестовые среды. Например, среда тестирования Let's Encrypt — https://acme-staging-v02.api.letsencrypt.org/directory.
|
Включает или отключает клиент; это полезно, например, для временного отключения клиента без его удаления из конфигурации. По умолчанию: |
|
Тип алгоритма закрытого ключа для сертификата.
Допустимые значения: По умолчанию: |
|
Количество битов в ключе сертификата.
По умолчанию: 256 для |
|
Необязательный адрес электронной почты для обратной связи; используется при создании учетной записи на сервере CA. |
|
Время до истечения срока действия сертификата, когда должно начаться его обновление. По умолчанию: |
|
Время до повторной попытки,
если получить сертификат не удалось.
Если задано значение По умолчанию: |
acme_client_path#
Переопределяет путь к каталогу для хранения сертификатов и ключей,
заданному при сборке с помощью параметра сборки
--http-acme-client-path
.
Встроенные переменные#
$acme_cert_<name>
#
Содержимое последнего файла сертификата (если он есть), полученного клиентом с этим именем.
$acme_cert_key_<name>
#
Содержимое файла ключа сертификата, используемого клиентом с этим именем.
Важно
Файл сертификата доступен, только если клиент ACME получил хотя бы один сертификат, а вот файл ключа доступен сразу после запуска.