Ctrl+K
Приглашаем в команду разработчика на языке С и тестировщика со знанием Perl

Ctrl+K
Angie в Telegram

Модуль http_acme

Модуль http_acme#

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

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

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

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

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

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

  3. Убедитесь, что принимаются вызовы ACME: сейчас Angie поддерживает только проверку доменных имен по HTTP, что требует ответа на специальный запрос на порту 80 от удостоверяющего центра (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_<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; # Нет ответа, соединение закрыто
}

Директивы#

acme#

Синтаксис:

acme имя;

Умолчание:

—

Контекст:

server

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

Примечание

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

acme_client#

Синтаксис:

acme_client имя uri [enabled=on|off] [key_type=тип] [key_bits=число] [email=email] [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.

email

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

renew_before_expiry

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

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

retry_after_error

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

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

acme_client_path#

Синтаксис:

acme_client_path путь;

Умолчание:

—

Контекст:

http

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

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

$acme_cert_<name>#

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

$acme_cert_key_<name>#

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

Важно

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

Содержание