@@ -6,7 +6,7 @@ import useBaseUrl from '@docusaurus/useBaseUrl';
# Onlinedienste
### Aufgaben für die Anbindung an das Produktivsystem
### Aufgaben zur Anbindung an das Produktivsystem
:::note Hinweis
Vor der Anbindung an das Produktivsystem von FIT-Connect ist es erforderlich, Ihren Onlinedienst mit der Testumgebung von FIT-Connect zu testen. Für den Zugang zur Testumgebung ist keine Anmeldung bei der FITKO erforderlich. <br/>
...
...
@@ -22,8 +22,8 @@ Sie legen API-Clients im Self-Service-Portal (SSP) der FITKO an. Das SSP erreich
### 1. Rechtliche Voraussetzung erfüllen
Die rechtliche Voraussetzung für eine Anbindung an das Produktivsystem ist ein gültiger Auftragsdatenverarbeitungsvertrag (AVV) mit der FITKO. <br/>
Nach Abschluss des Vertrags erstellt die FITKO für den Onlinedienst einen Account für FITKO-Gitlab. Damit kann im Self-Service-Portal ein API-Client angelegt werden (siehe folgenden Punkt):
Schließen Sie mit der FITKO einen Auftragsdatenverarbeitungsvertrag (AVV). <br/>
Nach Abschluss des Vertrags erstellt die FITKO einen Account für FITKO-Gitlab. Damit kann im Self-Service-Portal ein API-Client angelegt werden (siehe folgenden Punkt):
Bei der verschlüsselten Übertragung in FIT-Connect werden JSON Web Keys (JWK) gemäß [RFC 7517](https://tools.ietf.org/html/rfc7517) eingesetzt. Die JSON Web Keys werden aus Zertifikaten abgeleitet. Der öffentlichen Schlüssel eines Schlüsselpaares wird in einem Zustellpunkt hinterlegt.
Bei der verschlüsselten Übertragung in FIT-Connect werden JSON Web Keys (JWK) gemäß [RFC 7517](https://tools.ietf.org/html/rfc7517) eingesetzt.
Die JSON Web Keys werden aus Zertifikaten abgeleitet. Der öffentliche Schlüssel eines Schlüsselpaares wird in einem Zustellpunkt hinterlegt.
Es können mehrere JWKs hinterlegt werden, welche entweder für die Verschlüsselung oder Signaturprüfung verwendet werden können.
:::note Hinweis
Die Zertifikate und damit verbundene JWKs haben eine begrenzte Gültigkeitsdauer und müssen gemäß den Vorgaben der Zertifikatsinfrastruktur in regelmäßigen Intervallen erneuert werden.
Die Zertifikate und die damit verbundenen JWKs haben eine begrenzte Gültigkeit und müssen gemäß den Vorgaben der Zertifikatsinfrastruktur in regelmäßigen Intervallen erneuert werden.
:::
## Beantragung von Zertifikaten aus der Verwaltungs-PKI
### Zertifikate der Verwaltungs-PKI
:::note Hinweis
In der Testumgebung ist die Absicherung der öffentlichen Schlüssel eines Zustellpunktes durch Zertifikate optional. Stattdessen können in der Testumgebung selbstgenerierte Zertifikate genutzt werden. Das Vorgehen ist im Artikel [Erstellen von JSON Web Keys für Testzwecke](../details/jwk-creation.md) beschrieben.
:::
Die Voraussetzung, damit sendende Systeme Daten verschlüsseln bzw. Signaturen prüfen können, ist die Hinterlegung eines gültigen X.509-Zertifikats aus der Verwaltungs-PKI in einem Zustellpunkt.
Ihr Zertifikat erhalten Sie von der Zertifizierungsstelle (Certification Authority, CA) „Deutschland Online Infrastruktur-Certification Authority“ (DOI-CA), welche durch die Deutsche Telekom Security GmbH im Trust Center betrieben wird und in die Verwaltungs-Public Key Infrastructure (V-PKI, auch *Verwaltungs-PKI*) des Bundesamtes für die Sicherheit in der Informationstechnik (BSI) integriert ist.
Da Zertifikate aus der Verwaltungs-PKI nur an Behörden ausgestellt werden dürfen, ist es erforderlich, dass die im Zertifikat angegebenen Daten sicher überprüft werden.
Hierzu ist eine Identifizierung durch die siegelführende Stelle Ihrer Behörde erforderlich („Behörden-Ident“).
Der von der siegelführenden Stelle gegengezeichnete Antrag muss dann zu einer Registrierungsstelle (Registration Authority, RA) gesendet werden, welche dann nach einer Überprüfung der Daten die Zertifikatserzeugung freigibt.
Weitere Vorgaben für die eingesetzten X.509-Zertifikate sind unter [Vorgaben für kryptographische Verfahren in FIT-Connect](../details/crypto.md#certificates) dokumentiert.
### Beantragunsgprozess über das Web-Portal der DOI-CA
Um Zertifikate aus der Verwaltungs-PKI beantragen zu können, melden Sie sich im [Webportal der DOI-CA](https://doi.telesec.de/doi/ee/) an.
Nach der erfolgreichen Anmeldungen sehen Sie die folgende Startseite:
Sie benötigen Zertifikate der Verwaltungs-PKI, um ein Fachverfahren an das Produktivsystem von FIT-Connect anzubinden.
Wie Sie Zertifikate der Verwaltungs-PKI beantragen, das ist [hier](../getting-started/account#anmeldung-am-self-service-portal) beschrieben.
<img width="600" alt="Management von Zertifikaten der DOI-CA" src={useBaseUrl('/images/certificate_registration/certificate_registration_1.png')} />
In der Navigationsspalte auf der linken Seite sehen Sie durch einen Klick auf den Menü-Punkt **Software-Zertifikat** weitere Unterpunkte.
Wählen Sie hier den Menü-Punkt **beantragen** aus.
Es öffnet sich dann eine Webseite, auf der Sie unter verschiedenen Möglichkeiten eine Domäne auswählen können, die dann im Zertifikat als "Organizational Unit (OU) übernommen wird.
Je nachdem ob Sie eine Smartcard oder ein Software-Zertifikat beantragen, stehen Ihnen nur bestimmte Domänen zur Auswahl.
Wählen Sie hier die Sub-Domäne `DOI_OSCI` aus und bestätigen sie Ihre Auswahl mit **Weiter**.
:::info Hinweis
Bei der Beantragung von Zertifikaten über die **Thüringer Registrierungsstelle** beim TLRZ wählen Sie stattdessen die Sub-Domäne `Kommunikation Thüringen`.
:::note Hinweis
Für die Testumgebung von FIT-Connect sind keine Zertifikate der Verwaltungs-PKI erforderlich. Hier können selbst signierte Zertifikate genutzt werden. Das Vorgehen ist im Artikel [Erstellen von JSON Web Keys für Testzwecke](../details/jwk-creation.md) beschrieben.
:::
<img width="600" alt="Auswahl der Domäne" src={useBaseUrl('/images/certificate_registration/certificate_registration_2.png')} />
Im nächsten Schritt gilt es den Zertifikatstyp auszuwählen.
Zur Wahl stehen ein personenbezogenes Zertifikat, wenn das Zertifikat für eine konkrete Person beantragt werden soll, oder ein Gruppen- bzw. Funktions-Zertifikat, welches für Personengruppen, Funktionen, Rollen, Systeme oder IT-Prozesse Anwendung findet.
In Abhängigkeit der zuvor gewählten Domäne, kann auch nur eine der beiden Möglichkeiten zur Auswahl stehen.
Für unseren Anwendungsfall wählen Sie bitte `Gruppen-/Funktions-Zertifikat` und bestätigen sie Ihre Auswahl mit **Weiter**.
<img width="600" alt="Auswahl des Zertifikatstyps" src={useBaseUrl('/images/certificate_registration/certificate_registration_3.png')} />
Es folgt die Erfassung der Anschrift und Kontaktdaten des Anstragsstellers bzw. des Schlüsselverantwortlichen.
Der Schlüsselverantwortliche ist der Repräsentant einer Gruppe und verantwortlich für die sichere Verteilung, Nutzung und ggf. Sperrung des Schlüssels.
Er wird wie ein Antragsteller für ein personenbezogenes Zertifikat identifiziert und registriert.
Bestätigen sie Ihre Eingaben mit **Weiter**.
<img width="600" alt="Erfassung der Daten des Antragstellers/Schlüsselverantwortlichen" src={useBaseUrl('/images/certificate_registration/certificate_registration_4.png')} />
Mit Eingabe der Zertifikatsdaten werden die eigentlichen zu beglaubigenden Inhalte erfasst.
Da zuvor als Zertifikatstyp Gruppen-/Funktions-Zertifikat gewählt wurde, ist jetzt im Common Name des Zertifikats der Gruppen-/Funktionsname zu benennen.
Gemäß der Zertifikats-Policy muss dieser mit Zusatz `GRP: ` beginnen.
Im Feld E-Mail-Adresse sollten Sie zur Gewährleistung der Erreichbarkeit, sofern vorhanden, eine zentrale E-Mail-Adresse bzw. ein Funktionspostfach eintragen.
An diese E-Mail-Adresse werden sowohl die Informationen über die Zertifikatserstellung als auch später eine Erinnerung vor Ablauf des Zertifikats zur Erneuerung gesendet.
Geben Sie jetzt den Gruppen-/Funktionsname sowie die E-Mail-Adresse ein und bestätigen sie Ihre Eingaben mit **Weiter**.
<img width="600" alt="Zertifikatsdaten: Name und E-Mail-Adresse" src={useBaseUrl('/images/certificate_registration/certificate_registration_5.png')} />
Zusätzlich zu Name und E-Mail-Adresse können weitere Daten zu Ihrer Behörde optional in das Zertifikat aufgenommen werden.
Im Feld Dienstort können Sie den Dienstort Ihrer Behörde erfassen.
Im Feld Kennung 1 tragen Sie bitte den Namen Ihrer Behörde ein, sofern sich dieser nicht bereits aus dem Gruppennamen ergibt.
Nach Eingabe der optionalen Angaben bestätigen sie Ihre Eingaben mit **Weiter**.
Neben den Zertifikatsinhalten haben Sie als antragstellende Person auch die Möglichkeit über einige technische Rahmenbedingungen zu entscheiden.
So können Sie wählen, ob das das zu erstellende Zertifikat neben einer Veröffentlichung im DOI-Netz auch über einen im Internet verfügbaren Verzeichnisdienst veröffentlicht werden soll.
Damit wird das Zertifikat auch für nicht öffentliche Stellen im Internet auffindbar.
Für die Verwendung der Zertifikate in FIT-Connect müssen gemäß den [Vorgaben für kryptographische Verfahren](../details/crypto.md#certificates) der Hash-Algorithmus `SHA-512` und der Schlüsseltyp `4096 Bit` ausgewählt werden.
Das Sperrpasswort wird benötigt, wenn Sie Ihr Zertifikat vor Ende seiner Laufzeit sprerren müssen.
Notwendig kann das z. B. bei Kompromittierung des geheimen Schlüssels, dem Ausscheiden einer Person aus der Behörde oder der Auflösung einer Organisationseinheit der Fall sein.
Haben Sie sich für die technischen Rahmenbedingungen entschieden, bestätigen sie Ihre Eingaben mit **Weiter**.
<img width="600" alt="Veröffentlichung, Hash-Algorithmus, Schlüsseltyp und Sperrpasswort" src={useBaseUrl('/images/certificate_registration/certificate_registration_7.png')} />
Für die Abrechnung Ihres Zertifikats geben Sie bitte in diesem Schritt die Rechnungsanschrift des zuständigen Rechnungsempfängers an.
Nach Eingabe der Rechnungsanschrift bestätigen sie Ihre Eingaben mit **Weiter**.
Im nächsten Schritt haben Sie die Möglichkeit der zuständigen Registreierungsstelle eine Mitteilung bis maximal 170 Zeichen länge zu Ihrem Antrag zu übermitteln.
Bestätigen Sie Ihre Eingabe mit **Weiter**.
<img width="600" alt="Mitteilung an die Registrierungsstelle" src={useBaseUrl('/images/certificate_registration/certificate_registration_9.png')} />
Im letzten Schritt der Zertifikatsbeantragung werden Ihnen noch einmal sämtliche Antragsdaten übersichtlich in einer Zusammenfassung dargestellt.
Sollten Ihnen hier noch etwaige Fehler auffallen, können Sie mithilfe von **Zurück** zu vorherigen Seiten zurück navigieren.
Sind Sie mit in der Zusammenfassung angezeigten Daten zufrieden, schließen Sie Ihren Zertifikatsantrag mit **Absenden** ab.
Ihr Antrag wird dann an das Trustcenter gesendet und Ihnen anschließend das daraus erstellte Antragsformular zum Download als PDF-Dokument angeboten.
<img width="600" alt="Zusammenfassung der Antragsdaten" src={useBaseUrl('/images/certificate_registration/certificate_registration_10.png')} />
Ihr Antrag ist damit bei der Zertifizierungsstelle eingegangen.
Laden Sie nun bitte über die Schaltfläche **Zertifikatsantrag herunterladen** den PDF-Antrag herunter.
Der Antrag beinhaltet neben dem eigentlichen Antrag für die Registrierungsstelle auch noch eine Kopie des Antrags für Ihre Unterlagen, einen PIN-Brief sowie ggf. weitere Blätter.
Drucken Sie diesen Antrag bitte aus, unterschreiben ihn und lassen Sie sich gemäß den Vorgaben (siehe Antrag) in einer siegelführenden Stelle Ihrer Behörde identifizieren.
Senden Sie den Antrag an die zuständige Registrierungsstelle.
Die Anschrift finden Sie im Antragsformular.
Mit dem Versand des Antrags an die Registrierungsstelle ist der Vorgang für Sie zunächst abgeschlossen.
Nachdem Ihr Zertifikat ausgestellt wurde, erhalten Sie eine E-Mail mit weiteren Informationen zu der Abholung Ihres Zertifikats.
<img width="600" alt="Download und Versand des Zertifikatsantrags" src={useBaseUrl('/images/certificate_registration/certificate_registration_10_2.png')} />
### Abruf des Zertifikats
Nach dem das Trust Center der Telekom Ihr Zertifikat erstellt hat, werden Sie über die für den Antragsteller/Schlüsselverantwortlichen hinterlegte E-Mail-Adresse darüber informiert, dass Ihr Zertifikat bereit zum Download steht.
Rufen Sie dazu die Startseite des [Webportal der DOI-CA](https://doi.telesec.de/doi/ee/) auf.
Nach dem erfolgreichen Login sehen Sie in der Navigationsspalte auf der linken Seite durch einen Klick auf den Menü-Punkt **Software-Zertifikat** weitere Unterpunkte.
Wählen Sie hier den Menü-Punkt **abholen** aus.
Geben Sie bitte anschließend in den entsprechenden Feldern die Referenznummer und das Download-Passwort ein, welche Sie Ihrem Antragsformular bzw. dem PIN-Brief entnehmen können und bestätigen Sie Ihre Eingaben mit **Suchen**.
Bei erfolgreicher Eingabe wird Ihnen Ihr Zertifikat angezeigt.
Klicken Sie auf **Herunterladen** und speichern Sie die Datei auf Ihrer Festplatte oder einem Datenträger.
Bei der PKCS-12-Datei handelt es sich um einen Container, in dem Schlüsselpaar (öffentlicher und geheimer Schlüssel, siehe dazu auch [Verschlüsselte Übertragung in FIT-Connect](../getting-started/encryption.mdx) sowie das Zertifikat enthalten sind.
**Hinweis:** Die Anzahl der möglichen Downloads ist auf drei Versuche begrenzt!
Sollten Sie nach dem 3. Versuch den erfolgreichen Download nicht bestätigt haben, wird beim nächsten Versuch das Zertifikat gesperrt und der geheime Schlüssel gelöscht.
Die PKCS12-Datei kann dann nicht mehr heruntergeladen werden und ein Zugriff auf die Schlüssel ist nicht länger möglich.
Sie müssen in dem Fall einen neuen Antrag stellen.
Nach dem Herunterladen der Datei müssen Sie den erfolgreichen Download zwingend mit **Bestätigen** quittieren, damit die geheimen Schlüssel gelöscht werden und die Datei kein weiteres Mal heruntergeladen werden kann.
Darüber hinaus wird mit dieser Bestätigung das Zertifikat in den Verzeichnissen veröffentlicht.
Sie erhalten nach der Bestätigung eine Meldung, dass Ihr Zertifikat freigeschaltet wurde.
<img width="600" alt="Zertifikat als *.der-Datei herunterladen" src={useBaseUrl('/images/certificate_registration/certificate_registration_11_3.png')} />
## Ableitung von JSON Web Keys (JWKs) aus einem Zertifikat
JWKs sind das Austauschformat, mit dem kryptografische Schlüssel in FIT-Connect zwischen der Destination und dem
Onlinedienst ausgetauscht werden. Private Schlüssel sollten nach Möglichkeit dort generiert werden, wo sie am Ende eingesetzt werden.
...
...
@@ -192,7 +57,7 @@ $ poetry install
Das Skript benötigt die folgenden Parameter:
- Den Pfad zu einem Zertifikat im PKCS#12-Format (`-i`)
- Den Pfad zu dem Verzeichnis, in dem die JWKs gespeichert werden sollen (`-o`)
- Die Umgebung, in der Gearbeitet wird. Die Default-Einstellung hierfür ist "prod". (`-e`)
- Die Umgebung, in der gearbeitet wird. Die Default-Einstellung hierfür ist "prod". (`-e`)
Ausgeführt wird das Skript dann mit dem folgenden Befehl.
...
...
@@ -213,12 +78,11 @@ These keys can be used to sign and decrypt in your client application.
```
:::note Hinweis
Die zwei Punkte im Ausgabepfad "**..**\res\privateKey_decryption.jwk.json" bedeuten das von dem aktuellen Verzeichnis ausgegangen wird. Beispielsweise "**C:\Users\username\fit-connect-tools**\res\rivateKey_decryption.jwk.json"
Die zwei Punkte im Ausgabepfad "**..**\res\privateKey_decryption.jwk.json" bedeuten, dass von dem aktuellen Verzeichnis ausgegangen wird. Beispielsweise "**C:\Users\username\fit-connect-tools**\res\rivateKey_decryption.jwk.json"
:::
### OpenSSL
Im Folgenden eine beispielhafte Schritt-für-Schritt-Anleitung, um aus einem Zertifikat aus der Verwaltungs-PKI einen
JSON-Web-Key zu erzeugen:
## OpenSSL
Dieses Kapitel enthält eine Schritt-für-Schritt-Anleitung, um aus einem Zertifikat der Verwaltungs-PKI einen JSON-Web-Key zu erzeugen:
1. Das von der Verwaltungs-PKI signierte Zertifikat muss nun in einen JWK umgewandelt werden:
