Jak wygenerować certyfikat wildcard Certbot przez DNS-01

Dlaczego certyfikat typu wildcard wymaga wyzwania DNS-01

Certyfikat typu wildcard obejmuje każdą subdomenę pierwszego poziomu danej domeny: *.example.com pasuje do app.example.com, blog.example.com oraz każdej innej nazwy o głębokości jednego segmentu. Let’s Encrypt wydaje certyfikaty wildcard wyłącznie poprzez wyzwanie DNS-01, dlatego Certbot musi udowodnić kontrolę nad strefą DNS domeny poprzez publikację rekordu TXT w _acme-challenge.example.com. Wyzwanie HTTP-01 nie jest dopuszczalne, ponieważ serwowanie pliku z tokenem potwierdza kontrolę jedynie nad konkretną nazwą hosta, z której serwer walidacyjny pobrał plik. Certyfikat wildcard jest deklaracją dotyczącą wszystkich możliwych nazw na jednym poziomie pod domeną, a jedynym publicznym rekordem, który reprezentuje całą przestrzeń nazw, jest sam system DNS.

Ten jeden wymóg determinuje wszystkie pozostałe kroki opisane w tym dokumencie. Aby przejść walidację DNS-01, należy mieć możliwość tworzenia rekordów TXT w strefie domeny lub w oddzielnej strefie walidacyjnej, na którą wskazuje rekord CNAME _acme-challenge (omówione poniżej), albo ręcznie, albo poprzez API (interfejs programowania aplikacji) dostawcy DNS. Metoda ręczna działa jednorazowo, lecz zawodzi przy odnawianiu z konkretnego powodu opisanego poniżej. Metoda z użyciem API, realizowana przez wtyczkę DNS dla Certbot, umożliwia automatyczne odnawianie i jest docelową konfiguracją, którą należy wdrożyć.

Niniejszy rozdział poświęcony jest certyfikatom wildcard w naszych przewodnikach dotyczących Certbot. Zwykłe certyfikaty dla pojedynczych nazw hostów, konfiguracja serwera WWW oraz reguły dla portu 80 zostały opisane w Certbot z nginx na Ubuntu 24.04 oraz Certbot z Apache na Ubuntu 24.04.

Jak działa rekord TXT _acme-challenge

Gdy Certbot wysyła żądanie *.example.com, Let's Encrypt odpowiada losowym tokenem. Certbot łączy ten token z kluczem konta ACME (automatic certificate management environment), haszuje wynik algorytmem SHA-256 i generuje krótką wartość tekstową. Wartość ta musi zostać umieszczona jako rekord TXT pod adresem _acme-challenge.example.com. Następnie Let's Encrypt odpytuje autorytatywne serwery nazw domeny ze swojej infrastruktury. Jeśli odczytany rekord jest zgodny z oczekiwaną wartością, użytkownik potwierdza kontrolę nad strefą, co jest uznawane za dowód kontroli nad każdą nazwą w jej obrębie.

Dwa szczegóły są najczęstszą przyczyną niepowodzeń:

• Żądanie example.com oraz *.example.com w ramach tego samego certyfikatu oznacza dwa oddzielne wyzwania, a oba rekordy TXT muszą znajdować się pod tą samą nazwą: _acme-challenge.example.com. Oba muszą istnieć jednocześnie. Dodanie drugiego rekordu jest poprawne; zastąpienie pierwszego drugim powoduje niepowodzenie pierwszego wyzwania.
• Walidacja odczytuje dane z autorytatywnych serwerów, jednak panele sterowania dostawców mogą potrzebować minuty lub dłużej, aby rozpropagować nowy rekord. Przed uruchomieniem walidacji należy sprawdzić stan z zewnątrz:

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

Gdy polecenie to zwróci wartość, o którą prosił Certbot, walidacja może zakończyć się powodzeniem. Jeśli nie zwróci nic, należy odczekać i ponowić próbę.

Weryfikacja działania: tryb ręczny

Tryb ręczny wymaga samodzielnej edycji rekordów DNS, co stanowi najlepszy sposób na zrozumienie mechanizmu przed jego automatyzacją:

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

Cudzysłowy wokół symbolu wieloznacznego zapobiegają interpretacji * przez powłokę jako wzorca nazwy pliku. Certbot wstrzymuje działanie i wyświetla instrukcje:

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

Należy utworzyć wspomniany rekord TXT w panelu dostawcy DNS, potwierdzić jego widoczność za pomocą polecenia dig, a dopiero potem nacisnąć Enter. Ponieważ to uruchomienie dotyczy domeny głównej oraz domeny z symbolem wieloznacznym, Certbot wyświetli monit dwukrotnie; oba rekordy muszą pozostać aktywne do momentu zakończenia wydawania certyfikatu. Sukces kończy się wyświetleniem znanych linii:

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

Dlaczego tryb manual nie może odnowić certyfikatu automatycznie

Każde odnowienie stanowi nowe wyzwanie z nowym tokenem, dlatego wartość TXT zmienia się za każdym razem. Rekord wklejony dzisiaj będzie bezużyteczny za 60 dni. Harmonogram odnawiania uruchamia Certbot w tle dwa razy dziennie, a brak użytkownika przy klawiaturze uniemożliwia wklejenie nowej wartości. Z tego powodu certyfikat wydany ręcznie kończy proces odnawiania tym właśnie błędem:

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.')

Wymóg ten można spełnić, tworząc skrypty --manual-auth-hook, które wywołują API dostawcy DNS, jednak w praktyce oznacza to ręczne budowanie wtyczki DNS. Tryb manual służy do poznania procesu lub do jednorazowego wydania certyfikatu dla domeny, której obsługi DNS nie można jeszcze zautomatyzować. Należy ustawić przypomnienie przed upływem 90 dni, ponieważ Let's Encrypt nie wysyła już powiadomień o wygaśnięciu. Do wszystkich pozostałych zastosowań należy używać wtyczki.

Ścieżka wtyczki: certbot-dns-cloudflare w systemie Ubuntu 24.04

Wtyczka DNS przechowuje dane uwierzytelniające API dostawcy DNS i samodzielnie wykonuje całą procedurę obsługi rekordu TXT, zarówno podczas wydawania certyfikatu, jak i przy każdym jego odnowieniu. Cloudflare stanowi tutaj przykład, ponieważ jest to wtyczka dostawcy najczęściej wymagana przez użytkowników i jest dostępna w pakietach Ubuntu.

Nasze przewodniki dotyczące Certbot zalecają korzystanie z pakietów apt w systemie Ubuntu 24.04 i zasada ta dotyczy również Cloudflare:

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

Jedna istotna uwaga dotycząca wersji. Archiwum 24.04 zawiera tę wtyczkę w wersji 2.0.0 obok Certbot 2.9.0; apt policy python3-certbot-dns-cloudflare wyświetla wersję zainstalowaną w systemie. Rozbieżność ta jest nieistotna, a ograniczone tokeny API działają poprawnie, ponieważ bazowa biblioteka python3-cloudflare w wersji 24.04 to 2.11.1, co przewyższa wymagane dla obsługi tokenów 2.3.1. W starszych wydaniach Ubuntu biblioteka ta była zbyt stara, co stanowi źródło ostrzeżeń dostępnych w Internecie, dotyczących wymuszania przez wtyczkę apt użycia klucza Global API Key. W wersji 24.04 problem ten już nie występuje.

W panelu Cloudflare należy utworzyć ograniczony token API, a nie klucz Global API Key: należy przejść do My Profile, następnie API Tokens, wybrać Create Token i nadać pojedyncze uprawnienie Zone / DNS / Edit, ograniczone do jednej strefy, dla której wydawany jest certyfikat. Plik należy zapisać w lokalizacji dostępnej tylko dla użytkownika 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 sprawdza uprawnienia i ostrzega o Unsafe permissions on credentials configuration file, jeśli plik jest dostępny dla innych użytkowników. Następnie należy wydać polecenie:

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

Wtyczka tworzy rekordy TXT za pośrednictwem API, oczekuje na propagację zmian, pozwala na przeprowadzenie walidacji, a następnie usuwa rekordy. Jeśli serwery nazw danej strefy wolno aktualizują zmiany, należy zwiększyć czas oczekiwania za pomocą --dns-cloudflare-propagation-seconds 60. Certyfikat zostanie zapisany w /etc/letsencrypt/live/example.com/, a w konfiguracji nginx lub Apache należy wskazać fullchain.pem oraz privkey.pem, dokładnie tak, jak opisano w podstawowych przewodnikach, uwzględniając również deploy hook.

Jeśli wtyczka Twojego dostawcy nie znajduje się w apt

Archiwum 24.04 zawiera pakiety wtyczek tylko dla wybranych dostawców, w tym Cloudflare, Route 53, DigitalOcean oraz ogólnego interfejsu RFC 2136. Uruchom apt search certbot-dns, aby wyświetlić listę. Jeśli Twojego dostawcy brakuje na liście, jest to jedyny przypadek, w którym odstępujemy od zalecenia używania apt: zainstaluj Certbot oraz wtyczkę za pomocą snap, usuwając wcześniej wersję z apt, aby dwa timery odnawiania nie wchodziły w konflikt o /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

Wtyczka snap łączy się wyłącznie z wersją Certbot typu snap; nie może rozszerzyć wersji z apt, dlatego obie instalacje nie mogą współistnieć. Jeśli Twój dostawca DNS nie oferuje żadnego API, masz trzy realne opcje. Możesz przenieść DNS domeny do dostawcy, który posiada API. Możesz uruchomić własny serwer nazw i wskazać na niego wtyczkę rfc2136. Możesz również zachować obecnego dostawcę DNS i dodać jednorazowy rekord CNAME z _acme-challenge.example.com do strefy walidacyjnej, która posiada API, takiej jak usługa acme-dns lub własny serwer acme-dns. Let’s Encrypt podąża za tym rekordem CNAME podczas walidacji, dzięki czemu rekordy TXT znajdują się w delegowanej strefie, a Twoja główna strefa nie wymaga dalszych zmian.

Odnawianie: sprawdź to teraz, nie za 60 dni

Certbot rejestruje sposób wydania każdego certyfikatu w /etc/letsencrypt/renewal/example.com.conf, w tym authenticator = dns-cloudflare oraz ścieżkę do danych uwierzytelniających, dzięki czemu standardowy harmonogram uruchamiany dwa razy dziennie odnawia go bez ingerencji użytkownika. Przetestuj cały proces w środowisku staging:

sudo certbot renew --dry-run

Pomyślny wynik oznacza, że dane uwierzytelniające są poprawne, a walidacja kończy się sukcesem; właściwe odnowienie za 60 dni przebiegnie w ten sam sposób. Warto wykonać dziś dwa dodatkowe kroki. Po pierwsze, odnowiony certyfikat na dysku nie zmienia niczego, dopóki serwer WWW go nie przeładuje, dlatego należy skonfigurować deploy hook opisany w przewodnikach dla nginx i Apache. Po drugie, należy zachować ostrożność w odniesieniu do pliku z danymi uwierzytelniającymi: każdy, kto może go odczytać, może edytować strefę DNS, co wystarczy do przekierowania poczty lub samodzielnego przejścia wyzwań DNS-01. Plik powinien mieć ustawione uprawnienia 600 w /root, token powinien być ograniczony do jednej strefy, a w przypadku podejrzenia wycieku należy go zrotować.

Kiedy certyfikat typu wildcard nie jest potrzebny

Certyfikat typu wildcard jest właściwym narzędziem dla wielu subdomen lub subdomen, których nie można przewidzieć. W pozostałych przypadkach nie powinien być wybierany domyślnie.

• Jedna subdomena lub kilka znanych: zwykły certyfikat SAN (Subject Alternative Name) jest prostszy. certbot --nginx -d example.com -d www.example.com -d app.example.com obsługuje do 100 nazw poprzez standardowe wyzwanie HTTP-01, a na serwerze nie muszą być przechowywane żadne dane uwierzytelniające API DNS.
• Certyfikat typu wildcard pasuje dokładnie do jednego poziomu etykiety. *.example.com nie obejmuje domeny głównej example.com, dlatego powyższe polecenia wymagają obu, nie obejmuje również a.b.example.com; w tym przypadku wymagany byłby zapis *.b.example.com.
• Za każdą subdomeną stoi jeden klucz prywatny. W przypadku przejęcia maszyny, na której jest on przechowywany, zagrożone stają się natychmiast wszystkie nazwy objęte certyfikatem wildcard.
• Jeśli Traefik zajmuje się terminacją TLS (Transport Layer Security) dla kontenerów, Certbot nie jest w ogóle potrzebny: Traefik samodzielnie żąda certyfikatów typu wildcard poprzez DNS-01, używając tego samego typu tokena dostawcy.

Sytuacje, w których certyfikat typu wildcard jest rzeczywiście uzasadniony: subdomeny tworzone dla poszczególnych klientów lub aplikacji szybciej, niż można by odnawiać certyfikaty, oraz hosty wewnętrzne bez publicznego portu 80, takie jak usługi dostępne wyłącznie przez sieć WireGuard VPN. Wyzwanie DNS-01 nie łączy się z hostem, dla którego wystawiany jest certyfikat, dzięki czemu nawet całkowicie odizolowana maszyna może posiadać publicznie zaufany certyfikat.

FAQ

Czy Certbot może wydać certyfikat wildcard przy użyciu HTTP-01?

Nie. HTTP-01 potwierdza kontrolę nad jedną nazwą hosta, ponieważ serwer walidacyjny pobiera plik z tokenem z dokładnie tej nazwy. Certyfikat wildcard obejmuje każdą nazwę pierwszego poziomu pod domeną, dlatego Let’s Encrypt wymaga dla niego wyzwania DNS-01, a uwierzytelniacze --nginx, --apache, --webroot oraz --standalone opierają się na HTTP. Jedyną drogą jest rekord TXT w _acme-challenge.example.com (lub w strefie delegowanej przez CNAME), umieszczony ręcznie lub przez wtyczkę DNS.

Czy certyfikat wildcard obejmuje domenę główną?

Nie. Wildcard pasuje dokładnie do jednego segmentu, więc *.example.com obejmuje www.example.com, ale nie samą domenę example.com ani a.b.example.com. Zawnioskuj o obie nazwy w jednym certyfikacie za pomocą -d example.com -d '*.example.com'. Wygeneruje to dwa wyzwania, a oba rekordy TXT będą znajdować się pod tą samą nazwą _acme-challenge.example.com, więc dodaj drugi rekord bez usuwania pierwszego.

Dlaczego mój certyfikat wildcard nie odnawia się automatycznie?

Ponieważ został wydany przy użyciu --manual. Każde odnowienie wymaga nowej wartości TXT, a automatyczny timer nie ma możliwości jej wprowadzenia, więc proces odnawiania kończy się błędem An authentication script must be provided with --manual-auth-hook when using the manual plugin non-interactively. Wydaj certyfikat ponownie przy użyciu wtyczki DNS, takiej jak certbot-dns-cloudflare, lub dostarcz skrypty --manual-auth-hook i --manual-cleanup-hook, które edytują rekord poprzez API Twojego dostawcy.

Jak długo trwa pojawienie się rekordu TXT _acme-challenge?

Zależy to od dostawcy DNS: od kilku sekund do kilku minut. Walidacja odczytuje autorytatywne serwery Twojej strefy, więc sprawdź to za pomocą dig +short TXT _acme-challenge.example.com @1.1.1.1 i poczekaj na pojawienie się oczekiwanej wartości przed kontynuowaniem ręcznego procesu. W przypadku wtyczki zwiększ wbudowany czas oczekiwania za pomocą opcji propagacji wtyczki, na przykład --dns-cloudflare-propagation-seconds 60, jeśli walidacja zgłasza, że rekord nie został znaleziony.

Czy certyfikat wildcard jest mniej bezpieczny niż zwykły certyfikat?

Kryptografia jest identyczna. Różnice są natury operacyjnej: jeden klucz prywatny obejmuje wszystkie subdomeny, więc skutki naruszenia bezpieczeństwa są szersze, a dane uwierzytelniające API DNS, wymagane przez automatyzację, są same w sobie wrażliwym sekretem przechowywanym na serwerze. Jeśli obsługujesz tylko kilka znanych subdomen, certyfikat typu SAN pozwala uniknąć obu tych problemów i właśnie w takich przypadkach niniejszy przewodnik zaleca rezygnację z wildcard.