Serverzertifikate über ACME

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:

• Enterprise Accounts
• Personal 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 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

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

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>

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>

  .\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/

Der ACME-Server von HARICA gibt im Fehlerfall teilweise nur sehr generische Meldungen zurück, z.B.

  {
    "type": "urn:ietf:params:acme:error:serverInternal",
    "detail": "failed to order certificate from RA"
  }

oder als Ausgabe von certbot

  An unexpected error occurred:
  AttributeError: can't set attribute

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.