diff --git a/docs/getting-started/event-log.mdx b/docs/getting-started/event-log.mdx index 13b8948fcc41c4aeda3e099c14d830c3fcdfa02a..f8a7aa3078447f47c87a8b6983c6805106d98d2b 100644 --- a/docs/getting-started/event-log.mdx +++ b/docs/getting-started/event-log.mdx @@ -213,17 +213,14 @@ boolean verifyZustelldienstSignature(SignedJWT securityEventToken, String keyId) ### Signaturprüfung eines vom empfangenden System ausgestellten SET -Um die Signatur eines SET zu überprüfen, welches von einem empfangenden System ausgestellt wurde, ist es notwendig, auf den verwendeten Schlüssel zugreifen zu können. -Die Schlüssel eines empfangenden Systems sind über die Destination in Form eines JSON Web Key (JWK) Sets öffentlich verfügbar. -Welche Schritte notwendig sind und wie die Prüfung letztendlich durchgeführt wird, wird im Folgenden anhand eines Beispiels beschrieben. +Um die Signatur eines von einem empfangenden System ausgestellen SET zu überprüfen ist es notwendig, auf den verwendeten Schlüssel zugreifen zu können. +Der bzw. die Schlüssel sind öffentlich verfügbar und können über die Submission API abgerufen werden. -:::caution Hinweis -Der Mechanismus zum Abrufen von kryptografischen Schlüsseln des empfangenden Systems wird sich bis zur Veröffentlichung der finalen API-Spezifikation noch einmal ändern. -::: - -Als Ausgangslage dient das Token mit dem folgenden Header und der entsprechenden Payload. -Aus dem Header wird die `kid` benötigt, sowie die `submissionId` aus dem Payload. -Konkret sind das hier +#### Ausgangslage: Das SET +Als Ausgangslage dient das folgende SET. +Aus dem Header wird die Schlüssel-ID aus dem Feld `kid` benötigt. +Aus dem Payload benötigen wir das Feld `submissionId`. +Konkret sind das hier: - kid: `dd0409e5-410e-4d98-85b6-f81a40b8d980` - submissionId: `F65FEAB2-4883-4DFF-85FB-169448545D9F` @@ -249,10 +246,12 @@ Konkret sind das hier } ``` +#### Abruf des JWK zur Gültigkeitsprüfung des SET + Mit der `submissionId` kann über den Endpunkt <ApiLink to="/submissions/{submissionId}" /> die zugehörige `destinationId` ermittelt werden. Hier ist das konkret der Wert `92f2f581-c89d-44a5-b834-1fe3f6fa48d5`. -```http title="Abfrage der Submission" +```http title="Abfrage der destinationId einer Submission" GET /submissions/F65FEAB2-4883-4DFF-85FB-169448545D9F { "destinationId": "92f2f581-c89d-44a5-b834-1fe3f6fa48d5", @@ -260,25 +259,33 @@ GET /submissions/F65FEAB2-4883-4DFF-85FB-169448545D9F } ``` -Mit den zwei Informationen `kid` und `destinationid` kann nun der JWK zur Signaturprüfung abgerufen werden. -Der Endpunkt hierfür ist <ApiLink to="/destinations/{destinationId}/keys/{keyId}" />. +Mit den zwei Informationen `kid` und `destinationid` kann nun der JWK zur Signaturprüfung abgerufen werden: -```http title="Abfrage der Destination" -GET /destinations/92f2f581-c89d-44a5-b834-1fe3f6fa48d5/keys/dd0409e5-410e-4d98-85b6-f81a40b8d980 +```shell title="Beispiel: Abruf des JWK eines Zustellpunktes" +$ KID=... +$ SERVICE_URL=... +$ DESTINATION_ID=... +$ curl -X GET \ + "$SERVICE_URL/destinations/$DESTINATION_ID/keys/$KID" +--- { - "alg": "PS512", + "kty": "RSA", "e": "AQAB", - "key_ops": [ - "verify" + "keyops": ["wrapKey"], + "x5c": [ + "LS0tLS1CRUdJTiBDRVJU...jN1NGKzQKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo=" ], - "kid": "dd0409e5-410e-4d98-85b6-f81a40b8d980", - "kty": "RSA", - "n": "…" + "x5t": "MTg6NTU6RUY6ME...MEM6QzM6ODQ6QjA6MkE6RkMK", + "kid": "787f3a1c-7da7-44d7-9b79-9783b1ea9be8", + "alg": "RSA-OAEP-256", + "n": "sX2DX7rG5BoJd23...FlxHZt8T6ZqjRa1QcFnkq3_M4-tk" } ``` -Die Verifikation mit dem Schlüssel ist dann ziemlich geradlinig. -Es wird noch überprüft, ob der Schlüssel den passenden Algorithmus hat und dann die eigentliche Verifikation über die Methode der Bibliothek durchgeführt. +#### Validierung des SET mit Hilfe des JWK + +Die Verifikation des SET mit dem eben abgerufenen JWK ist dann ziemlich geradlinig. +Es wird zunächst geprüft ob der Schlüssel den passenden Algorithmus hat. Anschließend wird die eigentliche Verifikation durch die Bibliothek durchgeführt. ```java boolean verifyClientSignature(SignedJWT securityEventToken, String keyId) { diff --git a/docs/getting-started/sending/encrypt.mdx b/docs/getting-started/sending/encrypt.mdx index b69de750ad1a86903330761f416f5a10d379f4ab..e7c43a11613bd73518be6f954fb19073e43588f4 100644 --- a/docs/getting-started/sending/encrypt.mdx +++ b/docs/getting-started/sending/encrypt.mdx @@ -6,11 +6,27 @@ sidebar_position: 4 import Tabs from '@theme/Tabs' import TabItem from '@theme/TabItem' -Viele Daten, die über den Zustelldienst übertragen werden, enthalten schützenswerte Informationen und müssen verschlüsselt werden. Eine Übertragung über FIT-Connect besteht aus einem Metadatensatz, optionalen Fachdaten und beliebig vielen (0-∞) Dokumenten (Anlagen). Die Metadaten, Fachdaten und Anlagen werden gemäß dem Standard [JSON Web Encryption (JWE)](https://tools.ietf.org/html/rfc7516) verschlüsselt. Als Datenformat für die Übertragung wird die sogenannte [JWE-Compact Serialisierung](https://tools.ietf.org/html/rfc7516#section-7.1) verwendet. Alle angehängten Dokumente müssen als Binärdateien und nicht als Strings kodiert verschlüsselt werden. +Über FIT-Connect versendete Daten sind oft schützenswert und müssen daher verschlüsselt werden. -Gegeben, dass ein öffentlicher Teil eines JWK eines Zustellpunktes [vorhanden ist](./get-destination.mdx#informationen-des-zustellpunktes-erhalten), können mit diesem Daten für diesen Zustellpunkt verschlüsselt werden. Ein Beispiel für den öffentlichen Teil eines JWK ist unten aufgeführt. +Eine Übertragung über FIT-Connect besteht aus -```json +* einem Metadatensatz +* einem Fachdatensatz (optional) +* beliebig vielen Dokumenten (optional) + +Alle drei Datensatzarten müssen mit [JSON Web Encryption (JWE)](https://tools.ietf.org/html/rfc7516) verschlüsselt und mit [JWE-Compact Serialisierung](https://tools.ietf.org/html/rfc7516#section-7.1) serialisiert werden. +Dokumente müssen als Binärdateien und nicht als Zeichenketten kodiert verschlüsselt werden. + +Der [vorher abgerufene Zustellpunkt](./get-destination.mdx#informationen-des-zustellpunktes-erhalten) beinhaltet die Schlüssel-ID des Verschlüsselungsschlüssels unter dem Feld `encryptionKid`. +Damit können wir den JWK des Zustellpunktes abrufen um Daten zu verschlüsseln. + +```shell title="Beispiel: Abruf des JWK eines Zustellpunktes" +$ KID=... # Wert des Feldes `encryptionKid` +$ SERVICE_URL=... +$ DESTINATION_ID=... +$ curl -X GET \ + "$SERVICE_URL/destinations/$DESTINATION_ID/keys/$KID" +--- { "kty": "RSA", "e": "AQAB", @@ -25,19 +41,26 @@ Gegeben, dass ein öffentlicher Teil eines JWK eines Zustellpunktes [vorhanden i } ``` -## Überprüfen öffentlicher Schlüssel (Zertifikatsprüfung) +Mit diesem Schlüssel könnten jetzt die oben genannten Datenssätze verschlüsselt werden. +Die so verschlüsselten Daten können ausschließlich von diesem Zustellpunkt mit gelesen werden. + +Bevor wir mit der Verschlüsselung loslegen können müssen wir den eben abgerufenen JWK noch auf Gültigkeit überprüfen. + +## Überprüfen des öffentlichen Schlüssel (Zertifikatsprüfung) + :::note Hinweis -In der Testumgebung ist die Absicherung der öffentlichen Schlüssel eines Zustellpunktes durch Zertifikate optional. Eine Prüfung der Zertifikate kann in diesem Fall zu Testzwecken entfallen. +In der Testumgebung ist die Absicherung der öffentlichen Schlüssel eines Zustellpunktes durch Zertifikate optional. +Eine Prüfung der Zertifikate kann in diesem Fall zu Testzwecken entfallen. ::: -Die JSON Web Keys MÜSSEN vor der Verwendung zwingend im Client auf Gültigkeit geprüft werden. Das umfasst insbesondere folgende Schritte: +JWKs MÜSSEN vor der Verwendung zwingend im Client auf Gültigkeit geprüft werden. Diese Prüfung umfasst folgende Schritte: - Überprüfung, dass der JSON Web Key für die Verschlüsselung geeignet ist (`"keyops": ["wrap_key"]`) - Überprüfung, dass der öffentliche Schlüssel mit dem im JSON Web Key hinterlegten Zertifikat übereinstimmt (Attribute `n` und `e`) - Überprüfung der Zertifikats-Kette bis zum Wurzelzertifikat (BSI) - Überprüfung gegen eine Certificate Revocation List und/oder einen OCSP-Endpunkt mit signierten Antworten -Weitere Informationen zur Gültigkeitsprüfung finden sich in der technischen Richtlinie [BSI TR-02103](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02103/BSI-TR-02103.pdf?__blob=publicationFile&v=4). +Weitere Informationen zur Gültigkeitsprüfung finden sich in der technischen Richtlinie [BSI TR-02103](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02103/BSI-TR-02103.pdf?__blob=publicationFile&v=4) des BSI. :::note Hinweis An dieser Stelle werden noch detailliertere Informationen und konkrete Implementierungsbeispiele zur Prüfung der JSON Web Keys ergänzt. @@ -130,8 +153,10 @@ Mit diesem umgewandelten Schlüssel können nun Zeichenketten und Binärdaten ve ```java JWEHeader header = new JWEHeader(JWEAlgorithm.RSA_OAEP_256, EncryptionMethod.A256GCM); +// Zeichenkette Payload payload = new Payload("{ \"Hello\": \"World\"}"); -/// Alternativ, bei einer Datei + +// InputStream (z.B. für Datei) Payload payload = new Payload(aFileInputStream.readAllBytes()); JWEObject jweObject = new JWEObject(header, payload); @@ -140,7 +165,7 @@ try { jweObject.encrypt(new RSAEncrypter(publicKey)); String encrypted = jweObject.serialize(); - System.out.println("Encrypted Text:"); + System.out.println("Encrypted Text"); System.out.println(encrypted); } catch (JOSEException e) { e.printStackTrace(); diff --git a/docusaurus.config.js b/docusaurus.config.js index 1f6d7c021f2d830b0b4a4fda949224f553de5295..769d5b96d3f1897fff6c76f273cc89fd22de4747 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -46,6 +46,7 @@ module.exports = { style: 'light', copyright: `Copyright © ${new Date().getFullYear()} FITKO (Föderale IT-Kooperation) | Zum Gottschalkhof 3 | 60594 Frankfurt am Main | E-Mail: poststelle@fitko.de | https://www.fitko.de | Die FITKO ist eine Anstalt des öffentlichen Rechts. Sie wird vertreten durch die Präsidentin Frau Dr. Annette Schmidt.`, }, + hideableSidebar: true, }, presets: [ [