Certbot wildcard сертифікат через DNS-01

Чому для wildcard-сертифіката потрібен DNS-01

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

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

Це розділ про wildcard у наших посібниках з Certbot. Звичайні сертифікати для одного hostname, конфігурація вебсервера та правила для port 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 для одного сертифіката означає два окремі завдання (challenges). Обидва 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-credentials вашого 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 показує вашу версію. Невідповідність версій не є критичною. Обмежені (scoped) 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, чекає на завершення поширення (propagation), запускає перевірку, а потім видаляє записи. Якщо NS-сервери вашої зони повільно оновлюють зміни, збільште час очікування за допомогою --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.

Renewal: перевірте зараз, а не через 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 challenges. Встановіть для файлу режим 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, наприклад, сервіси, доступні лише через WireGuard VPN. DNS-01 не підключається до хоста, для якого видається сертифікат, тому навіть повністю приватна машина може мати публічно довірений сертифікат.

FAQ

Чи може Certbot видати wildcard-сертифікат за допомогою HTTP-01?

Ні. HTTP-01 підтверджує контроль лише над одним хостом, оскільки сервер перевірки завантажує файл токена саме за цією назвою. Wildcard охоплює всі піддомени, тому Let's Encrypt вимагає для нього DNS-01 challenge. Аутентифікатори --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'. Це створить два завдання (challenges). Обидва 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. Це усуне обидва ризики, тому саме в таких випадках цей посібник рекомендує відмовитися від wildcard.