Unterschiede

Hier werden die Unterschiede zwischen zwei Versionen angezeigt.

--- de:dfnpki:tcs:2025:acme [2025/07/29 09:13] – Juergen Brauckmann
+++ de:dfnpki:tcs:2025:acme [2026/02/03 18:30] (aktuell) – [Wildcard-Zertifikate] Juergen Brauckmann
@@ Zeile 2: / Zeile 2: @@
 HARICA bietet die Möglichkeit, über das ACME-Protokoll und Standard-Werkzeuge Serverzertifikate zu beziehen.
-Hierfür müssen in der Oberfläche unter https://cm.harica.gr sogenannte ACME Accounts angelegt werden.
-Es gibt zwei verschiedene Typen ACME Accounts:
+Viele einführende Informationen finden sich in dem folgenden Foliensatz: {{ :de:dfnpki:harica:2026-01-22-automatisierung.pdf |Webinar "Automatisierung mit ACME"}}
-  * Enterprise Accounts
-  * Personal Accounts
+===== ACME EAB Accounts =====
-==== Enterprise Accounts ====
+Zur Nutzung von ACME mit HARICA müssen in der Oberfläche unter https://cm.harica.gr sogenannte ACME EAB Accounts angelegt werden.
+Es gibt zwei verschiedene Typen ACME EAB Accounts:
+  * Enterprise EAB Accounts
+  * Personal EAB Accounts
+==== Enterprise EAB Accounts ====
-=== Eigenschaften ===
   * Können nur vom Enterprise Admin angelegt werden
   * FQDN/Domains, für die Zertifikate ausgestellt werden können, können im Account sehr detailliert konfiguriert werden
@@ Zeile 25: / Zeile 28: @@
     * ACME Challenge, wenn die Domain keine aktuelle Validierung hat
-=== Anleitung ===
+Die Nutzung von Enterprise ACME EAB Accounts ist dokumentiert unter: [[https://doku.tid.dfn.de/de:dfnpki:tcs:2025:acme_enterprise|https://doku.tid.dfn.de/de:dfnpki:tcs:2025:acme_enterprise]]
-. Als Enterprise Admin unter dem Menüpunkt Enterprise den Tab ACME auswählen
-{{:de:dfnpki:harica:enterprise-acme.png?800|Bild des Dialogs Enterprises-ACME}}
-. Dort den Button "Create +" betätigen
-. **Unbedingt** einen Friendly Name vergeben
+==== Personal EAB Accounts ====
-  * Erforderlich zur späteren Identifikation des Accounts in der Übersichtsliste
-  * Kann nicht nachträglich eingefügt oder geändert werden
-. Auswahl von SSL DV oder SSL OV
-  * Eigenschaften siehe oben
-  * Kann nicht nachträglich geändert werden
-. Nach Betätigung des Buttons "Create" schließt sich der Dialog
-. Nun muss der neue Account in der Liste aufgesucht und geöffnet werden
-. Unter dem Tab "Domains" müssen Regeln hinzugefügt werden, für welche Subdomains oder FQDN Zertifikate ausgestellt werden sollen. Für eine neue Regel klicken Sie auf das "+" links neben einer Domain. Es können Deny oder Allow-Regeln konfiguriert werden, um komplexe Szenarien abbilden zu können.
-**Ohne explizit hinzugefügte Regeln können keine Zertifikate ausgestellt werden.**
-{{:de:dfnpki:harica:enterprise-acme-domains.png?600|Bild des Dialogs Enterprises-ACME-Domains}}
-. Nach dem Hinzufügen der Regeln können im Tab "Details" die ACME EAB Parameter abgelesen werden.
-{{:de:dfnpki:harica:enterprise-acme-details.png?800|Bild des Dialogs Enterprises-ACME-Details}}
-Ein Aufruf eines ACME-Clients geschieht beispielsweise mit:
-    certbot certonly --standalone --non-interactive --agree-tos --email <eigene Mailadresse> --eab-kid <Key ID> --eab-hmac-key <HMAC Key> --server <Server URL> --domain <FQDN des Zertifikats>
-Im Rahmen der Ausstellung muss keine ACME-Challenge beantwortet werden. Es ist keine Änderung am DNS und kein Kontakt per HTTP zwischen CA und Webserver notwendig.
-Beim Registrieren des Accounts mit dem ACME-Client muss eine Mailadresse muss angegeben werden. Andernfalls antwortet HARICA mit einem Fehler.
-==== Personal Accounts ====
-=== Eigenschaften ===
   * In einem Enterprise nur verfügbar, wenn der Admin die Möglichkeit hierzu freigeschaltet hat
@@ Zeile 77: / Zeile 40: @@
   * ACME Challenge bei jeder Zertifikatausstellung erforderlich, um die Berechtigung nachzuweisen
   * SSL DV Zertifikate (ohne Organisationsinformationen)
-=== Freischaltung und Nutzung von Personal ACME Accounts ===
-Die Funktionalität für Personal ACME Accounts ist erst nach einer Freischaltung durch den Enterprise Administrator verfügbar.
 Die Freischaltung und Nutzung ist dokumentiert unter: [[https://doku.tid.dfn.de/de:dfnpki:tcs:2025:acme_personal|https://doku.tid.dfn.de/de:dfnpki:tcs:2025:acme_personal]]
@@ Zeile 87: / Zeile 45: @@
 ==== Zertifikatketten ====
-Im Rahmen des Prozesses liefert der ACME-Server einen Zertifikatkette aus, die vom ACME-Client in der Regel zur Installation auf dem System verwendet wird.
-HARICA liefert per ACME eine Kette aus, die im Cross-Zertifikat für die Root CA 2015 endet. Damit ist eine größtmögliche Kompatibilität zu Anwendungssoftware gegeben.  [[https://doku.tid.dfn.de/de:dfnpki:tcs:2025:cacerts#legacy-root-ca-zertifikate_2015_fuer_serverzertifikate|Legacy-Root-CA-Zertifikate 2015]]
+HARICA liefert als Teil der Automatisierung per ACME eine Zertifikatkette aus, die eine größtmögliche Kompatibilität zu Anwendungssoftware sicherstellt. Die Zertifikatkette endet Cross-Zertifikat für die Root CA 2015.  [[https://doku.tid.dfn.de/de:dfnpki:tcs:2025:cacerts#legacy-root-ca-zertifikate_2015_fuer_serverzertifikate|Legacy-Root-CA-Zertifikate 2015]]
 ==== ACME Challenges ====
@@ Zeile 106: / Zeile 63: @@
 HARICA unterstützt die Challenge-Typen ''http-01'' und ''dns-01''.
-**Achtung:** Im Gegensatz zu Let's Encrypt folgt HARICA bei ''dns-01'' derzeit keinen CNAMEs!
+==== Wildcard-Zertifikate ====
-Folgendes funktioniert derzeit **nicht**:
-    _acme-challenge.<domain> IN CNAME <auth-domain>
-    <auth-domain> IN TXT <ACME dns-01 challenge>
+Wildcard-Zertifikate können ausgestellt werden, wenn die folgenden Bedingungen zutreffen:
+  * Enterprise EAB Account
+    * Mit Domainregeln, die Subdomains einschließt
+    * und vorvalidierten Domains
+    * **oder** beim Account-Typ SSL DV der Fähigkeit, dns-01-Challenges zu beantworten.
+  * Personal EAB Account
+    * Fähigkeit, dns-01-Challenges zu beantworten
-==== Beispielaufrufe ====
+Es gibt keine Möglichkeit, in der HARICA-Oberfläche die Ausstellung von Wildcard-Zertifikaten einzuschränken. Gegebenenfalls können hierfür [[https://doku.tid.dfn.de/de:dfnpki:tcs:2025:caa|CAA-Records]] verwendet werden (Achtung: Nur eingeschränkte Möglichkeiten bei Schreibzugriff aufs DNS von Subdomains, da CAA-Records von Subdomains die darüberliegende Domain überschreiben können!)
+==== Werkzeuge und Beispielaufrufe ====
+=== Allgemein ===
+Unter https://acmeclients.com/ findet sich eine Liste von aktuell verfügbaren ACME Clients.
 === certbot ===
@@ Zeile 125: / Zeile 92: @@
     certbot certonly --webroot --webroot-path /var/www --non-interactive --agree-tos --email <eigene Mailadresse> --eab-kid <Key ID> --eab-hmac-key <HMAC Key> --server <Server URL> --domain <FQDN>
+''certbot'' installiert unter Umständen bereits direkt einen ''cron''-Job und einen ''systemd''-Timer zu Erneuerung des Zertifikats. Bitte unbedingt kontrollieren!
-=== win-acme ===
+    systemctl show certbot.timer
+=== simple-acme ===
     .\wacs.exe --source manual --accepttos --eab-key-identifier <Key ID> --eab-key <HMAC Key> --baseuri <Server URL> --emailaddress <Mail> --host <FQDN>
@@ Zeile 171: / Zeile 141: @@
-==== Fehlermeldungen ====
-Der ACME-Server von HARICA gibt im Fehlerfall teilweise nur sehr generische Meldungen zurück, z.B.
+=== Apache Modul mod_md ===
-    {
-      "type": "urn:ietf:params:acme:error:serverInternal",
+Apache-Modul mod_md aktivieren:
-      "detail": "failed to order certificate from RA"
+   a2enmod md ssl
-    }
-oder als Ausgabe von certbot
+Konfiguration des Apache: Es sind nur wenige Zeilen in den Server-Context einzutragen (und nicht den Virtualhost!). Im VirtualHost muss lediglich SSL angeschaltet werden. Es sind keine Pfade zu Zertifikaten oder Keys zu konfiguieren.
-    An unexpected error occurred:
+   MDomain <fqdn>
-    AttributeError: can't set attribute
+   MDContactEmail <mailadresse>
+   MDCertificateAgreement accepted
+   MDCertificateAuthority <Server-URL wie im ACME EAB Account angegeben>
+   MDExternalAccountBinding /etc/apache2/<Datei mit EAB Details>
+   <VirtualHost *:443>
+      ServerName <fqdn>
+      SSLEngine On
+      DocumentRoot /var/www/html
+   </VirtualHost>
+Inhalt der Datei mit EAB-Details:
+    {"kid": "<Key ID aus HARICA", "hmac": "<HMAC Key aus HARICA"}
+In Experimenten war nach der initialen Konfiguration ein zweifacher Neustart des Apache notwendig.
+=== ACME-Proxy tiny-acme-server ===
+Von der Friedrich-Alexander-Universität Erlangen-Nürnberg gibt es den ''tiny-acme-server'', der nach innen zur Einrichtung hin ACME mit http-01-Challenge anbietet, und in Richtung des PKI-Anbieters mit dessen spezifischen API kommuniziert: https://gitos.rrze.fau.de/noc/tiny-acme-server/-/tree/master?ref_type=heads
+=== ACME-Proxy PKI Self Service Portal HM.edu ===
+Die Hochschule München veröffentlicht ihr PKI Self-Service-Portal unter: https://github.com/hm-edu/pki-portal-deployment/tree/main
+==== Fallstricke und Fehlermeldungen ====
+=== Fehler "not whitelisted" ===
+Die folgende Fehlermeldung bedeutet: Die Domain ist nicht im Enterprise EAB Account hinterlegt, aber prinzipiell im Enterprise verfügbar.
+Gegenmaßnahme:
+  * Angeforderte Domain prüfen. Tippfehler?
+  * Den Enterprise EAB Account konfigurieren: Im Tab "Domains" des Accounts eine Allow-Regel für die gewünschte Domain angelegen.
+    The following domains are not whitelisted: <fqdn>
+=== Fehler "Identifiers could not be parsed" ===
+Die folgende Fehlermeldung bedeutet: Die Domain ist nicht im Enterprise verfügbar.
+Gegenmaßnahme:
+  * Angeforderte Domain prüfen. Tippfehler?
+  * Domain dem Enterprise hinzufügen [Domainverwaltung](de:dfnpki:tcs:2025:domains#domains)
+    Identifiers could not be parsed from ACME Server
+=== Email-Adresse erforderlich ===
+Bitte unbedingt bei der Account-Erzeugung eine Email-Adresse übergeben (z.B. ''certbot''-Parameter ''--email'' oder entsprechende Konfigurationsparameter bei caddy, Traefik, ...). Das HARICA-System lehnt die Account-Erzeugung sonst ab.
+=== Prüfpunkte ===
 Beim Auftreten eines Fehlers sollten folgende Punkte zunächst geprüft werden:
@@ Zeile 196: / Zeile 217: @@
   - Ist es dem ACME Client möglich, eine HTTP- oder DNS-Challenge zu beantworten? Sind hierbei evtl. Fehler aufgetreten (prüfen im Log des ACME Clients)?
+=== Ansible ===
+Bei den ''community.crypto''-Module von Ansible muss der Parameter  ''modify_account: false'' angegeben werden, damit die Zertifikaterstellung funktioniert.