Zum Hauptinhalt springen

Zertifikate umwandeln

Die folgende Beschreibung zeigt, wie Sie aus einem Zertifikat Dateien ableiten, die JSON Web Keys (JWKs) enthalten (Zertifikatsumwandlung). Sie benötigen diese Dateien für einen Client des Typs Subscriber (Empfänger), siehe die Seite Zustellpunkt anlegen.

Ende-zu-Ende-Verschlüsselung

FIT-Connect verwendet zur Übertragung von Einreichungen (Anträgen) eine Ende-zu-Ende-Verschlüsselung: Der Sender (Onlinedienst) verschlüsselt die Anträge und sendet sie verschlüsselt über FIT-Connect an den Empfänger (Fachverfahren). Der Empfänger entschlüsselt die Anträge.

Schlüssel zum Ver- und Entschlüsseln

Der Sender benötigt den öffentlichen Verschlüsselungsschlüssel des Empfängers, um damit Antragsdaten zu verschlüsseln. Der Empfänger entschlüsselt die Antragsdaten mit Hilfe seines privaten Schlüssels, der nur ihm bekannt sein darf.

Zertifikate enthalten Schlüssel zum Ver- und Entschlüsseln

Der öffentliche und der private Schlüssel sind in einem Zertifikat enthalten, das dem Verantwortlichen für die Umsetzung (oder den beauftragten Entwickler:innen) vorliegen muss.

So erhalten Sie ein Zertifikat

Sie erhalten das erforderliche Zertifikat auf zwei Wegen:

  • Für die Test-Umgebung (TEST) von FIT-Connect erzeugen Sie selbst das erforderliche Zertifikat (siehe unten JSON Web Keys erzeugen)
  • Für die Stage-Umgebung (STAGE) und die Produktiv-Umgebung (PROD) von FIT-Connect beantragen Sie ein Zertifikat bei der Verwaltungs-PKI.

Hier finden Sie eine Beschreibung der Umgebungen von FIT-Connect.

Erforderliches Schlüssel-Format für FIT-Connect

Um die Zertifikate, die Sie selbst erzeugt oder von der Verwaltungs-PKI erhalten haben, innerhalb von FIT-Connect zu verwenden, müssen die Schlüssel im Format JSON Web Keys (JWK) vorliegen.

Programme der FITKO

JSON Web Keys erzeugen

Die Föderale IT-Kooperation (FITKO) sellt Ihnen zwei Programme zur Verfügung, um aus den Zertifikaten die Ver- und Entschlüsselungsschlüssel zu lesen und in das Format JWK umzusetzen.

  • Für die Test-Umgebung (TEST) von FIT-Connect verwenden Sie das Programm "testPkcs12ToJwk.py". Dieses Programm erzeugt intern für Sie selbstgenerierte Zertifikate, liest daraus die Ver- und Entschlüsselungsschlüssel und setzt die Schlüssel in das Format JWK um.
  • Für die Stage-Umgebung (STAGE) und die Produktiv-Umgebung (PROD) von FIT-Connect verwenden Sie das Programm "pkcs12ToJwk.py", um aus einem Zertifikat, das Sie von der Verwaltungs-PKI erhalten, die Ver- und Entschlüsselungsschlüssel zu lesen und in das Format JWK umzusetzen.

Programme der FITKO erhalten

Um die Programme der FITKO auf Ihren Rechner zu laden, klicken Sie auf den folgenden Link Programme der FITKO. Daraufhin erhält Ihr Browser die Programme als Zip-Datei und legt sie im Verzeichnis "Downloads" ab.
Das folgende Bild zeigt die Zip-Datei im Verzeichnis "Downloads":

Zip-Datei mit den Programmen der FITKO

Um diese Zip-Datei zu entpacken, klicken Sie auf die Zip-Datei (um sie auszuwählen), klicken Sie dann oben im Navigationsbereich auf die Schaltfläche "Öffnen". Klicken Sie anschließend auf "Alle extrahieren". Nun wählen Sie ein Verzeichnis aus, in das die Programme gespeichert werden sollen, zum Beispiel in das Verzeichnis "Dieser PC > System (C) > FITKO". Klicken Sie nun auf "Extrahieren".
Das folgende Bild zeigt die entpackten Dateien im Verzeichnis "fit-connect-tools-main":

Programmen der FITKO entpackt

Vorausetzungen

Python ist erforderlich

Die Programme der FITKO sind Python-Skripte, die Python benötigen, um auf einem Rechner zu laufen (ausgeführt zu werden). Deshalb benötigen Sie auf Ihrem Rechner eine installierte Version von Python.

Python auf einem Windows-Rechner installieren

Sie finden hier einen Link zur Downloadseite von Python für Windows.
Auf der Downloadseite klicken Sie auf den Link zum neusten Release (zum Beispiel "Latest Python 3 Release"). Dadurch werden Sie auf eine weitere Seite geleitet. Scrollen Sie auf dieser Seite nach unten und klicken Sie auf den Link zum "Windows installer (64-bit)". Daraufhin erhält Ihr Browser ein Installationsprogramm (Setup-Programm), zum Beispiel "python-3.11.4-amd64.exe". Klicken Sie auf dieses Programm und Ihr Rechner zeigt die folgende Programmoberfläche (GUI) an:

Installationprogramm

Setzen Sie ein Häkchen vor "Use admin privileges when installing py.exe" und vor "Add python.exe to PATH", indem Sie auf diese Texte klicken, falls die Häkchen noch nicht gesetzt sind.

Hinweis

Das Bild oben zeigt, dass auch das Programm PIP installiert wird: "Includes IDLE, pip and documentation".
Die Abkürzung "PIP" steht für "Pip Installs Packages". PIP ist das Paketverwaltungsprogramm für Python-Pakete. Pas Programm installiert Software-Pakete, die für Python-Programme (Skripte) erforderlich sind, siehe unten den Abschnitt Software-Pakete installieren. Sollte PIP in einer späteren Version des Setup-Programms nicht automatisch installiert werden, dann müssen Sie PIP manuell installieren.

Klicken Sie nun auf die Schaltfläche "Install Now" und lassen Sie Änderungen auf Ihrem Rechner zu. Python wird nun automatisch auf Ihrem Rechner installiert.
Nach der erfolgreichen Installation zeigt das Setup-Programm das folgende Bild an:

Installationprogramm erfolgreich durchlaufen

Klicken Sie auf die Schaltfläche "Close", um das Setup-Programm zu schließen.

Hinweis

Python sollte nicht über den Windows-Store installiert werden, da hier Probleme mit dem Installationspfad auftreten können. Außerdem sollte nach der Installation überprüft werden, ob Python auch wirklich der Systemvariablen PATH hinzugefügt wurde. Hierfür muss im Installationsprozess ein Häkchen gesetzt werden, siehe oben den Abschnitt Python auf einem Windows-Rechner installieren.

Kontextmenü aufrufen

Im Abschnitt Programme der FITKO erhalten wurde beschrieben, wie Sie die Programme der FITKO in einem Verzeichnis ablegen, im Beispiel oben in das Verzeichnis "Dieser PC > System (C) > FITKO".
Wechseln Sie nun in das Verzeichnis, in das Sie die Python-Skripte der FITKO gespeichert haben. Drücken Sie die Umschalttaste (Shift-Taste, Hochstelltaste), halten Sie die Umschalttaste gedrückt und klicken Sie mit der rechten Maustaste in das Verzeichnis, das die Python-Prgrammme der FITKO enthält. Das Kontextmenü wird nun angezeigt, mit dem Menüpunkt "PowerShell-Fenster hier öffnen".

Kontextmenü

Hinweis

Der Menüpunkt "PowerShell-Fenster hier öffnen" wird im Kontextmenü nur dann angezeigt, wenn Sie die Umschalttaste drücken und gleichzeitig mit der rechten Maustaste in ein Verzeichnis klicken.

Windows PowerShell aufrufen

Im Kontextmenü klicken Sie auf "PowerShell-Fenster hier öffnen", um die Powershell zu starten. Das folgende Bild zeigt die PowerShell, die im Verzeichnis mit den Python-Programmen geöffnet ist:

PowerShell geöffnet

Was ist die Windows PowerShell?

Die Windows PowerShell ist ein Programm (ein Interpreter), mit dem Sie auf Windows Skripte ausführen können, wie zum Beispiel die Python-Skripte der FITKO.

Installation von Python überprüfen

Testen Sie zunächst, ob Python richtig auf Ihrem Rechner installiert wurde. Dazu geben Sie den folgenden Befehl in die PowerShell ein python -V, um die installierte Version von Python zu erfragen.
Das folgende Bild zeigt den Befehl:

PowerShell mit Befehl python -V

Drücken Sie nun die Return-Taste: Python führt jetzt den Befehl python -V aus und gibt die Antwort in der PowerShell zurück.
Das folgende Bild zeigt die Antwort: Python 3.11.4.

PowerShell Antwort auf Befehl python -V

Hinweis

Das Bild oben zeigt den aktuellen Stand bei der Erstellung dieser Dokumentation. Wenn Sie Python zu einem späteren Zeitpunkt installieren, dann wird wahrscheinlich eine höhere Versionsnummer angezeigt werden.
Sollte hier ein Fehler ausgegeben werden, dann muss statt 'python' zum Beispiel 'python3' oder 'py' verwendet werden.

Software-Pakete installieren

Die Python-Skripte der FITKO verwenden Software-Pakete, die Sie auf Ihrem Rechner installieren müssen, damit die Skripte ausgeführt werden können. Das Installieren der Software-Pakete erfolgt in zwei Schritten:

  • Geben Sie in die PowerShell den folgenden Befehl ein: pip install poetry und drücken Sie auf die Return-Taste, um die Ausführung dieses Befehls zu starten. Warten Sie, bis der Befehl ausgeführt wurde.
  • Geben Sie anschließend den folgenden Befehl ein: poetry install und drücken Sie auf die Return-Taste.

Wenn die Software-Pakete installiert sind, dann zeigt die PowerShell die folgende Rückmeldung an.

Poetry installieren

JSON Web Keys (JWKs) erzeugen

JWK-Dateien für die Test-Umgebung erstellen

Dieser Abschnitt beschreibt, wie Sie für die Test-Umgebung (TEST) von FIT-Connect Dateien im Format JSON Web Key erhalten:

  • Öffnen Sie die PowerShell im Verzeichnis, in dem Sie die Programme der FITKO gespeichert haben, im Beispiel im Ordner "C:\FITKO\fit-connect-tools-main".
  • Geben Sie den Befehl "poetry run python createSelfSignedJwks.py" in die PowerShell ein und drücken Sie die Return-Taste. Das folgende Bild zeigt den Befehl:
JWKs erzeugen für Test

Das folgende Bild zeigt die Ausgabe, nachdem der Befehl ausgeführt wurde:

JWKs wurden erzeugt für Test

Generierte Dateien

Der Befehl erzeugt für Sie die fogenden Dateien und speichert sie in einem Verzeichnis, das in der Ausgabe angegeben ist, im Beispiel im Ordner C:\Users\haidn\AppData\Local\Temp\tmp0hla04_9:

  • publicKey_encryption.json
    Diese Datei enthält den öffentlichen Schlüssel für das Verschlüsseln von Antragsdaten. Laden Sie diese Datei zum Self-Service-Portal hoch, wenn Sie einen Client des Typs Subscriber erstellen.
  • publicKey_signature_verification.json
    Diese Datei enthält den öffentlichen Signaturschlüssel. Laden Sie diese Datei zum Self-Service-Portal hoch, wenn Sie einen Client des Typs Subscriber erstellen.
  • privateKey_decryption.json
    Diese Datei enthält den privaten Schlüssel für das Entschlüsseln von Antragsdaten. Laden Sie diese Datei nicht zum Self-Service-Portal hoch. Dieser Schlüssel ist geheim.
  • privateKey_signing.json
    Diese Datei enthält den privaten Signaturschlüssel. Laden Sie diese Datei nicht zum Self-Service-Portal hoch. Dieser Schlüssel ist geheim.

JWK-Dateien für die Stage- und Produktiv-Umgebung erstellen

Dieser Abschnitt beschreibt, wie Sie für die Stage- und Produktiv-Umgebung von FIT-Connect Dateien erzeugen, die öffentliche und private Schlüssel im Format JSON Web Key enthalten:

  • Beantragen Sie für Ihr Fachverfahren ein Zertifikat der Verwaltungs-PKI.
  • Öffnen Sie die PowerShell im Verzeichnis, in dem Sie die Programme der FITKO gespeichert haben, im Beispiel im Ordner "C:\FITKO\fit-connect-tools-main".
  • Geben Sie den Befehl "poetry run python ./pkcs12ToJwk.py -i pfad/zum/pkcs12/Zertifikat.p12 -o pfad/für/die/jwks -e prod" in die PowerShell ein und drücken Sie auf die Return-Taste.

Der Befehl poetry run python ./pkcs12ToJwk.py -i pfad/zum/pkcs12/Zertifikat.p12 -o pfad/für/die/jwks -e prod benötigt die folgenden Angaben:

  • -i pfad/zum/pkcs12/Zertifikat.p12
    Fügen Sie hier den Pfad zu Ihrem Zertifikat mit der Endung .p12 ein, das Sie von der Verwaltungs-PKI erhalten haben.
    Ein Beispiel:
    Tragen Sie hier "-i ./mein_zertifikat.p12" ein, wenn Sie in das Verzeichnis mit den Python-Skripten Ihr Zertifikat mit dem Namen mein_zertifikat.p12 gespeichert haben.

  • -o pfad/für/die/jwks
    Fügen Sie hier den Pfad zu einem Verzeichnis ein, das Sie für die zu erzeugenden JSON-Dateien angelegt haben.
    Ein Beispiel:
    Tragen Sie hier "-o ./JWKs" ein, wenn Sie in das Verzeichnis mit den Python-Skripten ein Unterverzeichnis mit dem Namen "JWKs" angelegt haben.

  • -e prod
    Fügen Sie hier die Umgebung ein, für die Sie die JSON-Dateien mit JWKs benötigen.
    Ein Beispiel:
    Tragen Sie hier "-e prod" ein, wenn JSON-Dateien mit JWKs für die Stage-Umgebung (STAGE) oder die Produktiv-Umgebung (PROD) von FIT-Connect erstellen werden sollen.

Der Befehl lautet dann im Beispiel:

poetry run python ./pkcs12ToJwk.py -i ./mein_zertifikat.p12 -o ./JWKs -e prod

Hinweis

Sie können den Befehl oben per Copy & Paste in die PowerShell übernehmen:
Dazu markieren Sie den Text und drücken Sie dann gleichzeitig die Strg- und die C-Taste.
Klicken Sie dann in die PowerShell, um sie auszuwählen, und drücken Sie nun gleichzeitig die Strg- und die V-Taste.
Das folgende Bild zeigt die PowerShell mit dem Befehl: Einfuegen aus der Zwischenablage
Ändern Sie nun in diesem Befehl den Namen der p12-Datei ab, d. h. tragen Sie statt des Namens "mein_zertifikat.p12" den tatsächlichen Namen Ihres Zertifikats ein und drücken Sie die Return-Taste.

Passwort eingeben

Dateien mit der Endung .p12 enthalten ein Zertifikat. Falls Ihre Datei mit dieser Endung gegen unberechtigte Zugriffe geschützt ist, dann werden Sie jetzt nach dem Passwort gefragt. Das folgende Bild zeigt die PowerShell mit der Frage nach dem Passwort für den Keystore, d. h. für die Datei mit der Endung .p12:

Passwort eintragen

Geben Sie das Paswort ein und drücken Sie auf die Return-Taste. Das Python-Skript erstellt nun die JSON-Dateien.