fitconnect verwendet zur Übertragung von Antragsdaten und Metadaten mit direktem Bezug zu Anträgen, abgesehen von den für die Übermittlung zwingend notwendigen Daten (z.B. Destination-ID), Ende-zu-Ende-Verschlüsselung. Diese ist auf Basis der Standards [JSON Web Encryption (JWE)](https://tools.ietf.org/html/rfc7516) unter Zuhilfenahme von [JSON Web Keys (JWK)](https://tools.ietf.org/html/rfc7517) umgesetzt.
Diese Informationen sind relevant, wenn man:
Die Informationen auf dieser Seite sind relevant, wenn man:
- ein **Fachverfahren** mit fitconnenct-Anbindung entwickelt oder aufsetzt
- einen **Onlinedienst** mit fitconnenct-Anbindung entwickelt oder aufsetzt
### Warum?
### Warum ist Ende-zu-Ende-Verschlüsselung so 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 fitconnect ist die Zielsetzung einen möglichst einfachen, sicheren und klar definierten Standard zu etablieren. Deshalb ist richtig implementierte Krypotgraphie ein fundamentaler Standard von fitconenct.
Bei fitconnect ist die Zielsetzung einen möglichst einfachen, sicheren und klar definierten Standard zu etablieren. Deshalb ist richtig implementierte Kryptografie ein fundamentaler Teil von fitconenct und kann nicht ohne diese umgesetzt werden.
## Grundlagen
## Grundlagen zur sicheren Implementierung von fitconnect
1. Grundsätzlich muss die fitconnect-Verschlüsselung immer Ende-zu-Ende sein. Das bedeutet vom Endgerät der Nutzer*in bis in das Fachverfahren bzw. die Empfangsbehörde des Antrages.
Es ist nicht vorgesehen, das Antragsdaten unverschlüsselt von einem Endgerät einer Nutzer*in an ein Backend weitergeleitet werden, um dann von dort verschlüsselt per fitconnect an die Empfangsbehörde gesendet zu werden. Antragsdaten dürfen nicht in einem Backend gespeichert werden. Sollte eine längerfristige Speicherung der Antragsdaten benötigt werden, so muss diese immer clientseitig (z.B. in der IndexDB des Browsers, per Download, …) erfolgen.
### Ende-zu-Ende-Verschlüsselung
2. Die für die Verschlüsselung verwendeten JSON Web Keys müssen signiert werden, über eine Verwaltungs-PKI verifizierbar sein und auch durch den verschlüsselnden Client vollständig mit Hilfe der Verwaltungs-PKI verfiziert werden.
<imgsrc="../../assets/images/encryption/pki-check.png"alt="PKI-um Man-in-the-Middle zu verhindern"width="400"height="320">
Fitconnect basiert auf dem Ansatz von Ende-zu-Ende-Verschlüsselung. Das bedeutet das Daten immer vom Endgerät der Nutzer*in bis in die Zielbehörde bzw. das Fachverfahren asymmetrisch verschlüsselt sein müssen.
Es ist nicht vorgesehen nicht vertrauenswürdige Schlüssel für die Verschlüsselung von Anträgen zu verwenden. Das soll Angriffe wie Man-in-the-middle-Attacken erschweren.
3. Der Json Web Key muss immer die komplette Zertifikatskette bis zur Root-CA enthalten, um clientseitig korrekt validierbar zu sein.
Es ist nicht erlaubt, das Daten unverschlüsselt oder nur per TLS gesichert an ein Backend zu übermitteln und erst dort die für fitconnect spezifizierte Verschlüsselung anzuwenden. Sollte eine längerfristige Speicherung der Antragsdaten benötigt werden, so muss diese immer clientseitig (z.B. in der IndexDB des Browsers, per Download, …) erfolgen.
## Architektur
### Kryptografisches Material muss immer von einer Verwaltungs-PKI signiert sein
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) eines Antrags verbindet.
Jeder verwendete Public Key (idR. in Form eines JSON Web Keys) muss von einer 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.
Jedes fitconenct-System verfügt über einen Endpunkt, an den Anträge gesendet werden (Fachverfahren/Subscriber-API) und einen oder mehrere Endpunkte von denen Anträge verschlüsselt versendet werden (in der Regel: Onlinedienst, App, …).
### Kryptografisches Material muss vor der Verwendung immer geprüft werden
Die für die Verschlüsselung verwendeten JSON Web Keys müssen signiert werden, über eine Verwaltungs-PKI verifizierbar sein und auch bei der Verwendung durch den verschlüsselnden Client vollständig mit Hilfe der Verwaltungs-PKI verfiziert werden.
<imgsrc="../../assets/images/encryption/pki-check.png"alt="PKI-um Man-in-the-Middle zu verhindern"width="400"height="320">
## Konzept
Es wird nicht unterstützt nicht vertrauenswürdige Schlüssel für die Verschlüsselung von Anträgen zu verwenden. Das soll Angriffe wie Man-in-the-middle-Attacken erschweren.
### Aufbau der Übertragung
## Architektur
Eine Übertragung über FIT-Connect besteht aus einem Metadatensatz, optionalen Fachdaten und beliebig vielen (0-∞) Dokumenten (Anlagen). Da die Metadaten transportrelevante Informationen enthalten, werden diese immer unverschlüsselt übertragen. Bei aktivierter Verschlüsselung werden nur die Fachdaten und Anlagen verschlüsselt.
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) eines Antrags verbindet.
### Destination
Jedes fitconenct-System verfügt über einen Endpunkt, an den Anträge gesendet werden (Fachverfahren/Destination) und einen oder mehrere Endpunkte von denen Anträge verschlüsselt versendet werden (in der Regel: Onlinedienst, App, …).
Ein Antrag wird an eine Destination (Zielort) geschickt. Diese Destination legt der Empfänger über die "Application Subscriber API" an. Der Absender muss die ID der Destination kennen und kann dann Anträge über die "Application Sender API" an diese ID senden. Der Empfänger legt in der Destination fest, ob die Übertragung optional oder verpflichtend verschlüsselt werden muss. Hierzu enthält die Destination eine Liste von Schemas, aus denen der Absender eines auswählen muss. Diese Schemas enthalten unter anderem eine Angabe zum Encoding, über das eine Verschüsselung vorgegeben wird.
## Application Schema
Das Application Schema wurde in der Beta 7 um die Angabe "encoding" erweitert. Es kann drei verschiedene Werte annehmen: "plain", "base64" und "jwe".
## Bereitstellung eines Destination-Endpunktes
### encoding: plain
### Erstellung eines fitconnect-kompatiblen JSON Web Keys
"plain" ist der Defaultwert und entspricht der Arbeitsweise bis Beta 6. Hierbei werden die Fachdaten und Anlagen uncodierter Form übermittelt.
JSON Web Keys sind das Austauschformat in dem kryptografisches Material in fitconnect 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 zischen Servern/Computern sollte vermieden werden und wenn dann nur verschlüsselt erfolgen.
#### Beispiel
```json
{"test":true,"hello":"world"}
```
### encoding: base64
Im folgenden eine beispielhafte Schritt-für-Schritt-Anleitung um einen JSON-Web-Key zu generieren:
1. Lokale Generierung eines X.509 zugrundelgienden RSA-Keys. `openssl genrsa -out fachverfahren1.meineverwaltung.de.key 4096`
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**
"base64" legt fest, dass die Daten base64-codiert übertragen werden.
## Implementierung eines Onlinedienstes
#### Beispiel
### Aufbau der Übertragung
```
eyJ0ZXN0Ijp0cnVlLCJoZWxsbyI6IndvcmxkIn0K
```
Eine Übertragung über FIT-Connect besteht aus einem Metadatensatz, optionalen Fachdaten und beliebig vielen (0-∞) Dokumenten (Anlagen). Da die Metadaten transportrelevante Informationen enthalten, werden diese immer unverschlüsselt übertragen. Bei aktivierter Verschlüsselung werden nur die Fachdaten und Anlagen verschlüsselt.
### encoding: jwe
## Application Schema
Beim Encoding "jwe" werden die Fachdaten und Anlagen mit der JSON Web Encryption (RFC 7516) verschlüsselt.
Die Metadaten, Fachdaten und Anlagen werden immer mit dem Encoding "jwe" (JSON Web Encryption RFC 7516) verschlüsselt.
#### Beispiel
...
...
@@ -135,8 +127,6 @@ Der Absender muss die Destination-ID vorliegen haben und erfagt über die Applic
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.
## Übertragungsvarianten
Das gewählte Schema wird in den Metadaten des Antrags (Application Metadata) eingetragen und legt die Art der Übertragung fest. Im folgenden Beispiel wird ein verschlüsselter Fachdatensatz im JSON-Format und ein PDF-Dokument übertragen.
**Hinweis:** Das Encoding der Anlagen ist an das Encoding der Fachdaten gebunden. Alle Anlagen müssen mit dem gleichen Encoding wie die Fachdaten übertragen werden. Hier im Beispiel also verschlüsselt.
Bei der Übertragung der Fachdaten muss der passende Content-Type gesetzt werden, also "application/json" bzw. "application/xml". Alternativ ist "text/json" und "text/xml" auch zulässig. Bei der Übertragung der Anlage ist der in den Metadaten angegebene Datentyp (z.B. "application/pdf") zu verwenden.
#### Beispiel
```
PUT /delivery-service-beta7/sender/destinations/e1009dea-d97e-4104-b389-bf653d8bd30e/applications//data HTTP/1.1
