Jak wygenerować certyfikat wildcard Certbot przez DNS-01

Dlaczego certyfikat typu wildcard wymaga wyzwania DNS-01

Certyfikat typu wildcard obejmuje wszystkie subdomeny pierwszego poziomu danej domeny: *.example.com pasuje do app.example.com, blog.example.com oraz każdej innej nazwy o głębokości jednego członu. Let’s Encrypt wydaje certyfikaty wildcard wyłącznie w ramach wyzwania DNS-01, dlatego Certbot musi potwierdzić kontrolę nad strefą DNS domeny poprzez opublikowanie rekordu TXT w _acme-challenge.example.com. Wyzwanie HTTP-01 nie jest wystarczające, ponieważ udostępnienie pliku z tokenem potwierdza kontrolę jedynie nad konkretną nazwą hosta, z której serwer walidacyjny pobrał plik. Certyfikat wildcard stanowi deklarację dotyczącą wszystkich możliwych nazw w domenie, a jedynym publicznym rejestrem obejmującym całą przestrzeń nazw jest sam system DNS.

Ten jeden wymóg determinuje wszystkie pozostałe kroki opisane na tej stronie. Aby przejść walidację DNS-01, należy posiadać możliwość tworzenia rekordów TXT w strefie domeny, ręcznie lub poprzez API (interfejs programowania aplikacji) dostawcy DNS. Metoda ręczna sprawdza się jednorazowo, lecz zawodzi przy odnawianiu z konkretnego powodu przedstawionego poniżej. Metoda z użyciem API, realizowana przez wtyczkę DNS dla Certbot, umożliwia automatyczne odnawianie bez nadzoru i jest konfiguracją docelową.

Niniejszy rozdział naszych przewodników po Certbot dotyczy certyfikatów typu wildcard. Zwykłe certyfikaty dla pojedynczej nazwy hosta, konfiguracja serwera WWW oraz reguły dla portu 80 zostały omówione 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 dostawcy nie znajduje się w apt

Archiwum 24.04 zawiera pakiety wtyczek tylko dla kilku 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 korzystania z apt: zainstaluj Certbot oraz wtyczkę za pomocą snap, usuwając wcześniej wersję Certbot z apt, aby dwa timery odnawiania nigdy 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 zainstalowaną przez snap; nie może ona rozszerzyć wersji z apt, dlatego obie instalacje nie mogą współistnieć. Jeśli dostawca DNS nie oferuje żadnego API, realnymi opcjami są przeniesienie DNS domeny do dostawcy, który je posiada, lub uruchomienie własnego serwera nazw i skierowanie na niego wtyczki rfc2136.

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 typu wildcard przy użyciu wyzwania HTTP-01?

Nie. Wyzwanie HTTP-01 potwierdza kontrolę nad jedną nazwą hosta, ponieważ serwer walidacyjny pobiera plik z tokenem z konkretnego adresu. Certyfikat typu wildcard obejmuje wszystkie nazwy w domenie, dlatego Let's Encrypt wymaga w tym przypadku wyzwania DNS-01, a uwierzytelniacze --nginx, --apache, --webroot oraz --standalone opierają się wyłącznie na protokole HTTP. Jedyną drogą jest dodanie rekordu TXT w _acme-challenge.example.com, co można wykonać ręcznie lub za pomocą wtyczki DNS.

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

Nie. Wildcard dopasowuje dokładnie jeden człon nazwy, więc *.example.com obejmuje www.example.com, ale nie samą domenę example.com ani a.b.example.com. Należy wnioskować o obie nazwy w jednym certyfikacie przy użyciu -d example.com -d '*.example.com'. Wygeneruje to dwa wyzwania, a oba rekordy TXT muszą znaleźć się pod tą samą nazwą _acme-challenge.example.com, dlatego należy dodać drugi rekord bez usuwania pierwszego.

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

Ponieważ został wydany przy użyciu --manual. Każde odnowienie wymaga nowej wartości TXT, a automatyczny harmonogram nie ma możliwości jej wprowadzenia, przez co proces odnawiania kończy się błędem An authentication script must be provided with --manual-auth-hook when using the manual plugin non-interactively. Należy ponownie wydać certyfikat przy użyciu wtyczki DNS, takiej jak certbot-dns-cloudflare, lub dostarczyć skrypty --manual-auth-hook i --manual-cleanup-hook, które edytują rekord za pośrednictwem API dostawcy domeny.

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

Zależy to od dostawcy DNS: od kilku sekund do kilku minut. Walidacja odczytuje dane z autorytatywnych serwerów strefy, więc należy sprawdzić stan za pomocą dig +short TXT _acme-challenge.example.com @1.1.1.1 i poczekać na pojawienie się oczekiwanej wartości przed kontynuowaniem ręcznego procesu. W przypadku użycia wtyczki należy zwiększyć wbudowany czas oczekiwania za pomocą opcji propagacji, na przykład --dns-cloudflare-propagation-seconds 60, jeśli walidacja zgłasza brak rekordu.

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

Kryptografia jest identyczna. Różnice mają charakter operacyjny: jeden klucz prywatny obejmuje wszystkie subdomeny, więc skutki ewentualnego przejęcia serwera są poważniejsze, a dane uwierzytelniające API DNS wymagane do automatyzacji stanowią wrażliwy sekret przechowywany na serwerze. Jeśli obsługiwanych jest tylko kilka znanych subdomen, certyfikat typu SAN pozwala uniknąć obu tych problemów, dlatego w takiej sytuacji niniejszy przewodnik zaleca rezygnację z certyfikatu typu wildcard.