ACME und Let’s Encrypt¶

Siehe auch

Let’s Encrypt ist eine kostenlose, automatisierte und offene Zertifizierungsstelle (CA), betrieben von der Internet Security Research Group (ISRG). Ausgestellt werden ausschliesslich domain-validierte TLS-Zertifikate mit einer Gültigkeitsdauer von 90 Tagen. Die kurze Laufzeit zwingt zur Automatisierung der Erneuerung, weshalb sich auf der Client-Seite das ACME-Protokoll (Automated Certificate Management Environment, RFC 8555) etabliert hat.

Das Protokoll ist nicht an Let’s Encrypt gebunden. Es gibt weitere öffentliche ACME-CAs (u.a. BuyPass und ZeroSSL) sowie die Möglichkeit, eine eigene ACME-Instanz mit step-ca zu betreiben. Von Client-Seite her ist der Wechsel der CA darum meist nur ein Tausch der --server-URL.

Neben ACME existieren weitere Enrollment-Protokolle für andere Einsatzzwecke, insbesondere SCEP (RFC 8894) für Geräte-Zertifikate in Enterprise-Umgebungen (Cisco-Geräte, Microsoft-Intune via NDES, MDM-Lösungen). Die Abgrenzung zwischen ACME und SCEP und ein Kurzvergleich stehen in Step CA.

Die Linuxfabrik setzt als ACME-Client standardmässig acme.sh ein. Das Deployment erfolgt über die LFOps-Rolle acme_sh. certbot wird nur in Ausnahmefällen benutzt (z.B. wenn die Distribution den Client bereits im Paket liefert und man sich den zusätzlichen Aufwand sparen möchte). Für lokale Testsetups ohne öffentliche CA betreibt man eine eigene ACME-Instanz mit step-ca.

Begriffe

Account: Identität beim ACME-Server. Wird durch ein Schlüsselpaar abgebildet; im Account liegt typischerweise eine E-Mail-Adresse für Ablauf- und Sicherheits-Benachrichtigungen.
ACME: das Protokoll, über das ein Client bei einer CA Zertifikate bestellt, Challenges löst und Zertifikate einzieht. Die Referenz ist RFC 8555.
Challenge: der Nachweis, dass der Bestellende die Kontrolle über die beantragte Domain hat. Die drei gebräuchlichen Typen sind http-01, dns-01 und tls-alpn-01.
CA (Certificate Authority): die ausstellende Instanz. Im Kontext dieses Artikels meist Let’s Encrypt, kann aber auch BuyPass, ZeroSSL oder eine eigene step-ca- Installation sein.
Directory: Start-URL der CA, die dem Client die verschiedenen API-Endpoints bekanntmacht. Beispiele:
- Let’s Encrypt Produktion: https://acme-v02.api.letsencrypt.org/directory
- Let’s Encrypt Staging: https://acme-staging-v02.api.letsencrypt.org/directory
Order: eine konkrete Zertifikats-Anfrage für eine oder mehrere Domains. Eine Order durchläuft Authorization → Challenge → Finalize → Zertifikat.
Rate-Limit: Begrenzung der ACME-API. Wird bei Let’s Encrypt projektweit und kontospezifisch erhoben, siehe Abschnitt Rate-Limits.
Renewal: Erneuerung eines Zertifikats vor Ablauf. Convention: in den letzten 30 Tagen der Gültigkeit.
Staging: separate Test-CA von Let’s Encrypt, deren Zertifikate nicht von Browsern vertraut werden, aber das Setup eines neuen Clients ohne Rate-Limit-Risiko testen lassen.

Challenge-Typen¶

http-01: Der Client legt ein Token unter http://<domain>/.well-known/acme-challenge/<file> ab. Die CA fragt es per HTTP (Port 80) ab. Gängigste Variante, weil keine DNS-API nötig ist; setzt voraus, dass die CA die Domain über Port 80 erreicht. Nicht geeignet für Wildcard-Zertifikate.
dns-01: Der Client setzt einen _acme-challenge.<domain>-TXT-Record. Die CA prüft den Eintrag per DNS. Einziger Weg zu Wildcard-Zertifikaten. Setzt Schreibzugriff auf den DNS-Server bzw. dessen API voraus. Alle gängigen ACME-Clients bringen Plugins für die grossen DNS-Provider (Cloudflare, Route53, Hetzner, …) mit.
tls-alpn-01: Die CA baut eine TLS-Verbindung mit einem speziellen ALPN-Protokoll auf Port 443 auf und prüft das präsentierte Zertifikat. Nützlich, wenn Port 80 nicht verfügbar ist, der Port 443 aber sehr wohl durchgereicht wird. Setzt einen Client/Server voraus, der das ALPN-Protokoll acme-tls/1 beherrscht.

Rate-Limits¶

Let’s Encrypt begrenzt die API an mehreren Stellen, unter anderem die Zahl der Zertifikate pro registrierbarer Domain, die Zahl der Duplikat-Zertifikate, die Zahl der Orders pro Account sowie die Zahl der fehlgeschlagenen Validierungen pro Account und Hostname. Gerade der letzte Punkt schmerzt beim Aufsetzen eines neuen Clients: kleine Tippfehler bringen einen schnell ins Sperrfenster. Aus dem bisherigen Betrieb: Bei „Failed Validation“ wurde nach fünf Fehlschlägen pro Account und Hostname innerhalb einer Stunde gesperrt.

Die exakten Schwellwerte ändern Let’s Encrypt von Zeit zu Zeit. Vor Automatisierung und vor dem Aufsetzen neuer Produktionssysteme ist ein Blick in die aktuelle offizielle Übersicht Pflicht: https://letsencrypt.org/docs/rate-limits/.

Staging¶

Das Staging-System von Let’s Encrypt hat praktisch keine Rate-Limits und stellt funktionierende, aber von Browsern nicht akzeptierte Zertifikate aus. Setup und Automation werden immer zuerst gegen Staging getestet, erst dann wird gegen Produktion umgestellt.

Die Staging-URL ist https://acme-staging-v02.api.letsencrypt.org/directory. Alle Clients kennen sie als Option, typischerweise --staging oder --server <URL>.

Zertifikats-Lifecycle¶

Ein Let’s-Encrypt-Zertifikat ist aktuell 90 Tage gültig. Die gängige Praxis:

Renewal automatisieren, typischerweise mit einem gewissen Vorlauf vor Ablauf, damit bei einem Fehlschlag genug Zeit bleibt, ihn vor dem tatsächlichen Ablauf zu beheben. Alle hier beschriebenen Clients bringen dafür einen systemd-Timer oder einen Cron-Job mit.
Reload des Webservers (oder Restart, wenn nicht anders möglich) wird per Hook aus dem Renewal-Lauf ausgelöst, damit der neue Private Key und das neue Zertifikat sofort aktiv werden.
Monitoring der Zertifikats-Restlaufzeit, damit ein ausgelaufenes Zertifikat frühzeitig auffällt. Die meisten Icinga-/Nagios-Bestände bringen dafür einen generischen check_http- oder check_ssl_cert-Check mit.

Client-Vergleich¶

acme.sh: Pure-Shell-Implementierung, keine Python-Abhängigkeiten, rootless betreibbar. Reich an DNS-Provider-Plugins. Linuxfabrik-Default (siehe LFOps-Rolle acme_sh). Wartet eigene Zertifikatsdatenbank unter /etc/acme.sh/ und kopiert die ausgestellten Zertifikate per --install-cert an den vorgesehenen Platz.
certbot: Python-basierter Referenz-Client der EFF. In den meisten Distributionen als Paket verfügbar (RHEL via EPEL, Debian/Ubuntu direkt im Main-Repo). Apache- und Nginx-Plugins können die Webserver-Konfiguration automatisch anpassen. Eher gross, zieht eine Python-Laufzeitumgebung samt Abhängigkeiten mit.
step-ca: Kein ACME-Client, sondern ein eigener ACME-Server. Wird dort eingesetzt, wo man gegen eine lokale, kontrollierte CA arbeiten will (Offline-Setups, Testumgebungen, interne PKI). Kann gleichzeitig auch SCEP und weitere Provisioner-Protokolle sprechen.

Troubleshooting¶

urn:ietf:params:acme:error:rateLimited: Rate-Limit erreicht. Siehe Rate-Limits. Neue Versuche frühestens nach Ablauf des Fensters (in der Fehlermeldung angegeben). Für Tests auf Staging umschalten.
Failed authorization for <domain>: ... DNS problem: NXDOMAIN: Die Domain löst nicht auf. A/AAAA-Records prüfen, DNS-Propagierung abwarten. Bei dns-01 ausserdem prüfen, ob der Nameserver des Zone-Owners die _acme-challenge- TXT-Records überhaupt setzt.
Timeout during connect bei http-01: Die CA erreicht den Webserver auf Port 80 nicht. Firewall-Regeln und Provider-Firewall prüfen, bei Reverse-Proxy-Setups den Pfad /.well-known/acme-challenge/ bis zum ACME-Client durchreichen lassen. Cloud-Firewalls (AWS Security Groups, Hetzner Cloud Firewall) vergessen Admins gerne.
Zertifikat wurde ausgestellt, aber Browser meldet „Zertifikat abgelaufen“: Ein Renewal hat erfolgreich ein neues Zertifikat geholt, aber der Webserver lädt weiterhin das alte. Die post-renewal- oder --reloadcmd-Hook-Konfiguration prüfen, den Webserver manuell reloaden und die Hook-Konfiguration reparieren.