diff --git a/docs/getting-started/event-log/set-creation.mdx b/docs/getting-started/event-log/set-creation.mdx index ecd284e74da848b3414ecc36c65637f3008140e0..1c278293c4baf71a39bcb0cf35a1836c527a235d 100644 --- a/docs/getting-started/event-log/set-creation.mdx +++ b/docs/getting-started/event-log/set-creation.mdx @@ -5,19 +5,20 @@ title: Erzeugen eines Security-Event-Token (SET) import Tabs from '@theme/Tabs' import TabItem from '@theme/TabItem' -# Event +# SET Erzeugung -Je nach Event ist ein Payload für das Event vorgesehen. -Auf der Seite [Ereignisse](./events.mdx) finden Sie eine Liste der Ereignisse und deren Struktur. +## Ereignis Payload -Derzeit ist es weiterhin möglich, Events ohne Payload zu senden. -In diesem Fall darf kein Schema (`$schema`) angegeben werden. +Je nach SET ist ein Ereignis-Payload für das darin vorkommendes Ereignis vorgesehen. +Auf der Seite [Ereignisse](./events.mdx) finden Sie eine Liste der Ereignisse und deren Struktur. -## Event Payload +Derzeit ist es weiterhin möglich, Ereignise auch ohne Ereignis-Payload zu senden. +In diesem Fall darf kein SET-Payload-Schema (unter `$schema`) angegeben werden. +Denn sollte ein SET-Payload-Schema verwendet werden, das ein Ereignis-Payload vorschreibt, wird das SET ohne diese Ereignis-Payload vom Zustelldienst mit einem Fehler zurückgewiesen. -### Authentication Tags +### Authentication Tags Ereignis Payload -Die Struktur der "Authentication Tags" sieht wie folgt aus. +Die Struktur der `Authentication Tags` Ereignis Payload sieht wie folgt aus. ```json { @@ -83,9 +84,9 @@ values={[ </Tabs> -### Problems +### Problems Ereignis Payload -Die Struktur der "Problems" sieht wie folgt aus. +Die Struktur der `Problems` Ereignis Payload sieht wie folgt aus. ```json { @@ -165,17 +166,23 @@ values={[ </Tabs> -## SET Claims +## SET Claimset/Payload -Der SET Payload ist wie folgt aufgebaut. -Die Elemente der obersten Ebene sind bei allen SETs vorhanden. -Der Claim `events` enthält als Schlüssel das eigentliche Event, das ggf. einen Payload (hier: `authenticationTags`) enthält. +Die SET Payload ist wie folgt aufgebaut. +Die Elemente der obersten Ebene sind bei allen SETs vorhanden (Ausnahme `$schema`). +Der Claim `events` enthält als Schlüssel das eigentliche Ereignis, das ggf. einen eigenen Ereignis Payload (hier: `authenticationTags`) enthält. -:::info - -Derzeit ist die Version 0.1.0 des SET-Payload-Schemas aktuell. -Die in den Beispielen genannte Version 1.0.0 wird im Zuge des Rückkanals veröffentlicht. +Für die SET Payload wird unter `$schema` ein Schema zur Validierung definiert. +Entspricht ein SET Payload nicht dem definierten Schema wird es z.B. vom Zustelldienst zurückgeweisen. +Es ist aktuell noch möglich kein `$schema` zu setzten. Dadurch findet keine Validation statt. +Dies wird in unspezifizierter Zukunft `deprecated` und alle SETs müssen ein valides Schema verwenden. +:::info +Derzeit ist die Version [1.0.0](https://schema.fitko.de/fit-connect/set-payload/1.0.0/set-payload.schema.json) des SET-Payload-Schemas aktuell. +Mit diesem Schema `1.0.0` stellt auch der Zustelldienst seine SETs aus. +Bis auf weiteres kann auch noch die Version [0.1.0](https://schema.fitko.de/fit-connect/set-payload/1.0.0/set-payload.schema.json) verwendet werden. +Inhaltlich ist sie deckungsgleich mit der Version `1.0.0`. +Diese Version `0.1.0` wird deswegen in noch unspezifizierter Zukunft mit Ankündigung `deprecated` und sollte dann nicht mehr verwendet werden. ::: ```json diff --git a/docs/getting-started/event-log/set-validation.mdx b/docs/getting-started/event-log/set-validation.mdx index 925dd79ba8a266526b4ea92b1e9648fbe500e258..8c2e25a90a369c9bfe5561f57a9fce9b77eaf19e 100644 --- a/docs/getting-started/event-log/set-validation.mdx +++ b/docs/getting-started/event-log/set-validation.mdx @@ -6,31 +6,34 @@ import ApiLink from '@site/src/components/ApiLink' import Tabs from '@theme/Tabs' import TabItem from '@theme/TabItem' +# SET Prüfung + Um eine vollständige Prüfung eines Security-Event-Tokens durchzuführen, MUSS zwingend sowohl die Einhaltung der (kryptografischen) Vorgaben als auch die Signatur geprüft werden. Die Prüfung der Signatur des SET ist abhängig vom ausstellenden System (Zustelldienst, Subscriber oder Sender). +Aus technischer Sicht sollte auch das SET-Payload-Schema validiert werden um Sowohl die Prüfung der kryptografischen Vorgaben, als auch die Prüfung der Signatur darf KEINESFALLS ausgelassen werden. ## Prüfung der Einhaltung von kryptografischen Vorgaben und der Struktur Alle generierten Security-Event-Tokens MÜSSEN den Vorgaben aus [RFC 7519](https://tools.ietf.org/html/rfc7519) entsprechen und über folgende Header-Attribute verfügen: -| Feld | Inhalt | Erläuterung | -|-------|-------------------------------------|---------------------------------------------------------------------------------------| -| `typ` | `secevent+jwt` | Wird gemäß [RFC 8417, Abschnitt 2.3](https://datatracker.ietf.org/doc/html/rfc8417#section-2.3) auf den festen Wert "`secevent+jwt`" gesetzt. | -| `alg` | `PS512` | Zur Signaturerstellung wird der Signaturalgorithmus RSASSA-PSS mit SHA-512 und MGF1 mit SHA-512 verwendet. Vorgabe gemäß [BSI TR-02102](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.html) in der Version 2021-01 (Stand 24. März 2021). | -| `kid` | Key-ID des zugehörigen Public Keys | Die Key-ID des Public Key, mit dem die Signatur des JWT geprüft werden kann. | - -In der Payload des signierten SET MÜSSEN die folgenden [standardisierten Felder](https://www.iana.org/assignments/jwt/jwt.xhtml) gesetzt sein: - -| Feld | Inhalt | Erläuterung | -|-----------|-----------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `$schema` | Referenz auf das verwendete SET-Schema | Gibt das SET-Schema an, dem das SET entspricht. Das Schema kann von [schema.fitko.de](https://schema.fitko.de/fit-connect/set-payload/) bezogen werden. Mit dem Schema kann die Struktur des SET Payloads validiert werden. | -| `jti` | UUID des Token | Die JWT ID ist eine eindeutige ID des SET bzw. JWT. Es wird eine zufällige UUID verwendet. | -| `iss` | ID des Token Issuers | Diese Angabe dient dazu, um herauszufinden, wer den Token ausgestellt hat. Für SETs, die vom Zustelldienst ausgestellt sind, wird die Host-Adresse (API-URL) verwendet. Bei SETs von empfangenden Systemen ist die `destinationId`, an der dieser die Submission schickt. | -| `iat` | Timestamp (UNIX-Format) | Zeitpunkt der Ausstellung des SET. | -| `sub` | URI, die den Gegenstand des SET identifiziert | Das Subject eines SET ist eine Kombination aus dem Schlüsselwort `submission` und der Id `submissionId` der Resource. | -| `txn` | URI, die den Vorgang identifiziert | Als "Transaction Identifier" wird die Vorgangsreferenz `caseId` angegeben. | -| `events` | JSON-Objekt der Events in diesem Event-Token | Das Objekt `events` enthält genau ein Ereignis zu einem logischen Sachverhalt bzw. Gesamtereignis, wie bspw. der Versendung einer Einreichung durch den Sender. Dieses Objekt beinhaltet immer zwingend eine URI, die das jeweilige Gesamtereignis eindeutig identifiziert. Das Objekt der URI des Gesamtereignisses ist aktuell leer, kann aber zukünftig weitere Details zu einem Gesamtereignis enthalten. | +| Feld | Inhalt | Erläuterung | +|-------|------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `typ` | `secevent+jwt` | Wird gemäß [RFC 8417, Abschnitt 2.3](https://datatracker.ietf.org/doc/html/rfc8417#section-2.3) auf den festen Wert "`secevent+jwt`" gesetzt. | +| `alg` | `PS512` | Zur Signaturerstellung wird der Signaturalgorithmus RSASSA-PSS mit SHA-512 und MGF1 mit SHA-512 verwendet. Vorgabe gemäß [BSI TR-02102](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.html) in der Version 2021-01 (Stand 24. März 2021). | +| `kid` | Key-ID des zugehörigen Public Keys | Die Key-ID des Public Key, mit dem die Signatur des JWT geprüft werden kann. | + +In der Payload des signierten SET MÜSSEN die folgenden [standardisierten Felder](https://www.iana.org/assignments/jwt/jwt.xhtml) gesetzt sein (Temporäre Ausnahme `$schema`): + +| Feld | Inhalt | Erläuterung | +|-----------|----------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `$schema` | URL Referenz auf das verwendete SET-Payload-Schema | Gibt das SET-Payload-Schema an, dem das SET entspricht. Dieses Schema wird auch vom Zustelldienst validert. <br/> Jeddoch ist es aktuell noch möglich kein `$schema` anzugeben. In diesem Fall findet keine Validation im Zustelldienst statt. <br/> Das Schema kann zur eigenen Validierung der SET Payload von der referenzierten URL bezogen werden. Derzeit ist die Version [1.0.0](https://schema.fitko.de/fit-connect/set-payload/1.0.0/set-payload.schema.json) des SET-Payload-Schemas aktuell. Mit diesem Schema `1.0.0` stellt auch der Zustelldienst seine SETs aus. Bis auf Weiteres kann auch noch die Version [0.1.0](https://schema.fitko.de/fit-connect/set-payload/1.0.0/set-payload.schema.json) verwendet werden. Inhaltlich ist sie deckungsgleich mit der Version `1.0.0`. Diese Version `0.1.0` wird deswegen in noch unspezifizierter Zukunft mit Ankündigung `deprecated` und sollte nicht mehr verwendet werden. Aktuell muss eine Validation aber beide Schema Versionen (`0.1.0` und `1.0.0`) unterstüzen. | +| `jti` | UUID des Token | Die JWT ID ist eine eindeutige ID des SET bzw. JWT. Es wird eine zufällige UUID verwendet. | +| `iss` | ID des Token Issuers | Diese Angabe dient dazu, um herauszufinden, wer den Token ausgestellt hat. Für SETs, die vom Zustelldienst ausgestellt sind, wird die Host-Adresse (API-URL) verwendet. Bei SETs von empfangenden Systemen ist die `destinationId`, an der dieser die Submission schickt. | +| `iat` | Timestamp (UNIX-Format) | Zeitpunkt der Ausstellung des SET. | +| `sub` | URI, die den Gegenstand des SET identifiziert | Das Subject eines SET ist eine Kombination aus dem Schlüsselwort `submission` und der Id `submissionId` der Resource. | +| `txn` | URI, die den Vorgang identifiziert | Als "Transaction Identifier" wird die Vorgangsreferenz `caseId` angegeben. | +| `events` | JSON-Objekt der Events in diesem Event-Token | Das Objekt `events` enthält genau ein Ereignis zu einem logischen Sachverhalt bzw. Gesamtereignis, wie bspw. der Versendung einer Einreichung durch den Sender. Dieses Objekt beinhaltet immer zwingend eine URI, die das jeweilige Gesamtereignis eindeutig identifiziert. Das Objekt der URI des Gesamtereignisses kann leer sein oder weitergehende Informationen beinhalten (Siehe [Ereignisse](./events.mdx)) | :::note SET Beispiel diff --git a/docs/receiving/process-and-acknowledge.mdx b/docs/receiving/process-and-acknowledge.mdx index 8b54cdd3763a336239aa8095c72456429c74169f..038f85849960835092a6ba64da39a6f9dbf8b6b7 100644 --- a/docs/receiving/process-and-acknowledge.mdx +++ b/docs/receiving/process-and-acknowledge.mdx @@ -47,7 +47,7 @@ Weiterhin ist es notwendig, dass die Id der Einreichung (`submissionID`) und des String transactionId = "case:f73d30c6-8894-4444-8687-00ae756fea90"; // caseId ``` - Die Payload- und Header-Attribute des SET müssen wie oben beschrieben definiert werden (siehe markierte Zeilen). + Die Payload- und Header-Attribute des SET müssen wie oben beschrieben definiert werden (siehe markierte Zeilen). Mehr Informationen zu dem SET Aufbau finden Sie unter [SET Erzeugen](../getting-started/event-log/set-creation.mdx) Im dritten markierten Block wird das SET mit dem Schlüssel signiert. Anschließend kann der serialisierte Wert an den Endpunkt <ApiLink api="submission-api" to="/v1/cases/{caseId}/events" withMethod="post" /> gesendet werden. ```java {3-10,12-16,22-24}