From f93aa4b1b9571136a462c384fafe8ee22bd9b573 Mon Sep 17 00:00:00 2001
From: Marco Holz <marco.holz@fitko.de>
Date: Wed, 4 Aug 2021 21:35:07 +0200
Subject: [PATCH] Move contents from details/encryption to existing chapters
---
docs/details/encryption.mdx | 216 ------------------
docs/getting-started/encryption.mdx | 28 +++
docs/getting-started/overview.md | 7 +-
.../certificate.mdx} | 29 ++-
docs/getting-started/receiving/decrypt.mdx | 2 +-
.../getting-started/receiving/destination.mdx | 2 +-
.../receiving/download-submission.mdx | 2 +-
.../receiving/process-and-acknowledge.mdx | 2 +-
docs/getting-started/receiving/query.mdx | 3 +-
docs/getting-started/receiving/validate.mdx | 2 +-
docs/getting-started/sending/encrypt.mdx | 29 ++-
docs/sidebar.js | 1 -
12 files changed, 73 insertions(+), 250 deletions(-)
delete mode 100644 docs/details/encryption.mdx
create mode 100644 docs/getting-started/encryption.mdx
rename docs/getting-started/{encryption.md => receiving/certificate.mdx} (67%)
diff --git a/docs/details/encryption.mdx b/docs/details/encryption.mdx
deleted file mode 100644
index 36a1779ee..000000000
--- a/docs/details/encryption.mdx
+++ /dev/null
@@ -1,216 +0,0 @@
----
-title: Verschlüsselung
----
-
-import useBaseUrl from '@docusaurus/useBaseUrl';
-
-# Verschlüsselte Übertragung
-
-## Einleitung
-
-FIT-Connect verwendet zur Übertragung von Antragsdaten und Antragsmetadaten (abgesehen von den für die Übermittlung zwingend notwendigen Daten, z.B. Destination-ID) eine Ende-zu-Ende-Verschlüsselung. Diese ist auf Basis der Standards [JSON Web Encryption (JWE)](https://tools.ietf.org/html/rfc7516) und [JSON Web Keys (JWK)](https://tools.ietf.org/html/rfc7517) umgesetzt. Bei der Implementierung der Ende-zu-Ende-Verschlüsselung MÜSSEN die [Vorgaben für kryptographische Verfahren](crypto.md) beachtet werden.
-
-Die Informationen auf dieser Seite sind relevant, wenn man:
-
-- ein **Fachverfahren** mit FIT-Connect-Anbindung entwickelt oder aufsetzt
-- einen **Onlinedienst** mit FIT-Connect-Anbindung entwickelt oder aufsetzt
-
-### Warum ist Ende-zu-Ende-Verschlüsselung wichtig?
-
-Im Kontext von Anträgen an Behörden werden häufig höchstsensible Daten übermittelt, die im Rahmen von [Vorgaben des BSI](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR03107/TR-03107-1.pdf?__blob=publicationFile&v=4) nur Ende-zu-Ende-verschlüsselt übertragen werden dürfen.
-Bei FIT-Connect ist die Zielsetzung einen möglichst einfachen, sicheren und klar definierten Standard zu etablieren. Deshalb ist die verschlüsselte Übertragung von Antragsdaten ein integraler Bestandteil von FIT-Connect. Eine Übertragung von Antragsdaten erfolgt mit FIT-Connect ausschließlich verschlüsselt.
-
-## Grundlagen zur sicheren Implementierung von FIT-Connect
-
-### Ende-zu-Ende-Verschlüsselung
-
-FIT-Connect basiert auf dem Ansatz von Ende-zu-Ende-Verschlüsselung. Das bedeutet, dass Daten immer vom Endgerät der Nutzer*in bis in die Zielbehörde bzw. das Fachverfahren asymmetrisch verschlüsselt sein müssen.
-
-<img src={useBaseUrl('/images/encryption/tls-no-tls.png')} alt="Grafik zur Veranschaulichung einer Ende-zu-Ende-Verschlüsselung" width="600" />
-
-Zur Realisierung einer Ende-zu-Ende-Verschlüsselung vom Endgerät der Anwender:in bis zum Fachverfahren einer Behörde, dürfen Daten nicht unverschlüsselt oder nur per TLS gesichert an ein Backend übermittelt und erst dort die für FIT-Connect spezifizierte Verschlüsselung angewendet werden. Sollte eine längerfristige Speicherung der Antragsdaten nötig sein, so muss diese immer clientseitig (z.B. in der IndexDB des Browsers, per Download, …) erfolgen.
-
-### Zertifikate von Zustellpunkten müssen der Verwaltungs-PKI entstammen
-
-Jeder verwendete Public Key (idR. in Form eines JSON Web Keys) muss einem digitalen Zertifikat entstammen und von einer Zertifizierungsstelle innerhalb der Verwaltungs-PKI signiert werden. JSON Web Keys müssen immer mit der komplette Zertifikatskette bis zum Wurzelzertifikat ausgeliefert werden, um clientseitig korrekt validierbar zu sein.
-
-### Kryptografisches Material muss vor der Verwendung immer geprüft werden
-
-Die für die Verschlüsselung verwendeten JSON Web Keys müssen vor Verwendung anhand des zugehörigen Zertifikats aus der Verwaltungs-PKI auf Gültigkeit überprüft werden.
-
-<img src={useBaseUrl('/images/encryption/pki-check.png')} alt="Grafik zur Veranschaulichung der Einbindung einer PKI zur Verhinderung von Man-in-the-Middle-Angriffen" width="600" />
-
-Nicht vertrauenswürdige Schlüssel dürfen nicht für die Verschlüsselung von Anträgen verwendet werden. Das soll Angriffe wie Man-in-the-middle-Attacken verhindern.
-
-## Architektur
-
-Kern von FIT-Connect ist der Zustelldienst, der über die beiden APIs "Application Sender API" und "Application Subscriber API" den Absender (Sender) und Empfänger (Subscriber) einer Einreichung verbindet.
-
-Jedes empfangende System (Fachverfahren / virtuelle Poststelle) verfügt über einen oder mehrere Endpunkt, an den Anträge gesendet werden (Zustellpunkt) und einen oder mehrere Endpunkte von denen Anträge verschlüsselt versendet werden (in der Regel: Onlinedienst, App, …).
-
-Ein Einreichung wird an einen Zustellpunkt (Zielort) geschickt. Diesen Zustellpunkt legt der Empfänger über die "Application Subscriber API" an. Der Absender muss die Destination-ID des Zustellpunktes kennen und kann dann Anträge über die "Application Sender API" an diese Destination-ID senden.
-
-### Application Sender API
-
-Der Absender muss die Destination-ID vorliegen haben und erfagt über die Application Sender API die Informationen zum Zustellpunkt. Diesen entnimmt er die Liste der möglichen Schemas und wählt eines aus. Sofern es sich um eine verschlüsselte Übertragung handelt, wählt er einen öffentlichen Schlüssel.
-
-Derzeit muss die Destination-ID manuell vom Empfänger an den Absender übergeben werden. Dies soll in Zukunft automatisch mithilfe bestehender Mechanismen, z.B. XZufi oder DVDV passieren.
-
-Das gewählte Schema wird in den Metadaten der Einreichung (Application Metadata) eingetragen und legt die Art der Übertragung fest.
-
-### Application Subscriber API
-
-Über die Application Subscriber API werden die Destinations verwaltet, an die die Anträge gesendet werden. Eine Destination enthält eine Liste von Schemas, welche Formate der Empfänger akzeptiert.
-
-Der Empfänger kann in der Destination mehrere Schemas und mehrere öffentliche Schlüssel hinterlegen. Der Absender sucht sich davon für die Übertragung ein Schema und einen öffentlichen Schlüssel aus. Es wird empfohlen, genau ein Schema und genau einen öffentlichen Schlüssel anzubieten.
-
-Es ist geplant, dass die hinterlegten öffentlichen Schlüssel so organisiert werden, dass ein kontrolliertes Key-Rollover stattfinden kann. Dazu werden zu den Schlüsseln die Gültigkeitszeiträume ergänzt.
-
-### Ablauf einer Einreichung aus Bürger*innen-Client-Perspektive
-
-Wenn eine Bürger*in nun einen Einreichung im Web oder in einer App übermitteln möchte, läuft das in der Regel wie folgt ab:
-
-- Bürger*in findet den passenden Einreichung über einen Zuständigkeitsfinder.
-- Die Applikation erhält aus dem Zuständigkeitsfinder die passende Destination-ID zum Einreichung.
-- Die Applikation ruft über die Sender-API die Formular und Datenstruktur, Verschlüsselungszertifikat, … ab.
-- Die Applikation prüft das Verschlüsselungszertifikat.
-- Die Applikation übermittelt die Antragsdaten und optional einen Public Key des Users verschlüsselt an die Sender-API und erhält dafür einen Status-Token.
-- Mit dem Status-Token ruft die Applikation verschlüsselte Statusinformationen zum Einreichung aus der Sender-API ab.
-
-**TODO: add here some doc links about oauth**
-
-## Bereitstellung eines Destination-Endpunktes
-
-### Erstellung eines FIT-Connect-kompatiblen JSON Web Keys
-
-JSON Web Keys sind das Austauschformat in dem kryptografische Schlüssel in FIT-Connect zwischen der Destination und dem Onlinedienst ausgetauscht werden. Die kryptografischen Anforderungen an die Keys findet man unter **TODO**. Die Keys sollten bereits dort generiert werden, wo sie am Ende eingesetzt werden. Ein unnötiges übertragen von Privat Keys zwischen Servern/Computern sollte vermieden werden. Sollte dies doch notwendig sein, so muss die Übermittlung wenn dann nur verschlüsselt erfolgen.
-
-Im folgenden eine beispielhafte Schritt-für-Schritt-Anleitung um einen JSON-Web-Key zu generieren:
-
-1. Lokale Generierung eines X.509 zugrundeliegenden RSA-Keys. `openssl genrsa -out fachverfahren1.meineverwaltung.de.key 4096`
-2. Generierung des Zertifikatsrequests `openssl req -new -sha256 -key fachverfahren1.meineverwaltung.de.key -out fachverfahren1.meineverwaltung.de.csr`
-3. Dieser Zertifikatsrequest muss nun von einer Verwaltungs-PKI signiert werden.
-4. Das von der Verwaltungs-PKI signierte Zertifikat muss nun in einen JWK umgewandelt werden: … **TODO(Lilith): einfügen nachdem wir das einmal gemacht haben**
-
-Das dabei entstandene Zertifikat muss zur dem Fachverfahren gehörende Destination hinzugefügt werden
-
-### Anlegen eines Zustellpunktes
-
-Ein Zustellpunkt benötigt mindestens immer ein erlaubtes Fachdaten-Schema sowie einen Verschlüsselungs- und einen Signaturkey. Diese müssen in das Format JSON Web Key konvertiert und über den Zustelldienst als JSON Web Key bereitgestellt werden.
-
-#### Beispiel
-
-```json
-{
- "publicKeys": {
- "keys": [
- {
- "kty": "RSA",
- "key_ops": ["wrapKey"],
- "n": "……(Public Key)……",
- "e": "AQAB",
- "alg": "PS512",
- "kid": "……(Key ID)……",
- "x5t": "……(Fingerprint)……",
- "x5c": [
- "……(base64 encoded cert)……"
- "……(base64 encoded intermediate cert)……",
- "……(base64 encoded root cert)……",
- ]
- },
- {
- "kty": "RSA",
- "key_ops": ["verify"],
- "n": "……(Public Key)……",
- "e": "AQAB",
- "alg": "PS512",
- "kid": "……(Key ID)……",
- "x5t": "……(Fingerprint)……",
- "x5c": [
- "……(base64 encoded cert)……"
- "……(base64 encoded intermediate cert)……",
- "……(base64 encoded root cert)……",
- ]
- }
- ]
- },
- "schemas": [
- {
- "schemaSource": "none",
- "mimeType": "json",
- },
- {
- "schemaSource": "none",
- "mimeType": "xml",
- }
- ],
- "destinationId": "b444a551-74af-4a98-aa65-d1ffccd385d1"
-}
-```
-
-## Implementierung eines Onlinedienstes
-
-### Abrufen der Endpunktinformationen
-
-### Überprüfen der Json Web Keys
-
-Die JSON Web Keys müssen vor der Verwendung im Client auf Gültigkeit geprüft werden. Das umfasst insbesondere folgende Punkte:
-
-- Überprüfung gegen eine Certificate Revocation List und/oder einen OCSP-Endpunkt mit signierten Antworten.
-- Überprüfung der Zertifikats-Kette bis zum Wurzelzertifikat (BSI).
-
-Weitere Informationen zur Glütigkeitsprüfung finden sich im BSI [TR-02103](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02103/BSI-TR-02103.pdf?__blob=publicationFile&v=4) und im Abschnitt "[Anforderungen an das kryptografische Material](#Vorgaben-für-kryptographische-Verfahren)" .
-
-### Aufbau der Ãœbertragung
-
-Eine Übertragung über FIT-Connect besteht aus einem Metadatensatz, optionalen Fachdaten und beliebig vielen (0-∞) Dokumenten (Anlagen). Ein Teil der Metadaten enthälten transportrelevante Informationen und werden deshalb unverschlüsselt übertragen. Alle nicht transportrelevanten Metadaten, die Fachdaten und Anlagen werden verschlüsselt übertragen.
-
-Die Metadaten, Fachdaten und Anlagen werden gemäß dem Standard JSON Web Encryption RFC 7516) verschlüsselt. Als Datenformat für die Übertragung wird die sogenannte [JWE-Compact Serialisierung](https://tools.ietf.org/html/rfc7516#section-7.1) verwendet. Alle angehängten Dokumente müssen als Binärdateien und nicht als Strings enkodiert verschlüsselt werden.
-
-Zur Verschlüsselung wird ein JSON Web Key mit dem Typ "wrap_key" verwendet.
-
-#### Beispiel (Metadaten)
-
-```json
-{
- "contentStructure": {
- "data": {
- "schema": {
- "schemaSource": "none",
- "mimeType": "json",
- }
- },
- "docs": [
- {
- "size": 13046,
- "purpose": "attachment",
- "docId": "1",
- "mimeType": "application/pdf"
- }
- ]
- },
- "submissionId": "6f7b00f1-2f0c-46da-93c9-ca020aa1758f"
-}
-```
-
-#### Beispiel (Fachdaten)
-
-Bei der verschlüsselten Übertragung der Fachdaten und Anlagen wird der Content-Type "application/jose" (Achtung: jose, nicht json) verwendet.
-
-Beispiel:
-
-```text
-PUT /delivery-service-beta7/sender/destinations/e1009dea-d97e-4104-b389-bf653d8bd30e/applications/6f7b00f1-2f0c-46da-93c9-ca020aa1758f/data HTTP/1.1
-Content-Type: application/jose
-Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjM1ZTM2Nzk2LTM1NDAtNDUwMy1iYT...
-
-eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.yTSVS7re6hZKO46aDriHrRFOyc5-
-3TIIrvcKUf2qAfGdH7InufWPCrDyEnazSDI7HtOa5X2MU3iUnmmiEuP-Lef76xTPv2lmL4_lyhW5D8zq
-7zbrIaIaVhtg7ekF1r9Oy9nLsEBQWLD4EWda2PfAibV7iQbOVMn1rVk4DzKtCykj5RSrH96i-lbPVFl-
-Xw_E2G5XsL0gOHrdbAsjTF1h67bvh2hnojc9SH1GnlD0TlUO30n0GKLgC7tNNiLGtNrRo8ih3LUWYo-m
-34Q6NGjaNTycHnWMYZzXHbIcBzYr6WLTsrB07rKXEyrHGLaRL88y2c-ACyEzpgv4qR5DAp98Su2u45ar
-pfGU_7HxX4d-PLEoDfIRnh32nprarbaIesj9Ppgiu7QciWRApcyszk0a5rzZ7Dk_6-ydMfD92H2p3tdt
-OcFhj3XGUshVKec2nRhtCZPOMPTIjxFpozsiRetjZo9LFHzRcvr1eSS_hpteKJ3ltioY9nzt1IX2JqQm
-TGtY.VGOCnGM9LEZP5mUO.LQeKj4SKqsUNsBp4ZRN_56QbS8MQ01YTzRVFStk.Z0YMEua9kvCV7LkeJH
-kprA
-```
diff --git a/docs/getting-started/encryption.mdx b/docs/getting-started/encryption.mdx
new file mode 100644
index 000000000..dcea24602
--- /dev/null
+++ b/docs/getting-started/encryption.mdx
@@ -0,0 +1,28 @@
+# Verschlüsselte Übertragung
+
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+FIT-Connect verwendet zur Übertragung von Antragsdaten und Antragsmetadaten, abgesehen von den für die Übermittlung zwingend notwendigen Daten, eine Ende-zu-Ende-Verschlüsselung.
+Diese ist auf Basis der Standards [JSON Web Encryption (JWE)](https://tools.ietf.org/html/rfc7516) und [JSON Web Keys (JWK)](https://tools.ietf.org/html/rfc7517) umgesetzt. Bei der Implementierung der Ende-zu-Ende-Verschlüsselung MÜSSEN die [Vorgaben für kryptographische Verfahren](details/crypto.md) beachtet werden.
+
+## Warum ist Ende-zu-Ende-Verschlüsselung wichtig?
+Im Kontext von Anträgen an Behörden werden häufig höchstsensible Daten übermittelt, die im Rahmen von [Vorgaben des BSI](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR03107/TR-03107-1.pdf?__blob=publicationFile&v=4) nur Ende-zu-Ende-verschlüsselt übertragen werden dürfen.
+Zielsetzung von FIT-Connect ist ein möglichst einfaches, sicheres und klar definiertes Vorgehen zur Einreichung von Antragsdaten zu etablieren. Deshalb ist die verschlüsselte Übertragung von Antragsdaten ein integraler Bestandteil von FIT-Connect. Eine Übertragung von Antragsdaten erfolgt mit FIT-Connect ausschließlich verschlüsselt.
+
+## Grundlagen zur sicheren Implementierung von FIT-Connect
+### Ende-zu-Ende-Verschlüsselung
+FIT-Connect verfolgt den Ansatz einer Ende-zu-Ende-Verschlüsselung. Das bedeutet, dass Daten immer vom Endgerät der Nutzer:in bis in die Zielbehörde bzw. das Fachverfahren asymmetrisch verschlüsselt sind.
+
+<img src={useBaseUrl('/images/encryption/tls-no-tls.png')} alt="Grafik zur Veranschaulichung einer Ende-zu-Ende-Verschlüsselung" width="600" />
+
+Zur Realisierung einer Ende-zu-Ende-Verschlüsselung vom Endgerät der Anwender:in bis zum Fachverfahren einer Behörde, dürfen Daten nicht unverschlüsselt oder nur per TLS gesichert an ein Backend übermittelt und erst dort die für FIT-Connect spezifizierte Verschlüsselung angewendet werden. Sollte eine längerfristige Speicherung der Antragsdaten nötig sein, so muss diese immer clientseitig (z.B. in der IndexDB des Browsers, per Download, …) erfolgen.
+
+### Zertifikate von Zustellpunkten müssen der Verwaltungs-PKI entstammen
+Jeder verwendete Public Key (idR. in Form eines JSON Web Keys) muss einem digitalen Zertifikat entstammen und von einer Zertifizierungsstelle innerhalb der Verwaltungs-PKI signiert werden. JSON Web Keys müssen immer mit der komplette Zertifikatskette bis zum Wurzelzertifikat ausgeliefert werden, um clientseitig korrekt validierbar zu sein.
+
+### Kryptografisches Material muss vor der Verwendung immer geprüft werden
+Die für die Verschlüsselung verwendeten JSON Web Keys müssen vor Verwendung anhand des zugehörigen Zertifikats aus der Verwaltungs-PKI auf Gültigkeit überprüft werden.
+
+<img src={useBaseUrl('/images/encryption/pki-check.png')} alt="Grafik zur Veranschaulichung der Einbindung einer PKI zur Verhinderung von Man-in-the-Middle-Angriffen" width="600" />
+
+Nicht vertrauenswürdige Schlüssel dürfen nicht für die Verschlüsselung von Anträgen verwendet werden. Das soll Angriffe wie Man-in-the-middle-Attacken verhindern.
diff --git a/docs/getting-started/overview.md b/docs/getting-started/overview.md
index 813eb6d5a..cb547aa52 100644
--- a/docs/getting-started/overview.md
+++ b/docs/getting-started/overview.md
@@ -1,13 +1,12 @@
# Ãœberblick
Im folgenden "Getting Started"-Guide wird beschrieben, wie die ersten Interaktionen mit FIT-Connect ablaufen und FIT-Connect integriert werden kann.
-In den nächsten Abschnitten wird dann beschrieben, wie man sich gegenüber FIT-Connect authentifiziert, Daten für die Übertragung
-ver- und entschlüsselt werden, sowie welche Schritte für das einreichen bzw. empfangen von Einreichungen notwendig sind.
+In den nächsten Abschnitten wird beschrieben, wie man sich gegenüber FIT-Connect authentifiziert, Daten für die Übertragung ver- und entschlüsselt werden, sowie welche Schritte für das Einreichen bzw. Empfangen von Einreichungen notwendig sind.
:::note Hinweis
-
Als Voraussetzungen hierfür ist es notwendig einen Account zu besitzen, wie in "[Registrierung und Account-Verwaltung](../account.md)" beschrieben ist.
-
:::
+Kern von FIT-Connect ist der Zustelldienst, der sendende und empfangende Systeme einer Einreichung verbindet.
+Jedes empfangende System (Fachverfahren / virtuelle Poststelle) verfügt über einen oder mehrere Zustellpunkte (Destinations), an die Einreichungen (Anträge oder Berichte) gesendet werden. Zustellpunkte können von empfangenden Systemen konfiguriert und von sendenden Systemen adressiert werden.
diff --git a/docs/getting-started/encryption.md b/docs/getting-started/receiving/certificate.mdx
similarity index 67%
rename from docs/getting-started/encryption.md
rename to docs/getting-started/receiving/certificate.mdx
index edbb920ea..e717b2fa9 100644
--- a/docs/getting-started/encryption.md
+++ b/docs/getting-started/receiving/certificate.mdx
@@ -1,20 +1,14 @@
-# Verschlüsselte Übertragung
+---
+title: Zertifikatsbeantragung
+sidebar_position: 2
+---
-FIT-Connect verwendet zur Übertragung von Antragsdaten und Antragsmetadaten, abgesehen von den für die Übermittlung zwingend notwendigen Daten, eine Ende-zu-Ende-Verschlüsselung.
-Diese ist auf Basis der Standards [JSON Web Encryption (JWE)](https://tools.ietf.org/html/rfc7516) und [JSON Web Keys (JWK)](https://tools.ietf.org/html/rfc7517) umgesetzt.
-
-Die JSON Web Keys werden hierbei aber aus Zertifikaten abgeleitet und die öffentlichen Teile in einem Zustellpunkt für die Verwendung durch ein Fachverfahren 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 öffentlichen 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 Voraussetzung, damit Clients Daten verschlüsseln bzw. Signaturen prüfen können, ist ein gültiges X.509-Zertifikat
-aus der Verwaltungs-PKI. Bei der Erstellung von Zertifikaten und der Zertifikatsprüfung sind die Regelungen und
-Standards aus
-BSI [TR-02103](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02103/BSI-TR-02103.pdf?__blob=publicationFile&v=4)
-zu beachten.
+## Zertifikatsbeantragung
+Die Voraussetzung, damit sendende Systeme Daten verschlüsseln bzw. Signaturen prüfen können, ist die Hinterlegung eines gültiges X.509-Zertifikats aus der Verwaltungs-PKI in einem Zustellpunkt.
+Bei der Erstellung von Zertifikaten und der Zertifikatsprüfung sind die Regelungen und Standards aus BSI [TR-02103](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02103/BSI-TR-02103.pdf?__blob=publicationFile&v=4) zu beachten.
Weitere Vorgaben für die eingesetzten X.509-Zertifikate sind unter [Vorgaben für kryptographische Verfahren in FIT-Connect](https://docs.fitko.de/fit-connect/docs/details/crypto#vorgaben-f%C3%BCr-eingesetzte-x509-zertifikate) dokumentiert.
@@ -22,8 +16,11 @@ Weitere Vorgaben für die eingesetzten X.509-Zertifikate sind unter [Vorgaben f
Der Ablauf der Zertifikatsbeantragung ist je nach zuständiger Registrierungsstelle unterschiedlich. Details zur Beantragung von Zertifikaten werden an dieser Stelle noch ergänzt.
:::
-## Erstellung eines FIT-Connect-kompatiblen JSON Web Keys
+:::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.
+:::
+### 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
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.
@@ -38,7 +35,7 @@ JSON-Web-Key zu erzeugen:
openssl x509 -in certificate.pem -pubkey -noout
```
-2. :construction: :warning: *Muss noch geklärt werden*
+2. :construction: :warning: *wird noch ergänzt*
```bash
# pubkey --[into]--> JWK
diff --git a/docs/getting-started/receiving/decrypt.mdx b/docs/getting-started/receiving/decrypt.mdx
index eebee7395..49a5b1691 100644
--- a/docs/getting-started/receiving/decrypt.mdx
+++ b/docs/getting-started/receiving/decrypt.mdx
@@ -1,5 +1,5 @@
---
-sidebar_position: 5
+sidebar_position: 6
title: Entschlüsseln
---
diff --git a/docs/getting-started/receiving/destination.mdx b/docs/getting-started/receiving/destination.mdx
index 57ab8d9f4..83e454bd5 100644
--- a/docs/getting-started/receiving/destination.mdx
+++ b/docs/getting-started/receiving/destination.mdx
@@ -1,5 +1,5 @@
---
-sidebar_position: 2
+sidebar_position: 3
title: 🚧 Zustellpunkt anlegen
---
diff --git a/docs/getting-started/receiving/download-submission.mdx b/docs/getting-started/receiving/download-submission.mdx
index 4d5a45eda..a2a64ce9c 100644
--- a/docs/getting-started/receiving/download-submission.mdx
+++ b/docs/getting-started/receiving/download-submission.mdx
@@ -1,5 +1,5 @@
---
-sidebar_position: 4
+sidebar_position: 5
title: Einreichung herunterladen
---
diff --git a/docs/getting-started/receiving/process-and-acknowledge.mdx b/docs/getting-started/receiving/process-and-acknowledge.mdx
index bf9dbcc7b..73934cf64 100644
--- a/docs/getting-started/receiving/process-and-acknowledge.mdx
+++ b/docs/getting-started/receiving/process-and-acknowledge.mdx
@@ -1,5 +1,5 @@
---
-sidebar_position: 7
+sidebar_position: 8
title: 🚧 Empfangsbestätigung
---
diff --git a/docs/getting-started/receiving/query.mdx b/docs/getting-started/receiving/query.mdx
index 2c6228749..e659fd37a 100644
--- a/docs/getting-started/receiving/query.mdx
+++ b/docs/getting-started/receiving/query.mdx
@@ -1,5 +1,5 @@
---
-sidebar_position: 3
+sidebar_position: 4
title: Vorhandensein neuer Einreichungen prüfen
---
@@ -38,4 +38,3 @@ $ curl \
]
}
```
-
diff --git a/docs/getting-started/receiving/validate.mdx b/docs/getting-started/receiving/validate.mdx
index a0f20b0ca..10a73079e 100644
--- a/docs/getting-started/receiving/validate.mdx
+++ b/docs/getting-started/receiving/validate.mdx
@@ -1,5 +1,5 @@
---
-sidebar_position: 6
+sidebar_position: 7
title: Validierung des Metadatensatz
---
diff --git a/docs/getting-started/sending/encrypt.mdx b/docs/getting-started/sending/encrypt.mdx
index 3a33c1fc1..ff9b35dc5 100644
--- a/docs/getting-started/sending/encrypt.mdx
+++ b/docs/getting-started/sending/encrypt.mdx
@@ -6,7 +6,8 @@ sidebar_position: 4
import Tabs from '@theme/Tabs'
import TabItem from '@theme/TabItem'
-Viele Daten, die über den Zustelldienst übertragen werden, enthalten schützenswerte Informationen und müssen verschlüsselt werden. Dazu gehören die Metadaten der Einreichung, die Fachdaten selbst, sowie alle zugehörigen Anlagen.
+Viele Daten, die über den Zustelldienst übertragen werden, enthalten schützenswerte Informationen und müssen verschlüsselt werden. Eine Übertragung über FIT-Connect besteht aus einem Metadatensatz, optionalen Fachdaten und beliebig vielen (0-∞) Dokumenten (Anlagen). Die Metadaten, Fachdaten und Anlagen werden gemäß dem Standard [JSON Web Encryption (JWE)](https://tools.ietf.org/html/rfc7516) verschlüsselt. Als Datenformat für die Übertragung wird die sogenannte [JWE-Compact Serialisierung](https://tools.ietf.org/html/rfc7516#section-7.1) verwendet. Alle angehängten Dokumente müssen als Binärdateien und nicht als Strings kodiert verschlüsselt werden.
+
Gegeben, dass ein öffentlicher Teil eines JWK eines Zustellpunktes vorhanden ist, können mit diesem Daten für diesen Zustellpunkt verschlüsselt werden. Ein Beispiel für den öffentlichen Teil eines JWK ist unten aufgeführt.
```json
@@ -24,6 +25,22 @@ Gegeben, dass ein öffentlicher Teil eines JWK eines Zustellpunktes vorhanden is
}
```
+## Überprüfen öffentlicher Schlüssel
+Die JSON Web Keys MÜSSEN vor der Verwendung zwingend im Client auf Gültigkeit geprüft werden. Das umfasst insbesondere folgende Schritte:
+
+- Überprüfung, dass der JSON Web Key für die Verschlüsselung geeignet ist (`"keyops": ["wrap_key"]`)
+- Überprüfung, dass der öffentliche Schlüssel mit dem im JSON Web Key hinterlegten Zertifikat übereinstimmt (Attribute `n` und `e`)
+- Überprüfung der Zertifikats-Kette bis zum Wurzelzertifikat (BSI)
+- Überprüfung gegen eine Certificate Revocation List und/oder einen OCSP-Endpunkt mit signierten Antworten
+
+Weitere Informationen zur Gültigkeitsprüfung finden sich in der technischen Richtlinie [BSI TR-02103](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02103/BSI-TR-02103.pdf?__blob=publicationFile&v=4).
+
+:::note Hinweis
+An dieser Stelle werden noch detailliertere Informationen und konkrete Implementierungsbeispiele zur Prüfung der JSON Web Keys ergänzt.
+:::
+
+## Nutzung von JSON Web Keys zur Verschlüsselung
+
<Tabs
defaultValue="js"
values={[
@@ -53,9 +70,10 @@ const publicKey = await parseJwk({
})
```
-Mit diesem umgewandelten Schlüssel können nun Zeichenketten und Binärdaten verschlüsselt werden. Im Großen und Ganzen kann alles verschlüsselt werden, was vorher in ein `Uint8Array` umgewandelt wurde.
+## Verschlüsselung von Inhaltsdaten
+Mit dem zuvor eingelesenen Schlüssel können nun Zeichenketten und Binärdaten verschlüsselt werden.
-Für Texte kann man hier den TextEncoder aus der Browser-Runtime nutzen, der den String in die UTF8-Bytes und damit in ein `Uint8Array` umwandelt.
+Für die verschlüsselung von Zeichenketten (z.B. serialisierte JSON- oder XML-Objekte) kann die in Browser verfügbare [TextEncoder-API](https://developer.mozilla.org/en-US/docs/Web/API/TextEncoder) verwendet werden, die den String UTF8-kodiert in ein `Uint8Array` umwandelt.
```javascript
const data = {
@@ -102,9 +120,8 @@ String publicKeyAsString = new String(existingPublicKey.readAllBytes());
RSAKey publicKey = RSAKey.parse(publicKeyAsString).toRSAPublicKey();
```
-Mit diesem umgewandelten Schlüssel können nun Texte und Binärdaten verschlüsselt werden.
-Über die [Payload-Klasse](https://www.javadoc.io/doc/com.nimbusds/nimbus-jose-jwt/latest/com/nimbusds/jose/Payload.html) können verschiedene Typen,
-wie `byte[]` oder `String`, verschlüsselt werden.
+Mit diesem umgewandelten Schlüssel können nun Zeichenketten und Binärdaten verschlüsselt werden.
+Über die [Payload-Klasse](https://www.javadoc.io/doc/com.nimbusds/nimbus-jose-jwt/latest/com/nimbusds/jose/Payload.html) können verschiedene Typen, wie `byte[]` oder `String`, verschlüsselt werden.
```java
JWEHeader header = new JWEHeader(JWEAlgorithm.RSA_OAEP_256, EncryptionMethod.A256GCM);
diff --git a/docs/sidebar.js b/docs/sidebar.js
index ec3eb546f..50335e014 100644
--- a/docs/sidebar.js
+++ b/docs/sidebar.js
@@ -73,7 +73,6 @@ module.exports = {
type: 'category',
label: 'Detailinformationen',
items: [
- 'details/encryption',
'details/crypto',
'details/status',
'details/event-log',
--
GitLab