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: 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 HARICAs' Flexible ACME Guide für die Konfigurationen in HARICA's Certificate Manager.

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

• 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

• 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

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. Legacy-Root-CA-Zertifikate 2015

Abhängig vom Account-Typ, der gewählten Variante und der angefragten Domain sind ACME Challenges erforderlich.

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

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

HARICA kann via ACME mit Domain-Control-Validierungs-Methode (DCV) ACME-HTTP-01 Serverzertifikate mit IP-Adressen ausstellen. Für die IP-Adresse wird immer eine ACME-HTTP-01-Domain-Control-Validierungs-Challenge an Port 80 der 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. Es werden IPv4 und IPv6 Adressen unterstützt. Z.B. unterstützt certbot IP-Adressen in Zertifikaten ab Version 5.5.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.

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

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

  .\wacs.exe --source manual --accepttos --eab-key-identifier <Key ID> --eab-key <HMAC Key> --baseuri <Server URL> --emailaddress <Mail> --host <FQDN>

  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>

  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/

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.

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

Die Hochschule München veröffentlicht ihr PKI Self-Service-Portal unter: https://github.com/hm-edu/pki-portal-deployment/tree/main

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>

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 
  

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.

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

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.

Beim Auftreten eines Fehlers sollten folgende Punkte zunächst geprüft werden:

Enterprise ACME Accounts:

1. Sind die Daten Key-ID, HMAC-Key, Server-URL korrekt im Aufruf des ACME Clients angegeben?
2. 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?
3. Ist die Domain im Enterprise erfolgreich validiert?
4. Wurde dem ACME Client ein Parameter –email übergeben?

Personal ACME Accounts:

1. Sind die Daten Key-ID, HMAC-Key, Server-URL korrekt im Aufruf des ACME Clients angegeben?
2. Ist die Domain im Enterprise gelisted (Validierung im CertManager nicht erforderlich)?
3. Wurde dem ACME Client ein Parameter –email übergeben?
4. 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)?