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

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.

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

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.

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 wurden die Liste der möglichen Algorithmen 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:

• Hashingalgorithmus: SHA-512
• Keylänge: 4096
• Signaturstandard: RSASSA-PSS

Signatur des JSON Web Keys durch Verwaltung-PKI

Das X.509 Zertifikat muss durch eine Verwaltungs-PKI signiert werden. Dabei sind die Regeln und Standarts aus BSI TR-02103 zu beachten.

Insbesondere:

• Muss sie Teil der Verwaltung-PKI sein, sprich das Wurzelzertifikat muss vom BSI stammen
• Muss sie über CRL Distribution Points (siehe 8.5 BSI TR-02103 ) verfügen
• Muss ein OCSP-Endpunkt (siehe 8.5.5 BSI TR-02103) mit signierten Antworten nach RFC 6125 bereitstellen

Zusammensetzung des JSON Web Keys

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) verfügen:

Field	Content
kty	RSA
key_ops	[verify, encrypt]
alg	PS512
x5c	die Zertifikatskette (base64 encoded)
x5t	der Zertifikatsfingerprint

Das bedeutet, der JSON Web Key sollte diesem Format entsprechen:

{
  "kty": "RSA",
  "key_ops": ["verify", "encrypt"],
  "alg": "PS512"
  "x5t": "……(Fingerprint)……",
  "x5c": [
      "……(base64 encoded root cert)……",
      "……(base64 encoded intermediate cert)……",
      "……(base64 encoded cert)……"
  ],
}

Algorithmen zur Verschlüsselung des Inhalts mit JSON Web Encryption

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"

Konzept

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

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 den folgenden Wert annehmen: "jwe".

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