Zertifikatserneuerung

Der REST-Server kann sein TLS-Zertifikat selbst bei der Zertifizierungsstelle Let's Encrypt beantragen und vor Ablauf erneuern. Zertifikat und privater Schlüssel entstehen auf Ihrem Server und verlassen ihn nicht. Diese Seite beschreibt, wie Sie die Erneuerung je nach Netzaufbau einrichten.

Auf einen Blick

Zwei Prüfarten. http-01 prüft über Port 80, dns-01 über einen DNS-Eintrag und braucht keinen offenen Port.
Selbsttest vorab. Vor dem ersten Zertifikat und danach wöchentlich prüft der Dienst den Weg über das Testsystem der Zertifizierungsstelle.
Erneuerung ab 30 Tagen Restlaufzeit. Das bisherige Zertifikat bleibt als Rückfall erhalten.
dns-01 braucht nur ausgehende Verbindungen und eignet sich damit für VPN und für Server ohne Portfreigabe.

Voraussetzungen

Ein Name, auf den das Zertifikat lautet, zum Beispiel obs.firma.de. Platzhalter-Zertifikate (*.firma.de) werden nicht unterstützt.
Ein Server-Profil mit TLS, also ohne Haken kein SSL.
Ausgehende HTTPS-Verbindungen zur Zertifizierungsstelle (acme-v02.api.letsencrypt.org und für den Selbsttest acme-staging-v02.api.letsencrypt.org).
Bei dns-01 zusätzlich ausgehende HTTPS-Verbindungen zur Schnittstelle des DNS-Anbieters bzw. zur acme-dns-Instanz.

Welche Prüfart?

Prüfart	Funktioniert, wenn	Aus dem Internet erreichbar sein muss
http-01	der Name öffentlich auf diesen Server zeigt und Port 80 von aussen auf ihn weitergeleitet ist	Port 80
dns-01	sich der DNS-Eintrag `_acme-challenge.<Name>` über eine Schnittstelle schreiben lässt, direkt oder über einen CNAME	nichts

Welche Prüfart zu Ihrer öffentlichen Freigabe passt:

Direkte Portfreigabe: http-01 oder dns-01. Mit dns-01 bleibt Port 80 geschlossen.
Reverse-Proxy: Das öffentliche Zertifikat liegt am Proxy, die Erneuerung im REST-Server wird nicht gebraucht.
VPN: dns-01.

Wege bei dns-01

Bei dns-01 fragt die Zertifizierungsstelle den TXT-Eintrag _acme-challenge.<Name> ab. Der Dienst schreibt ihn vor der Prüfung und löscht ihn danach wieder. Dafür gibt es drei Wege:

Weg	Wann	Einmalig beim DNS des Namens	Einstellung DNS-Anbieter
Direkt beim Anbieter	Die Zone des Namens liegt bei Hetzner, Cloudflare oder IONOS	nichts, Sie brauchen nur ein API-Token	Hetzner, Cloudflare oder IONOS
CNAME auf eine Zone bei einem Anbieter	Die Zone des Namens liegt bei einem anderen Anbieter, oder im REST-Server sollen keine Zugangsdaten zur eigenen Zone liegen	CNAME `_acme-challenge.<Name>` auf einen Namen in einer Zone bei Hetzner, Cloudflare oder IONOS	Hetzner, Cloudflare oder IONOS
CNAME auf acme-dns	Eine acme-dns-Instanz steht zur Verfügung, im eigenen Betrieb oder bei einem Dienstleister	CNAME `_acme-challenge.<Name>` auf die fulldomain des acme-dns-Kontos	acme-dns

Beim CNAME-Weg genügt beim DNS-Anbieter des Namens ein von Hand angelegter Eintrag, auch bei Anbietern ohne Schnittstelle. Der REST-Server bekommt dann nur Zugang zur Zone, auf die der CNAME zeigt.

HINWEIS: Namen von DynDNS-Diensten (zum Beispiel …myfritz.net) eignen sich in der Regel nicht als Zertifikatsname, weil sich dort keine eigenen Einträge anlegen lassen. Verwenden Sie einen Namen unter Ihrer eigenen Domain. Der DynDNS-Name bleibt davon unberührt, zum Beispiel für den Zugang zum VPN.

Vorgehen

Gemeinsame Einstellungen

Wählen Sie Stammdaten → Z Weitere Stammdaten → REST-Server → Server und öffnen Sie das Server-Profil.
Stellen Sie auf der Registerkarte 4 Zertifikaterneuerung das Feld Automatische Erneuerung auf Produktivbetrieb.
Tragen Sie im Feld Zertifikatsname (FQDN) den Namen ein, auf den das Zertifikat lauten soll.
Tragen Sie unter Kontakt bei der CA eine E-Mail-Adresse ein. Die Zertifizierungsstelle schickt dorthin Warnungen, wenn ein Zertifikat abzulaufen droht.
Richten Sie die Registerkarte 5 DNS-Prüfung nach einem der folgenden Abschnitte ein und speichern Sie.
Starten Sie den REST-Dienst neu.

Prüfart http-01

Lassen Sie den Namen öffentlich auf die Adresse Ihres Internetanschlusses zeigen.
Leiten Sie am Router Port 80 von aussen auf den Server des REST-Dienstes weiter.
Wählen Sie auf der Registerkarte 5 DNS-Prüfung im Feld Prüfart den Eintrag http-01 (Port 80). Die übrigen Felder bleiben leer.
Geben Sie in der Konsole des REST-Servers cert test ein.

Port 80 darf auf dem Server des REST-Dienstes von keinem anderen Dienst belegt sein, häufig ist das ein Webserver wie IIS. Der REST-Server öffnet den Port nur für die Dauer der Prüfung und schliesst ihn danach wieder.

Prüfart dns-01 direkt beim DNS-Anbieter

Erstellen Sie beim Anbieter der Zone ein API-Token:
- Hetzner: ein API-Token des Projekts mit Lese- und Schreibrecht in der Hetzner Console. Zonen in der früheren DNS-Konsole (dns.hetzner.com) werden nicht unterstützt.
- Cloudflare: ein API-Token mit der Berechtigung, DNS zu bearbeiten, beschränkt auf die Zone.
- IONOS: einen API-Schlüssel. Er besteht aus Präfix und Secret.
Wählen Sie auf der Registerkarte 5 DNS-Prüfung im Feld Prüfart den Eintrag dns-01 (DNS-Eintrag) und im Feld DNS-Anbieter den Anbieter.
Tragen Sie unter Schlüssel / API-Token das Token ein, bei IONOS in der Form Präfix.Secret.
Lassen Sie Name des TXT-Eintrags leer.
Geben Sie in der Konsole cert test ein.

Prüfart dns-01 mit CNAME auf eine Zone bei einem DNS-Anbieter

Legen Sie in einer Zone bei Hetzner, Cloudflare oder IONOS einen Namen für die Prüfung fest, zum Beispiel obs-firma.acme.example.de. Einen Eintrag müssen Sie dort nicht anlegen.
Legen Sie beim DNS-Anbieter Ihres Namens einen CNAME an: _acme-challenge.obs.firma.de auf obs-firma.acme.example.de.
Erstellen Sie ein API-Token für die Zone, in der das Ziel liegt, wie im vorigen Abschnitt beschrieben.
Wählen Sie auf der Registerkarte 5 DNS-Prüfung die Prüfart dns-01 (DNS-Eintrag) und den Anbieter dieser Zone.
Tragen Sie unter Schlüssel / API-Token das Token ein.
Tragen Sie unter Name des TXT-Eintrags das Ziel des CNAME ein, hier obs-firma.acme.example.de.
Geben Sie in der Konsole cert test ein.

Prüfart dns-01 mit CNAME auf acme-dns

Wählen Sie auf der Registerkarte 5 DNS-Prüfung die Prüfart dns-01 (DNS-Eintrag) und den DNS-Anbieter acme-dns.
Tragen Sie unter Adresse (acme-dns) die Adresse der Instanz ein. Sie beginnt mit https://.
Lassen Sie Benutzer (acme-dns), Schlüssel / API-Token und Name des TXT-Eintrags leer und speichern Sie.
Geben Sie in der Konsole cert test ein. Der Dienst legt das Konto bei acme-dns an und trägt Benutzer, Schlüssel und Name selbst ein. Unter Letzte Meldung steht danach der CNAME, den Sie anlegen müssen.
Legen Sie beim DNS-Anbieter Ihres Namens diesen CNAME an: _acme-challenge.<Name> auf die genannte fulldomain.
Geben Sie in der Konsole erneut cert test ein.

ACHTUNG: Leeren Sie die drei Felder später nicht. Der Dienst würde ein neues Konto mit einer neuen fulldomain anlegen, und der gesetzte CNAME zeigte ins Leere. Ein bestehendes Konto tragen Sie mit allen drei Angaben ein. Teilweise gefüllte Angaben weist die Maske beim Speichern ab.

Erstes Zertifikat holen

Ist der Selbsttest bestanden, holt der Dienst das Zertifikat bei der nächsten stündlichen Prüfung. Sofort geht es mit cert renew in der Konsole. Bis das erste Zertifikat da ist, kann sich kein Client mit dem Server-Profil verbinden.

Testbetrieb

ACHTUNG: Im Testbetrieb beantragt der Dienst das Zertifikat beim Testsystem der Zertifizierungsstelle. Einem solchen Zertifikat vertraut kein Client, Anwendungen können sich danach nicht mehr mit diesem Server verbinden. Verwenden Sie den Testbetrieb ausschliesslich auf Testsystemen. Zurück in den Produktivbetrieb kommen Sie, indem Sie das Feld Automatische Erneuerung auf Produktivbetrieb stellen. Der Dienst holt daraufhin sofort ein gültiges Zertifikat, auch wenn das Testzertifikat noch lange läuft.

Ergebnis

Nach bestandenem Selbsttest ist auf der Registerkarte 4 Zertifikaterneuerung der Haken Selbsttest bestanden gesetzt. Unter Letzte Meldung steht "Selbsttest bestanden - von aussen erreichbar" (http-01) bzw. "Selbsttest bestanden - DNS-Eintrag von der CA geprueft" (dns-01). Nach der Ausstellung zeigt Zertifikat gültig bis das Ablaufdatum, und cert in der Konsole zeigt den Stand je Profil.

Danach läuft die Erneuerung selbständig:

Prüfung: Der Dienst sieht stündlich nach, ob etwas ansteht.
Selbsttest: Einmal wöchentlich und nach jeder Änderung von Zertifikatsname, Prüfart, DNS-Anbieter oder Name des TXT-Eintrags prüft der Dienst den Weg über das Testsystem der Zertifizierungsstelle. Besteht der Test nicht, beantragt er kein Zertifikat.
Erneuerung: Ab 30 Tagen Restlaufzeit beantragt der Dienst ein neues Zertifikat.
Übernahme: Der Dienst prüft das neue Zertifikat, speichert es und bewahrt das bisherige als Rückfall auf. Anschliessend startet nur das betroffene Server-Profil neu.
Rückfall: Startet das Profil mit dem neuen Zertifikat nicht, aktiviert der Dienst wieder das vorherige.

Nach einem Fehlschlag wartet der Dienst zunehmend länger, bevor er es erneut versucht: eine, zwei, vier, acht und höchstens 24 Stunden. Das Feld Gesperrt bis zeigt, bis wann. cert test und cert renew in der Konsole wirken sofort, auch während der Sperre.

Befehl	Wirkung
`cert`	Zeigt je Profil Betriebsart, Ablaufdatum, Zustand und das Ergebnis des letzten Selbsttests
`cert test`	Prüft sofort den Weg über das Testsystem der Zertifizierungsstelle. Beantragt kein Zertifikat
`cert renew`	Stösst die Erneuerung sofort an, auch wenn sie noch nicht fällig ist

Bei dns-01 wartet der Dienst nach dem Schreiben des Eintrags 30 Sekunden und dann bis zu drei Minuten, bis der Eintrag über öffentliche DNS-Server sichtbar ist. Erst dann löst er die Prüfung aus.

Wenn es nicht klappt

Die Meldungen stehen unter Letzte Meldung und im Protokoll des REST-Servers.

Meldung	Ursache
"Port 80 laesst sich nicht oeffnen - er ist belegt"	Ein anderer Dienst auf dem Server des REST-Dienstes belegt Port 80, häufig IIS. Dienst abschalten oder die Prüfart dns-01 verwenden
"dns-01 ist eingestellt, aber kein DNS-Anbieter"	Auf der Registerkarte 5 DNS-Prüfung ist kein DNS-Anbieter gewählt
"kein API-Token"	Das Feld Schlüssel / API-Token ist leer
"acme-dns: Konto unvollstaendig"	Von Benutzer, Schlüssel und Name des TXT-Eintrags ist nur ein Teil gefüllt
"Hetzner: keine Zone zu … im Projekt des Tokens"	Das Token gehört zu einem anderen Projekt, oder die Zone liegt noch in der früheren DNS-Konsole
"Cloudflare: keine Zone zu …, die das Token sehen darf"	Das Token ist nicht für diese Zone freigegeben
"IONOS: keine Zone zu … im Vertrag des Schluessels"	Der API-Schlüssel gehört zu einem anderen Vertrag
"… lehnt den TXT-Eintrag ab (HTTP 401)" oder "(HTTP 403)"	Das Token ist ungültig oder darf keine DNS-Einträge ändern
"… ist nach 210 Sekunden noch nicht ueberall sichtbar"	Der Eintrag ist über öffentliche DNS-Server nicht zu sehen. Meist fehlt der CNAME oder zeigt auf ein anderes Ziel als Name des TXT-Eintrags. Der Dienst löst die Prüfung trotzdem aus
"kein oeffentlicher DNS-Server erreichbar"	Ausgehendes DNS (Port 53) ist gesperrt. Der Dienst kann die Sichtbarkeit nicht prüfen und wartet fest 60 Sekunden
"acme-dns-Konto angelegt - jetzt CNAME … setzen"	Kein Fehler: Legen Sie den genannten CNAME an und geben Sie `cert test` ein

Siehe auch