diff --git a/docs/Detailinformationen/Encryption.md b/docs/Detailinformationen/Encryption.md index a8e6eb7ba84c95e42e27bfa7a8a090b0e0eb6fd0..fa00a23fcd1fd326d22d4f989254132f959055a6 100644 --- a/docs/Detailinformationen/Encryption.md +++ b/docs/Detailinformationen/Encryption.md @@ -38,51 +38,53 @@ Kern von FIT-Connect ist der Zustelldienst, der über die beiden APIs "Applicati 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. +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. Diese Schemas enthalten unter anderem eine Angabe zum Encoding, über das eine Verschüsselung vorgegeben wird. -## Bereitstellung eines Destination-Endpunktes +### Application Sender API -### Erstellung eines fitconnect-kompatiblen JSON Web Keys +Der Absender muss die Destination-ID vorliegen haben und erfagt über die Application Sender API die Informationen zur Destination. 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. -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. +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. -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` -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 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. -## Implementierung eines Onlinedienstes +### Application Subscriber API -### Aufbau der Übertragung +Ü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. -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. +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. -## Application Schema +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. -Die Metadaten, Fachdaten und Anlagen werden immer mit dem Encoding "jwe" (JSON Web Encryption RFC 7516) verschlüsselt. +### Ablauf eines Antrags aus Bürger*innen-Client-Perspektive -#### Beispiel +Wenn eine Bürger*in nun einen Antrag im Web oder in einer App übermitteln möchte läuft das in der Regel wie folgt ab: -``` -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 -``` +- Bürger*in findet den passenden Antrag über einen Zuständigkeitsfinder. +- Die Applikation erhält aus dem Zuständigkeitsfinder die passende Destination-ID zum Antrag. +- 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 Antrag aus der Sender-API ab. -## Application Subscriber API +**TODO: add here some doc links about oauth** -Ü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. +## Bereitstellung eines Destination-Endpunktes -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. +### Erstellung eines fitconnect-kompatiblen JSON Web Keys -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. +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. 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 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** + +Das dabei entstandene Zertifikat muss zur dem Fachverfahren gehörende Destination hinzugefügt werden + +### Anlegen eines Zustellpunktes #### Beispiel @@ -109,27 +111,31 @@ ofh__YzMgEdzoIJ6_pd3nojtm1vRKfcKWiT4Z09DW8qoF1" { "schemaSource": "none", "mimeType": "json", - "encoding": "jwe" }, { "schemaSource": "none", "mimeType": "xml", - "encoding": "jwe" } ], "destinationId": "b444a551-74af-4a98-aa65-d1ffccd385d1" } ``` -## Application Sender API +## Implementierung eines Onlinedienstes -Der Absender muss die Destination-ID vorliegen haben und erfagt über die Application Sender API die Informationen zur Destination. 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. +### Abrufen der Endpunktinformationen -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. +### Überprüfen der Json Web Keys -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. +### Aufbau der Übertragung -**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. +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 immer mit dem Encoding "jwe" (JSON Web Encryption RFC 7516) verschlüsselt. + +Als Datenformat für die Übertragung wird die sogenannte [JWE-Compact Sterilisierung](https://tools.ietf.org/html/rfc7516#section-7.1) verwendet. + +Alle angehängten Dokumente müssen als Binärdateien und nicht als Strings verschlüsselt werden. #### Beispiel (Metadaten) @@ -158,23 +164,9 @@ Das gewählte Schema wird in den Metadaten des Antrags (Application Metadata) ei #### Beispiel (Fachdaten) -``` -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 -```` - -### encoding: jwe +Bei der verschlüsselten Übertragung der Fachdaten und Anlagen wird der Content-Type "application/jose" (Achtung: jose, nicht json) verwendet. -Bei der Übertragung der Fachdaten und Anlagen wird der Content-Type "application/jose" (Achtung: jose, nicht json) verwendet. - -#### Beispiel +Beispiel: ``` PUT /delivery-service-beta7/sender/destinations/e1009dea-d97e-4104-b389-bf653d8bd30e/applications//data HTTP/1.1 @@ -191,3 +183,6 @@ OcFhj3XGUshVKec2nRhtCZPOMPTIjxFpozsiRetjZo9LFHzRcvr1eSS_hpteKJ3ltioY9nzt1IX2JqQm TGtY.VGOCnGM9LEZP5mUO.LQeKj4SKqsUNsBp4ZRN_56QbS8MQ01YTzRVFStk.Z0YMEua9kvCV7LkeJH kprA ``` + + +