Unterschiede

Hier werden die Unterschiede zwischen zwei Versionen angezeigt.

--- de:dfnpki:tcs:2025:acme [2025/06/24 14:40] – Juergen Brauckmann
+++ de:dfnpki:tcs:2025:acme [2025/08/08 13:54] (aktuell) – Juergen Brauckmann
@@ Zeile 11: / Zeile 11: @@
 ==== Enterprise Accounts ====
-=== Eigenschaften ===
   * Können nur vom Enterprise Admin angelegt werden
-  * Vorvalidiert, keine ACME Challenges
+  * FQDN/Domains, für die Zertifikate ausgestellt werden können, können im Account sehr detailliert konfiguriert werden
-  * Ausschließlich für Domains, die im HARICA CertManager bereits validiert wurden
+  * Variante SSL OV:
-  * FQDN/Domains, für die Zertifikate ausgestellt werden können, können im Accont sehr detailliert konfiguriert werden
+    * Zertifikate mit Organisationsinformationen (O=Hochschule Musterstadt)
-  * Zertifikate mit (SSL OV) bzw. ohne Organisationsinformationen (SSL DV)
+    * Für Domains, die in dem Enterprise gelistet sind
+    * Domains benötigen eine aktuelle Validierung. Bedeutet konkret: Im UI liegt das Datum in der Spalte "Validity" in der Zukunft.
+    * Keine ACME Challenge
+  * Variante SSL DV:
+    * Zertifikate ohne Organisationsinformationen
+    * Für Domains, die in dem Enterprise gelistet sind
+    * ACME Challenge, wenn die Domain keine aktuelle Validierung hat
-=== Anleitung ===
+Die Nutzung von Enterprise ACME 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
-Im folgenden Dialog unbedingt einen Friendly Name vergeben (kann nicht nachträglich geändert werden). An dieser Stelle können noch keine Einstellungen bzgl. Domains gemacht 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.
-Eine Mailadresse muss angegeben werden, HARICA antwortet sonst mit einem Fehler.
 ==== Personal Accounts ====
-=== Eigenschaften ===
   * In einem Enterprise nur verfügbar, wenn der Admin die Möglichkeit hierzu freigeschaltet hat
   * Für jeden User in diesem Enterprise zugänglich (wenn freigeschaltet)
+  * Für alle Domains, die in dem Enterprise gelistet sind, dem der User zugeordnet ist
+  * Auch für Domains, die zwar gelistet, aber nicht validiert wurden
   * Pro User maximal drei zeitgleich aktive ACME Accounts
   * ACME Challenge bei jeder Zertifikatausstellung erforderlich, um die Berechtigung nachzuweisen
-  * **Derzeit für alle Domains, unabhängig von Domain-Listen im Enterprise**
   * 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 ===
+==== Zertifikatketten ====
-Ob Personal ACME Accounts generell in einem Enterprise zur Verfügung stehen oder nicht, kann konfiguriert werden. Es können keine individuelle User von der Nutzung von ACME ausgeschlossen werden.
+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.
-Zur Konfiguration muss ein Enterprise Admin unter dem Menüpunkt „Enterprise→Admin“ die eigene Einrichtung aufrufen.
+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]]
-Anschließend oben rechts das "Etikett"-Symbol anklicken, und #ACME-Personal aktivieren.
+==== ACME Challenges ====
-{{:de:dfnpki:harica:enterprise-details-tags.png?800|Bild des Dialogs Enterprise-Details}}
+Abhängig vom Account-Typ, der gewählten Variante und der angefragten Domain sind ACME Challenges erforderlich.
+^ Account Typ      ^ Variante       ^ Domain          ^ Challenge?          ^
+| Enterprise    | SSL DV     | vorvalidiert        | nein |
+|               |            | nicht validiert     | **ja** |
+| Enterprise    | SSL OV     | vorvalidiert        | nein |
+|               |            | nicht validiert     | **nicht möglich, Fehler** |
+| Personal      |            | vorvalidiert        | **ja** |
+|               |            | nicht validiert     | **ja** |
-=== 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.
+HARICA unterstützt die Challenge-Typen ''http-01'' und ''dns-01''.
-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.
+**Achtung:** Im Gegensatz zu Let's Encrypt folgt HARICA bei ''dns-01'' derzeit keinen CNAMEs!
+Folgendes funktioniert derzeit **nicht**:
+    _acme-challenge.<domain> IN CNAME <auth-domain>
+    <auth-domain> IN TXT <ACME dns-01 challenge>
-{{:de:dfnpki:harica:personal-acme.png?800|Bild des Dialogs Personal ACME}}
+==== Beispielaufrufe ====
+=== certbot ===
+Für Enterprise Accounts mit vor-validierten Domains (ohne ACME Challenge):
+    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>
-Ein Aufruf eines ACME-Clients geschieht beispielsweise mit:
-    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>
+Für Personal ACME Accounts mit HTTP-Validierung über einen bereits laufenden Webserver mit Dokumenten-Root in ''/var/www'':
-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.
+    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>
-Eine Mailadresse muss angegeben werden, HARICA antwortet sonst mit einem Fehler.
+=== win-acme ===
+    .\wacs.exe --source manual --accepttos --eab-key-identifier <Key ID> --eab-key <HMAC Key> --baseuri <Server URL> --emailaddress <Mail> --host <FQDN>
-==== Bekannte Inkompatibilitäten ====
-Derzeit funktioniert HARICAs ACME nicht mit dem cert-manager von Kubernetes.
+=== cert-manager für Kubernetes ===
-Die Fehlermeldung ist:
-    Failed to wait for order resource "test" to become ready: order is in "errored" state: Failed to create Order: 400 urn:ietf:params:acme:error:malformed: No Key ID in JWS header.
-HARICA arbeitet an einer Lösung.
+    apiVersion: cert-manager.io/v1
+    kind: ClusterIssuer
+    metadata:
+      name: 'harica-prod'
+      namespace: cert-manager
+    spec:
+      acme:
+        email: <Email>
+        externalAccountBinding:
+          keyID: <Key ID>
+          keySecretRef:
+            key: secret
+            name: harica-key
+        preferredChain: ''
+        privateKeySecretRef:
+          name: harica-prod-key
+        server: <Server URL>
+        solvers:
+          - http01:
+              ingress:
+                class: ingress-intern
-==== Fehlermeldungen ====
+Dazu wird ein Secret benötigt, das den HMAC-Schlüssel für das External Account Binding enthält:
+    apiVersion: v1
+    kind: Secret
+    metadata:
+      name: harica-key
+      namespace: cert-manager
+    type: Opaque
+    data:
+      secret: <BASE64(HMAC Key aus dem HARICA Portal)>
+Über diesen ClusterIssuer können dann gemäß der cert-manager-Dokumentation Zertifikate beantragt und automatisch ausgestellt werden.
+https://cert-manager.io/docs/usage/certificate/
+==== Fallstricke und Fehlermeldungen ====
+=== Fehlermeldungen ===
 Der ACME-Server von HARICA gibt im Fehlerfall teilweise nur sehr generische Meldungen zurück, z.B.
     {
@@ Zeile 117: / Zeile 137: @@
     AttributeError: can't set attribute
-Beim Auftreten eines Fehlers sollte zuerst geprüft werden:
+=== 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:
+Enterprise ACME Accounts:
   - Sind die Daten Key-ID, HMAC-Key, Server-URL korrekt im Aufruf des ACME Clients angegeben?
   - Ist der FQDN, für den ein Zertifikat beantragt wird, im ACME-Account wirklich freigeschaltet und verfügbar? Haben Sie expliizite Regeln im Tab  "Domains" hinzugefügt?
   - Ist die Domain im Enterprise erfolgreich validiert?
-  - Wurde dem ACME-client ein Parameter ''--email'' übergeben?
+  - Wurde dem ACME Client ein Parameter ''--email'' übergeben?
+Personal ACME Accounts:
+  - Sind die Daten Key-ID, HMAC-Key, Server-URL korrekt im Aufruf des ACME Clients angegeben?
+  - Ist die Domain im Enterprise gelisted (Validierung im CertManager nicht erforderlich)?
+  - Wurde dem ACME Client ein Parameter ''--email'' übergeben?
+  - 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.