Certbot Wildcard Zertifikat DNS-01 Anleitung

Warum ein Wildcard-Zertifikat DNS-01 benötigt

Ein Wildcard-Zertifikat deckt jede Subdomain der ersten Ebene einer Domain ab: *.example.com passt zu app.example.com, blog.example.com und jedem anderen Namen mit einer Label-Tiefe. Let's Encrypt stellt Wildcard-Zertifikate nur über die DNS-01-Challenge aus. Daher muss Certbot die Kontrolle über die DNS-Einstellungen der Domain nachweisen, indem ein TXT-Record bei _acme-challenge.example.com veröffentlicht wird. Die HTTP-01-Challenge ist nicht geeignet, da das Bereitstellen einer Token-Datei nur die Kontrolle über einen einzelnen Hostnamen beweist – nämlich den Hostnamen, von dem der Validierungsserver die Datei abgerufen hat. Ein Wildcard-Zertifikat gilt für jeden möglichen Namen unterhalb der Domain. Der DNS-Eintrag ist der einzige öffentliche Datensatz, der für den gesamten Namensraum gilt.

Diese eine Anforderung bestimmt alle weiteren Details auf dieser Seite. Um die DNS-01-Challenge zu bestehen, müssen Sie TXT-Records in der Zone der Domain erstellen können. Dies geschieht entweder manuell oder über die API (Application Programming Interface) Ihres DNS-Anbieters. Die manuelle Methode funktioniert nur einmal; bei der Erneuerung schlägt sie fehl, aus dem unten genannten Grund. Die API-Methode über ein Certbot-DNS-Plugin ermöglicht eine automatisierte Erneuerung. Dies ist die empfohlene Konfiguration.

Dies ist das Wildcard-Kapitel unserer Certbot-Anleitungen. Informationen zu gewöhnlichen Zertifikaten für einzelne Hostnamen, der Webserver-Konfiguration und den Port-80-Regeln finden Sie in Certbot mit nginx auf Ubuntu 24.04 und Certbot mit Apache auf Ubuntu 24.04.

Funktionsweise des _acme-challenge TXT-Records

Wenn Certbot *.example.com anfordert, antwortet Let's Encrypt mit einem zufälligen Token. Certbot kombiniert dieses Token mit Ihrem ACME (automatic certificate management environment) Account-Key, hasht das Ergebnis mit SHA-256 und erzeugt einen kurzen Textwert. Dieser Wert muss als TXT-Record unter _acme-challenge.example.com erscheinen. Let's Encrypt fragt dann die autoritativen Nameserver Ihrer Domain von der eigenen Infrastruktur aus ab. Wenn der gelesene Record mit dem erwarteten Wert übereinstimmt, haben Sie die Kontrolle über die Zone bewiesen. Die Kontrolle über die Zone wird als Kontrolle über alle darunterliegenden Namen akzeptiert.

Zwei Details verursachen die meisten Fehler:

• Die Anforderung von example.com und *.example.com für dasselbe Zertifikat bedeutet zwei separate Challenges. Beide TXT-Records liegen unter demselben Namen, _acme-challenge.example.com. Beide müssen gleichzeitig existieren. Das Hinzufügen des zweiten Records ist korrekt; das Ersetzen des ersten durch den zweiten führt zum Fehlschlagen der ersten Challenge.
• Die Validierung liest Ihre autoritativen Server aus, aber Provider-Control-Panels benötigen oft eine Minute oder länger, um einen neuen Record zu propagieren. Prüfen Sie den Status von extern, bevor Sie die Validierung starten:

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

Wenn der Befehl den von Certbot angeforderten Wert ausgibt, kann die Validierung erfolgreich sein. Wenn keine Ausgabe erfolgt, warten Sie und führen Sie den Befehl erneut aus.

Einmalig testen: manueller Modus

Im manuellen Modus müssen Sie die DNS-Änderung selbst vornehmen. Dies ist der beste Weg, um den Mechanismus vor der Automatisierung zu verstehen:

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

Die Anführungszeichen um den Wildcard verhindern, dass die Shell * als Dateimuster interpretiert. Certbot pausiert und zeigt 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 Control Panel Ihres DNS-Anbieters. Überprüfen Sie die Sichtbarkeit mit dem oben genannten Befehl dig. Drücken Sie erst danach die Enter-Taste. Da dieser Durchlauf sowohl die Root-Domain als auch den Wildcard anfordert, erscheint die Aufforderung von Certbot zweimal. Behalten Sie beide Einträge bei, bis die Ausstellung abgeschlossen ist. Bei Erfolg erscheint die folgende Meldung:

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

Warum der manuelle Modus keine automatische Erneuerung ermöglicht

Jede Erneuerung erfordert einen neuen Token, weshalb sich der TXT-Wert jedes Mal ändert. Der heute eingefügte Datensatz ist in 60 Tagen ungültig. Der Certbot-Erneuerungszeitplan läuft zweimal täglich im Hintergrund ab. Da niemand die neuen Werte manuell einfügt, 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-Anbieters aufrufen. In diesem Fall bauen Sie jedoch manuell ein DNS-Plugin nach. Nutzen Sie den manuellen Modus, um den Ablauf zu erlernen oder für einmalige Aufgaben bei Domains, deren DNS noch nicht automatisiert werden kann. Setzen Sie sich eine Erinnerung deutlich vor Ablauf der 90 Tage, da Let's Encrypt keine E-Mails zur Ablauffrist mehr versendet. Verwenden Sie für alle anderen Anwendungsfälle ein Plugin.

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

Ein DNS-Plugin nutzt API-Anmeldedaten Ihres DNS-Anbieters und führt den gesamten Prozess der TXT-Einträge selbstständig aus, sowohl bei der Ausstellung als auch bei jeder Erneuerung. Cloudflare dient hier als Beispiel, da es das am häufigsten benötigte Anbieter-Plugin ist und in Ubuntu enthalten ist.

Unsere Certbot-Anleitungen empfehlen die Verwendung von apt-Paketen unter Ubuntu 24.04. Dies gilt auch für Cloudflare:

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

Ein Hinweis zu den Versionen. Das 24.04-Archiv liefert dieses Plugin in der Version 2.0.0 zusammen mit Certbot 2.9.0 aus; apt policy python3-certbot-dns-cloudflare zeigt Ihre installierte Version. Diese Abweichung ist unbedenklich. Scoped API-Tokens funktionieren, da die zugrunde liegende python3-cloudflare-Bibliothek in 24.04 die Version 2.11.1 nutzt, was über der für die Token-Unterstützung erforderlichen Version 2.3.1 liegt. Bei älteren Ubuntu-Versionen war diese Bibliothek zu alt für Tokens. Dies ist die Ursache für Warnungen im Internet, die besagen, dass das apt-Plugin den Globalen API-Key erzwingt. Unter 24.04 sind diese Warnungen nicht mehr relevant.

Erstellen Sie im Cloudflare-Dashboard ein Scoped API-Token statt des Globalen API-Keys: My Profile, dann API Tokens, dann Create Token. Wählen Sie die einzelne Berechtigung Zone / DNS / Edit und beschränken Sie diese auf die eine Zone, für die Sie das Zertifikat ausstellen. Speichern Sie das Token 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 Dateiberechtigungen 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-Einträge über die API, wartet eine kurze Propagationszeit, lässt die Validierung laufen und löscht die Einträge 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 in /etc/letsencrypt/live/example.com/ gespeichert. Verweisen Sie nginx oder Apache genau wie in den Basis-Anleitungen auf fullchain.pem und privkey.pem, inklusive des Deploy-Hooks.

Wenn das Plugin Ihres Providers nicht in apt enthalten ist

Das 24.04-Archiv enthält Plugins nur für eine begrenzte Anzahl von Providern. Dazu gehören 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, gilt hier eine Ausnahme von unserer bevorzugten apt-Installation: Installieren Sie Certbot und das Plugin stattdessen über snap. Entfernen Sie vorher die apt-Version von Certbot, damit zwei Erneuerungs-Timer nicht 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 verbindet sich nur mit dem snap-Certbot; es kann das apt-Paket nicht erweitern. Deshalb dürfen die beiden Installationen nicht gleichzeitig existieren. Falls Ihr DNS-Host keine API anbietet, haben Sie zwei Möglichkeiten: Verschieben Sie die DNS-Einstellungen der Domain zu einem Provider mit API-Unterstützung oder betreiben Sie einen eigenen Nameserver und verwenden Sie das rfc2136-Plugin dafür.

Erneuerung: Jetzt testen, nicht erst in 60 Tagen

Certbot protokolliert die Ausstellung jedes Zertifikats in /etc/letsencrypt/renewal/example.com.conf, einschließlich authenticator = dns-cloudflare und des Pfads für die Anmeldedaten. Der standardmäßige Timer, der zweimal täglich läuft, führt die Erneuerung ohne Ihr Eingreifen durch. Testen Sie den gesamten Vorgang in der Staging-Umgebung:

sudo certbot renew --dry-run

Ein erfolgreicher Test bedeutet, dass die Anmeldedaten korrekt sind und die Validierung vollständig abgeschlossen wird. Die tatsächliche Erneuerung in 60 Tagen folgt demselben Ablauf. Zwei Vorbereitungen sollten Sie heute treffen. Erstens: Ein erneuertes Zertifikat auf der Festplatte hat keine Auswirkung, bis der Webserver es neu lädt. Implementieren Sie daher den Deploy-Hook, der in den Anleitungen für nginx und Apache beschrieben wird. Zweitens: Behandeln Sie die Datei mit den Anmeldedaten mit besonderer Sorgfalt. Jeder, der diese Datei lesen kann, kann Ihre DNS-Zone bearbeiten. Dies reicht aus, um Ihre E-Mails umzuleiten oder eigene DNS-01-Challenges zu bestehen. Speichern Sie die Datei mit dem Modus 600 unter /root, beschränken Sie den Token auf eine Zone und rotieren Sie ihn, falls Sie einen Datenabfluss vermuten.

Wann Sie keinen Wildcard-Zertifikats-Typ benötigen

Ein Wildcard-Zertifikat ist das richtige Werkzeug für viele Subdomains oder für Subdomains, die nicht vorhersehbar sind. Für alle anderen Fälle ist es als Standard nicht geeignet.

• Eine einzelne Subdomain oder eine kleine Anzahl bekannter Subdomains: Ein normales SAN (Subject Alternative Name) Zertifikat ist einfacher. certbot --nginx -d example.com -d www.example.com -d app.example.com unterstützt bis zu 100 Namen über HTTP-01, und es müssen keine DNS-API-Anmeldedaten auf dem Server hinterlegt werden.
• Ein Wildcard deckt exakt ein Label ab. *.example.com deckt das nackte example.com nicht ab, weshalb die obigen Befehle beide anfordern; es deckt auch a.b.example.com nicht ab; dafür wäre *.b.example.com erforderlich.
• Hinter jeder Subdomain steht ein privater Schlüssel. Wenn der Host, auf dem dieser Schlüssel liegt, kompromittiert wird, sind alle durch das Wildcard-Zertifikat abgedeckten Namen gleichzeitig betroffen.
• Wenn Traefik TLS (Transport Layer Security) für Ihre Container terminiert, benötigen Sie Certbot nicht: Traefik fordert Wildcard-Zertifikate selbst über DNS-01 an, wobei derselbe Provider-Token verwendet wird.

Einsatzgebiete für Wildcard-Zertifikate: Kunden- oder App-spezifische Subdomains, die schneller erstellt werden, als Sie Zertifikate erneuern können, sowie interne Hosts ohne öffentlichen Port 80, wie etwa Dienste, die nur über ein WireGuard VPN erreichbar sind. DNS-01 stellt keine Verbindung zum zu zertifizierenden Host her, sodass selbst eine vollständig private Maschine ein öffentlich vertrauenswürdiges Zertifikat besitzen kann.

FAQ

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

Nein. HTTP-01 beweist die Kontrolle über einen einzelnen Hostnamen, da der Validierungsserver eine Token-Datei von genau diesem Namen abruft. Ein Wildcard-Zertifikat deckt alle Namen unter der Domain ab. Daher erfordert Let's Encrypt für Wildcard-Zertifikate die DNS-01-Challenge. Die Authentifikatoren --nginx, --apache, --webroot und --standalone basieren alle auf HTTP. Der einzige Weg ist ein TXT-Eintrag bei _acme-challenge.example.com, der manuell oder über ein DNS-Plugin gesetzt wird.

Deckt ein Wildcard-Zertifikat die Root-Domain ab?

Nein. Das Wildcard-Zertifikat passt auf genau ein Label. Daher deckt *.example.com www.example.com ab, aber nicht die nackte Domain example.com und auch nicht a.b.example.com. Fordern Sie beide Namen mit -d example.com -d '*.example.com' in einem Zertifikat an. Dies erzeugt zwei Challenges. Beide TXT-Einträge liegen unter demselben _acme-challenge.example.com-Namen. Fügen Sie den zweiten Eintrag hinzu, ohne den ersten zu löschen.

Warum wird mein Wildcard-Zertifikat nicht automatisch erneuert?

Weil es mit --manual ausgestellt wurde. Jede Erneuerung benötigt einen neuen TXT-Wert. Der automatisierte Timer kann diesen Wert nicht einfügen, weshalb die Erneuerung mit dem Fehler An authentication script must be provided with --manual-auth-hook when using the manual plugin non-interactively abbricht. Stellen Sie das Zertifikat mit einem DNS-Plugin wie certbot-dns-cloudflare neu aus oder verwenden Sie --manual-auth-hook und --manual-cleanup-hook Skripte, die den Eintrag über die API Ihres Providers bearbeiten.

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

Dies hängt von Ihrem DNS-Provider ab: es dauert zwischen wenigen Sekunden und mehreren Minuten. Die Validierung liest die autoritativen Server Ihrer Zone aus. Prüfen Sie dies mit dig +short TXT _acme-challenge.example.com @1.1.1.1 und warten Sie, bis der erwartete Wert erscheint, bevor Sie einen manuellen Durchlauf fortsetzen. Erhöhen Sie bei Verwendung eines Plugins die integrierte Wartezeit über die Propagation-Option des Plugins, zum Beispiel --dns-cloudflare-propagation-seconds 60, falls die Validierung meldet, dass der Eintrag nicht gefunden wurde.

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

Die Kryptografie ist identisch. Die Unterschiede sind operativer Natur: Ein privater Schlüssel deckt alle Subdomains ab, wodurch sich die Auswirkungen einer Kompromittierung vergrößern. Zudem ist die für die Automatisierung erforderliche DNS-API-Anmeldedaten ein sensibles Geheimnis, das auf dem Server gespeichert wird. Wenn Sie nur wenige bekannte Subdomains betreiben, vermeidet ein SAN-Zertifikat beide Probleme. In diesem Fall empfiehlt dieser Leitfaden, auf Wildcard-Zertifikate zu verzichten.