From 322bd95ec1daaa5611000a4bee082c8be078ca29 Mon Sep 17 00:00:00 2001
From: Lilith Wittmann <mail@lilithwittmann.de>
Date: Thu, 22 Apr 2021 18:44:47 +0200
Subject: [PATCH] doc(encryption_keys): split up developer documentation from
key requirements
---
docs/Detailinformationen/Encryption.md | 154 +++++++++---------
.../Encryption_Key_Requirements.md | 118 ++++++++++++++
2 files changed, 198 insertions(+), 74 deletions(-)
create mode 100644 docs/Detailinformationen/Encryption_Key_Requirements.md
diff --git a/docs/Detailinformationen/Encryption.md b/docs/Detailinformationen/Encryption.md
index 3f65c8fa..ee5551a0 100644
--- a/docs/Detailinformationen/Encryption.md
+++ b/docs/Detailinformationen/Encryption.md
@@ -3,122 +3,100 @@
## Einleitung
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 auf dieser Seite sind relevant, wenn man:
-- ein Fachverfahren mit fitconnenct-Anbindung entwickelt oder aufsetzt
-- einen Onlinedienst mit fitconnenct-Anbindung entwickelt oder aufsetzt
-
-Im Folgenden werden Beschrieben:
-- die Grundlegenden Anforderungen an die JSON Web Keys
-
-**TODO(@Lilith) Inhaltsverzeichnis**
+Diese Informationen sind relevant, wenn man:
+- ein **Fachverfahren** mit fitconnenct-Anbindung entwickelt oder aufsetzt
+- einen **Onlinedienst** mit fitconnenct-Anbindung entwickelt oder aufsetzt
### Warum?
-Im Kontext von Anträgen an Behörden werden häufig höchstsensible Daten übermittelt, die im Rahmen der [Vorgaben des BSI für eGovernment-Dienste](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 Teil von fitconenct und kannn nicht ohne diese umgesetzt werden.
+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.
-### Architektur im fitconnect Kontext
-Jedes fitconenct-System verfügt mindestens über einen Endpunkt, von dem Anträge empfangen werden (Fachverfahren/Subscriber-API) und einen oder mehreren Endpunkten, von denen Anträge verschlüsselt versendet werden (in der Regel: Onlinedienst, App, …). In diesem Abschnitt der Dokumentation werden einerseits Regeln und Standards definiert, denen Public-Keys (JSON Web Keys), die von Fachverfahren bereitgestellt werden, entsprechen müssen. Andrerseits wird erklärt, wie diese JSON Web Keys durch Clients verifiziert und danach zur Verschlüsselung der Inhaltsdaten eingesetzt werden sollten.
+## Architektur
+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, …).
-**Dazu relevant:**
-**TODO(@Lilith) auf die anderen Seiten verweisen die die Architektur erklären**
## Vorgaben
### Grundlagen
-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.
-<img src="../../assets/images/encryption/tls-no-tls.png" alt="Ende-zu-Ende-Verschlüsselung Bedeutung" width="400" height="320">
+1. Grundsätzlich muss die fitconnect-Verschlüsselung immer Ende-zu-Ende sein. Das bedeutet vom Endgerät der Nutzer*in bis in 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.
+2.
-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.
-<img src="../../assets/images/encryption/pki-check.png" alt="PKI-um Man-in-the-Middle zu verhindern" width="400" height="320">
-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.
+### Anforderungen an die JSON Web Keys
+Unter Berücksichtigung der Vorgaben des BSI in der Richtlinie [TR-02102-1](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.html) wurden die [Liste der möglichen Algorithmen](https://www.iana.org/assignments/jose/jose.xhtml#web-signature-encryption-algorithms) eingeschränkt.
-3. Der Json Web Key muss immer die komplette Zertifikatskette bis zur Root-CA enthalten, um clientseitig korrekt validierbar zu sein.
+- Asymmetrisches Verschlüsselungsverfahren, um den "Content Encryption Key" zu verschlüsseln ("alg"): "RSA-OAEP-256"
+- Symmetrisches Verschlüsselungsverfahren zur Verschlüsselung des Payloads ("enc"): "A128GCM" oder "A256GCM"
-### Anforderungen an die JSON Web Keys und JSON Web Encryption
-Beim Einsatz von Verschlüsselung ist es elementar, das die dabei verwendeten kryptographischen Methoden sicher sind. Unter Berücksichtigung der Vorgaben des BSI in der Richtlinie [TR-02102-1](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.html) wurden die [Liste der möglichen Algorithmen](https://www.iana.org/assignments/jose/jose.xhtml#web-signature-encryption-algorithms) auf die, welche sich am Besten zur Implementierung von fitconnect eignen, eingeschränkt. Diese Auswahl erfolgte insbesondere auf Basis des Kriteriums, welche Algorithmen am häufigsten in Libraries verwendet werden und deswegen einfach zu implementieren sein sollten.
-#### Algorithmen zur Erstellung des JSON Web Keys
-Das dem JSON Web Key zugrundelgiegende X.509-Zertifikat muss auf Basis der folgenden Standards erstellt werden:
+## Architektur
-- Hashingalgorithmus: SHA-512
-- Keylänge: 4096
-- Signaturstandard: RSASSA-PSS
+
-##### Signatur des JSON Web Keys durch Verwaltung-PKI
+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.
-Das X.509 Zertifikat muss durch eine Verwaltungs-PKI signiert werden. Dabei sind die Regeln und Standarts 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.
-**Insbesondere:**
+## Konzept
-- Muss sie Teil der Verwaltung-PKI sein, sprich das [Wurzelzertifikat muss vom BSI stammen](https://www.bsi.bund.de/DE/Themen/Oeffentliche-Verwaltung/Moderner-Staat/Verwaltungs-PKI/Wurzelzertifizierungsstelle/wurzelzertifizierungsstelle_node.html;jsessionid=E33702EEFB110FA230DDA266C9512436.internet471)
-- Muss sie über CRL Distribution Points (siehe 8.5 BSI [TR-02103](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02103/BSI-TR-02103.pdf?__blob=publicationFile&v=4) ) verfügen
-- Muss ein OCSP-Endpunkt (siehe 8.5.5 BSI [TR-02103](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02103/BSI-TR-02103.pdf?__blob=publicationFile&v=4)) mit signierten Antworten nach [RFC 6125](https://tools.ietf.org/html/rfc6125) bereitstellen
+### Aufbau der Ãœbertragung
-##### Zusammensetzung des JSON Web Keys
+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.
-Das generierte X.509 Zertifikat, alle Intermediate Zertifikate und das Root Zertifikat müssen zu PEM konvertiert, base64 encoded und mit denen im Standard vorgesehenen Metadaten versehen werden. Der dabei entstandene JSON Web Key sollte über die folgenden Attribute (nach [RFC 7517](https://tools.ietf.org/html/rfc7517#section-4)) verfügen:
+### Destination
-| Field | Content |
-| ----------- | -------------------------------------- |
-| kty | RSA |
-| key_ops | [wrapKey] |
-| alg | PS512 |
-| x5c | die Zertifikatskette (base64 encoded) |
-| x5t | der Zertifikatsfingerprint |
+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 bedeutet, der JSON Web Key sollte diesem Format entsprechen:
+Das Application Schema wurde in der Beta 7 um die Angabe "encoding" erweitert. Es kann drei verschiedene Werte annehmen: "plain", "base64" und "jwe".
-```json
+### encoding: plain
-{
- "kty": "RSA",
- "key_ops": ["wrapKey"],
- "alg": "PS512"
- "x5t": "……(Fingerprint)……",
- "x5c": [
- "……(base64 encoded root cert)……",
- "……(base64 encoded intermediate cert)……",
- "……(base64 encoded cert)……"
- ],
-}
-```
+"plain" ist der Defaultwert und entspricht der Arbeitsweise bis Beta 6. Hierbei werden die Fachdaten und Anlagen uncodierter Form übermittelt.
-#### Algorithmen zur Verschlüsselung des Inhalts mit JSON Web Encryption
+#### Beispiel
-Der Content im verschlüsselten JSON Web encryption Objekt muss mit den folgenden Methoden verschlüsselt werden:
-- Asymmetrisches Verschlüsselungsverfahren, um den "Content Encryption Key" zu verschlüsseln ("alg"): "RSA-OAEP-256"
-- Symmetrisches Verschlüsselungsverfahren zur Verschlüsselung des Payloads ("enc"): "A128GCM" oder "A256GCM"
+```json
+{"test":true,"hello":"world"}
+```
-## Konzept
+### encoding: base64
-### Erstellung eines fitconnect-kompatiblen JSON Web Keys
-Im folgenden eine beispielhafte Schritt-für-Schritt-Anleitung um einen JWK zu generieren:
-1. Lokale Generierung eines X.509 zugrundelgienden 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**
+"base64" legt fest, dass die Daten base64-codiert übertragen werden.
+#### 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
-### Destination
+Beim Encoding "jwe" werden die Fachdaten und Anlagen mit der JSON Web Encryption (RFC 7516) verschlüsselt.
-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. Hierzu enthält die Destination eine Liste von Schemas, aus denen der Absender eines auswählen muss. Die Fachdaten und Anlagen werden immer mit der JSON Web Encryption (RFC 7516) verschlüsselt.
+#### Beispiel
+
+```
+eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.nlXGAufYH36IABDy0En0LXEhGfC2
+0IZSSchs27ADalHpRoTZKfXhc7hcMk8Y9V8yTP0jYbmrq6NtEg-QS2O5TQFD9Hluhpb631PBgKjPXHYX
+1Y6iUcR1sXxSUPjePi8F8PcZUZuUJLnhz6myyc9scdAq9BXG2cDJVgkfLI8eZdrqnrY24Hh32_7d5OKL
+FSpSDrBlqfyQuY8Wbs2h8Wy4Z4hwT1aWDO7b-SqJA181hUbNcF_rR4Mze3Fdtu-3uOIQYgLBBRmN1ZHD
+Lk0EKNCI4B8MyDKLGPoM0ZomV5lVwVWjAMRI4CgQkIQ9rnm-Adof-GbegQL3yJSoNIWRWgzCnZBYZ638
+QgPllCMVW3WvEVvsgj0Hj16PbofqXTQ5S73LINfP6FZawfC0yMrYjSV_N2L0Lkp2KI3BkJcy-PcFhBnh
+wu2IsJGAlyDRCnXdVqig8m5yLHuSMQTpLW69LzPEskfsjhnNDR-CEBZpicjMfc-4CL6U7E7YoGc_99Dz
+E5U5._JfqyKH23GiKsnDW.ZtMMjZ3GgcgHss8qbFRhrjl4L0kAfbco-oXICkk.VBHJ00FyDTYjOA_OYf
+iz5g
+```
## Application Subscriber API
-Über die Application Subscriber API werden die Destinations verwaltet, an die die Anträge gesenet werden. Eine Destination enthält eine Liste von Schemas, welche Formate der Empfänger akzeptiert. Außerdem enthält sie immer mindestens einen Json Web Key zur Verschlüsselung der Daten.
+Über die Application Subscriber API werden die Destinations verwaltet, an die die Anträge gesenet werden. Eine Destination enthält eine Liste von Schemas, welche Formate der Empfänger akzeptiert. Um sicherzustellen, dass immer eine verschlüsselte Übertragung stattfindet muss jedes dieser Schemas bei der Eigenschaft "encoding" den Wert "jwe" enthalten. Sofern mindestens ein verschlüsseltes Schema angeboten wird, muss auch mindestens ein öffentlicher Schlüssel angeboten werden.
-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.
+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 udn 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.
@@ -210,6 +188,34 @@ TGtY.VGOCnGM9LEZP5mUO.LQeKj4SKqsUNsBp4ZRN_56QbS8MQ01YTzRVFStk.Z0YMEua9kvCV7LkeJH
kprA
````
+### encoding: plain
+
+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
+Content-Type: application/json
+Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjM1ZTM2Nzk2LTM1NDAtNDUwMy1iYT...
+
+{"test":true,"hello":"world"}
+```
+
+### encoding: base64
+
+Bei der Übertragung der Fachdaten und Anlagen wird der Content-Type "text/plain" für Base64 verwendet.
+
+#### Beispiel
+
+```
+PUT /delivery-service-beta7/sender/destinations/e1009dea-d97e-4104-b389-bf653d8bd30e/applications//data HTTP/1.1
+Content-Type: text/plain
+Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjM1ZTM2Nzk2LTM1NDAtNDUwMy1iYT...
+
+eyJ0ZXN0Ijp0cnVlLCJoZWxsbyI6IndvcmxkIn0K
+```
+
### encoding: jwe
Bei der Ãœbertragung der Fachdaten und Anlagen wird der Content-Type "application/jose" (Achtung: jose, nicht json) verwendet.
diff --git a/docs/Detailinformationen/Encryption_Key_Requirements.md b/docs/Detailinformationen/Encryption_Key_Requirements.md
new file mode 100644
index 00000000..3887fd35
--- /dev/null
+++ b/docs/Detailinformationen/Encryption_Key_Requirements.md
@@ -0,0 +1,118 @@
+# Anforderungen an das kryptographischen Material
+
+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.
+
+Außerdem bietet fitconnect digital signierte Eingangsbestätigungen für Anträge. Die ausgestellten Signaturen werden **TODO** und die dazugehörigen Public Keys mit Hilfe von [JSON Web Keys (JWK)](https://tools.ietf.org/html/rfc7517) implementiert. **TODO(@Lilith): ergänzen**
+
+#### Allgemeine Anforderungen an die JSON Web Keys und JSON Web Encryption
+
+Beim Einsatz von Verschlüsselung ist es elementar, das die dabei verwendeten kryptographischen Methoden sicher sind. Unter Berücksichtigung der Vorgaben des BSI in der Richtlinie [TR-02102-1](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.html) wurde die [Liste der möglichen Algorithmen](https://www.iana.org/assignments/jose/jose.xhtml#web-signature-encryption-algorithms) auf die, welche sich am Besten zur Implementierung von fitconnect eignen, eingeschränkt. Diese Auswahl erfolgte insbesondere auf Basis des Kriteriums, welche Algorithmen am häufigsten in Libraries verwendet werden und deswegen einfach zu implementieren sein sollten.
+
+### Regeln zur Erstellung des JSON Web Keys zur Verschlüsselung von Antragsdaten und der Signatur von Eingangsbestätigungen
+
+Dem JSON Web Key zur **Verschlüsselung von Antragsdaten** muss ein für die Empfangsbehörde des Antrags signiertes X.509 Zertifikat zugrundeliegen. Der JSON Web Key, der zur **Signaturprüfung von digitalen Eingangsbestätigungen verwendet wird,** muss ein für die Behörde, die den Antrag im fitconnect-System zwischenspeichert oder empfängt, signiertes X.509 Zertifikat zugrundeliegen.
+
+Die den JSON Web Keys zugrundeliegenden X.509-Zertifikate müssen auf Basis der folgenden Standards erstellt werden:
+
+| Feld | Inhalt | **Erläuterung** |
+| ------------------ | ---------- | ------------------------------------------------------------ |
+| Hashingalgorithmus | SHA-512 | Gibt den Algorithmus der zur digitalen Signatur des Zertifikats verwendet werden muss an. Dieser muss im Fall von fitconnect immer SHA-512 sein. (vgl. [BSI TR-02102-1 Tabelle 4.1](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.html)) |
+| Keylänge | 4096 | Länge des zugrundeliegenden RSA-Keys. Diese entspricht der Empfehlung des BSIs für ab dem Jahr 2023. (vgl. [BSI TR-02102-1 Tabelle 3.1](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.html)) |
+| Signaturstandard | RSASSA-PSS | Entspricht dem Standard beschrieben in [RFC 4056](https://tools.ietf.org/html/rfc4056) und vom BSI empfohlen in [BSI TR-02102-1 Abschnitt 5.4.1.](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.html) |
+
+### Signatur der X.509 Zertifikate durch die Verwaltung-PKI
+
+Die X.509 Zertifikate müssen durch eine Verwaltungs-PKI signiert werden. Als Verwaltungs-PKIs werden alle Zertifizierungsstellen, die ein Wurzelzertifikat des BSI verwenden und sich an die vom [BSI definierten Regelungen für Wurzelzertifizierungsstellen](https://www.bsi.bund.de/DE/Themen/Oeffentliche-Verwaltung/Moderner-Staat/Verwaltungs-PKI/Dokumente/dokumente_node.html) halten, bezeichnet.
+
+Bei der Erstellung und Signierung der Zertifikate sind alle Regeln und Standarts 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.
+
+**Für die Verwendbarkeit in fitconnect sind insbesondere die folgenden Anforderungen an die Verwaltungs.-PKI besonders wichtig:**
+
+- Sie müssen eine Verwaltungs-PKI sein, sprich das [Wurzelzertifikat muss vom BSI stammen.](https://www.bsi.bund.de/DE/Themen/Oeffentliche-Verwaltung/Moderner-Staat/Verwaltungs-PKI/Wurzelzertifizierungsstelle/wurzelzertifizierungsstelle_node.html;jsessionid=E33702EEFB110FA230DDA266C9512436.internet471)
+- Sie müssen über CRL Distribution Points (siehe 8.5 BSI [TR-02103](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02103/BSI-TR-02103.pdf?__blob=publicationFile&v=4) ) verfügen.
+- Sie müssen einen OCSP-Endpunkt (siehe 8.5.5 BSI [TR-02103](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02103/BSI-TR-02103.pdf?__blob=publicationFile&v=4)) mit signierten Antworten nach [RFC 6125](https://tools.ietf.org/html/rfc6125) bereitstellen.
+
+### Zusammensetzung des JSON Web Keys zur Verschlüsselung
+
+Das generierte X.509 Zertifikat, alle Intermediate Zertifikate und das Root Zertifikat müssen zu PEM konvertiert, base64 enkodiert und mit denen im JSON Web Key Standard vorgesehenen Metadaten versehen werden. Der dabei entstandene JSON Web Key muss über die folgenden Attribute (nach [RFC 7517](https://tools.ietf.org/html/rfc7517#section-4)) verfügen.
+
+| Field | Inhalt | **Erläuterung** |
+| ------- | ------------------------------------- | ------------------------------------------------------------ |
+| kty | RSA | Gibt den Keytype nach [RFC 7517 Abschnitt 4](https://tools.ietf.org/html/rfc7517#section-4) an. |
+| key_ops | [wrapKey] | Gibt die Funktion des Keys (Verschlüsselung des Verschlüsellungskeys) an. (nach [RFC 7517 Abschnitt 4.3](https://tools.ietf.org/html/rfc7517#4.3)) |
+| alg | PS512 | Gibt den Algorithmus der zur digitalen Signatur des Zertifikats verwendet werden muss an. Dieser muss im Fall von fitconnect immer PS512 sein. (vgl. [BSI TR-02102-1 Tabelle 4.1](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.html)) |
+| x5c | die Zertifikatskette (base64 encoded) | Entspricht der Zertifikatskette vom Wurzelzertifikat bis zum Zertifikat selbst. ([Abschnitt 4.7 RFC 7518](https://tools.ietf.org/html/rfc7517#section-4.7)) |
+| x5t | der Zertifikatsfingerprint | Der Fingerprint des Zertifikats selbst. ([Abschnitt 4.8 RFC 7518](https://tools.ietf.org/html/rfc7517#section-4.8)) |
+| kid | eindeutige ID des Keys | Diese ID wird verwendet, um sie bei der Verschlüsselung des asymmetrischen Keys zur Verschlüsselung des Symetrischen Keys zur Inhaltsverschlüsselung zu referenzieren und somit darzustellen, welcher Key zur Entschlüsselung benötigt wird (siehe [RFC 7516 4.1.6](https://tools.ietf.org/html/rfc7516#section-4.1.6)) |
+
+Das bedeutet, der JSON Web Key zur Verschlüsselung muss diesem Format entsprechen:
+
+```json
+{
+ "kty": "RSA",
+ "key_ops": ["wrapKey"],
+ "alg": "PS512",
+ "kid": "……(Key ID)……",
+ "x5t": "……(Fingerprint)……",
+ "x5c": [
+ "……(base64 encoded root cert)……",
+ "……(base64 encoded intermediate cert)……",
+ "……(base64 encoded cert)……"
+ ],
+}
+```
+
+### Zusammensetzung des JSON Web Keys zur Signaturprüfung von Eingangsbestätigungen
+
+Das generierte X.509 Zertifikat, alle Intermediate Zertifikate und das Root Zertifikat müssen zu PEM konvertiert, base64 enkodiert und mit den im JSON Web Key Standard vorgesehenen Metadaten versehen werden. Der dabei entstandene JSON Web Key muss über die folgenden Attribute (nach [RFC 7517](https://tools.ietf.org/html/rfc7517#section-4)) verfügen.
+
+| Field | Inhalt | **Erläuterung** |
+| ------- | ------------------------------------- | ------------------------------------------------------------ |
+| kty | RSA | Gibt den Keytype nach [RFC 7517 Abschnitt 4](https://tools.ietf.org/html/rfc7517#section-4) an. |
+| key_ops | [verify] | Gibt die Funktion des Keys (Verschlüsselung des Verschlüsellungskeys) an. (nach [RFC 7517 Abschnitt 4.3](https://tools.ietf.org/html/rfc7517#4.3)) |
+| alg | PS512 | Gibt den Algorithmus der zur digitalen Signatur des Zertifikats verwendet werden muss an. Dieser muss im Fall von fitconnect immer PS512 sein. (vgl. [BSI TR-02102-1 Tabelle 4.1](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.html)) |
+| x5c | die Zertifikatskette (base64 encoded) | Entspricht der Zertifikatskette vom Wurzelzertifikat bis zum Zertifikat selbst. ([Abschnitt 4.7 RFC 7518](https://tools.ietf.org/html/rfc7517#section-4.7)) |
+| x5t | der Zertifikatsfingerprint | Der Fingerprint des Zertifikats selbst. ([Abschnitt 4.8 RFC 7518](https://tools.ietf.org/html/rfc7517#section-4.8)) |
+| kid | eindeutige ID des Keys | Diese ID wird verwendet, um zur Prüfung der Signatur den richtigen Key auswählen zu können. (siehe [RFC 7516 4.1.6](https://tools.ietf.org/html/rfc7516#section-4.1.6)) |
+
+Das bedeutet, der JSON Web Key zur Prüfung von digitalen Signaturen muss dem folgenden Format entsprechen:
+
+```json
+{
+ "kty": "RSA",
+ "key_ops": ["verify"],
+ "alg": "PS512"
+ "kid": "……(Key ID)……",
+ "x5t": "……(Fingerprint)……",
+ "x5c": [
+ "……(base64 encoded root cert)……",
+ "……(base64 encoded intermediate cert)……",
+ "……(base64 encoded cert)……"
+ ],
+}
+```
+
+**TODO(Lilith): hier etwas über key austausch einfügen (vermutlich müssen wir keys, die zur Verifizierung dienen, weiterhin ausliefern, während Verschlüsselungskeys ausgetauscht werden)**
+
+## Algorithmen zur Verschlüsselung des Antragsinhalts mit JSON Web Encryption
+
+Zur Verschlüsselung des eigentlichen Antragsinhalts wird ein Symmetrischer Schlüssel verwendet. Dieser Symmetrische Schlüssel wird danach mit dem JSON Web Key, der vom bereitgestellt wird und die Verwendungsart "wrapKey" haben muss, asymmetrisch verschlüsselt.
+
+### Verschlüsselungsverfahren
+
+Der Content im verschlüsselten JSON Web Encryption Objekt muss mit den folgenden Methoden verschlüsselt werden:
+
+- Asymmetrisches Verschlüsselungsverfahren, um den "Content Encryption Key" zu verschlüsseln ("alg"): "RSA-OAEP-256"
+- Symmetrisches Verschlüsselungsverfahren zur Verschlüsselung des Payloads ("enc"): "A256GCM"
+
+#### JSON Web Encryption Header (JOSE)
+
+Im Header des JSON Web Encryption Objektes müssen einige Metadaten über die verwendeten Verschlüsselungen sowie das dazu verwendete Keymaterial übergeben werden. Diese Headerinformationen werden in der Umsetzung als Base64URL Safe encodiert.
+
+| Field | Inhalt | **Erläuterung** |
+| ----- | ------------------ | ------------------------------------------------------------ |
+| alg | RSA-OAEP-256 | Asymmetrisches Verschlüsselungsverfahren, um den „Content Encryption Key“ (CEK) zu verschlüsseln, mit dem der Payload über das in „enc“ Verfahren symmetrisch verschlüsselt wurde. Hierfür wird der im Header kid referenzierte öffentliche Schlüssel genutzt. Der JSOE Header wird in RFC 7516 definiert und der Bezeichner des Algorithmus in [RFC 7518 Abschnitt 4.1](https://tools.ietf.org/html/rfc7518#4.1). |
+| enc | A256GCM | Symmetrisches Verschlüsselungsverfahren zur Verschlüsselung des Payloads. Nach RFC 7518 |
+| zip | DEF | Der Komprimieriungsalgorithmus für die Inhaltsdaten nach [RFC 7516 Abschnit 4.1.3](https://tools.ietf.org/html/rfc7516#section-4.1.3) |
+| kid | ID des Public Keys | Die ID des JSON Web Keys mit dem Attribute "wrapKey", aus dem von der Subscriber-API bereitgestellten Keysets, der zur Verschlüsselung des unter enc verschlüsselten symmetrischen Keys verwendet wurde. |
+
--
GitLab