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"

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

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>

  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/

Apache-Modul mod_md aktivieren:

 a2enmod md ssl
 

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.

 MDomain <fqdn>
 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.

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.

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

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