Encryption.md

Verschlüsselte Übertragung

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) unter Zuhilfenahme von JSON Web Keys (JWK) 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

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 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.

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, …).

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 Nutzerin bis in das Fachverfahren bzw. die Empfangsbehörde des Antrages. ) Es ist nicht vorgesehen, das Antragsdaten unverschlüsselt von einem Endgerät einer Nutzerin an ein Backend weitergeleitet werden, um dann von dort verschlüsselt per fitconnect an die Empfangsbehörde gesendet zu werden.

2. Die für die Verschlüsselung verwendeten JSON Web Keys müssen signiert werden und über eine Verwaltungs-PKI verifizierbar sein und auch durch den verschlüsselnden Client verfiziert werden. 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 wurden die Liste der möglichen Algorithmen eingeschränkt.

• 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"

Konzept

Aufbau der Übertragung

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.

Destination

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".

encoding: plain

"plain" ist der Defaultwert und entspricht der Arbeitsweise bis Beta 6. Hierbei werden die Fachdaten und Anlagen uncodierter Form übermittelt.

Beispiel

{"test":true,"hello":"world"}

encoding: base64

"base64" legt fest, dass die Daten base64-codiert übertragen werden.

Beispiel

eyJ0ZXN0Ijp0cnVlLCJoZWxsbyI6IndvcmxkIn0K

encoding: jwe

Beim Encoding "jwe" werden die Fachdaten und Anlagen 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. 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 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.

Beispiel

{
  "publicKeys": {
    "keys": [
      {
        "kty": "RSA",
        "e": "AQAB",
        "use": "enc",
        "kid": "c3bb7326-c498-4027-85f4-b102d0c69ebb",
        "n": "zcKRdaV9RjpekpyYqlbXQRhNgs_L2RwerlZKJJWdSaQWCD90yHk-bOlG6gjadalWpL
OF9aOPqqviVKRO2Gq-_mkdBJVuX2pLcx7IuxbEFaFRi81CXPUB3rbKiV_L5bQ2U9_m3X97wV72bkV07R
IJgH9QfCxcGwohN9hU_qLNMfrbwiwOF2WWgxL-x3NpnKhmWiXmIH0b17NH0NTeLTkXnKPWvFmTd_fCwW
Y-Z3L3hQik170z2R-hT4SpQOHN-UhXAbZ-SOER3roGObjHj3K8scFOhyOfd0wUPYP8gX_Lz6nR4AU-Ty
qqfpJ_kaeJdcWbH1z0HWXAenNxTGHOJeyYJGCjctphlSUwJVqrrtNAq15ilFWCw38vvOHbnt8WIqfE-j
hjtz80el2ieb4wQwcwFLGefKcnaNs5K82bIBXF993RqKKKtJfimz8KJAIPYsxpJ9swx4voPjUAdV99Ek
ofh__YzMgEdzoIJ6_pd3nojtm1vRKfcKWiT4Z09DW8qoF1"
      }
    ]
  },
  "schemas": [
    {
      "schemaSource": "none",
      "mimeType": "json",
      "encoding": "jwe"
    },
    {
      "schemaSource": "none",
      "mimeType": "xml",
      "encoding": "jwe"
    }
  ],
  "destinationId": "b444a551-74af-4a98-aa65-d1ffccd385d1"
}

Application Sender API

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.

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.

Beispiel (Metadaten)

{
  "contentStructure": {
    "data": {
      "schema": {
        "schemaSource": "none",
        "mimeType": "json",
        "encoding": "jwe"
      }
    },
    "docs": [
      {
        "size": 13046,
        "purpose": "attachment",
        "docId": "1",
        "mimeType": "application/pdf"
      }
    ]
  },
  "applicationId": "6f7b00f1-2f0c-46da-93c9-ca020aa1758f"
}

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: 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.

Beispiel

PUT /delivery-service-beta7/sender/destinations/e1009dea-d97e-4104-b389-bf653d8bd30e/applications//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