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-записи в DNS-зоні домену вручну або через 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 запитує авторитетні сервери імен вашого домену зі своєї інфраструктури. Якщо отриманий запис відповідає очікуваному значенню, ви підтверджуєте контроль над зоною. Контроль над зоною вважається підтвердженням контролю над усіма іменами в ній.

Більшість помилок спричиняють два моменти:

• Запит example.com і *.example.com в одному сертифікаті означає два окремі challenge. Обидва TXT-записи мають бути розміщені за одним іменем — _acme-challenge.example.com. Вони мають існувати одночасно. Додати другий запис правильно; заміна першого другим призводить до помилки під час першого challenge.
• Перевірка читає дані з ваших авторитетних серверів, але панелі керування DNS-провайдерів можуть витратити хвилину або більше на поширення нового запису на ці сервери. Перед запуском перевірки перевірте запис із зовнішньої мережі:

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 не дають shell сприйняти * як шаблон імені файлу. 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

Чому manual mode не може поновити сертифікат самостійно

Кожне поновлення — це нове challenge з новим token, тому значення 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 plugin. Використовуйте manual mode, щоб зрозуміти цей процес, або для справді одноразового отримання сертифіката для домену, DNS якого поки що неможливо автоматизувати. Встановіть нагадування задовго до 90-го дня, оскільки Let's Encrypt більше не надсилає повідомлення про завершення строку дії сертифіката. В усіх інших випадках використовуйте plugin.

Маршрут із плагіном: 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

Важливе уточнення щодо версій. Архів Ubuntu 24.04 містить цей плагін версії 2.0.0 разом із Certbot 2.9.0; apt policy python3-certbot-dns-cloudflare покаже встановлену у вас версію. Невідповідність версій не створює проблем. Обмежені API-токени працюють, оскільки базова бібліотека python3-cloudflare в Ubuntu 24.04 має версію 2.11.1, яка новіша за версію 2.3.1, потрібну плагіну для підтримки токенів. У старіших випусках Ubuntu ця бібліотека була надто старою для роботи з токенами. Саме тому в попередженнях, які можна знайти в Інтернеті, йдеться про те, що apt-плагін примусово використовує Global API Key. Для Ubuntu 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. Він не може розширити Certbot, встановлений через apt. Тому ці два варіанти встановлення не повинні співіснувати. Якщо ваш DNS-хостинг не надає API, реалістичні варіанти такі: перенести DNS домену до провайдера, який має API, або запустити власний сервер імен і вказати на нього плагін 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. Встановіть для файлу режим 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 охоплює рівно один label. *.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 підтверджує контроль над одним hostname, оскільки сервер перевірки отримує файл із токеном саме за цим іменем. Wildcard охоплює всі імена в домені, тому Let's Encrypt вимагає challenge DNS-01, а authenticators --nginx, --apache, --webroot і --standalone працюють через HTTP. Єдиний варіант — TXT-запис за адресою _acme-challenge.example.com, доданий вручну або за допомогою DNS-плагіна.

Чи охоплює wildcard-сертифікат кореневий домен?

Ні. Wildcard відповідає рівно одному label, тому *.example.com охоплює www.example.com, але не bare-домен example.com і не a.b.example.com. Запросіть обидва імені в одному сертифікаті за допомогою -d example.com -d '*.example.com'. Буде створено два challenges, і обидва TXT-записи матимуть те саме ім’я _acme-challenge.example.com, тому додайте другий запис, не видаляючи перший.

Чому мій wildcard-сертифікат не поновлюється автоматично?

Тому що його було випущено з параметром --manual. Для кожного поновлення потрібне нове значення TXT, а unattended timer не може додати його, тому поновлення припиняється з помилкою 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-провайдера: від кількох секунд до кількох хвилин. Перевірка читає авторитетні сервери вашої DNS-зони, тому скористайтеся dig +short TXT _acme-challenge.example.com @1.1.1.1 і зачекайте, доки не з’явиться очікуване значення, перш ніж продовжувати ручний запуск. Якщо використовується плагін, збільште вбудований час очікування за допомогою параметра поширення плагіна, наприклад --dns-cloudflare-propagation-seconds 60, якщо під час перевірки повідомляється, що запис не знайдено.

Чи є wildcard-сертифікат менш безпечним за звичайний сертифікат?

Криптографія однакова. Відмінності стосуються адміністрування: один приватний ключ охоплює всі субдомени, тому компрометація дає змогу атакувати більше ресурсів, а облікові дані DNS API, потрібні для автоматизації, є чутливим секретом, що зберігається на сервері. Якщо ви використовуєте лише кілька відомих субдоменів, SAN-сертифікат усуває обидві проблеми. Саме в такому випадку цей посібник рекомендує не використовувати wildcard.