Skip to content
Snippets Groups Projects
Commit 84ccb355 authored by Lilith Wittmann's avatar Lilith Wittmann
Browse files

doc(encryption_keys): fix lots of missing/br0ken links, spelling and todos 

- some RFC links to sections were br0ken
- spelling errors
- elaborate on key rotation for signature keys (TODO: discuss that with Marco)
parent c9890627
No related branches found
No related tags found
1 merge request!26doc(encryption_keys): fix lots of missing/br0ken links, spelling and todos
Hide whitespace changes
Inline Side-by-side
docs/Detailinformationen/Encryption_Key_Requirements.md
+ 27
− 25
View file @ 84ccb355
# Anforderungen an das kryptographische Material
# Anforderungen an das kryptografische Material
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 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.
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
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](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.html) wurde die [Liste der möglichen Algorithmen](https://www.iana.org/assignments/jose/jose.xhtml#web-signature-encryption-algorithms) 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.
Beim Einsatz von Verschlüsselung ist es elementar, dass die dabei verwendeten kryptografischen Methoden sicher sind. Unter Berücksichtigung der Vorgaben des BSI in der Richtlinie [TR-02102-1](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.html) wurde die [Liste der standartisierten Algorithmen](https://www.iana.org/assignments/jose/jose.xhtml#web-signature-encryption-algorithms) 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 Softwarebiblotheken verwendet werden und deswegen einfach zu implementieren sein sollten.
### Regeln zur Erstellung des JSON Web Keys zur Verschlüsselung von Antragsdaten und der Signatur von Eingangsbestätigungen
......@@ -22,11 +22,11 @@ Die den JSON Web Keys zugrundeliegenden X.509-Zertifikate müssen auf Basis der
### Signatur der X.509 Zertifikate durch die Verwaltung-PKI
Die X.509 Zertifikate müssen durch eine Verwaltungs-PKI signiert werden. Als Verwaltungs-PKIs werden alle Zertifizierungsstellen, die ein Wurzelzertifikat des BSI verwenden und sich an die vom [BSI definierten Regelungen für Wurzelzertifizierungsstellen](https://www.bsi.bund.de/DE/Themen/Oeffentliche-Verwaltung/Moderner-Staat/Verwaltungs-PKI/Dokumente/dokumente_node.html) halten, bezeichnet.
Die X.509-Zertifikate müssen durch eine Verwaltungs-PKI signiert werden. Als Verwaltungs-PKIs werden alle Zertifizierungsstellen, die ein Wurzelzertifikat des BSI verwenden und sich an die vom [BSI definierten Regelungen für Wurzelzertifizierungsstellen](https://www.bsi.bund.de/DE/Themen/Oeffentliche-Verwaltung/Moderner-Staat/Verwaltungs-PKI/Dokumente/dokumente_node.html) halten, bezeichnet.
Bei der Erstellung und Signierung der Zertifikate sind alle Regeln und Standarts aus BSI [TR-02103](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02103/BSI-TR-02103.pdf?__blob=publicationFile&v=4) zu beachten.
Bei der Erstellung und Signierung der Zertifikate sind alle Regeln und Standards aus BSI [TR-02103](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02103/BSI-TR-02103.pdf?__blob=publicationFile&v=4) zu beachten.
**Für die Verwendbarkeit in fitconnect sind insbesondere die folgenden Anforderungen an die Verwaltungs.-PKI besonders wichtig:**
**Für die Verwendbarkeit in fitconnect sind insbesondere die folgenden Anforderungen an die Verwaltungs-PKI besonders wichtig:**
- Sie müssen eine Verwaltungs-PKI sein, sprich das [Wurzelzertifikat muss vom BSI stammen.](https://www.bsi.bund.de/DE/Themen/Oeffentliche-Verwaltung/Moderner-Staat/Verwaltungs-PKI/Wurzelzertifizierungsstelle/wurzelzertifizierungsstelle_node.html;jsessionid=E33702EEFB110FA230DDA266C9512436.internet471)
- Sie müssen über CRL Distribution Points (siehe 8.5 BSI [TR-02103](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02103/BSI-TR-02103.pdf?__blob=publicationFile&v=4) ) verfügen.
......@@ -34,12 +34,12 @@ Bei der Erstellung und Signierung der Zertifikate sind alle Regeln und Standarts
### Zusammensetzung des JSON Web Keys zur Verschlüsselung
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.
Das generierte X.509 Zertifikat, alle Intermediate Zertifikate und das Wurzelzertifikat müssen zum PEM-Format konvertiert, base64 encodiert 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.
| 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)) |
| 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#section-4.3)) |
| alg | PS512 | Gibt den Algorithmus der zur digitalen Signatur des Zertifikats verwendet werden muss an. Dieser muss im Fall von fitconnect immer PS512 sein. (vgl. [BSI TR-02102-1 Tabelle 4.1](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.html)) |
| x5c | die Zertifikatskette (base64 encoded) | Entspricht der Zertifikatskette vom Wurzelzertifikat bis zum Zertifikat selbst. ([Abschnitt 4.7 RFC 7518](https://tools.ietf.org/html/rfc7517#section-4.7)) |
| x5t | der Zertifikatsfingerprint | Der Fingerprint des Zertifikats selbst. ([Abschnitt 4.8 RFC 7518](https://tools.ietf.org/html/rfc7517#section-4.8)) |
......@@ -66,16 +66,18 @@ Das bedeutet, der JSON Web Key zur Verschlüsselung muss diesem Format entsprech
Zur Signaturprüfung wird das verfahren JSON Web Signature ([RFC 7515](https://tools.ietf.org/html/rfc7515)) eingesetzt. Der dafür im Keyset bereitgestellte Key unterscheidete sich vom für die JSON Web Encryption bereitgestellten Key primär durch seine Funktion und nicht durch die verwendeten kryptographischen Methoden. Das soll vor allem zu einer Vereinfachung der Implementierung führen.
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.
Das generierte X.509 Zertifikat, alle Intermediate Zertifikate und das Root Zertifikat müssen zu PEM konvertiert, base64 encodiert 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.
Die Auswahl welcher JSON Web Key aus der Liste der zur Verfügung gestellten Keys verwendet werden muss, wird anhand der "kid" entschieden. Deshalb ist diese verpflichtend anzugeben und muss pro Destination-ID einmalig sein. Es wird empfohlen eine UUID nach [RFC 4122](https://tools.ietf.org/html/rfc4122) zu verwenden.
| 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)) |
| 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#section-4.3)) |
| alg | PS512 | Gibt den Algorithmus der zur digitalen Signatur des Zertifikats verwendet werden muss an. Dieser muss im Fall von fitconnect immer PS512 sein. (vgl. [BSI TR-02102-1 Tabelle 4.1](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.html)) |
| x5c | die Zertifikatskette (base64 encoded) | Entspricht der Zertifikatskette vom Wurzelzertifikat bis zum Zertifikat selbst. ([Abschnitt 4.7 RFC 7518](https://tools.ietf.org/html/rfc7517#section-4.7)) |
| x5t | der Zertifikatsfingerprint | Der Fingerprint des Zertifikats selbst. ([Abschnitt 4.1.7 RFC 7515](https://tools.ietf.org/html/rfc7515#section-4.1.7)) |
| kid | eindeutige ID des Keys | Diese ID wird verwendet, um zur Prüfung der Signatur den richtigen Key auswählen zu können. (siehe [RFC 7515 4.1.6](https://tools.ietf.org/html/rfc7515#section-4.1.6)) |
| kid | eindeutige ID des Keys | Diese ID wird verwendet, um zur Prüfung der Signatur den richtigen Key auswählen zu können. (siehe [RFC 7515 4.1.4](https://tools.ietf.org/html/rfc7515#section-4.1.4)) Als Format der ID wird UUID nach [RFC 4122](https://tools.ietf.org/html/rfc4122) empfohlen. |
Das bedeutet, der JSON Web Key zur Prüfung von digitalen Signaturen muss dem folgenden Format entsprechen:
......@@ -94,43 +96,43 @@ Das bedeutet, der JSON Web Key zur Prüfung von digitalen Signaturen muss dem fo
}
```
**TODO(Lilith): hier etwas über key austausch einfügen (vermutlich müssen wir keys, die zur Verifizierung dienen, weiterhin ausliefern, während Verschlüsselungskeys ausgetauscht werden)**
Abgelaufene oder nichtmehr Verwendete JSON Web Keys müssen nach Ende der Verwendung weiterhin solange die signierten Security Event Tokens abrufbar sind - **mindestens jedoch für weitere mindestens 24 Monate** - über den Endpunkt (bzw. die Destination-ID) abrufbar sein. Das soll sicherstellen, das auch bei bereits versendete Anträgen weiterhin der Antragsstatus verifiziert werden kann.
## 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 dann mit dem JSON Web Key, der vom **Fachverfahren** bereitgestellt wird und die Verwendungsart **"wrapKey"** haben muss, asymmetrisch verschlüsselt.
Zur Verschlüsselung des eigentlichen Antragsinhalts wird ein s 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:
Verschlüsselugnsverfahren Der Content im verschlüsselten JSON Web Encryption Objekt muss mit den folgenden Methoden verschlüsselt werden:
- 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"
- Symmetrisches Verschlüsselungsverfahren zur Verschlüsselung der Formularinhalts- sowie der Metadaten ("Payload"- Feld im JSON: "enc"): "A256GCM" (definiert in [RFC 7518 Abschnitt 4.1](https://tools.ietf.org/html/rfc7518#section-4.1))
- Asymmetrisches Verschlüsselungsverfahren, um den "Content Encryption Key" zu verschlüsseln ("alg"): "RSA-OAEP-256" (definiert in [RFC 7518 Abschnitt 4.3](https://tools.ietf.org/html/rfc7518#section-4.3)
#### JSON Web Encryption Header (JOSE)
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.
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 encodiert.
| 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) |
| 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#section-4.1). |
| enc | A256GCM | Symmetrisches Verschlüsselungsverfahren zur Verschlüsselung des Payloads. Nach [RFC 7518 5.1](https://tools.ietf.org/html/rfc7518#section-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)) |
| 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.4](https://tools.ietf.org/html/rfc7516#section-4.1.4)). Als Format der ID wird UUID nach [RFC 4122](https://tools.ietf.org/html/rfc4122) empfohlen. |
## Algorithmen 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.
Zur Signatur der Event Tokens verfügt der Server, der die Tokens ausstellt, über einen Signaturschlüssel. Bei der Verwaltung der Signaturschlüssel sind insbesondere die Hinweise in [BSI TR-03116-4 Abschnitt 6](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR03116/BSI-TR-03116-4.html) und [BSI TR-02102-1 Abschnitt 8](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.html) 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.
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:
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 encodierten JOSE Headers sein:
| 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. |
| 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 Verifizierung der Signatur dient. (vgl. [RFC7515 Abschnitt 4.1.4](https://tools.ietf.org/html/rfc7515#section-4.1.4)) |
| | | |
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment