Let’s Encrypt mit Cert Warden

Let’s Encrypt mit Cert Warden (DNS-01 Challenge)

Cert Warden ist ein selbst betriebener Zertifikatsmanager, der Let’s Encrypt Zertifikate bestellt, verlängert und an Ihre Server verteilt. Mit den beiden folgenden Skripten erledigt Cert Warden die Prüfung über unsere DNS-API, also über die DNS-01 Challenge. Das funktioniert ohne offenen Port 80 und auch für Systeme, die aus dem Internet gar nicht erreichbar sind, sowie für Wildcard-Zertifikate wie *.ihredomain.ch.

Voraussetzungen

Die Domain muss auf unsere Nameserver zeigen, die DNS-Zone also bei FireStorm liegen
API-Zugang im Kundenbereich aktiviert (admin.firestorm.ch => Konto => Kundenprofil)
Eine laufende Cert Warden Installation, üblicherweise als Docker-Container
Im Container muss curl vorhanden sein. jq wird verwendet, wenn es da ist, ist aber nicht nötig

1. API-Key erstellen

Melden Sie sich im Kundenbereich an und öffnen Sie Konto => Kundenprofil.

Setzen Sie den Haken bei API Zugang und klicken Sie auf API KEYS VERWALTEN.

Erstellen Sie einen neuen Key:

Bezeichnung: zum Beispiel certwarden
Domains: die betroffenen Domains auswählen
Auch volle DNS-Verwaltung erlauben: Haken setzen

Notieren Sie sich den API Key. Er wird nur ein einziges Mal angezeigt.

2. Skripte bereitstellen

Legen Sie die beiden Skripte auf dem dauerhaften Speicher Ihres Cert Warden Containers ab, zum Beispiel unter /app/data/scripts/:

curl -o /app/data/scripts/firestorm_dns01_challenge_add.sh https://api.firestorm.ch/downloads/firestorm_dns01_challenge_add.txt
curl -o /app/data/scripts/firestorm_dns01_challenge_del.sh https://api.firestorm.ch/downloads/firestorm_dns01_challenge_del.txt
chmod 755 /app/data/scripts/firestorm_dns01_challenge_add.sh /app/data/scripts/firestorm_dns01_challenge_del.sh

Laden Sie die Dateien über einen Windows-Rechner herunter, achten Sie darauf, dass sie mit Unix-Zeilenenden gespeichert werden. Sonst meldet der Container beim Start des Skripts bad interpreter.

3. Challenge Provider in Cert Warden anlegen

Öffnen Sie in Cert Warden den Bereich Providers und erstellen Sie einen New Challenge Provider.

Feld	Wert
Provider Type	`DNS-01 Manual Script`
Domains	Ihre Domain, zum Beispiel `ihredomain.ch`
Post Provision Wait	`300`
Environment Variables	`FIRESTORM_API_KEY=IHR-API-KEY`
Path to DNS Record Create Script	`/app/data/scripts/firestorm_dns01_challenge_add.sh`
Path to DNS Record Delete Script	`/app/data/scripts/firestorm_dns01_challenge_del.sh`

Speichern Sie mit SUBMIT. Danach können Sie ein Zertifikat bestellen, Cert Warden setzt den TXT-Eintrag selbständig und räumt ihn nach der Prüfung wieder ab.

Weitere Einstellungen

Die Skripte lassen sich über Umgebungsvariablen steuern. Nötig ist nur der API-Key, alles andere ist freiwillig:

Variable	Bedeutung
`FIRESTORM_API_KEY`	Ihr API-Key. Einzige Pflichtangabe
`FIRESTORM_ZONE_ID`	Feste Zone-ID. Bleibt sie leer, sucht das Skript die passende Zone selbst über die Zonenliste. Mit einem zonenbeschränkten Key, der die Zonenliste nicht sehen darf, tragen Sie die ID fest ein
`FIRESTORM_TTL`	Gültigkeitsdauer des TXT-Eintrags, Standard `60`
`FIRESTORM_TIMEOUT`	Wartezeit für den API-Aufruf in Sekunden, Standard `180`
`FIRESTORM_DEBUG`	`1` schreibt Aufrufe und Antworten ins Protokoll, der Key bleibt dabei unkenntlich

Die Zone-ID liefert Ihnen dieser Aufruf:

curl -H "X-Api-Key: IHR-API-KEY" https://api.firestorm.ch/dns/v1/zones

Von Hand testen

Beide Skripte lassen sich direkt aufrufen, auch mit anderen ACME-Clients. Der Probelauf verändert nichts und zeigt nur, was gesendet würde:

FIRESTORM_API_KEY=IHR-API-KEY ./firestorm_dns01_challenge_add.sh --dry-run "_acme-challenge.test.ihredomain.ch" "testwert"

Ohne --dry-run wird der Eintrag tatsächlich gesetzt und wieder entfernt:

FIRESTORM_API_KEY=IHR-API-KEY ./firestorm_dns01_challenge_add.sh "_acme-challenge.test.ihredomain.ch" "testwert"
FIRESTORM_API_KEY=IHR-API-KEY ./firestorm_dns01_challenge_del.sh "_acme-challenge.test.ihredomain.ch" "testwert"

Mit --help zeigen die Skripte ihre vollständige Beschreibung an.

Fehlerbehebung

Das Anlegen dauert eine bis zwei Minuten
Das ist so gewollt. Unsere API wartet bei Challenge-Einträgen selbst, bis alle unsere Nameserver den Wert kennen, und antwortet erst dann. Das Skript hängt also nicht, es wartet.

«Authentifizierung fehlgeschlagen»
Prüfen Sie den API-Key und ob der API-Zugang im Kundenprofil aktiviert ist. Nach mehreren falschen Versuchen sperrt unser Schutzmechanismus die IP-Adresse vorübergehend.

«Zugriff verweigert»
Der Key ist auf bestimmte Domains beschränkt und die angefragte Zone gehört nicht dazu, oder die volle DNS-Verwaltung wurde beim Erstellen nicht erlaubt.

«Keine passende Zone gefunden»
Die Domain liegt nicht als Zone in Ihrem Konto, oder der Key darf sie nicht sehen. Tragen Sie in diesem Fall FIRESTORM_ZONE_ID fest ein.

«bad interpreter» beim Start des Skripts
Die Datei hat Windows-Zeilenenden. Speichern Sie sie mit Unix-Zeilenenden, oder führen Sie im Container sed -i 's/\r$//' firestorm_dns01_challenge_add.sh aus.

Die Prüfung schlägt trotz gesetztem Eintrag fehl
Erhöhen Sie in Cert Warden den Wert bei Post Provision Wait.

Weitere Anleitungen zu unserer Schnittstelle finden Sie im Artikel DNS API. Für Proxmox und pfSense gibt es den Artikel Let’s Encrypt mit DNS-Validierung. Die Skripte wurden uns freundlicherweise von einem unserer Kunden zur Verfügung gestellt.