ACME#

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

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

Шаги для включения запроса сертификатов в конфигурации:

  1. Настройте клиент ACME в блоке http с помощью директивы acme_client, задающей уникальное имя клиента и другие параметры; можно настроить несколько клиентов ACME.

  2. Укажите домены, для которых запрашиваются сертификаты: для доменных имен, перечисленных во всех директивах server_name всех блоков server с директивами acme, указывающими на один и тот же клиент ACME, будет выдан единый сертификат.

  3. Обеспечьте прием вызовов ACME, открыв порт 80; остальное сделает модуль. Сейчас Angie поддерживает проверку доменных имен только по HTTP, что требует ответа на специальный запрос от удостоверяющего центра (CA); это так называемый вызов ACME.

  4. Настройте 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_<имя> и $acme_cert_key_<имя>. Они содержат соответствующие файлы, которые используются с 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#

Синтаксис

acme имя;

По умолчанию

—

Контекст

server

Для всех доменов, указанных в директивах 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#

Синтаксис

acme_client имя uri [enabled=on | off] [key_type=тип] [key_bits=число] [email=email] [max_cert_size=число] [renew_before_expiry=время] [retry_after_error=off|время];

По умолчанию

—

Контекст

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.

enabled

Включает или отключает клиент; это полезно, например, для временного отключения клиента без его удаления из конфигурации.

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

key_type

Тип алгоритма закрытого ключа для сертификата. Допустимые значения: rsa, ecdsa.

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

key_bits

Количество битов в ключе сертификата. По умолчанию: 256 для ecdsa, 2048 для rsa.

email

Необязательный адрес электронной почты для обратной связи; используется при создании учетной записи на сервере CA.

max_cert_size

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

Если в момент запуска сертификат уже существует, но его размер превышает значение max_cert_size, значение max_cert_size динамически увеличивается до размера существующего файла сертификата.

Если размер сертификата, полученного при обновлении, превышает max_cert_size, процесс обновления завершится с ошибкой.

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

renew_before_expiry

Время до истечения срока действия сертификата, когда должно начаться его обновление.

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

retry_after_error

Время до повторной попытки, если получить сертификат не удалось. Если задано значение off, клиент не будет снова пытаться получить сертификат после ошибки.

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

acme_client_path#

Синтаксис

acme_client_path путь;

По умолчанию

—

Контекст

http

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

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

$acme_cert_<имя>#

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

$acme_cert_key_<имя>#

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

Важно

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