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 umfasst app.example.com, blog.example.com und jeden anderen Namen mit genau einem Label. Let’s Encrypt stellt Wildcard-Zertifikate nur über die DNS-01-Challenge aus. Certbot muss daher die Kontrolle über die DNS-Zone der Domain nachweisen, indem es unter _acme-challenge.example.com einen TXT-Record veröffentlicht. Die HTTP-01-Challenge reicht dafür nicht aus. Das Bereitstellen einer Token-Datei weist nur die Kontrolle über den einen Hostnamen nach, von dem der Validierungsserver die Datei abgerufen hat. Ein Wildcard-Zertifikat bezieht sich auf jeden möglichen Namen 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. Das ist entweder manuell oder über die API (application programming interface) Ihres DNS-Providers möglich. Der manuelle Weg funktioniert einmalig, schlägt bei der Erneuerung jedoch aus einem konkreten, weiter unten beschriebenen Grund fehl. Der API-Weg verwendet ein Certbot-DNS-Plugin und erneuert Zertifikate unbeaufsichtigt. Diese Konfiguration sollten Sie am Ende 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 behandelt.

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 auf Ubuntu 24.04

Ein DNS-Plugin speichert ein API-Zertifikat für Ihren DNS-Provider und erledigt den gesamten Ablauf mit dem TXT-Record selbst. Das gilt sowohl bei der Ausstellung als auch bei jeder Verlängerung. Cloudflare dient hier als Beispiel, weil dieses Provider-Plugin von den meisten Benutzern benötigt wird und in Ubuntu paketiert ist.

Unsere Certbot-Anleitungen empfehlen auf Ubuntu 24.04 die apt-Pakete. Das gilt auch für Cloudflare:

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

Ein wichtiger Hinweis zu den Versionen: Das 24.04-Archiv enthält dieses Plugin in Version 2.0.0 zusammen mit Certbot 2.9.0; apt policy python3-certbot-dns-cloudflare zeigt Ihre Version an. Die Abweichung ist unproblematisch. Scoped API Tokens funktionieren, weil die zugrunde liegende python3-cloudflare-Bibliothek in 24.04 Version 2.11.1 hat. Das liegt über der für die Token-Unterstützung erforderlichen Version 2.3.1 des Plugins. In älteren Ubuntu-Versionen war diese Bibliothek zu alt für Tokens. Daher stammen die online zu findenden Warnungen, dass das apt-Plugin den Global API Key erzwingt. Auf 24.04 gelten sie nicht mehr.

Erstellen Sie im Cloudflare-Dashboard ein Scoped API Token, nicht den Global API Key: My Profile, dann API Tokens und anschließend Create Token. Verwenden Sie ausschließlich die Berechtigung Zone / DNS / Edit und beschränken Sie sie auf die Zone, für die Sie das Zertifikat ausstellen. Speichern Sie das Token in einer Datei, die nur root lesen kann:

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 mit Unsafe permissions on credentials configuration file, wenn andere Benutzer die Datei lesen können. Stellen Sie das Zertifikat nun 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 kurz auf die Verteilung, führt die Validierung aus und löscht die Records anschließend wieder. Wenn 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. Verweisen Sie nginx oder Apache auf fullchain.pem und privkey.pem, genau wie in den grundlegenden Anleitungen beschrieben, einschließlich des Deploy-Hooks.

Wenn das Plugin Ihres Providers nicht in apt enthalten ist

Das Archiv für 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, weicht unsere Empfehlung für apt-first an dieser Stelle ab: Installieren Sie Certbot und das Plugin stattdessen über snap. Entfernen Sie vorher den apt-Certbot, 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, bleiben Ihnen realistisch nur zwei Möglichkeiten: Sie übertragen das DNS der Domain zu einem Provider mit API oder Sie betreiben einen eigenen Nameserver und verweisen das rfc2136-Plugin darauf.

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. Mit HTTP-01 wird die Kontrolle über einen Hostnamen nachgewiesen, weil der Validierungsserver eine Token-Datei unter genau diesem Namen abruft. Ein Wildcard-Zertifikat gilt für jeden Namen unterhalb der Domain. Deshalb verlangt Let's Encrypt dafür die DNS-01-Challenge. Die Authenticatoren --nginx, --apache, --webroot und --standalone arbeiten jedoch alle auf HTTP-Basis. Es bleibt nur ein TXT-Record unter _acme-challenge.example.com, der manuell oder durch ein DNS-Plugin gesetzt wird.

Deckt ein Wildcard-Zertifikat die Root-Domain ab?

Nein. Das Wildcard-Zertifikat entspricht genau einem Label. *.example.com deckt daher www.example.com ab, aber weder die nackte example.com noch 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 verwenden denselben Namen _acme-challenge.example.com. Fügen Sie deshalb den zweiten Record hinzu, ohne den ersten zu löschen.

Warum wird mein Wildcard-Zertifikat nicht automatisch erneuert?

Weil es mit --manual ausgestellt wurde. Bei jeder Erneuerung ist ein neuer TXT-Wert erforderlich. Der unbeaufsichtigte Timer kann diesen Wert nicht eintragen. Deshalb bricht die Erneuerung mit dem Fehler An authentication script must be provided with --manual-auth-hook when using the manual plugin non-interactively ab. Stellen Sie das Zertifikat mit einem DNS-Plugin wie certbot-dns-cloudflare neu aus. Alternativ können Sie die Skripte --manual-auth-hook und --manual-cleanup-hook 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. Die Dauer reicht von wenigen Sekunden bis zu mehreren Minuten. Die Validierung fragt die autoritativen Server Ihrer Zone ab. Prüfen Sie den Eintrag mit dig +short TXT _acme-challenge.example.com @1.1.1.1 und warten Sie, bis der erwartete Wert erscheint, bevor Sie einen manuellen Lauf fortsetzen. Erhöhen Sie bei einem Plugin die integrierte Wartezeit über die Propagationsoption des Plugins, zum Beispiel 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 reicht der Schaden daher weiter. Außerdem ist das für die Automatisierung erforderliche DNS-API-Credential 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 das Wildcard-Zertifikat zu verzichten.