Zertifikate

Zertifikate

ZPO besorgt TLS-Zertifikate über ACME (eingebettetes lego — keine externen Werkzeuge), erneuert sie rechtzeitig und verteilt sie ohne Reload auf alle Proxy-Knoten. Fremdzertifikate lassen sich hochladen.

Für den Nachweis, dass die Domains dir gehören, gibt es zwei Wege:

Challenge	Wie	Wann
DNS (DNS-01)	ZPO setzt einen TXT-Eintrag über die API deines DNS-Providers.	Wildcards, Dienste ohne offenen Port 80, interne Namen mit öffentlicher Zone.
HTTP (HTTP-01)	Ein Proxy mit öffentlicher Adresse beantwortet die Anfrage der CA unter /.well-known/acme-challenge/.	Kein DNS-Provider mit API nötig — die Domain muss nur öffentlich auf den Proxy zeigen. Keine Wildcards.

Vorbereitung

ACME-Konto anlegen

Ein ACME-Konto besteht aus Directory-URL und E-Mail; Registrierung und Kontoschlüssel entstehen beim ersten Gebrauch und liegen danach verschlüsselt.

Feld	Bedeutung
Directory-URL	z. B. https://acme-v02.api.letsencrypt.org/directory — jede beliebige ACME-CA ist möglich.
E-Mail	Kontaktadresse der Registrierung.
EAB	External Account Binding (KID und HMAC), für CAs, die es verlangen.

DNS-01-Provider hinterlegen

Die DNS-01-Challenge braucht einen API-Zugang zum DNS der Domain. ZPO bietet zweierlei:

• Gepflegte Masken für häufige Provider: nur die Felder der Maske ausfüllen.

  Provider	Code	Zugangsdaten
  Cloudflare	cloudflare	API-Token mit dem Recht Zone → DNS → Edit
  Amazon Route 53	route53	Access Key, Secret Key, Region
  Hetzner DNS	hetzner	API-Token aus der Hetzner Cloud Console (Sicherheit → API-Token, Lesen und Schreiben)
  hosting.de	hostingde	API-Schlüssel aus secure.hosting.de → Profil → API-Keys, mit den Rechten DNS_ZONES_LIST und DNS_ZONES_EDIT; der Zonenname ist nur nötig, wenn ZPO die Zone nicht selbst findet
  deSEC	desec	Token
  DigitalOcean	digitalocean	API-Token
  IONOS	ionos	API-Schlüssel im Format Präfix.Geheimnis

• Anderer lego-Provider: für alle übrigen DNS-Provider.

Die Zugangsdaten liegen verschlüsselt und verlassen den Server nie.

Anderer lego-Provider — was das heißt

ZPO bestellt Zertifikate nicht über Certbot oder ein anderes externes Werkzeug, sondern über die eingebaute Go-Bibliothek lego. lego kennt über 150 DNS-Provider. Jeder hat

• einen Code (z. B. njalla, netcup, inwx, ovh) und
• eigene Umgebungsvariablen für die Zugangsdaten (z. B. NETCUP_CUSTOMER_NUMBER, NETCUP_API_KEY, NETCUP_API_PASSWORD).

Beides steht in der Liste der DNS-Provider auf der Seite des jeweiligen Providers, dort meist auch, wo es den Schlüssel gibt. In der Maske wählst du anderer lego-Provider, trägst den Code ein und die Variablen als NAME=WERT, eine je Zeile:

NETCUP_CUSTOMER_NUMBER=12345
NETCUP_API_KEY=…
NETCUP_API_PASSWORD=…

Sobald der Code eingetragen ist, verlinkt die Maske direkt auf die passende Seite der lego-Dokumentation. Optionale Variablen wie *_PROPAGATION_TIMEOUT oder *_TTL lassen sich genauso setzen.

Wer von Certbot kommt: Die Certbot-Plugins (certbot-dns-…) haben eigene Ini-Dateien und Namen; für ZPO gelten die Variablen aus der lego-Dokumentation.

Zugang testen

Im Dialog jedes Providers steht Zugang testen. Du gibst eine Domain an, die bei diesem Provider liegt, und ZPO macht, was eine Bestellung auch tut: Es legt den TXT-Eintrag _acme-challenge.<Domain> an und entfernt ihn gleich wieder. Der Test nimmt die Werte der Maske, sie müssen dafür nicht gespeichert sein. Scheitert er, steht die Meldung des Providers darunter und im Protokoll von ZPO.

Ein reiner Lesezugriff wäre schneller, würde aber einen Schlüssel ohne Schreibrecht durchwinken — und genau der fällt erst bei der nächsten Erneuerung auf.

Zertifikat bestellen

Auf der Zertifikatsseite stehen zwei Knöpfe: Neues Zertifikat (DNS-Challenge) und Neues Zertifikat (HTTP-Challenge). Im Dienst-Dialog bietet die Zertifikatsauswahl dieselben zwei Einträge an; das Zertifikat entsteht dann beim Speichern für alle Hostnamen des Dienstes.

Einstellung	Bedeutung
Domains	eine oder mehrere — bei DNS auch Wildcards, z. B. *.beispiel.de und beispiel.de im selben Zertifikat (SAN).
DNS-Provider	nur DNS-Challenge: der Zugang, über den ZPO den TXT-Eintrag setzt.
Proxy	nur HTTP-Challenge: der Proxy, der die Anfrage der CA beantwortet. Zur Wahl stehen nur Proxys mit öffentlicher Adresse (unter Proxy-Knoten eingetragen).
Schlüsseltyp	ec256 (Vorgabe: modern, schnell), ec384, rsa2048, rsa4096, rsa8192. RSA für Abwärtskompatibilität zu alten Clients.
ACME-Profil	das Profil der CA, leer heißt: Standardprofil.
Laufzeit (Tage)	gewünschte Laufzeit; 0 heißt: die CA entscheidet. Die CA darf kürzen, nicht verlängern.
Automatisch erneuern	ARI-gesteuerte Erneuerung (Vorgabe an).

Warnung zum Profil shortlived: Zertifikate mit rund sechs Tagen Laufzeit machen ZPO zur kritischen Komponente. Steht ZPO eine Woche still, laufen die Zertifikate ab. ZPO fragt die Bestätigung dieses Hinweises ab, bevor das Profil scharf wird, und alarmiert früh, wenn eine Erneuerung ausbleibt.

So läuft die HTTP-Challenge

1. Alle Domains müssen im öffentlichen DNS schon auf die öffentliche Adresse des gewählten Proxys zeigen, und Port 80 muss dort beim Proxy ankommen (bei einem Router davor: Portweiterleitung). Die Maske zeigt die Adresse an.
2. ZPO legt das Token der CA über die Runtime-API in die Map zpo_acme.map des Proxys — ohne Reload.
3. Die Grundkonfiguration beantwortet /.well-known/acme-challenge/<token> aus dieser Map, noch vor der https-Umleitung, den Zugangslisten und dem Rate-Limit — die CA fragt von überall und per http.
4. Nach der Prüfung entfernt ZPO das Token wieder und verteilt das Zertifikat wie jedes andere auf die Proxys, deren Dienste es nutzen.

Die DNS-Einträge müssen bleiben: Jede Erneuerung läuft denselben Weg.

Erneuerung

ZPO fragt das von der CA vorgeschlagene Erneuerungsfenster ab (ARI, RFC 9773) und erneuert darin. Bei einem Massenwiderruf zieht die CA dieses Fenster auf „sofort” — ZPO reagiert damit automatisch. Kann eine CA kein ARI, greift die Zwei-Drittel-Regel: erneuert wird nach etwa zwei Dritteln der Laufzeit.

Der Takt des Erneuerers (renew_interval_seconds, Vorgabe eine Stunde) sorgt nur dafür, dass das Fenster nicht verpasst wird — den Zeitpunkt bestimmt die CA. Eine Erneuerung lässt sich auch jederzeit von Hand anstoßen.

Der Erneuerer prüft zusätzlich über den Runtime-Socket der Proxys, welches Zertifikat dort gerade gebunden ist, und meldet Abweichungen.

Fremdzertifikate hochladen

Zertifikate anderer Herkunft (Wildcard einer kommerziellen CA, interne PKI) werden als PEM-Paar hochgeladen: Zertifikatskette plus privater Schlüssel. ZPO prüft die Dateien beim Einlesen und verteilt sie wie eigene — erneuert aber nicht: die Erneuerung bleibt Aufgabe der ausstellenden Stelle.

Verteilung ohne Reload

Jedes Zertifikat wird zum kombinierten PEM-Bundle (Kette plus Schlüssel) zusammengesetzt und über die Data Plane API an /services/haproxy/storage/ssl_certificates geschrieben. Weil die Grundkonfiguration das Zertifikatsverzeichnis generisch bindet (bind ... ssl crt /etc/haproxy/certs/), greift ein neues oder erneuertes Zertifikat ohne Prozess-Neustart und ohne Verbindungsabbrüche.

Herunterladen

Jedes ausgestellte Zertifikat lässt sich über das Download-Symbol in der Liste herunterladen:

Format	Datei	Wofür
Vollständige Kette (PEM)	.fullchain.pem	nginx, Apache, Traefik
Nur das Zertifikat (PEM)	.crt	Server, die Zertifikat und Kette getrennt wollen
Nur die Zwischenzertifikate (PEM)	.chain.pem	dito
Zertifikat binär (DER)	.cer	Windows, Java, Geräte ohne PEM
Kette als PKCS#7	.p7b	Windows, IIS, Java-Keystores
Kette und Schlüssel (PEM)	.pem	HAProxy
Nur der private Schlüssel (PEM)	.key	zusammen mit der vollständigen Kette
PKCS#12 (AES-256)	.pfx	Windows, IIS, Exchange, aktuelles Java — mit Passwort
PKCS#12 kompatibel (3DES)	.pfx	ältere Windows-, macOS- und Java-Versionen

Formate mit privatem Schlüssel verlangen das Recht, Zertifikate zu ändern, und jeder Abruf landet als Schlüssel exportiert im Audit-Log.

Kurze Laufzeiten: was zu beachten ist

• Der Erneuerer muss laufen: renew_interval_seconds nicht auf 0 stellen.
• ZPO selbst braucht Verfügbarkeit — Dienst überwachen, Alarme einrichten.
• DNS-Provider-Zugangsdaten müssen dauerhaft gültig bleiben; ein abgelaufener API-Token stoppt die Erneuerung.
• Die Metrik zpo_certificate_days_left je Zertifikat deckt den drohenden Ablauf über /metrics ab — siehe Betrieb.