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

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

Warning

Этот модуль еще не опубликован как nginx-module-acme в репозиториях APT. Следите за новостями или напишите на support@getpagespeed.com, чтобы запросить его.

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

nginx-acme

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

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

  • RFC8555 (Автоматическая среда управления сертификатами) с ограничениями:
    • Поддерживается только тип вызова HTTP-01
  • RFC8737 (Расширение ACME для TLS Протокола Переговоров уровня приложений (ALPN))
  • RFC8738 (Расширение проверки идентификаторов IP ACME)
  • draft-ietf-acme-profiles (Расширение профилей ACME, версия 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, который будет использоваться для issuer.

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

  • 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-ключом для внешней авторизации аккаунта.

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

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

preferred_chain

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

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

Контекст: acme_issuer

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

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

Если сервер ACME предлагает несколько цепочек сертификатов, предпочитайте цепочку с верхним сертификатом, выданным от Subject Common Name 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.