Certbot: Wildcard-Zertifikat mit DNS-01 erstellen

Warum ein Wildcard-Zertifikat DNS-01 benötigt

Ein Wildcard-Zertifikat gilt für jede Subdomain der ersten Ebene einer Domain: *.example.com entspricht app.example.com, blog.example.com und jedem anderen Namen mit genau einem Label. Let’s Encrypt stellt Wildcard-Zertifikate ausschließlich über die DNS-01-Challenge aus. Certbot muss daher die Kontrolle über das DNS der Domain nachweisen, indem es unter _acme-challenge.example.com einen TXT-Record veröffentlicht. Die HTTP-01-Challenge reicht dafür nicht aus, weil eine bereitgestellte Token-Datei nur die Kontrolle über einen Hostnamen nachweist, von dem der Validierungsserver die Datei abgerufen hat. Ein Wildcard-Zertifikat gilt dagegen für jeden möglichen Namen eine Ebene unterhalb der Domain. Der einzige öffentliche Record, der für den gesamten Namensraum steht, ist DNS.

Diese eine Anforderung bestimmt alle weiteren Schritte auf dieser Seite. Für DNS-01 müssen Sie TXT-Records in der Zone der Domain anlegen können. Alternativ können Sie eine separate Validierungszone verwenden, auf die _acme-challenge mit einem CNAME verweist (siehe unten). Das Anlegen kann manuell oder über die API (application programming interface) Ihres DNS-Providers erfolgen. Der manuelle Weg funktioniert einmalig, schlägt bei der Erneuerung jedoch aus einem weiter unten konkret beschriebenen Grund fehl. Der API-Weg über ein Certbot-DNS-Plugin erneuert das Zertifikat unbeaufsichtigt. Diese Konfiguration sollten Sie letztlich verwenden.

Dies ist das Wildcard-Kapitel unserer Certbot-Anleitungen. Gewöhnliche Zertifikate für einzelne Hostnamen, die Webserver-Konfiguration und die Regeln für Port 80 werden in Certbot mit nginx unter Ubuntu 24.04 und Certbot mit Apache unter Ubuntu 24.04 beschrieben.

Funktionsweise des TXT-Eintrags _acme-challenge

Wenn Certbot *.example.com anfordert, antwortet Let's Encrypt mit einem zufälligen Token. Certbot kombiniert dieses Token mit dem ACME-Kontoschlüssel (automatic certificate management environment), hasht das Ergebnis mit SHA-256 und erzeugt einen kurzen Textwert. Dieser Wert muss als TXT-Eintrag unter _acme-challenge.example.com vorhanden sein. Let's Encrypt fragt anschließend die autoritativen Nameserver Ihrer Domain von seiner eigenen Infrastruktur aus ab. Wenn der gelesene Eintrag mit dem erwarteten Wert übereinstimmt, ist damit nachgewiesen, dass Sie die Kontrolle über die Zone haben. Die Kontrolle über die Zone gilt dann als Kontrolle über jeden darunterliegenden Namen.

Zwei Details verursachen die meisten Fehler:

• Wenn Sie example.com und *.example.com im selben Zertifikat anfordern, handelt es sich um zwei separate Challenges. Beide TXT-Einträge befinden sich unter demselben Namen, _acme-challenge.example.com. Beide müssen gleichzeitig vorhanden sein. Den zweiten Eintrag hinzuzufügen ist korrekt. Den ersten durch den zweiten zu ersetzen, lässt die erste Challenge fehlschlagen.
• Die Validierung fragt Ihre autoritativen Server ab. Provider-Kontrollfelder können jedoch eine Minute oder länger benötigen, um einen neuen Eintrag an diese Server zu übertragen. Prüfen Sie den Eintrag von außerhalb, bevor Sie die Validierung starten:

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

Wenn dieser Befehl den von Certbot angeforderten Wert ausgibt, kann die Validierung erfolgreich sein. Wenn er nichts ausgibt, warten Sie und führen Sie ihn erneut aus.

Einmal manuell durchführen: manueller Modus

Im manuellen Modus müssen Sie den DNS-Eintrag selbst ändern. Das ist die beste Möglichkeit, den Mechanismus zu verstehen, bevor Sie ihn automatisieren:

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

Die Anführungszeichen um den Wildcard-Ausdruck verhindern, dass Ihre Shell * als Dateinamensmuster behandelt. Certbot hält mit Anweisungen an:

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

Erstellen Sie diesen TXT-Eintrag im Bedienfeld Ihres DNS-Providers. Prüfen Sie mit dem oben gezeigten Befehl dig, ob er sichtbar ist, und drücken Sie erst dann die Eingabetaste. Da dieser Aufruf die Basisdomain und den Wildcard-Ausdruck anfordert, fordert Certbot Sie zweimal dazu auf. Lassen Sie beide Einträge bestehen, bis die Ausstellung abgeschlossen ist. Bei Erfolg endet die Ausgabe mit den bekannten Zeilen:

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

Warum der manuellen Modus sich nicht selbst erneuern kann

Jede Erneuerung ist eine neue Challenge mit einem neuen Token. Deshalb ändert sich der TXT-Wert jedes Mal. Der Datensatz, den Sie heute eingetragen haben, ist in 60 Tagen nicht mehr gültig. Der Erneuerungs-Timer führt Certbot zweimal täglich unbeaufsichtigt aus. Niemand sitzt an der Tastatur, um den neuen Wert einzutragen. Deshalb schlägt die Erneuerung eines manuell ausgestellten Zertifikats mit genau diesem Fehler fehl:

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

Sie können diese Anforderung erfüllen, indem Sie --manual-auth-hook-Skripte schreiben, die die API Ihres DNS-Providers aufrufen. Damit erstellen Sie jedoch manuell ein DNS-Plugin neu. Verwenden Sie den manuellen Modus, um den Ablauf kennenzulernen, oder für einen einmaligen Vorgang bei einer Domain, deren DNS Sie noch nicht automatisieren können. Setzen Sie eine Erinnerung deutlich vor Tag 90, da Let's Encrypt keine Ablauf-E-Mails mehr versendet. Verwenden Sie in allen anderen Fällen ein Plugin.

Der Plugin-Weg: certbot-dns-cloudflare unter Ubuntu 24.04

Ein DNS-Plugin speichert ein API-Credential für Ihren DNS-Provider und erledigt den gesamten Ablauf mit dem TXT-Record selbst, sowohl bei der Ausstellung als auch bei jeder Erneuerung. Cloudflare dient hier als Beispiel, da es das am häufigsten benötigte Provider-Plugin ist und für Ubuntu als Paket bereitsteht.

Unsere Certbot-Anleitungen empfehlen die apt-Pakete unter Ubuntu 24.04, und dieser Ansatz gilt auch für Cloudflare:

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

Ein ehrlicher Hinweis zu den Versionen: Das 24.04-Archiv liefert dieses Plugin in Version 2.0.0 zusammen mit Certbot 2.9.0 aus; apt policy python3-certbot-dns-cloudflare zeigt Ihre Version. Die Diskrepanz ist harmlos, und eingeschränkte API-Tokens funktionieren, da die zugrunde liegende python3-cloudflare-Bibliothek in 24.04 in Version 2.11.1 vorliegt – das ist mehr als die für die Token-Unterstützung erforderliche Version 2.3.1. Auf älteren Ubuntu-Versionen war diese Bibliothek zu alt für Tokens; daher stammen die Warnungen, die Sie möglicherweise online finden, dass das apt-Plugin die Verwendung des Global API Key erzwingt. Unter 24.04 sind diese nicht mehr relevant.

Erstellen Sie im Cloudflare-Dashboard ein eingeschränktes API-Token, nicht den Global API Key: Navigieren Sie zu My Profile, dann API Tokens, dann Create Token, und wählen Sie die einzelne Berechtigung Zone / DNS / Edit, beschränkt auf die eine Zone, für die Sie das Zertifikat ausstellen. Speichern Sie es in einer Datei, die nur für root lesbar ist:

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 prüft die Dateirechte und warnt vor Unsafe permissions on credentials configuration file, falls die Datei für andere lesbar ist. Führen Sie nun den Befehl aus:

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

Das Plugin erstellt die TXT-Records über die API, wartet eine kurze Zeit auf die Propagation, lässt die Validierung durchlaufen und löscht die Records anschließend wieder. Falls die Nameserver Ihrer Zone Änderungen nur langsam übernehmen, erhöhen Sie die Wartezeit mit --dns-cloudflare-propagation-seconds 60. Das Zertifikat wird unter /etc/letsencrypt/live/example.com/ abgelegt, und Sie verweisen in nginx oder Apache auf fullchain.pem und privkey.pem, genau wie in den grundlegenden Anleitungen beschrieben, inklusive des deploy hook.

Wenn das Plugin Ihres Providers nicht in apt enthalten ist

Das Archiv von 24.04 enthält nur Plugins für einige wenige Provider, darunter Cloudflare, Route 53, DigitalOcean und die generische RFC-2136-Schnittstelle. Führen Sie apt search certbot-dns aus, um die Liste anzuzeigen. Wenn Ihr Provider fehlt, weichen wir an dieser Stelle von unserer apt-first-Empfehlung ab: Installieren Sie Certbot und das Plugin stattdessen über snap. Entfernen Sie Certbot aus apt vorher, damit nicht zwei Erneuerungs-Timer um /etc/letsencrypt konkurrieren:

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

Ein snap-Plugin kann nur eine snap-Installation von Certbot anbinden. Es kann die apt-Installation nicht erweitern. Deshalb dürfen beide Installationen nicht gleichzeitig vorhanden sein. Wenn Ihr DNS-Host überhaupt keine API anbietet, haben Sie drei praktikable Möglichkeiten. Sie können das DNS der Domain zu einem Provider mit API umziehen. Sie können einen eigenen Nameserver betreiben und das rfc2136-Plugin darauf verweisen. Oder Sie behalten Ihren bisherigen DNS-Host und legen einmalig einen CNAME von _acme-challenge.example.com zu einer Validierungszone an, die über eine API verfügt, beispielsweise zu einem gehosteten acme-dns-Dienst oder zu einem selbst betriebenen acme-dns-Server. Let’s Encrypt folgt diesem CNAME bei der Validierung. Die TXT-Records liegen dadurch in der delegierten Zone, und Ihre Hauptzone muss danach nicht mehr geändert werden.

Verlängerung: Jetzt testen, nicht erst in 60 Tagen

Certbot speichert in /etc/letsencrypt/renewal/example.com.conf, wie jedes Zertifikat ausgestellt wurde, einschließlich authenticator = dns-cloudflare und des Pfads zu den Zugangsdaten. Der standardmäßige, zweimal täglich ausgeführte Timer verlängert das Zertifikat dadurch ohne Ihr Zutun. Testen Sie den gesamten Ablauf gegen die Staging-Umgebung:

sudo certbot renew --dry-run

Ein erfolgreicher Test bedeutet, dass die Zugangsdaten funktionieren und die Validierung vollständig durchläuft. Die tatsächliche Verlängerung in 60 Tagen folgt demselben Ablauf. Zwei weitere Schritte sollten Sie heute durchführen. Erstens ändert ein erneuertes Zertifikat auf dem Datenträger nichts, solange der Webserver es nicht neu lädt. Richten Sie daher den in den Anleitungen zu nginx und Apache beschriebenen Deploy-Hook ein. Zweitens müssen Sie die Datei mit den Zugangsdaten schützen: Jeder, der sie lesen kann, kann Ihre DNS-Zone bearbeiten. Damit lassen sich beispielsweise Ihre E-Mails umleiten oder eigene DNS-01-Challenges bestehen. Setzen Sie die Datei unter /root auf den Modus 600, beschränken Sie das Token auf eine Zone und rotieren Sie es, sobald Sie einen möglichen Verlust vermuten.

Kein Wildcard-Zertifikat erforderlich

Ein Wildcard-Zertifikat ist für viele Subdomains oder für nicht vorhersehbare Subdomains das richtige Werkzeug. Für alle anderen Fälle ist es nicht die Standardlösung.

• Eine Subdomain oder wenige bekannte Subdomains: Ein normales SAN-Zertifikat (Subject Alternative Name) ist einfacher. certbot --nginx -d example.com -d www.example.com -d app.example.com deckt über HTTP-01 ohne DNS-API bis zu 100 Namen ab, und auf dem Server muss kein DNS-API-Zugang hinterlegt werden.
• Ein Wildcard-Zertifikat deckt genau eine Label-Ebene ab. *.example.com deckt die Root-Domain example.com nicht ab. Deshalb fordern die obigen Befehle beide Namen an. Auch a.b.example.com wird nicht abgedeckt. Dafür wäre *.b.example.com erforderlich.
• Hinter jeder Subdomain steht derselbe private Schlüssel. Wird der Rechner, auf dem dieser Schlüssel liegt, kompromittiert, sind alle vom Wildcard-Zertifikat abgedeckten Namen gleichzeitig betroffen.
• Wenn Traefik TLS (Transport Layer Security) für Ihre Container terminiert, benötigen Sie Certbot dafür überhaupt nicht: Traefik fordert Wildcard-Zertifikate selbst über DNS-01 an und verwendet dabei einen Zugangstoken desselben Anbietertyps.

Ein Wildcard-Zertifikat ist besonders dann sinnvoll, wenn Subdomains pro Kunde oder Anwendung schneller erstellt werden, als Sie Zertifikate neu ausstellen möchten, sowie für interne Hosts ohne öffentlich erreichbaren Port 80, beispielsweise Dienste, die nur über ein WireGuard-VPN erreichbar sind. DNS-01 verbindet sich nie mit dem Host, für den das Zertifikat ausgestellt wird. Daher kann auch ein vollständig privater Rechner ein öffentlich vertrauenswürdiges Zertifikat verwenden.

FAQ

Kann Certbot mit HTTP-01 ein Wildcard-Zertifikat ausstellen?

Nein. HTTP-01 weist die Kontrolle über einen einzelnen Hostnamen nach, weil der Validierungsserver eine Token-Datei genau unter diesem Namen abruft. Ein Wildcard-Zertifikat gilt für jeden Namen der ersten Ebene unterhalb der Domain. Deshalb verlangt Let’s Encrypt dafür die DNS-01-Challenge. Die Authentikatoren --nginx, --apache, --webroot und --standalone arbeiten alle über HTTP. Die einzige Möglichkeit ist ein TXT-Record unter _acme-challenge.example.com oder in der Zone, an die dieser Name per CNAME delegiert ist. Der Record wird manuell oder über ein DNS-Plugin angelegt.

Gilt ein Wildcard-Zertifikat auch für die Root-Domain?

Nein. Das Wildcard-Zertifikat gilt genau für ein Label. *.example.com gilt daher für www.example.com, aber nicht für die nackte example.com und auch nicht für a.b.example.com. Fordern Sie beide Namen mit -d example.com -d '*.example.com' in einem Zertifikat an. Dadurch entstehen zwei Challenges. Beide TXT-Records liegen unter demselben Namen _acme-challenge.example.com. Fügen Sie den zweiten Record daher hinzu, ohne den ersten zu löschen.

Warum wird mein Wildcard-Zertifikat nicht automatisch erneuert?

Weil es mit --manual ausgestellt wurde. Für jede Erneuerung ist ein neuer TXT-Wert erforderlich. Der unbeaufsichtigte Timer kann diesen Wert nicht eintragen. Deshalb endet die Erneuerung mit dem Fehler An authentication script must be provided with --manual-auth-hook when using the manual plugin non-interactively. Stellen Sie das Zertifikat mit einem DNS-Plugin wie certbot-dns-cloudflare neu aus. Alternativ können Sie --manual-auth-hook und --manual-cleanup-hook-Skripte bereitstellen, die den Record über die API Ihres Providers ändern.

Wie lange dauert es, bis der TXT-Record _acme-challenge erscheint?

Das hängt von Ihrem DNS-Provider ab. Es kann wenige Sekunden bis mehrere Minuten dauern. Die Validierung liest die autoritativen Nameserver Ihrer Zone. Prüfen Sie den Eintrag daher mit dig +short TXT _acme-challenge.example.com @1.1.1.1 und warten Sie, bis der erwartete Wert angezeigt wird, bevor Sie einen manuellen Lauf fortsetzen. Mit einem Plugin können Sie die integrierte Wartezeit über die Propagationsoption des Plugins erhöhen, beispielsweise mit --dns-cloudflare-propagation-seconds 60, wenn die Validierung meldet, dass der Record nicht gefunden wurde.

Ist ein Wildcard-Zertifikat weniger sicher als ein normales Zertifikat?

Die Kryptografie ist identisch. Die Unterschiede liegen im Betrieb: Ein privater Schlüssel gilt für jede Subdomain. Bei einer Kompromittierung ist daher ein größerer Bereich betroffen. Außerdem ist das für die Automatisierung benötigte DNS-API-Zugangstoken ein sensibles Geheimnis, das auf dem Server gespeichert wird. Wenn Sie nur wenige bekannte Subdomains betreiben, vermeidet ein SAN-Zertifikat beide Risiken. Genau in diesem Fall empfiehlt diese Anleitung, auf ein Wildcard-Zertifikat zu verzichten.