diff --git a/docs/Detailinformationen/Encryption_Key_Requirements.md b/docs/Detailinformationen/Encryption_Key_Requirements.md index 66dfea61961e9d6ea05091045eec80548a8acc35..ac2e2fde4a1ffd4f74bbcc4a36e1fd3272f5448b 100644 --- a/docs/Detailinformationen/Encryption_Key_Requirements.md +++ b/docs/Detailinformationen/Encryption_Key_Requirements.md @@ -2,7 +2,7 @@ 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** +Außerdem bietet fitconnect digital signierte Eingangsbestätigungen für Anträge. Die ausgestellten Signaturen werden auf Basis von [Security Event Tokens](https://tools.ietf.org/html/rfc8417) erzeugt und die dazugehörigen Public Keys mit Hilfe von [JSON Web Keys (JWK)](https://tools.ietf.org/html/rfc7517) implementiert. #### Allgemeine Anforderungen an die JSON Web Keys und JSON Web Encryption @@ -36,7 +36,7 @@ Bei der Erstellung und Signierung der Zertifikate sind alle Regeln und Standarts 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** | +| Feld | 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)) | @@ -68,7 +68,7 @@ Zur Signaturprüfung wird das verfahren JSON Web Signature ([RFC 7515](https://t 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 7515](https://tools.ietf.org/html/rfc7515#section-4)) verfügen. -| Field | Inhalt | **Erläuterung** | +| Feld | Inhalt | **Erläuterung** | | ------- | ------------------------------------- | ------------------------------------------------------------ | | kty | RSA | Gibt den Keytype nach [RFC 7515 Abschnitt 4](https://tools.ietf.org/html/rfc7515#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)) | @@ -98,23 +98,39 @@ Das bedeutet, der JSON Web Key zur Prüfung von digitalen Signaturen muss dem fo ## 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. +Zur Verschlüsselung des eigentlichen Antragsinhalts wird ein Symmetrischer Schlüssel verwendet. Dieser Symmetrische Schlüssel wird dann mit dem JSON Web Key, der vom **Fachverfahren** 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" +- Asymmetrisches Verschlüsselungsverfahren, um den "Content Encryption Key" zu verschlüsseln ("alg"): "RSA-OAEP-256" #### 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. +Im Header des JSON Web Encryption Objektes werden die Metadaten zu den verschlüsselten Antragsdaten übergeben. Diese Headerinformationen werden in der Umsetzung als Base64URL Safe enkodiert. + +| Feld | 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 5.1](https://tools.ietf.org/html/rfc7518#5.1) | +| 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. (siehe [RFC 7516 4.1.6](https://tools.ietf.org/html/rfc7516#section-4.1.6)) | + +## Signaturverfahren zur Signierung von Security Event Tokens + +Für die Bereitstellung von signierten Statusinformationen über Security Event Tokens (vgl. [RFC 8417](https://tools.ietf.org/html/rfc8417)) wird das Verfahren [JSON Web Signature](https://tools.ietf.org/html/rfc7515) verwendet. + +Zur Signatur der Even Tokens verfügt der Server, der die Tokens ausstellt, über einen Signaturschlüssel. Bei der Verwaltung der Signaturschlüssel sind insbesondere die Hinweise BSI… zu beachten. Der Public Key, zu dem auf dem Server verwendeten Signaturschlüssel, muss über den JSON Web Key Endpunkt als Key mit der Funktion "verify" verfügbar sein. + +Als Algorithmus für die Signatur muss RSASSA-PSS in Verbindung mit SHA-512 eingesetzt werden. Das Entspricht dem Standard beschrieben in [RFC 7518 Abschnitt 3.5](https://www.rfc-editor.org/rfc/rfc7518.html#section-3.5) und wird vom BSI als Signaturverfahren 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) empfohlen. + +Zu Übermittlung der Signatur wird das in [RFC 7515 Abschnitt 7.1](https://tools.ietf.org/html/rfc7515#section-7.1) beschriebene "JWS Compact Serialization" Verfahren verwendet. Die folgende Attribute müssen teil des Base64URL Safe enkodierten JOSE Headers sein: -| 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 5.1](https://tools.ietf.org/html/rfc7518#5.1) | -| 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. (siehe [RFC 7516 4.1.6](https://tools.ietf.org/html/rfc7516#section-4.1.6)) | +| Feld | Inhalt | Erläuterung | +| ---- | ------------------ | ------------------------------------------------------------ | +| alg | PS512 | Legt RSASSA-PSS mit SHA512 als standard für die Signatur fest (vgl. [RFC 7518 Abschnitt 3.5](https://www.rfc-editor.org/rfc/rfc7518.html#section-3.5)) | +| kid | ID des Public Keys | Die ID des JSON Web Keys mit dem Attribute "verify", aus dem von der Subscriber-API bereitgestellten Keysets, der zur Verifizieung der Signatur dient. | +| | | |