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

1. Als Enterprise Admin unter dem Menüpunkt Enterprise den Tab ACME auswählen

2. Dort den Button „Create +“ betätigen

3. Unbedingt einen Friendly Name vergeben

• Erforderlich zur späteren Identifikation des Accounts in der Übersichtsliste
• Kann nicht nachträglich eingefügt oder geändert werden

4. Auswahl von SSL DV oder SSL OV

• Eigenschaften siehe oben
• Kann nicht nachträglich geändert werden

5. Nach Betätigung des Buttons „Create“ schließt sich der Dialog

6. Nun muss der neue Account in der Liste aufgesucht und geöffnet werden

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

8. Nach dem Hinzufügen der Regeln können im Tab „Details“ die ACME EAB Parameter abgelesen werden.

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.

Beim Registrieren des Accounts mit dem ACME-Client muss eine Mailadresse muss angegeben werden. Andernfalls antwortet HARICA mit einem Fehler.

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

Ob Personal ACME Accounts generell in einem Enterprise zur Verfügung stehen oder nicht, kann konfiguriert werden. Die Konfiguration gilt für das gesamte Enterprise, es gibt keine Steuerung für individuelle User.

Zur Konfiguration muss ein Enterprise Admin unter dem Menüpunkt „Enterprise→Admin“ die eigene Einrichtung aufrufen.

Anschließend oben rechts das „Etikett“-Symbol anklicken, und #ACME-Personal aktivieren.

Die Personal ACME Accounts können von jedem User im System über den Punkt „ACME“ im linken Seitenmenü verwaltet werden.

1. Der Button Create+ erzeugt einen Account.

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

Ein Aufruf eines ACME-Clients geschieht beispielsweise mit (Beispiel 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 des Zertifikats>

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; alternativ eine DNS-basierte Methode.

Beim Registrieren des Accounts mit dem ACME-Client muss eine Mailadresse muss angegeben werden. Andernfalls antwortet HARICA mit einem Fehler.

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

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

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