Auf dieser Seite stellen wir den Teilnehmern an der DFN-PKI eine FAQ-Seite zur Einführung in TCS zur Verfügung. Diese Seite wird permanent mit den Fragen der Anwender weiter entwickelt.

TCS (Trust Certificate Service) ist ein PKI-Angebot, dass der DFN-Verein über GÉANT bezieht. GÉANT realisiert den Dienst mit Hilfe von externen Anbietern, die über regelmäßige Ausschreibungen gefunden werden. Der aktuelle Anbieter ist Sectigo.

Überblick über den Dienst bei GÉANT: https://www.geant.org/Services/Trust_identity_and_security/Pages/TCS.aspx

Der DFN-Verein führt das Angebot zur Zeit in einer Pilotphase ein.

In der Pilotphase werden die Prozesse zum Ausrollen des Angebots an alle Teilnehmer der DFN-PKI mit einem eingeschränkten Nutzerkreis erprobt. Die Erprobung ist nicht nur in Bezug auf die internen Prozesse der DFN-PCA zur Versorgung der Teilnehmer notwendig, sondern auch zur Einschätzung der Abläufe und Vorgehensweisen des TCS-Anbieters insbesondere im Bereich der Organisationsvalidierung.

Hierdurch kann leider noch nicht jeder Einrichtung, die dies wünscht, sofort ein Zugang gegeben werden, da der voraussichtlich entstehende Support-Aufwand nicht abgedeckt werden kann.

Wenn genügend Erfahrungen vorliegen, wird das Angebot an alle Teilnehmer der DFN-PKI ausgerollt. Nach derzeitigem Stand wird dies im Sommer 2021 der Fall sein.

Nach Abschluss der Pilotphase (voraussichtlich Sommer 2021) wird der DFN-Verein auf alle Teilnehmer der DFN-PKI zukommen, um einen Zugang zu TCS zu geben.

Voraussetzung ist der Abschluss einer Dienstvereinbarung. Das initiale Setup erfolgt dann in direkter Absprache mit dfnpca@dfn-cert.de.

Bei GÉANT gibt es eine Zusammenstellung von FAQs: https://wiki.geant.org/display/TCSNT/TCS+2020+FAQ

Die Dokumentation von Sectigo zur Administrations-Oberfläche und zu ACME ist zu finden unter https://support.sectigo.com/Com_KnowledgeDetailPage?Id=kA01N000000bvJA

Die REST-API ist dokumentiert unter https://support.sectigo.com/Com_KnowledgeDetailPage?Id=kA01N000000XDkE

Anwender haben Zugriff über die Administrations-Oberfläche unter https://cert-manager.com/customer/DFN

Dort gibt es, wie in der Java RA-Oberfläche der DFN-PKI, einen direkten Überblick über offene Anträge und ausgestellte Zertifikate und eine Verwaltung von Domains. Es gibt eine Verwaltung von weiteren Administratoren und Abteilungen. Im cert-manager ist die sofortige Ausstellung von neuen Server- und Nutzerzertifikaten möglich.

TCS bietet zusätzlich:

Der Anbieter muss die Existenz und den Namen der Organisation regelmäßig über ein Register verifizieren. Der aktuelle Validierungszustand ist über Settings→Organizations einsehbar.

Die Stammdaten der Organisation können nur von der DFN-PCA geändert werden.

Es wird zwischen verschiedenen Rollen unterschieden, die in sich noch einmal mit unterschiedlichen Privilegien versehen werden können.

  • RAO und DRAO sind Registration Authority Officer auf Organisations- oder Department-(Abteilungs)-Ebene. Je nach den diesen Accounts bei der Einrichtung zugewiesenen Rechten können RAO/DRAO weitere RAOs/DRAOs anlegen oder modifizieren, und eine Auswahl der Zertifikattypen SSL, Client und Code Signing erstellen.

Der erste RAO einer Einrichtung wird von der DFN-PCA angelegt. Weitere RAOs oder DRAOs können dann eigenständig angelegt und verwaltet werden. Es ist keine weitere Kommunikation mit der DFN-PCA erforderlich.

  • Privilegien ermöglichen u.a. das Anlegen oder modifizieren von weiteren RAOs/DRAOs. Die meisten Privilegien können nach der Erstellung eines Accounts nur noch von der DFN-PCA geändert werden.
  • API-Only-User: Ein RAO/DRAO kann auf API-Only eingeschränkt werden (Privileg „WS-API only“ im Dialog „Add New Client Admin“, Menü Admins, Button Add). Mit diesem Account kann dann ausschl. das REST-API bedient werden. Nach unseren Erkenntnissen sollte diese Checkbox initial noch nicht angekreuzt werden, da der neue Account sich einmal an der Web-Oberfläche anmelden muss um sein Passwort vom Initial-Passwort zu setzen. Erst nach dem Setzen des richtigen Passworts sollte „WS-API only“ angekreuzt werden. Da dieses Privileg nur von der DFN-PCA geändert werden kann, ist für die Nutzung dieses Features Kommunikation mit der DFN-PCA erforderlich.

Zur weiteren Strukturierung der Organisation können RAOs Abteilungen anlegen. Hierzu Settings→Organizations, Button Departments wählen.

Es können dann DRAOs angelegt werden, die nur innerhalb der zugewiesenen Abteilung Zertifikate verwalten können.

Um Zertifikate zu erhalten, müssen die entspr. Domains unter Settings→Domains→Delegations eingetragen und unter Settings-Domains-DCV validiert werden (Validation Status muss auf „Validated“ gesetzt sein).

Wichtig: Nach dem Eintragen und der Validierung müssen die Domains an eine Organization „delegiert“ werden. Hierzu entweder über Settings→Organizations per Button Domains oder über Settings→Domains, Submenü Delegations, Button Delegate gehen.

Domainvalidierungen können über Settings→Domains, Submenü DCV eingesehen oder neu angestoßen werden.

Nach derzeitigem Kenntnisstand muss zunächst die Hauptdomain eingetragen und validiert werden, z.B. example.org. Nach erfolgreicher Validierung kann dann ein Sternchen-Eintrag *.example.org erzeugt werden. Nur mit dem Sternchen-Eintrag scheinen Zertifikate zu beliebigen FQDN erzeugt werden können.

  • Die Serverzertifikate („OV Multi-Domain“) aus TCS enthalten sowohl den Zertifikatzweck serverAuth als auch clientAuth. Es können also prinzipiell alle Zwecke mit dem Standard-Zertifikatprofile abgedeckt werden. Nicht verfügbar sind die Funktionalitäten aus: - Webserver mustStaple - DomainController?
  • Die Nutzerzertifikate („Client Certificate“) enthalten clientAuth und E-Mail Protection, und sind damit ebenfalls universell einsetzbar.
  • Die Code-Signing Zertifikate sind für die Signatur von Java JARs & MS Office Macros verwendbar. Für höherwertigen Trust müssen EV Code-Signing-Zertifikate separat bestellt werden. https://wiki.geant.org/display/TCSNT/TCS+2020+FAQ#TCS2020FAQ-Q:HowDoIOrderEVCodeSigningCertificates

Wir empfehlen in jedem Fall OV Multi Domain zu verwenden. Im Zertifikatprofil OV Multi Domain sind mehrere Servernamen möglich, z.B. fachbereich1.example.org, fachbereich2.example.org

Im Zertifikatprofil OV SSL wird automatisch jedem Zertifikat ein zweiter, in den meisten Fällen sicherlich unerwünschter Alternativer Name „www.“ hinzugefügt.

Beispiel: Antrag enthält fachbereich1.example.org ⇒ Das ausgestellte Zertifikat enthält die Namen fachbereich1.example.org und !www.fachbereich1.example.org.

EV-Zertifikate können nur erstellt werden, nachdem in cert-manager ein sog. EV Anchor angelegt wurde. Dies ist ein spezielles administratives Zertifikat, dessen Ausstellung von allen Prozeduren zur besonderen Prüfung nach EV-Standard begleitet wurde.

  • Bitte versuchen Sie auf keinen Fall, ein normales EV-Zertifikat vor der Erstellung eines EV Anchors zu beantragen.
  • Vor der Erstellung eines EV-Anchors müssen die EV-Informationen unter Settings→Organizations→Edit Tab „EV Details“ korrekt sein. Diese EV Details müssen von der DFN-PCA gesetzt werden, allerdings benötigen wir Ihre Mithilfe.

Die Anleitung im GÈANT FAQ ist zu finden unter: https://wiki.geant.org/display/TCSNT/TCS+2020+FAQ#TCS2020FAQ-Q:HowdoIcreateanEVAnchor? Versuchen Sie auf keinen Fall mehrere EV Anchor zu erstellen.

Für spezielle Document Signing Zertifikate, die voreingestellten Trust in Adobe haben, gibt es einen separaten Antragsweg außerhalb von cert-manager. Es entstehen zusätzliche Kosten, da von Sectigo ein Crypto-Token erstellt und versandt wird.

https://wiki.geant.org/display/TCSNT/TCS+2020+FAQ#TCS2020FAQ-Q:AreDocumentSigningCertificatesavailableviaSectigo?

Für Nutzerzertifikate, die um Grid-Umfeld verwendet werden sollen, verwenden Sie bitte eines der IGTF-Profile.

Die Serverzertifikate aus den Standard-Profilen (z.B. „OV Multi Domain“) sind direkt im Grid-Umfeld verwendbar.

Die Anforderungen an die Identifizierung und die Dokumentation für Nutzerzertifikate sind im TCS Certification Practice Statement - Personal, eScience Personal and Document Signing Certificates festgehalten:

https://wiki.geant.org/display/TCSNT/TCS+Repository

Die höchsten Anforderungen bestehen bei „TCS eScience Personal“ Zertifikaten, die nach den Regeln der IGTF ausgestellt werden. Hiervon sind die Zertifikatprofile IGTF MICS und IGTF Classic betroffen, die jeweils eine persönliche Identifizierung voraussetzen. Die exakten Regeln sind bei der IGTF nachzulesen: https://www.igtf.net/ap/mics/IGTF-AP-MICS-1.3 und https://www.eugridpma.org/guidelines/authn-assurance/igtf-authn-assurance-1.1.pdf

Die Anforderungen an die Identifizierung und die Dokumentation für Serverzertifikate sind im TCS Certification Practice Statement - Server, eScience Server and Code Signing Certificates festgehalten:

https://wiki.geant.org/display/TCSNT/TCS+Repository

Mit Web-Formularen können Nutzer ohne eigenen Login in cert-manager Zertifikate beantragen. Zur Nutzung eines Web-Formulars ist ein sogenannter „Access Codes“ notwendig. Jeder, der diesen Access Code kennt, kann Zertifikate beantragen.

Access Codes werden von einem RAO unter Settings→Enrollment Endpoints, SSL-Web Form bzw. Client Certificate Web Form mit dem Button „Accounts“ erstellt.

Bitte richten Sie keine Accounts zur Nutzung von Web-Formularen für Nutzerzertifikate ein. Die Nutzer können bei diesem Antragsweg beliebige Vor- und Nachnamen angeben, und Sie haben keine Möglichkeit, diese vor Ausstellung zu verifizieren. Der korrekte Weg für Nutzerzertifikate in TCS ist die Anbindung eines IdP aus der DFN-AAI, siehe hierzu die Beschreibung der Möglichkeiten über SAML.

Bei Accounts für SSL Web Forms setzen Sie bitte auf keinen Fall die Checkbox „Automatically Approve Requests“. Genehmigen Sie eingehende Requests immer manuell nach Prüfung über out-of-band-Methoden (z.B. eine informelle E-Mail).

Die URL ist für alle Web-Formulare aller Einrichtungen im DFN-Mandanten von TCS identisch: https://cert-manager.com/customer/DFN/ssl

Erst der Access Code sorgt für die Zuordnung eines Antrags zu Ihrer Einrichtung.

Zertifikate mit mehreren Servernamen (FQDN) können mit einem der „Multidomain“-Profile erstellt werden. In den Profilen ohne „Multidomain“ ist nur ein Servername möglich.

Ein External Requester wird optional bei den Antragsformularen für Serverzertifikate abgefragt. Hier kann schlicht eine zusätzliche Mailadresse angegeben werden, die Benachrichtigungen zum Zertifikat erhält.

Im Profil „Wildcard SSL“ können direkt Wildcard-Zertifikate erzeugt werden. Es ist ein CSR der Form *.example.org einzureichen.

Ein Einrichtungs-eigener IdP aus der DFN-AAI kann für drei verschiedene Zwecke an das TCS-System angebunden werden.

Unter https://cert-manager.com/customer/DFN/ssocheck/ steht ein Test-SP bereit, mit dem die übergebenen Attribute eingesehen werden können.

Mit diesem Weg können sich RAOs oder DRAOs in cert-manager.com einloggen. Eine Beschreibung der Voraussetzungen ist zu finden unter: https://wiki.geant.org/display/TCSNT/TCS+2020+FAQ#TCS2020FAQ-ToenableSAMLforadminaccesstoSCM:

Hierbei gibt es zwei verschiedene Wege:

  1. Bei einem per Admins, Button „Add“, manuell angelegten Account mit Passwort kann zusätzlich das Feld „Identity Provider“ auf „Your Institution“ gesetzt werden, und „IdP Person Id“ auf den Wert des Attributes eduPersonPrincipalName. Anschließend kann sich dieser Account per Nutzername/Password und alternativ auch per SAML einloggen.
  2. Mit dem Weg Admins, Button „Add IdP User“, kann ein Account ohne Passwort angelegt werde, der sich nur über den IdP einloggen kann. Zur Zeit müssen diese Accounts noch von der DFN-PCA manuell freigeschaltet werden. Ohne Freischaltung ist kein Login möglich.

Über diesen Weg können direkt per AAI-Login Serverzertifikate beantragt werden.

Der IdP muss in eduGain eingebunden sein. Über Settings→Enrollment Endpoints muss ein SAML SSL Endpoint angelegt werden. Über die URI Extension wird eine einrichtungsspezifische URL angelegt, über die die Beantragung möglich ist.

Mit der Checkbox „Automatically Approve Requests“ gibt es die Option, zu derart authentifizierten Anträge direkt das Zertifikat zu erstellen. Wir empfehlen, diese Einstellung nur nach reichlicher Überlegung zu treffen, da es nach unserem Kenntnisstand keine Möglichkeit gibt, die akzeptierten Nutzer eines IdP einzuschränken. Hiermit kann dann jeder Nutzer in Ihrem IdP jedes Serverzertifikat erstellen.

Ist diese Checkbox nicht aktiviert, müssen die Anträge von einem RAO oder DRAO über Certificates→Approve freigeschaltet werden.

Über diesen Weg können Nutzer direkt per AAI-Login Nutzerzertifikate beziehen. Die Zertifikate werden automatisch ohne weiteren Genehmigungsschritt ausgestellt.

In der Verwaltungsoberfläche müssen unter Settings→Organizations→Edit Tab General die Felder Secondary Organization Name und Academic code (SCHAC Home Organization) gesetzt sein.

Der IdP muss in eduGain eingebunden sein und alle Attribute wie in folgender Beschreibung von GÈANT freigeben: https://wiki.geant.org/display/TCSNT/TCS+2020+FAQ#TCS2020FAQ-TouseSAMLinordertoallowuserstoorderclientcertificates:

Insbesondere muss ein eduPersonEntitlement urn:mace:terena.org:tcs:personal-user gesetzt werden.

Bitte beachten Sie die Identifizierungsvoraussetzungen, wenn Sie über diesen Weg IGTF-Zertifikate ausstellen (siehe FAQ „Identifizierung und Dokumentation“).

Wenn diese Voraussetzungen gegeben sind, können über https://cert-manager.com/customer/DFN/idp/clientgeant Zertifikate bezogen werden.

Die Zertifikate werden automatisiert, ohne Einwirkung eines RAO oder DRAO ausgestellt.

Achtung: Unter Settings→Enrollment Endpoints gibt es die (theoretische) Option, einen individuellen SAML Client Endpoint anzulegen. Dieser Weg führt nicht zum Erfolg, hierüber ist keine Zertifikatausstellung möglich.

Achtung: Für Zertifikate, die auf diesem Wege ausgestellt werden, ist kein Key-Escrow möglich!

Zur Nutzung von ACME müssen im cert-manager.com spezielle ACME-Accounts angelegt werden. Hierzu muss unter Settings→Enrollment Endpoints zu einem der ACME-Endpoints der Button Accounts betätigt werden. Dann per Button Add einen neuen Account anlegen.

Achtung: Zustände von ACME-Accounts sind anscheinend nicht notwendigerweise komplett synchron zu Hintergrundsystemen bei Sectigo. Im Test konnte bspw. ein ACME-Account nicht direkt, sondern erst nach einer Wartezeit über Nacht gelöscht werden.

Vorausgesetzt, dass die dem Account zugewiesene Domain validiert und delegiert ist, kann direkt im Anschluss ein Zertifikat erzeugt werden:

certbot certonly --standalone --non-interactive --agree-tos --email <Email-Adresse> --server <Sectigo-Server> --eab-kid <Wert von eab-kid> --eab-hmac-key <Wert von eab-hmac-key> --domain <Servername> 

Der ACME-Account ist anschließend auf dem System, auf dem die o.g. Zeile aufgerufen wurde, mit einem dort abgelegten Account-Key verknüpft und kann nicht ohne weiteres auf anderen Systemen durch einfache erneute Eingabe von eab-kid und eab-hmac-key verwendet werden.

Um einen ACME-Account auf mehreren Systemen zu verwenden, muss die Account-Information des ACME-Clients kopiert werden. Für certbot liegen die Account-Informationen in /etc/letsencrypt/accounts/acme.sectigo.com . Da die ACME-Accounts in der Regel unlimitierte Fähigkeiten zum Ausstellen von Zertifikaten haben, ist sorgfältig abzuwägen ob die Account-Infomationen zwischen mehreren Servern geteilt werden sollten oder aber besser mit separaten ACME-Accounts gearbeitet werden soll.

Ein Ansible-Gerüst zum zentralen Erstellen eines ACME-Accounts per REST-API und zum Bezug von Zertifikaten per ACME findet sich unter https://github.com/francescm/acme-ansible-debian-sectigo

Achtung: Per ACME ausgestellte Zertifikate sind nicht in cert-manager.com sichtbar!

Per ACME ausgestellte Zertifikate können nur per ACME-Client wie certbot gesperrt werden. certbot benötigt Zugriff auf die Account-Informationen von der initialen Ausstellung des Zertifikats. Wenn diese Voraussetzung gegeben ist, kann folgendermaßen gesperrt werden:

certbot revoke --cert-path <Pfad zum zu sperrenden Zertifikat> --server <Sectigo-Server>

Die Systeme von Sectigo können per REST-API angesprochen werden. Eine Dokumentation hierzu finden Sie unter: https://support.sectigo.com/Com_KnowledgeDetailPage?Id=kA01N000000XDkE

Die REST-API kann nur dann zum Enrollment verwendet werden, wenn unter Settings→Organizations per Button Edit in den Tabs „SSL Certificate“ bzw. „Client Certificate“ die Checkbox „Web-API“ angekreuzt ist und ein Secret-Key eingetragen ist. Der Secret-Key wird zwar nur für eine veraltete SOAP-API aktiv verwendet, muss aber trotzdem vergeben werden.

Es ist entweder Nutzername/Passwort eines im Cert-Manager angelegten Nutzers zu übergeben, oder aber eine Client-Authentifizierung per Zertifikat.

Tipp: Man kann einen Nutzer in seiner Rolle so einschränken, dass ausschließlich der REST-API-Zugang verwendet werden kann. Hierzu unter Admins→<Auswahl>→Edit die Checkbox „WS API Only“ ankreuzen. (Wichtig: Erst nachträglich nach der Vergabe des endgültigen Passworts setzen!)

Beispiel für die Beantragung von Serverzertifikaten:

curl 'https://cert-manager.com/api/ssl/v1/enroll' -i -X POST \
    -H "Content-Type: application/json;charset=utf-8" \
    -H "login: <account>" \
    -H "password: <passwort>" \
    -H "customerUri: DFN" \
    -d '{"orgId":<OrgId>,"subjAltNames":"<FQDN des Servers>","certType":<Nummer des Zertifikatprofils>,"numberServers":0,"serverType":-1,"term":365,"comments":"","externalRequester":"","customFields": [],"csr":"-----BEGIN CERTIFICATE REQUEST-----\nMIICYjCCAU...N818=\n-----END CERTIFICATE REQUEST-----"}'

Die <OrgId> ist direkt im cert-manager.com ablesbar: Settings→Organizations, Button Edit, Tab General

Die <Nummer des Zertifikatprofils> muss einmalig mit folgendem Aufruf ermittelt werden:

curl 'https://cert-manager.com/api/ssl/v1/types' -H "password: $PASS" -i -X GET \
    -H "Content-Type: application/json;charset=utf-8" \
    -H "login: <account>" \
    -H "password: <passwort>" \
    -H "customerUri: DFN" \

Ausgestellte Zertifikate können mit folgendem Aufruf abgeholt werden:

curl  'https://cert-manager.com/api/ssl/v1/collect/<Antragsnummer>/<Format>' -H "password: $PASS" -i -X GET \
    -H "Content-Type: application/json;charset=utf-8" \
    -H "login: <account>" \
    -H "password: <passwort>" \
    -H "customerUri: DFN" \

<Antragsnummer> wurde bei einem vorherigen Aufruf von …enroll als Rückgabewert zurückgeliefert.

<Format> spezifiziert das Rückgabeformat, z.B. „pem“, weitere mögliche Werte siehe https://sectigo.com/knowledge-base/detail/SCM-Sectigo-Certificate-Manager-REST-API/kA01N000000XDkE

Für Nutzerzertifikate ist die Beantragung ähnlich aufgebaut. Die Aufrufe müssen an https://cert-manager.com/api/smime/v1/types, ….smime/v1/enroll und ….smime/v1/collect geschickt werden. Für weitere Details zu den Parametern ist die API-Dokumentation von Sectigo heranzuziehen.

Die Schüsselerzeugung bei Nutzerzertifikaten („Client Certificates“) geschieht bei den Antragswegen „Web-Formular“ und „SAML“ auf Seiten der Server von Sectigo, wenn nicht explizit ein manuell erstellter PKCS#10-Request hochgeladen wird.

Für den (nicht empfehlenswerten) Antragsweg „Web-Formular“ ist es möglich, Key Escrow zu konfigurieren. Bei der Einrichtung einer Organisation oder eines Departments kann ausgewählt werden, ob für die auf Serverseite erzeugten Schlüssel eine Schlüsselhinterlegung stattfinden soll. Wenn ja, wird vor dem Ausstellen von Nutzerzertifikaten von der Organisation oder dem Department durch die Rollen RAO oder DRAO ein Master Encryption Key erzeugt. Dieser Master Encryption Key liegt anschließend ausschließlich innerhalb der Organisation oder des Departments vor.

Die geheimen Schlüssel der Nutzer werden dann an diesen Master Encryption Key verschlüsselt.

Ein RAO oder DAO kann geheime Schlüssel von Nutzern wiederherstellen, indem der Master Encryption Key beim Wiederherstellungsprozess per Hand in ein entspr. Formular in cert-manager eingegeben wird. Zertifikate, deren Schlüssel so wiederhergestellt wurden, werden automatisch gesperrt.

Achtung: Dies ist beim Antragsweg „SAML“ für Nutzerzertifikate nicht möglich!

Wenn Sie CAA-Records setzen möchten, um die Ausstellung von Zertifikaten auf bestimmte CAs einzuschränken, verwenden Sie für TCS:

muster-uni.de.       IN    CAA    0 issue "sectigo.com"

Wir helfen gerne per dfnpca@dfn-cert.de

Ein direkter Kontakt mit dem Sectigo Support ist auch möglich, es ist aber zu empfehlen zunächst mit uns zu sprechen. Das Support-Portal von Sectigo ist erreichbar unter: https://sectigo.com/support-ticket Bitte unbedingt den folgenden Hinweis einfügen: „We are a DFN member of the GEANT TCS service, using the https://cert-manager.com/customer/DFN SCM instance.“

  • Zuletzt geändert: vor 9 Tagen