Wildcard-сертификат Certbot через 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 с использованием плагина Certbot для DNS выполняет продление без участия администратора. Именно такую конфигурацию следует использовать в итоге.

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

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

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

Большинство сбоев вызывают два обстоятельства:

• Запрос 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 мы рекомендуем пакеты apt в Ubuntu 24.04. Для 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 показывает установленную у вас версию. Несовпадение версий не мешает работе. Ограниченные токены API поддерживаются, поскольку базовая библиотека python3-cloudflare в 24.04 имеет версию 2.11.1. Это выше версии 2.3.1, необходимой плагину для поддержки токенов. В старых выпусках Ubuntu эта библиотека была слишком старой для работы с токенами. Поэтому в найденных в интернете предупреждениях говорится, что плагин apt требует Global API Key. Для 24.04 эти предупреждения больше не актуальны.

В панели Cloudflare создайте ограниченный токен API, а не 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-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, либо запустить собственный сервер имён и указать его в плагине rfc2136.

Продление: выполните проверку сейчас, а не через 60 дней

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

sudo certbot renew --dry-run

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

Когда вам не нужен 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 соответствует ровно одному уровню. *.example.com не покрывает основной домен example.com, поэтому приведенные выше команды запрашивают оба имени. Он также не покрывает a.b.example.com: для этого потребуется *.b.example.com.
• За всеми субдоменами стоит один закрытый ключ. Если машина, на которой он хранится, будет скомпрометирована, это сразу затронет все имена, покрываемые wildcard.
• Если Traefik завершает TLS (transport layer security) для ваших контейнеров, Certbot вообще не нужен: Traefik самостоятельно запрашивает wildcard-сертификаты через DNS-01, используя токен провайдера того же типа.

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

FAQ

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

Нет. HTTP-01 подтверждает контроль над одним именем хоста, поскольку сервер проверки получает файл с токеном именно по этому имени. Wildcard-сертификат охватывает все имена в домене, поэтому Let's Encrypt требует для него проверку 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 и дождитесь появления ожидаемого значения перед продолжением ручного запуска. При использовании плагина увеличьте встроенное время ожидания через параметр распространения записей плагина, например --dns-cloudflare-propagation-seconds 60, если проверка сообщает, что запись не найдена.

Менее ли защищён wildcard-сертификат по сравнению с обычным сертификатом?

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