Merge branch 'gettingStarted_encryption' into 'main'

Getting started encryption

See merge request !30

docs/getting-started/encryption.mdx

-# 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.
+# Verschlüsselte Übertragung von Antragsdaten
 
-## 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.
+Ziel von FIT-Connect ist es, ein möglichst einfaches, sicheres und klar definiertes Vorgehen zur Einreichung von Antragsdaten zu etablieren.
+Deshalb erfolgt eine Übertragung von Antragsdaten 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.
+## Warum ist Ende-zu-Ende-Verschlüsselung wichtig?
+Im Kontext von Anträgen an Behörden werden häufig höchstsensible personenbezogene Daten übermittelt.
+Auf grund ihres hohen Schutzbedarfs dürfen solche Daten nach den [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.
 
 <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.
+FIT-Connect verwendet zur Absicherung der Übertragung von Antragsdaten und Antragsmetadaten eine auf asymmetrischer Kryptographie basierenden Ende-zu-Ende-Verschlüsselung.
+Abgesehen von denen für die Übermittlung zwingend notwendigen Daten können so nur die Zielbehörde bzw. das Ziel-Fachverfahren die Antragsdaten und Antragsmetadaten entschlüsseln und lesen.
+Bei der Umsetzung einer Ende-zu-Ende-Verschlüsselung zwischen dem Endgerät der Nutzer:in und der zuständigen Fachbehörde verlassen sämtliche Inhaltsdaten das Endgerät der Nutzer:in immer verschlüsselt.
+
+## Grundlagen zur eingesetzten Verschlüsselung
+
+Die Ende-zu-Ende-Verschlüsselung von FIT-Connect wird mithilfe von hybrider Verschlüsselung auf Basis von [JSON Web Encryption (JWE)](https://datatracker.ietf.org/doc/html/rfc7516) umgesetzt.
+Dieser Ansatz kombiniert die Vorteile von symmetrischer und asymmetrischer Verschlüsselung.
+Im Folgenden sollen die Grundlagen kurz erläutert werden.
+
+### Symmetrische Verschlüsselung
+
+Eine Verschlüsselung wird als symmetrisch bezeichnet, wenn für für Ver- und Entschlüsselung derselbe Schlüssel verwendet wird.
+Das ist gleichzeitig auch der größte Nachteil der symmetrischen Verschlüsselung.
+Für eine sichere Kommunikation muss immer zuerst allen beteiligten Parteien der geheime Verschlüsselungsschlüssel übermittelt werden.
+Man spricht hier auch von einem gemeinsamen Geheimnis (*shared secret*).
+Kommt dieses abhanden oder wird beim Austausch abgefangen, ist die Sicherheit der Kommunikation nicht mehr gewährleistet.
+Jeder, der in Besitz dieses Schlüssels gelangt, ist im Stande, alle mit ihm verschlüsselten Nachrichten zu entschlüsseln und damit lesen zu können.
+Dem gegenüber steht der große Vorteil, dass es mit symmetrischer Verschlüsselung schnell und effizient möglich ist, auch große Datenmengen zu verschlüsseln.
+
+### Asymmetrische Verschlüsselung
+
+Eine Verschlüsselung wird als asymmetrisch bezeichnet, wenn es für Ver- und Entschlüsselung im Gegensatz zur symmetrischer Verschlüsselung jeweils einen eigenen Schlüssel gibt.
+Die beiden Schlüssel bilden zusammen ein Schlüsselpaar, bestehend aus einem öffentlichen Schlüssel (*public key*) und einem geheimzuhaltenden privaten Schlüssel (*private key*, auch *secret key*).
+Der große Vorteil dieses Verfahrens besteht darin, dass für eine sichere Kommunikation den sendenen Parteien nur der öffentliche Schlüssel ausgehändigt werden muss.
+Lediglich die zum öffentlichen Schlüssel passenden privaten Schlüssel, mit denen empfangende Nachrichten wieder entschlüsselt werden können, müssen die Nachrichten-Empfänger geheim halten.
+Der öffentliche Schlüssel baut bildlich gesprochen einen Schutzcontainer um die Nachricht auf, die nur der zugehörige Empfänger öffnen kann, wie z. B. bei einem Briefkasten, der auch nur vom Besitzer des passenden Briefkastenschlüssels geöffnet werden kann.
+
+<img src={useBaseUrl('/images/encryption/Briefkasten.png')} alt="Beziehung öffentlicher und privater Schlüssel" width="600" />
+
+Im Vergleich zur symmetrischen Verschlüsselung sind die Schlüssel hier jedoch um ein vielfaches länger und die Ver- und Entschlüsselung von Nachrichten erfordert mehr Rechenleistung.
+Aus diesem Grund werden die beiden Verfahren bei der Ende-zu-Ende-Verschlüsselung von FIT-Connect kombiniert (sog. *hybride Verschlüsselung*).
 
-### 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.
+### Hybride Verschlüsselung
 
-### 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.
+Kombiniert man die Vorteile von symmetrischer und asymmetrischer Verschlüsselung in einem gemeinsamen Verfahren, spricht man von einem hybriden Verschlüsselungsverfahren.
+Mithilfe von asymmetrischer Verschlüsselung, d. h. dem öffentlichen Schlüssel des Empfängers, verschlüsselt man dabei den symmetrischen Verschlüsselungsschlüssel und kann diesen verschlüsselten Schlüssel dann auch auf einem ungesicherten Kanal übertragen.
+Der symmetrische Verschlüsselungsschlüssel kann jetzt in Folge für die eigentliche Inhaltsverschlüsselung genutzt werden, welche dank symmetrischer Verfahren schnell und effizient verschlüsseln kann.
+
+## Sichere Implementierung der Ende-zu-Ende-Verschlüsselung mit FIT-Connect
+Die folgenden Abschnitte geben wichtige grundlegende Hinweise zur sicheren Implementierung der Ende-zu-Ende-Verschlüsselung mit FIT-Connect. Konkrete Implementierungsbeispiele finden sich darüber hinaus in den Artikeln zur [Verschlüsselung](sending/encrypt.mdx) und [Entschlüsselung](receiving/decrypt.mdx) von Antragsdaten. Vorgaben zu zulässigen kryptographischen Algorithmen und Schlüssellängen finden sich im Artikel [Vorgaben für kryptographische Verfahren](../details/crypto.md).
+
+### Herkunft und Zugehörigkeit von Schlüsseln prüfen
+
+Wird einem Sender der öffentliche Schlüssel vom designierten Empfänger der Nachricht im Vorlauf nicht sicher und idealerweise sogar persönlich übermittelt, muss auf anderem Weg der oder die Eigentümerin eines Schlüssels ermittelt werden.
+Nur so kann man sicher gehen, auch den richtigen Schlüssel zu verwenden.
+
+Für genau diesen Fall wurden digitale Zertifikate entwickelt.
+Digitale Zertifikate sind nichts weiter als öffentliche Schlüssel, angereichert mit beglaubigten Informationen zu seiner Herkunft und dem Eigentümer.
+Diese Beglaubigung von Schlüssel und Metainformationen erfolgt durch eine vertrauenswürdige dritte Person oder Institution - üblicherweise einer so genannten Zertifizierungstelle (CA - Certificate Authority) - mithilfe seiner digitalen, für Dritte prüfbaren Unterschrift.
+
+Ein so ausgestelltes Zertifikat kann dann vom Empfänger wie eine Visitenkarte vor Beginn der verschlüsselten Kommunikation verteilt werden, da es nur öffentliche und auch prüfbare Informationen enthält.
+
+Die für die Verschlüsselung verwendeten öffentlichen Schlüssel lassen sich so vor Verwendung anhand des zugehörigen Zertifikats aus der Verwaltungs-PKI auf Gültigkeit überprüfen.
+Im Artikel [Überprüfen öffentlicher Schlüssel](sending/encrypt.mdx#certificateValidation) werden die zur Prüfung notwendigen Schritte näher erläutert.
+Behörden, die zum Empfang von Anträgen berechtigt sind, können sich, wie im Artikel [Zertifikatsbeantragung](receiving/certificate.mdx) beschrieben, Zertifikate aus der Verwaltungs-PKI ausstellen lassen. Für sendende Systeme ist derzeit keine Zertifikatsbeantragung notwendig.
 
 <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.
+Nicht vertrauenswürdige Schlüssel werden abgelehnt und dürfen nicht für die Verschlüsselung von Anträgen verwendet werden.
+Die Prüfung von Zertifikaten ist zwingend erforderlich, da sonst Angriffe wie [Man-in-the-middle-Attacken](https://de.wikipedia.org/wiki/Man-in-the-Middle-Angriff) möglich sind.
+
+### JSON Web Encryption und JWE Compact Serialization
+
+Die vorangegangen Grundlagen zur Verschlüsselung, hybriden Verfahren und Zertifikaten finden in FIT-Connect in Form von [JSON Web Encryption (JWE)](https://datatracker.ietf.org/doc/html/rfc7516) bei der Verschlüsselung von Antragsdaten (Submissions) Anwendung.
+JWE standardisiert die einheitliche Anwendung von kryptographischen Algorithmen und die Repräsentation der dabei genutzten Datenstrukturen.
+Dazu nutzt FIT-Connect die [JWE Compact Serialization](https://datatracker.ietf.org/doc/html/rfc7516#section-3.1).
+Die Daten innerhalb eines JWE werden möglichst sparsam kodiert und als eine kompakte, URL-sichere Zeichenkette (String) dargestellt.
+Der String besteht dabei aus fünf konkatenierten, durch Punkte (.) voneinander getrennten, BASE64URL kodierten Elementen:
+
+ - `JOSE Header` - beschreibt mit welchen asymmetrischen Verfahren der symmetrische Schlüssel zur Inhaltsverschlüsselung verschlüsselt wurde und mit welchem symmetrischen Verfahren die Inhaltsdaten (Ciphertext) verschlüsselt wurden
+ - `JWE Encrypted Key` - asymmetrisch verschlüsselter, symmetrischer Schlüssel zur Inhaltsverschlüsselung
+ - `JWE initialization vector` - zufällig ausgewürfelter Initialisierungsvektor, der als Input für die symmetrische Verschlüsselung benötigt wird
+ - `JWE Ciphertext` - mit dem symmetrischen Schlüssel zur Inhaltsverschlüsselung verschlüsselte Inhaltsdaten
+ - `JWE Authentication Tag`- bei der Verschlüsselung der Inhaltsdaten zusätzlich ausgegebene Kontrolldaten zur Integritätssicherung
+
+In unserem Anwendungsfall werden die benötigten öffentlichen Schlüssel der Empfänger mit ihren herkunftsbestätigenden Zertifikaten im System als [JSON Web Key (JWK)](https://tools.ietf.org/html/rfc7517) hinterlegt und können auf Anfrage über die API von sendenden Clients abgerufen werden.
+Wie dieser JWK-Abruf im Detail erfolgt, wie Sie die im JWK enthaltenen Zertifikate prüfen können und wie dann mit Hilfe von JWE Antragsdaten verschlüsselt werden, wird im Artikel [Verschlüsseln](sending/encrypt.mdx) beschrieben.
+Die Entschlüsselung von Antragsdaten wird im Artikel [Entschlüsseln](receiving/decrypt.mdx) beschrieben.

docs/getting-started/sending/encrypt.mdx

@@ -45,8 +45,7 @@ Die so verschlüsselten Daten können ausschließlich von diesem Zustellpunkt ge
 
 Bevor wir mit der Verschlüsselung loslegen können müssen wir den eben abgerufenen JWK noch auf Gültigkeit überprüfen.
 
-## Überprüfen des öffentlichen Schlüssel (Zertifikatsprüfung)
-
+## Überprüfen des öffentlichen Schlüssels (Zertifikatsprüfung) {#certificateValidation}
 :::note Hinweis
 In der Testumgebung ist die Absicherung der öffentlichen Schlüssel eines Zustellpunktes durch Zertifikate optional.
 Eine Prüfung der Zertifikate kann in diesem Fall zu Testzwecken entfallen.