de:dfnpki:tcs:2025:acme [Dokumentation DFN-AAI, DFN-PKI und eduroam]

Diese Seite ist nicht editierbar. Sie können den Quelltext sehen, jedoch nicht verändern. Kontaktieren Sie den Administrator, wenn Sie glauben, dass hier ein Fehler vorliegt.
====== Serverzertifikate über ACME ======

HARICA bietet die Möglichkeit, über das ACME-Protokoll und Standard-Werkzeuge Serverzertifikate zu beziehen.

Viele einführende Informationen finden sich in dem folgenden Foliensatz: {{ :de:dfnpki:harica:2026-01-22-automatisierung.pdf |Webinar "Automatisierung mit ACME"}}

(Der verlinkte Foliensatz wurde am 12.02.2026 mit Hinweisen auf die derzeitige Inkompatibilität von ''mod_md'' ergänzt.)

Zusätzlich gibt es [[https://www.harica.gr/en/guides/harica-flexible-acme/|HARICAs' Flexible ACME Guide]] für die Konfigurationen in HARICA's Certificate Manager.

===== ACME EAB 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 ====

  * 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
  * Variante SSL OV:
    * Zertifikate mit Organisationsinformationen (O=Hochschule Musterstadt)
    * 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

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]]


==== Personal EAB Accounts ====

  * 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
  * 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]]

==== Zertifikatketten ====


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 ====

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** |


HARICA unterstützt die Challenge-Typen ''http-01'' und ''dns-01''.

==== Wildcard-Zertifikate ====

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

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!) 

==== Zertifikate mit IP-Adressen (IPv4/IPv6) ====

HARICA kann via ACME mit Domain-Control-Validierungs-Methode (DCV) ''ACME-HTTP-01'' Serverzertifikate mit IP-Adressen ausstellen. Für diese IP-Adressen **wird immer** eine ''ACME-HTTP-01''-Domain-Control-Validierungs-Challenge an Port 80 der jeweiligen IP-Adresse durchgeführt. **Bei HARICA muss für/in ein Serverzertifikat mit einer IP-Adresse immer auch mindestens ein FQDN mit beantragt/aufgenommen werden.** Die aufzunehmenden IP-Adressen werden einfach beim Zertifikatsbezug über den verwendeten ACME-Client mit angefragt und müssen nicht vorab bei HARICA eingetragen werden.

Es werden IPv4 und IPv6 Adressen unterstützt. Z.B. unterstützt ''certbot'' die Beantragung von IP-Adressen in Zertifikaten ab Version 5.3.0 und acme.sh ab Version 3.1.4. Beim acme.sh Aufruf ist die Reihenfolge der ''--domain'' Optionen relevant: Zuerst die IP-Adresse(n) dann der/die FQDN(s) angeben.

In der Regel werden nur in seltenen technischen Spezialfällen Serverzertifikate mit IP-Adressen benötigt.

==== Werkzeuge und Beispielaufrufe ====

=== Allgemein ===

Unter https://acmeclients.com/ findet sich eine Liste von aktuell verfügbaren ACME Clients.

=== 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>


Für Personal ACME Accounts 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>

''certbot'' installiert unter Umständen bereits direkt einen ''cron''-Job und einen ''systemd''-Timer zu Erneuerung des Zertifikats. Bitte unbedingt kontrollieren!

    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>

=== acme.sh ===

    acme.sh --register-account --eab-kid <Key ID> --eab-hmac-key <HMAC Key> --server <Server URL>
    acme.sh --issue --standalone --domain <FQDN> --server <Server URL>

=== cert-manager für Kubernetes ===


    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

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/


=== Nicht nutzbar: Apache Modul mod_md ===

Neuere Versionen von ''mod_md'' sind derzeit nicht mit HARICA kompatibel. Das erste Ausstellen eines Zertifikats funktioniert, allerdings scheitert die Erneuerung aufgund eines Bugs in der ARI-Implementierung von ''mod_md''. Teilweise wurde auch beobachtet, dass ''mod_md'' soviele Anfragen an die ACME-Directory-URL des HARICA-Systems schickt, dass dort eine IP-Sperre greift.

Der Fehler ist nach unserem Kenntnisstand mindestens ab ''mod_md'' v2.6.0 enthalten (Achtung: Versionssnummern von ''mod_md'' sind unabhängig von den Apache-Versionen).
 

''mod_md'' ist damit derzeit nicht nutzbar.

=== 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.

=== Ansible ===

Bei den ''community.crypto''-Module von Ansible muss der Parameter  ''modify_account: false'' angegeben werden, damit die Zertifikaterstellung funktioniert.

=== certbot mit --dry-run oder --test-cert Option ===

Sofern die ''certbot''-Software mit einer der Optionen ''--dry-run'' oder ''--test-cert'' genutzt wird, gibt es Fehlermeldungen und Fehlfunktionen, weil ''certbot'' bei diesen Testfunktionalitäten hart verdrahtete ACME-Endpunkte von Let'sEncrypt verwendet, die naturgemäß mit ACME-Accounts, die im HARICA-System angelegt wurden, nicht funktionieren.

Um z.B. eine Zertifikaterneuerung vorab zu "testen", kann ''certbot renew --force-renewal'' verwendet werden.

=== 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?

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)?