Unterschiede

Hier werden die Unterschiede zwischen zwei Versionen angezeigt.

--- de:dfnpki:tcs:2025:acme [2025/07/28 09:06] – 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
+==== Personal EAB Accounts ====
-{{:de:dfnpki:harica:enterprise-acme.png?800|Bild des Dialogs Enterprises-ACME}}
-. Dort den Button "Create +" betätigen
-. **Unbedingt** einen Friendly Name vergeben
-  * 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 78: / Zeile 41: @@
   * SSL DV Zertifikate (ohne Organisationsinformationen)
+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]]
-=== Freischaltung von Personal ACME Accounts ===
-Ob Personal ACME Accounts generell in einem Enterprise zur Verfügung stehen oder nicht, kann konfiguriert werden. Die Konfiguration gilt für das gesamte Enterprise, es gibt keine Steuerung für individuelle User.
-Zur Konfiguration muss ein Enterprise Admin unter dem Menüpunkt „Enterprise→Admin“ die eigene Einrichtung aufrufen.
-Anschließend oben rechts das "Etikett"-Symbol anklicken, und #ACME-Personal aktivieren.
-{{:de:dfnpki:harica:enterprise-details-tags.png?800|Bild des Dialogs Enterprise-Details}}
-=== Nutzung von Personal ACME Accounts ===
-Die Personal ACME Accounts können von jedem User im System über den Punkt "ACME" im linken Seitenmenü verwaltet werden.
-. Der Button Create+ erzeugt einen Account.
-. Aufruf des neuen Accounts in der Liste klappt die Details auf. Dort können die Parameter Key ID, HMAC Key und Server URL abgelesen werden, die für die Verwendung mit einem ACME Client benötigt werden.
-{{:de:dfnpki:harica:personal-acme.png?800|Bild des Dialogs Personal ACME}}
-Ein Aufruf eines ACME-Clients geschieht beispielsweise mit (Beispiel mit HTTP-Validierung über einen bereits laufenden Webserver mit Dokumenten-Root in ''/var/www''):
-    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 des Zertifikats>
-Zur Ausstellung des Zertifikats muss eine ACME-Challenge beantwortet werden, um die Berechtigung innerhalb des Enterprises nachzuweisen. Es ist daher ein Kontakt per HTTP zwischen CA und auf dem FQDN laufenden Webserver notwendig; alternativ eine DNS-basierte Methode.
-Beim Registrieren des Accounts mit dem ACME-Client muss eine Mailadresse muss angegeben werden. Andernfalls antwortet HARICA mit einem Fehler.
 ==== 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 134: / 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 153: / 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 199: / 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 224: / 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.