Перейти к содержанию

acme: Модуль автоматического управления сертификатами (ACMEv2) для NGINX

Установка на Debian/Ubuntu

Эти документы относятся к пакету APT nginx-module-acme, предоставляемому репозиторием GetPageSpeed Extras.

  1. Настройте APT-репозиторий, как описано в настройке APT-репозитория.
  2. Установите модуль:
sudo apt-get update
sudo apt-get install nginx-module-acme
Показать дистрибутивы и архитектуры 
| Distro   | Suite             | Component   | Architectures   |
|----------|-------------------|-------------|-----------------|
| debian   | bookworm          | main        | amd64, arm64    |
| debian   | bookworm-mainline | main        | amd64, arm64    |
| debian   | trixie            | main        | amd64, arm64    |
| debian   | trixie-mainline   | main        | amd64, arm64    |
| ubuntu   | focal             | main        | amd64, arm64    |
| ubuntu   | focal-mainline    | main        | amd64, arm64    |
| ubuntu   | jammy             | main        | amd64, arm64    |
| ubuntu   | jammy-mainline    | main        | amd64, arm64    |
| ubuntu   | noble             | main        | amd64, arm64    |
| ubuntu   | noble-mainline    | main        | amd64, arm64    |

Статус проекта: Активно – Проект достиг стабильного, рабочего состояния и активно разрабатывается. Поддержка сообщества Форум сообщества Лицензия Ковенант участников

nginx-acme

nginx-acme это модуль NGINX, реализующий протокол автоматического управления сертификатами (ACMEv2).

Модуль реализует следующие спецификации:

  • RFC8555 (Автоматическая среда управления сертификатами) с ограничениями:
    • Поддерживается только тип задачи HTTP-01
  • RFC8737 (Расширение ACME TLS Application-Layer Protocol Negotiation (ALPN) Challenge)
  • RFC8738 (Расширение ACME IP Identifier Validation)
  • draft-ietf-acme-profiles (Расширение ACME Profiles, версия 00)

Начало работы

Клонирование, настройка и сборка NGINX в ../nginx

cd nginx-acme export NGINX_BUILD_DIR=$(realpath ../nginx/objs) cargo build --release 

Результат будет находиться по адресу `target/release/libnginx_acme.so`.

Другой способ - использовать предоставленный скрипт конфигурации:

```sh
## в директории исходников NGINX
auto/configure \
    --with-compat \
    --with-http_ssl_module \
    --add-[dynamic-]module=/path/to/nginx-acme

Результат будет находиться по адресу objs/ngx_http_acme_module.so.

В настоящее время этот метод создает немного большую библиотеку, так как мы не указываем компоновщику выполнять LTO и удалять неиспользуемый код.

Тестирование

Репозиторий содержит набор тестов интеграции на основе nginx-tests. Следующая команда соберет модуль и запустит тесты:

## Путь к исходному коду nginx, по умолчанию ../nginx, если не указан.
export NGINX_SOURCE_DIR=$(realpath ../nginx)
## Путь к клону nginx-tests; по умолчанию ../nginx/tests, если не указан.
export NGINX_TESTS_DIR=$(realpath ../nginx-tests)

make test

Большинство тестов требуют бинарный файл тестового сервера pebble в пути или в локации, указанной через переменную окружения TEST_NGINX_PEBBLE_BINARY.

Как использовать

Добавьте модуль в конфигурацию NGINX и настройте, как описано ниже. Обратите внимание, что этот модуль требует настройки resolver в блоке http.

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

resolver 127.0.0.1:53;

acme_issuer example {
    uri         https://acme.example.com/directory;
    # contact     admin@example.test;
    state_path  /var/cache/nginx/acme-example;
    accept_terms_of_service;
}

acme_shared_zone zone=ngx_acme_shared:1M;

server {
    listen 443 ssl;
    server_name  .example.test
                 192.0.2.1      # не поддерживается некоторыми ACME серверами
                 2001:db8::1    # не поддерживается некоторыми ACME серверами
                 ;

    acme_certificate example;

    ssl_certificate       $acme_certificate;
    ssl_certificate_key   $acme_certificate_key;

    # не анализировать сертификат при каждом запросе
    ssl_certificate_cache max=2;
}

server {
    # слушатель на порту 80 необходим для обработки задач ACME HTTP-01
    listen 80;

    location / {
        return 404;
    }
}

Директивы

[!ВАЖНО] Справочные данные ниже отражают текущую версию разработки. См. документацию ngx_http_acme_module на nginx.org для последней выпущенной версии.

acme_issuer

Синтаксис: acme_issuer name { ... }

По умолчанию: -

Контекст: http

Определяет объект эмитента сертификата ACME.

uri

Синтаксис: uri uri

По умолчанию: -

Контекст: acme_issuer

URL директории ACME сервера. Эта директива обязательна.

account_key

Синтаксис: account_key alg[:size] | file

По умолчанию: -

Контекст: acme_issuer

Закрытый ключ аккаунта, используемый для аутентификации запроса.

Допустимые значения:

  • ecdsa:256/384/521 для алгоритмов JSON Web Signature ES256, ES384 или ES512
  • rsa:2048/3072/4096 для RS256.
  • Путь к файлу для существующего ключа с использованием одного из вышеперечисленных алгоритмов.

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

challenge

Синтаксис: challenge type

По умолчанию: http-01

Контекст: acme_issuer

Эта директива появилась в версии 0.2.0.

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

Допустимые значения:

  • http-01 (http)
  • tls-alpn-01 (tls-alpn)

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

contact

Синтаксис: contact URL

По умолчанию: -

Контекст: acme_issuer

Устанавливает массив URL-адресов, которые ACME сервер может использовать для связи с клиентом по вопросам аккаунта. Схема mailto: будет использоваться, если не указано явно.

external_account_key

Синтаксис: external_account_key kid file

По умолчанию: -

Контекст: acme_issuer

Эта директива появилась в версии 0.2.0.

Указывает идентификатор ключа kid и file с MAC ключом для внешней авторизации аккаунта.

Значение data:key может быть указано вместо file, что позволит загрузить ключ непосредственно из конфигурации без использования промежуточных файлов.

В обоих случаях ожидается, что ключ будет закодирован в base64url.

preferred_chain

Синтаксис: preferred_chain name

По умолчанию: -

Контекст: acme_issuer

Эта директива появилась в версии 0.3.0.

Указывает предпочтительную цепочку сертификатов.

Если ACME сервер предлагает несколько цепочек сертификатов, предпочитайте цепочку с верхним сертификатом, выданным изолированному общему имени name. Если совпадений нет, будет использована цепочка по умолчанию.

profile

Синтаксис: profile name [require]

По умолчанию: -

Контекст: acme_issuer

Эта директива появилась в версии 0.3.0.

Запрашивает профиль сертификата name у ACME сервера.

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

ssl_trusted_certificate

Синтаксис: ssl_trusted_certificate file

По умолчанию: системная CA база

Контекст: acme_issuer

Указывает file с доверенными CA сертификатами в формате PEM, используемыми для проверки сертификата ACME сервера.

ssl_verify

Синтаксис: ssl_verify on | off

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

Контекст: acme_issuer

Включает или отключает проверку сертификата ACME сервера.

state_path

Синтаксис: state_path path | off

По умолчанию: acme_<name>

Контекст: acme_issuer

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

В директории содержится чувствительный контент, такой как ключ аккаунта, выданные сертификаты и закрытые ключи.

Параметр off (0.2.0) отключает сохранение информации об аккаунте и выданных сертификатах на диске.

До версии 0.2.0 директория состояния не создавалась по умолчанию.

accept_terms_of_service

Синтаксис: accept_terms_of_service

По умолчанию: -

Контекст: acme_issuer

Соглашается с условиями обслуживания, под которыми будет использоваться ACME сервер. Некоторые серверы требуют принятия условий обслуживания перед регистрацией аккаунта. Условия обычно доступны на сайте ACME сервера, и URL будет напечатан в журнале ошибок, если это необходимо.

acme_shared_zone

Синтаксис: acme_shared_zone zone=name:size

По умолчанию: zone=ngx_acme_shared:256k

Контекст: http

Позволяет увеличить размер памяти хранения модуля. Зона общей памяти будет использоваться для хранения выданных сертификатов, ключей и данных о вызовах для всех настроенных эмитентов сертификатов.

Размер по умолчанию достаточно для хранения примерно 50 ключей ECDSA prime256v1 или 35 ключей RSA 2048.

acme_certificate

Синтаксис: acme_certificate issuer [identifier ...] [key=alg[:size]]

По умолчанию: -

Контекст: server

Определяет сертификат со списком identifiers, запрашиваемых у эмитента issuer.

Явный список идентификаторов может быть пропущен. В этом случае идентификаторы будут взяты из директивы server_name в том же server блоке. Не все значения, принимаемые в server_name, являются допустимыми идентификаторами сертификатов: регулярные выражения и подстановочные знаки не поддерживаются.

Параметр key устанавливает тип сгенерированного закрытого ключа. Поддерживаемые алгоритмы ключей и размеры: ecdsa:256 (по умолчанию), ecdsa:384, ecdsa:521, rsa:2048, rsa:3072, rsa:4096.

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

Модуль ngx_http_acme_module поддерживает встроенные переменные, действительные в server блоке с директивой acme_certificate:

$acme_certificate

SSL-сертификат, который можно передать в ssl_certificate.

$acme_certificate_key

Закрытый ключ SSL-сертификата, который можно передать в ssl_certificate_key.