====== 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"}} ===== 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!) ==== 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 --eab-kid --eab-hmac-key --server --domain 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 --eab-kid --eab-hmac-key --server --domain ''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 --eab-key --baseuri --emailaddress --host === cert-manager für Kubernetes === apiVersion: cert-manager.io/v1 kind: ClusterIssuer metadata: name: 'harica-prod' namespace: cert-manager spec: acme: email: externalAccountBinding: keyID: keySecretRef: key: secret name: harica-key preferredChain: '' privateKeySecretRef: name: harica-prod-key server: 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: Ü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 === 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 MDContactEmail MDCertificateAgreement accepted MDCertificateAuthority MDExternalAccountBinding /etc/apache2/ ServerName SSLEngine On DocumentRoot /var/www/html Inhalt der Datei mit EAB-Details: {"kid": " === 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. === 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)? === Ansible === Bei den ''community.crypto''-Module von Ansible muss der Parameter ''modify_account: false'' angegeben werden, damit die Zertifikaterstellung funktioniert.