diff --git a/docs/receiving/certificate.mdx b/docs/receiving/certificate.mdx index 02f20be17e4a9d31a02e5fa0b8e6c9934827ec59..1a7a66dce0310c6140a03cbba8fc4f8d6e297fe6 100644 --- a/docs/receiving/certificate.mdx +++ b/docs/receiving/certificate.mdx @@ -156,16 +156,67 @@ Sie erhalten nach der Bestätigung eine Meldung, dass Ihr Zertifikat freigeschal <img width="600" alt="Zertifikat als *.der-Datei herunterladen" src={useBaseUrl('/images/certificate_registration/certificate_registration_11_3.png')} /> -## Ableitung eines FIT-Connect-kompatiblen JSON Web Keys aus einem Zertifikat -JSON Web Keys sind das Austauschformat in dem kryptografische Schlüssel in FIT-Connect zwischen der Destination und dem +## 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. Ein Übertragen von privaten Schlüsseln zwischen Servern/Computern sollte vermieden werden. -Sollte dies doch notwendig sein, so muss die Übermittlung nur verschlüsselt erfolgen. +Sollte dies doch notwendig sein, so muss die Übermittlung verschlüsselt erfolgen. Im Folgenden wird beschrieben, wie diese JWKs erzeugt werden können. :::note Hinweis -An dieser Stelle wird zeitnah ein Tool für die Konvertierung von Zertifikaten bereitgestellt. +[Hier](../details/jwk-creation.md) wird beschrieben, wie Sie JWKs für Testzwecke ohne ein Zertifikat erstellen. ::: +### Python Skript +Für das Erzeugen von JWKs aus PKCS#12-Dateien stellt die FITKO das Skript [pkcs12-to-jwk.py](https://git.fitko.de/fit-connect/fit-connect-tools) bereit. <br/> +Dieses Skript erstellt zwei JSON Web Keys (JWKs): +- ein JWK mit einem [öffentlichen Schlüssel zum Verschlüsseln](https://docs.fitko.de/fit-connect/docs/details/crypto/#vorgaben-zur-ver--und-entschl%C3%BCsselung-von-daten) <br/> +- ein JWK mit einen [öffentlichen Schlüssel zum Überprüfen von Signaturen](https://docs.fitko.de/fit-connect/docs/details/crypto/#vorgaben-zur-signaturerstellung-und--pr%C3%BCfung). + +Diese beiden JWKs mit öffentlichen Schlüsseln benötigen Sie zum Konfiguration eines Zustellpunkts im Self-Service-Portal der FITKO. <br/> +Zudem erzeugt das Skript zwei weitere JWKs: Diese JWKs enthalten die privaten Schlüssel, die zu den öffentlichen Schlüsseln gehören. <br/> + +### Herunterladen der FIT-Connect Tools +Laden Sie die [FIT-Connect-Tools als Zip-Datei](https://git.fitko.de/fit-connect/fit-connect-tools/-/archive/main/fit-connect-tools-main.zip) herunter und entpacken Sie sie an einem Ort Ihrer Wahl (Alternativ: Klonen Sie [unser Git-Repository](https://git.fitko.de/fit-connect/fit-connect-tools): `git clone https://git.fitko.de/fit-connect/fit-connect-tools.git`). + +Navigieren Sie anschließend zum Verzeichnis, in dem Sie die Tools entpackt haben, und öffnen Sie dort unter Windows eine **PowerShell** bzw. unter Linux ein **Terminal**. Alternativ können Sie auch innerhalb der **PowerShell** oder des **Terminals** zum Verzeichnis navigieren. + +### Erforderliche Python-Pakete installieren +Um das Skript zur Erstellung von JSON Web Keys auszuführen, werden zusätzliche Python Pakete benötigt. Diese lassen sich mithilfe von **pip** und **poetry** nachinstallieren. Dazu kann unter Windows die **PowerShell** sowie das **Terminal** unter Linux verwendet werden. + +```console +$ pip3 install poetry +$ poetry install +``` + +### Ausführung des Skripts +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`) + +Ausgeführt wird das Skript dann mit dem folgenden Befehl. + +```console +$ poetry run python ./pkcs12-to-jwk.py -i "pfad/zum/pkcs12/Zertifikat.p12" -o "pfad/für/die/jwks" -e prod +``` + +Sollte das Zertifikat mit einem Passwort gesichert sein, dann erfragt das Skript das Passwort über die Konsole. Danach wird im Erfolgsfall der Speicherort der Schlüssel ausgegeben: + +```console +🔒 Wrote JWK representation of encryption public key (key_use=wrapKey) to ..\res\publicKey_encryption.jwk.json +🔒 Wrote JWK representation of signature validation public key (key_use=verify) to ..\res\publicKey_signature_verification.jwk.json +Please upload these keys when creating a destination in the self service portal. + +🔒 Wrote JWK representation of decryption private key (key_use=unwrapKey) to ..\res\privateKey_decryption.jwk.json +🔒 Wrote JWK representation of signing private key (key_use=sign) to ..\res\privateKey_signing.jwk.json +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" +::: + +### OpenSSL Im Folgenden eine beispielhafte Schritt-für-Schritt-Anleitung, um aus einem Zertifikat aus der Verwaltungs-PKI einen JSON-Web-Key zu erzeugen: