Certbot wildcard через DNS-01: инструкция

Почему для wildcard-сертификата требуется DNS-01

Wildcard-сертификат охватывает все поддомены первого уровня домена: *.example.com соответствует app.example.com, blog.example.com и любому другому имени с одним уровнем вложенности. Let's Encrypt выпускает wildcard-сертификаты только через проверку DNS-01. Поэтому Certbot должен подтвердить контроль над DNS домена, опубликовав TXT-запись в _acme-challenge.example.com. Проверка HTTP-01 не подходит, так как размещение файла токена подтверждает контроль только над одним конкретным хостом, с которого сервер проверки загрузил файл. Wildcard-сертификат распространяется на все возможные имена в домене, а DNS является единственным публичным реестром, представляющим все пространство имен.

Это требование определяет все остальные аспекты, описанные на этой странице. Для прохождения DNS-01 вы должны иметь возможность создавать TXT-записи в зоне домена вручную или через API (application programming interface) вашего DNS-провайдера. Ручной способ работает один раз, но не подходит для автоматического обновления по причине, указанной ниже. Использование API через DNS-плагин Certbot позволяет выполнять обновление без участия пользователя; это рекомендуемый способ настройки.

Это раздел о wildcard-сертификатах в наших руководствах по Certbot. Обычные сертификаты для одного хоста, конфигурация веб-сервера и правила для порта 80 описаны в Certbot с nginx на Ubuntu 24.04 и Certbot с Apache на Ubuntu 24.04.

Как работает TXT-запись _acme-challenge

Когда Certbot запрашивает *.example.com, Let's Encrypt отвечает случайным токеном. Certbot объединяет этот токен с ключом вашей учетной записи ACME (automatic certificate management environment), вычисляет хеш результата с помощью SHA-256 и получает короткое текстовое значение. Это значение должно быть добавлено как TXT-запись для _acme-challenge.example.com. Затем Let's Encrypt запрашивает данные у ваших авторитарных DNS-серверов из своей инфраструктуры. Если считанная запись совпадает с ожидаемым значением, вы подтверждаете контроль над зоной. Контроль над зоной считается подтверждением контроля над всеми именами внутри нее.

Большинство сбоев вызвано двумя причинами:

• Запрос example.com и *.example.com для одного сертификата означает две отдельные проверки. Обе TXT-записи должны находиться по одному и тому же имени, _acme-challenge.example.com. Обе записи должны существовать одновременно. Нельзя заменять первую запись второй; это приведет к ошибке первой проверки. Необходимо добавить вторую запись к первой.
• Проверка выполняется на ваших авторитарных серверах, но панелям управления провайдеров может потребоваться минута или более для обновления записей. Проверьте результат извне перед запуском проверки:

dig +short TXT _acme-challenge.example.com @1.1.1.1

Если команда выводит значение, запрошенное Certbot, проверка может завершиться успешно. Если команда ничего не выводит, подождите и запустите ее снова.

Проверка работы в ручном режиме

В ручном режиме вам необходимо редактировать DNS самостоятельно. Это лучший способ изучить механизм перед автоматизацией:

sudo certbot certonly --manual --preferred-challenges dns -d example.com -d '*.example.com'

Кавычки вокруг wildcard-записи предотвращают интерпретацию * оболочкой как шаблона имени файла. Certbot приостановит работу и выведет инструкции:

Please deploy a DNS TXT record under the name:
_acme-challenge.example.com.
with the following value:
Jx9mQ2wLr8vTn5cKp0aYdG3hB7fZs4eN1oiRuXqMk6E

Создайте TXT-запись в панели управления вашего DNS-провайдера. Убедитесь в ее наличии с помощью команды dig, приведенной выше, и только после этого нажмите Enter. Поскольку в данном запросе указаны основной домен и wildcard, Certbot выведет два запроса; не удаляйте обе записи до завершения процесса выпуска сертификата. Успешное завершение подтверждается следующими строками:

Successfully received certificate.
Certificate is saved at: /etc/letsencrypt/live/example.com/fullchain.pem

Почему ручной режим не может выполнять самообновление

Каждое обновление требует нового токена, поэтому значение TXT меняется каждый раз. Запись, которую вы вставили сегодня, станет недействительной через 60 дней. Certbot запускает таймер обновления дважды в день в фоновом режиме. Поскольку в этот момент никто не вводит новое значение, сертификат, выпущенный вручную, не может обновиться и выдает следующую ошибку:

Failed to renew certificate example.com with error: The manual plugin is not
working; there may be problems with your existing configuration.
The error was: PluginError('An authentication script must be provided with
--manual-auth-hook when using the manual plugin non-interactively.')

Вы можете выполнить это требование, написав --manual-auth-hook скрипты для вызова API вашего DNS-провайдера, но в таком случае вы фактически создаете DNS-плагин вручную. Используйте ручной режим для изучения процесса или для разовых задач на доменах, DNS которых еще нельзя автоматизировать. Установите напоминание задолго до истечения 90 дней, так как Let's Encrypt больше не отправляет уведомления об окончании срока действия. Для всех остальных задач используйте плагин.

Использование плагина: certbot-dns-cloudflare на Ubuntu 24.04

DNS-плагин использует API-учетные данные вашего DNS-провайдера и самостоятельно выполняет все операции с TXT-записями при выпуске и при каждом обновлении сертификата. В качестве примера используется Cloudflare, так как это наиболее востребованный плагин и он доступен в репозиториях Ubuntu.

В наших руководствах по Certbot для Ubuntu 24.04 рекомендуется использовать пакеты из apt, и это правило применимо к Cloudflare:

sudo apt update
sudo apt install certbot python3-certbot-dns-cloudflare

Примечание относительно версий. В репозитории 24.04 этот плагин поставляется версии 2.0.0 вместе с Certbot 2.9.0; ваша версия указана в apt policy python3-certbot-dns-cloudflare. Несоответствие версий не критично. Ограниченные (scoped) API-токены работают, так как используемая в 24.04 библиотека python3-cloudflare имеет версию 2.11.1, что выше версии 2.3.1, необходимой плагину для поддержки токенов. В старых версиях Ubuntu эта библиотека была слишком старой для работы с токенами. Именно отсюда берутся предупреждения в сети о том, что плагин apt принудительно использует Global API Key. В Ubuntu 24.04 это более не актуально.

В панели управления Cloudflare создайте ограниченный API-токен (scoped API token), а не Global API Key: My Profile, затем API Tokens, затем Create Token. Установите только одно разрешение: Zone / DNS / Edit, ограниченное одной зоной, для которой вы выпускаете сертификат. Сохраните данные в файл, доступный только пользователю root:

sudo mkdir -p /root/.secrets
sudo tee /root/.secrets/cloudflare.ini > /dev/null <<'EOF'
dns_cloudflare_api_token = paste_your_scoped_token_here
EOF
sudo chmod 600 /root/.secrets/cloudflare.ini

Certbot проверяет права доступа и выдает предупреждение о Unsafe permissions on credentials configuration file, если файл доступен для чтения другим пользователям. Теперь запустите выпуск:

sudo certbot certonly \
  --dns-cloudflare \
  --dns-cloudflare-credentials /root/.secrets/cloudflare.ini \
  -d example.com -d '*.example.com'

Плагин создает TXT-записи через API, ожидает завершения распространения DNS, запускает проверку, а затем удаляет записи. Если DNS-серверы вашей зоны медленно применяют изменения, увеличьте время ожидания с помощью флага --dns-cloudflare-propagation-seconds 60. Сертификат будет сохранен в /etc/letsencrypt/live/example.com/. Настройте nginx или Apache на fullchain.pem и privkey.pem в точном соответствии с базовыми руководствами, включая использование deploy hook.

Если плагин вашего провайдера отсутствует в apt

В архиве 24.04 включены пакеты только для ограниченного числа провайдеров. В их число входят Cloudflare, Route 53, DigitalOcean и стандартный интерфейс RFC 2136. Выполните apt search certbot-dns, чтобы просмотреть список. Если вашего провайдера нет в списке, в этом случае наше правило «сначала apt» не применяется: установите Certbot и плагин через snap. Перед этим необходимо удалить Certbot из apt, чтобы два таймера обновления не конфликтовали за /etc/letsencrypt:

sudo apt remove certbot python3-certbot-dns-cloudflare
sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot
sudo snap set certbot trust-plugin-with-root=ok
sudo snap install certbot-dns-yourprovider

Плагин snap работает только с Certbot из snap; он не может расширять функционал версии из apt. Именно поэтому эти две установки не должны сосуществовать. Если ваш DNS-хостинг не предоставляет API, у вас есть два варианта: перенести DNS домена к провайдеру с поддержкой API или запустить собственный name server и направить плагин rfc2136 на него.

Обновление: проверьте сейчас, а не через 60 дней

Certbot записывает данные о каждом выданном сертификате в /etc/letsencrypt/renewal/example.com.conf, включая authenticator = dns-cloudflare и путь к учетным данным. Стандартный таймер запускается дважды в день и обновляет сертификаты автоматически. Протестируйте весь процесс в staging-среде:

sudo certbot renew --dry-run

Успешное выполнение означает, что учетные данные верны и проверка пройдена полностью. Реальное обновление через 60 дней пройдет по тому же пути. Рекомендуется выполнить два действия уже сегодня. Во-первых, обновленный сертификат на диске не вступит в силу, пока веб-сервер не перезагрузит его. Настройте deploy hook, описанный в руководствах для nginx и Apache. Во-вторых, обеспечьте безопасность файла учетных данных: любой, кто имеет к нему доступ на чтение, может редактировать вашу DNS-зону. Этого достаточно, чтобы перенаправить вашу почту или пройти собственные DNS-01 проверки. Установите права доступа mode 600 в директории /root, ограничьте токен одной зоной и смените его при любом подозрении на утечку.

Когда wildcard не требуется

Wildcard-сертификат подходит для большого количества поддоменов или для поддоменов, которые невозможно предсказать. В остальных случаях использование wildcard по умолчанию нецелесообразно.

• Один поддомен или несколько известных поддоменов: обычный сертификат SAN (subject alternative name) проще в использовании. certbot --nginx -d example.com -d www.example.com -d app.example.com поддерживает до 100 имен через HTTP-01, при этом на сервере не нужно хранить учетные данные DNS API.
• Wildcard соответствует ровно одной метке (label). *.example.com не охватывает основной example.com, поэтому в командах выше запрашиваются оба варианта; wildcard также не охватывает a.b.example.com; для этого требуется *.b.example.com.
• Для каждого поддомена используется отдельный закрытый ключ. Если сервер с этим ключом будет скомпрометирован, под угрозой окажутся все имена, охваченные wildcard.
• Если Traefik выполняет TLS (transport layer security) для ваших контейнеров, Certbot не требуется: Traefik самостоятельно запрашивает wildcard-сертификаты через DNS-01, используя тот же тип токена провайдера.

Wildcard оправдан в следующих случаях: поддомены для каждого клиента или приложения, которые создаются быстрее, чем вы успеваете перевыпускать сертификаты; а также внутренние хосты без открытого порта 80, например, сервисы, доступные только через WireGuard VPN. DNS-01 не подключается к сертифицируемому хосту, поэтому даже полностью изолированная машина может иметь публично доверенный сертификат.

FAQ

Может ли Certbot выпустить wildcard-сертификат с помощью HTTP-01?

Нет. HTTP-01 подтверждает владение одним хостом, так как сервер проверки запрашивает файл токена по этому конкретному имени. Wildcard-сертификат охватывает все имена в домене, поэтому Let's Encrypt требует использования challenge DNS-01. Аутентификаторы --nginx, --apache, --webroot и --standalone работают только через HTTP. Единственный способ — создать TXT-запись в _acme-challenge.example.com вручную или с помощью DNS-плагина.

Охватывает ли wildcard-сертификат корневой домен?

Нет. Wildcard соответствует только одному уровню поддомена. Таким образом, *.example.com охватывает www.example.com, но не охватывает example.com и a.b.example.com. Чтобы запросить оба имени в одном сертификате, используйте -d example.com -d '*.example.com'. Это создаст две задачи проверки. Оба TXT-записи будут находиться в одном имени _acme-challenge.example.com, поэтому добавляйте вторую запись, не удаляя первую.

Почему мой wildcard-сертификат не обновляется автоматически?

Потому что он был выпущен с помощью --manual. Для каждого обновления требуется новое значение TXT. Автоматический таймер не может вставить его самостоятельно, поэтому обновление прерывается с ошибкой An authentication script must be provided with --manual-auth-hook when using the manual plugin non-interactively. Перевыпустите сертификат с помощью DNS-плагина, например certbot-dns-cloudflare, или используйте скрипты --manual-auth-hook и --manual-cleanup-hook для редактирования записи через API вашего провайдера.

Сколько времени требуется для появления TXT-записи _acme-challenge?

Время зависит от вашего DNS-провайдера: от нескольких секунд до нескольких минут. Проверка выполняется на авторитативных серверах вашей зоны. Проверьте результат с помощью dig +short TXT _acme-challenge.example.com @1.1.1.1 и дождитесь появления ожидаемого значения перед продолжением ручного запуска. При использовании плагина можно увеличить время ожидания через опцию распространения (propagation), например --dns-cloudflare-propagation-seconds 60, если проверка сообщает, что запись не найдена.

Менее ли wildcard-сертификат безопасен, чем обычный?

Криптография идентична. Различия заключаются в эксплуатации: один закрытый ключ охватывает все поддомены, поэтому компрометация затрагивает больше ресурсов. Кроме того, учетные данные DNS API, необходимые для автоматизации, являются конфиденциальными данными, хранящимися на сервере. Если вы используете только несколько известных поддоменов, сертификат с SAN (Subject Alternative Name) позволяет избежать обеих проблем. Именно в таких случаях данное руководство рекомендует не использовать wildcard.