Skip to content
Snippets Groups Projects
Commit c4186246 authored by David Schwarzmann's avatar David Schwarzmann
Browse files

refactor: Format markdown and add background to the event log

parent de784dac
No related branches found
No related tags found
1 merge request!9Followup for Event tokens
This commit is part of merge request !9. Comments created here will be created in the context of that merge request.
Hide whitespace changes
Inline Side-by-side
docs/details/event-log.md deleted 100644 → 0
+ 0
− 111
View file @ de784dac
# Event Log
Im Ereignisprotokoll werden relevante Ereignisse (events) aufgezeichnet.
Beim Abruf des Ereignisprotokoll liefert die API ein Array von JSON Web Token (JWT) gemäß [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519).
Der JWT ist einen Security Event Token (SET) gemäß [RFC 8417](https://datatracker.ietf.org/doc/html/rfc8417).
Bei der Erstellung und Prüfung der Security Event Token MÜSSEN die [Vorgaben für kryptographische Verfahren](./crypto.md) beachtet werden.
## Aufbau eines Security Event Token (SET)
### Header
Alle generierten Security Event Tokens MÜSSEN den Vogaben 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. |
**Beispiel**
```json
{
"typ": "secevent+jwt",
"alg": "PS512",
"kid": "dd0409e5-410e-4d98-85b6-f81a40b8d980"
}
```
### Payload
Im Payload des signierten SET MÜSSEN mindestens die folgenden [standartisierten Felder](https://www.iana.org/assignments/jwt/jwt.xhtml) gesetzt sein:
| Feld | Inhalt | Erläuterung |
| ------ | ----------------------------------------- | ------------------------------------------------------------ |
| iss | Identifizierungsmerkmal des Token Issuers | Dient dazu, um herauszufinden, wer den Token ausgestellt hat. Für vom Zustelldienst ausgestellt SET wird die Basis-Adresse (API-URL) verwendet. Für die antragsendenden und -empfangenden Systeme wird empfohlen, auch eine dem System zugeordnete URL zu verwenden. Sofern das System keine zur Identifikation nutzbare URL hat, ist eine andere eindeutige URI zu verwenden. |
| iat | Timestamp (UNIX-Format) | Zeitpunkt der Ausstellung des SET. |
| jti | UUID des Token | Die JWT ID ist eine eindeutige ID des SET bzw. JWT. Es wird eine zufällige UUID verwendet. |
| sub | URI, die den Gegenstand des SET identifiziert. | Das Subject eines SWT ist entweder eine Übertragung (submission), eine Antwort (reply) oder eine Vorgangsreferenz (case id). Die Angabe besteht jeweils aus Typ und ID (UUID) der Resource. |
| events | Dict der Events in diesem Event-Token | Das Objekt "events" enthält immer genau ein Event. Das Event selbst ist wieder ein Objekt, welches derzeit immer leer ist. Events könnten in Zukunft um Zusatzinformationen ergänzt werden. Siehe [Liste der möglichen Events](./status.md) |
| txn | URI, die den Vorgang identifiziert | Als "Transaction Identifier" wird die Vorgangsreferenz angegeben, auch wenn das Subject selbst die Vorgangsreferenz ist. In diesem Fall sind Subject und Transaction Identifier gleich. |
**Hinweis:** Das Ereignisprotokoll darf keine personenbezogenen oder -beziehbaren Daten enthalten.
**Wichtig**: Ohne Prüfung der Signatur des Security Event Token DARF NICHT auf die Korrektheit (Integrität) der Inhalte des SET-Payload vertraut werden.
**Beispiel**
```json
{
"iss": "https://api.fitko.de/fit-connect/",
"iat": 1622796532,
"jti": "0BF6DBF6-CE7E-44A3-889F-82FE74C3E715",
"sub": "submission:F65FEAB2-4883-4DFF-85FB-169448545D9F",
"events": {
"https://schema.fitko.de/fit-connect/events/accept-submission": {}
},
"txn": "case:F73D30C6-8894-4444-8687-00AE756FEA90"
}
```
## Beispiel
> **Hinweis:** Folgende Punkte in dieser Dokumentation sind noch nicht final:
- Die in den Beispielen verwendete API-Adresse `https://api.fitko.de/fit-connect/` ist durch die Basis-Adresse der real verwendeten API zu ersetzen.
Der Sender ruft die Operation "Get Event Log" auf, z.B. `https://api.fitko.de/fit-connect/submissions/F65FEAB2-4883-4DFF-85FB-169448545D9F/log`.
Das Ergebnis könnte wie folgt aussehen.
```json
{
"eventLog": [
"eyJraWQiOiJkZDA0MDllNS00MTBlLTRkOTgtODViNi1mODFhNDBiOGQ5ODAiLCJ0eXAiOiJzZWNldmVudCtqd3QiLCJhbGciOiJQUzUxMiJ9.ewogICJpc3MiOiAiaHR0cHM6Ly9hcGkuZml0a28uZGUvZml0LWNvbm5lY3QvIiwKICAiaWF0IjogMTYyMjc5NDMxOSwKICAianRpIjogIkVEQ0ZCRjIxLTVCMTYtNEQwNi05OUQwLURDNEMyNkY0RkI5RSIsCiAgInN1YiI6ICJzdWJtaXNzaW9uOkY2NUZFQUIyLTQ4ODMtNERGRi04NUZCLTE2OTQ0ODU0NUQ5RiIsCiAgImV2ZW50cyI6IHsKICAgICJodHRwczovL3NjaGVtYS5maXRrby5kZS9maXQtY29ubmVjdC9ldmVudHMvY3JlYXRlLXN1Ym1pc3Npb24iOiB7fQogIH0sCiAgInR4biI6ICJjYXNlOkY3M0QzMEM2LTg4OTQtNDQ0NC04Njg3LTAwQUU3NTZGRUE5MCIKfQ.TQBR_CBsoULi3cGaGg4oqFelQ9GVn8G-cNokzTVDZgZf4D7x_8wjsDcgTd0aamiy8ErlnV1xoAoDcPw81vajrBCaYgf9KI4sNhsW78jlDi_ywK04YhFbkvloDMioGf_5zCNTBreN9bTnU_VYuWB23R_YrYGi2exONft-ZReN_crEvDaKLdG9hqnaCRFwKJ1t8TbLvIyBKLqQYEqP0Oh6m3WA9IRz3EB41S-PZgJCIzmz_GvXdRvw_1B8A_Q7aHr2SQ6Dc-c406UJ5P_7FuypE6tLyuYf5GkmFZSauQ51H4LLl8pLrsW2PJJ28cMavOEx0AWoRLwB7yKK5bAGtcALWw-0W7Wmw1QEX3DZGTpXbEUM0U_7iXeEFrdtfCCbFPMVbmlK-b66IyKK_6yeaOAEjQvCUOrALfa2sSOS6RWiNOKyA1l1L29VoIBXgQ8np72NMV8-AP7UnQO1NPBghBM6LW6tcXceWeP8ayy4eEaZQ639pqH4TJRRkQqnuoTeADpYL9sX2hM9173O4abWiE-Z8zW2AQ1jhUvVXJ8w9ddtMIyjZJZOqoy3TbHxUYpn4UqbedlDyahpUiKCT7-qU2jOjeXAXEPQvWlSzLigNtFvYCEq-fOe1lpeNktoQQrC3Y-szk2vNj5fT_KmJY1QG1bhyrUMoGbA-pe45c-FcCE7ErQ",
"eyJraWQiOiJkZDA0MDllNS00MTBlLTRkOTgtODViNi1mODFhNDBiOGQ5ODAiLCJ0eXAiOiJzZWNldmVudCtqd3QiLCJhbGciOiJQUzUxMiJ9.ewogICJpc3MiOiAiaHR0cHM6Ly9hcGkuZml0a28uZGUvZml0LWNvbm5lY3QvIiwKICAiaWF0IjogMTYyMjc5NTczMiwKICAianRpIjogIjkwRDlCMjlELUMwNUYtNEYwMy04MUMwLUUyMzMxMTZDNTZEOSIsCiAgInN1YiI6ICJzdWJtaXNzaW9uOkY2NUZFQUIyLTQ4ODMtNERGRi04NUZCLTE2OTQ0ODU0NUQ5RiIsCiAgImV2ZW50cyI6IHsKICAgICJodHRwczovL3NjaGVtYS5maXRrby5kZS9maXQtY29ubmVjdC9ldmVudHMvc3VibWl0LXN1Ym1pc3Npb24iOiB7fQogIH0sCiAgInR4biI6ICJjYXNlOkY3M0QzMEM2LTg4OTQtNDQ0NC04Njg3LTAwQUU3NTZGRUE5MCIKfQ.THmHiZoYEMyyWCu2R4nEJtvgtB5PF0KAqtfu_Z-yVjfjSkXW7TtZnX96UAeCGsjpxkBJvXTXAgSB5n378KjZXebAtI7nbFE0gYgt3fwmxmpJitA-4e8v6KfvhwNcdqJHLKDzYRMq_yw7UiwLx1Cxz6nBiOKfR4piL707muKXTgD7DuP0kv-c6V9dGNQ4KzT_sJP5zDWogEzGWSVaLaJZrmDZHoUZMZ6C9kI7SvC-A7Q0ROkFznU_cpjjEAIG74_YCiICvjr91ueQWTdNyc1DBvxpEBtBWq6nWPTg0d91iQlhPUgNKbmC4QtG_tFctTYhX7stO-JbL-4VnAQjQHD5uw4SvvpPrTN4Z3Wz2IjMm8-ClI9imGKThfAqwTaWtJv7Bn_FDiN_nEuGyN2of-M2vZWa-DlZ2iPFct6ESp9PumaO_pIF5cUrX4IBoe3fcmg788-ClReytCMjD13uPVOVoIb3yimUdupOUROxb3MITowHP2-YG1gWqhQp22XSQXktugDHWezAuN0xuimwAJq_OvyoDxj4lsnn6BQkqZYdqD0hJghwqZIytg8PlIi76Cdvh8NFgVw48xZ0WUOFvBPJO2Qe8PiTSVX_P9CIIWxsKlYwg8vJ226qi0eYfD70ynjBDQIPmsOOSut6bFKgOLBFa9ZvCy6HmhyLa-EsgLhS4uc",
"eyJraWQiOiJkZDA0MDllNS00MTBlLTRkOTgtODViNi1mODFhNDBiOGQ5ODAiLCJ0eXAiOiJzZWNldmVudCtqd3QiLCJhbGciOiJQUzUxMiJ9.ewogICJpc3MiOiAiaHR0cHM6Ly9hcGkuZml0a28uZGUvZml0LWNvbm5lY3QvIiwKICAiaWF0IjogMTYyMjc5NjUzMiwKICAianRpIjogIjBCRjZEQkY2LUNFN0UtNDRBMy04ODlGLTgyRkU3NEMzRTcxNSIsCiAgInN1YiI6ICJzdWJtaXNzaW9uOkY2NUZFQUIyLTQ4ODMtNERGRi04NUZCLTE2OTQ0ODU0NUQ5RiIsCiAgImV2ZW50cyI6IHsKICAgICJodHRwczovL3NjaGVtYS5maXRrby5kZS9maXQtY29ubmVjdC9ldmVudHMvYWNjZXB0LXN1Ym1pc3Npb24iOiB7fQogIH0sCiAgInR4biI6ICJjYXNlOkY3M0QzMEM2LTg4OTQtNDQ0NC04Njg3LTAwQUU3NTZGRUE5MCIKfQ.blxz8Tw_Sl8_tomcqxezamX_DVGyGiu61iYGv3mA3yVLLSDlPscjcHm_MCNm5iq-ODUk-FCW1ljOexN2czZJic8wvLhWhcUt8U2kkkjis-CWz4oqhuB4ynAj7Yyn4H4xkLoH7Y6k9pqW9P2mN7984o_578mJJ4mQSNEGcPr_BDbRc2nUKcupG7iS-hx6VTjrRTP7LGPyOblDB8oL_QyT9qY0US7PT35QgiraUSK3RWhDpj6C0I4bOV5cQeSqlXT2xIfeO3sUPeWLYVmGjuB8QWvDsniKz6JqRN-v39FrAppsOufdiRim36wtBZt9o-3txjtz5wu0_eSfjOueGJbfqAeWsbd2TYwZtL-7Z-MPfoe3XInDNmmTfxo4KXkF1GkRnGnjniwrWBHeh18A04NNHYcX-vsoijEreqDN2lEKwks3pDK5Twe5O9RxJ0cYB8oeKB55rJzs15pfla69qVn9zFvCAc_ji_9WaAa_mIG0zimMucG3qA0KrUww88FaS4heh5-Gs1Ik35QoUOCCa7ZMJMKxYArFCgUqHw-gX60U5mp4hy7tVe3hD-RxIRnlTIkEkHgDGmslVc1t8fC9oPgljQirPcTIeWhVyLmk6rJLgR5nqizujz3hDUCdBuRF43fS6qedmYfHq1MyakJzEFe2ht1rpGw4ftAt0kcOBOf2jyQ"
]
}
```
Im Log dieser Submission wurden drei Events aufgezeichnet.
Das erste SET hat folgenden Payload.
```json
{
"iss": "https://api.fitko.de/fit-connect/",
"iat": 1622794319,
"jti": "EDCFBF21-5B16-4D06-99D0-DC4C26F4FB9E",
"sub": "submission:F65FEAB2-4883-4DFF-85FB-169448545D9F",
"events": {
"https://schema.fitko.de/fit-connect/events/create-submission": {}
},
"txn": "case:F73D30C6-8894-4444-8687-00AE756FEA90"
}
```
In dem SET ist folgende Information abgelegt:
- Er wurde vom Zustelldienst https://api.fitko.de/fit-connect/ ausgestellt (iss = issuer)
- Er wurde am 04.06.2021 um 10:11:59 (Unixzeit 1622794319) aufgezeichnet (iat = issued at)
- Er hat die eindeutige ID `EDCFBF21-5B16-4D06-99D0-DC4C26F4FB9E` (jti = JWT ID)
- Er betrifft die Submission `F65FEAB2-4883-4DFF-85FB-169448545D9F` (sub = subject)
- Die Submission wurde angelegt "createSubmission" (events)
- Die Submission gehört zur Vorgangsreferenz (case) `F73D30C6-8894-4444-8687-00AE756FEA90`
## Verarbeitung des Ereignisprotokolls
Um die Informationen des Security Event Log abzurufen gehen Sie wie folgt vor:
### 1. Abruf des Ereignisprotokolls über die API
### 2. Decodierung jedes SET innerhalb des Arrays "securityEventLog"
Übergeben Sie den JWT an die Bibliothek.
Die Bibliothek kümmert sich automatisch um die Dekodierung und Validierung des JWT.
Je verwendeter Bibliothek unterscheidet sich der Zugriff auf den Payload des JWT/SET.
Wenn ein Onlinedienst den Eventlog darstellen möchte, muss dieser sicherstellen, das die im Eventlog enthaltenen Einträge über eine valide Signatur verfügen und falls sich Einträge mit einer invaliden Signatur im Eventlog befinden, muss das für den User erkennbar sein.
docs/getting-started/event-log.mdx 0 → 100644
+ 290
− 0
View file @ c4186246
---
title: Event Log
---
import ApiLink from '@site/src/components/ApiLink'
Im Ereignisprotokoll (Event Log) werden relevante Ereignisse (events) aufgezeichnet.
Beim Abruf des Ereignisprotokolls liefert die API ein Array von JSON Web Token (JWT) gemäß [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519).
Der JWT ist einen Security-Event-Token (SET) gemäß [RFC 8417](https://datatracker.ietf.org/doc/html/rfc8417).
Wie mit den Security-Event-Token (SET) umgegangen wird, wird in diesem Abschnitt beschrieben.
## Hintergrund
Für die Übermittlung von Einreichungen zwischen Sendern und Empfängern soll gewährleistet werden, dass alle Schritte nachweissicher dokumentiert werden, um im Streitfall den Ablauf eines erfolgten Übermittlungsvorgang zweifelsfrei zu dokumentieren.
Zudem sollen diese Nachweise außerhalb der API und der damit verbundenen Systeme genutzt werden können, damit diese Dritten einfach zur Verfügung gestellt werden können.
SETs erfüllen diese Anforderungen durch folgende Merkmale:
- Für jedes SET wird ein eindeutiger Herausgeber definiert (`Iss`)
- Jedes SET kann eindeutig einem konkreten fachlichen Kontext zugeordnet werden (`Sub`)
- Mehrere SETs aus unterschiedliche fachlichen Kontexten können zu einem gemeinsamen Vorgang zusammengeführt werden (`txn`)
- SETs können für unterschiedliche Ereignisse ausgeprägt werden und innerhalb dieser Ereignisse können Detailinformationen ergänzt werden, die diese Ereignisse näher beschreiben
- Über ein Zeitstempel (`iat`) können diese Ereignisse zudem konkreten Zeitpunkt zugeordnet werden
- Durch eine Signatur im JWS Format wird sichergestellt, dass alle SETs integritätsgesichert ist und eindeutig dem Schlüsselinhaber als Ersteller zugeordnet werden können.
Die Nutzung ist aber nicht auf die Klärung von Streitigkeiten zu technischen Übermittlungen beschränkt. SETs können aufgrund dieser Merkmale unter anderem auch für folgende Zwecke genutzt werden:
- Als Auditinstrument, dass bei Prüfungen oder Sicherheitsvorfällen durch Dritte (bspw. Datenschutz- oder Sicherheitsbeauftragte) genutzt wird,
- oder als Nachweis für den Start von Fristen in Verwaltungsverfahren, die in der Regel dann beginnen, wenn eine zuständige Stelle Kenntnis von einer Einreichung hat oder wenn diese Einreichung in den Hoheitsbereich der empfangenden Stelle gelangt.
In der Submission API werden SETs durch den Zustelldienst und das empfangende System erstellt.
Während die SETs des Zustelldienstes dazu dienen, die korrekte Übermittlung an den Zustelldienst und die Inkenntnissetzung von empfangende Systemen über neue Einreichungen dokumentieren, sollen SETs des empfangenden Systems die Bestätigung oder Ablehnung der technische Verarbeitbarkeit einer Einreichung nachweisen.
## Events
Das folgende Statusdiagramm zeigt die Status und Ereignisse einer Einreichung. Die Status sind als orange Ovale dargestellt.
Rechtecke stehen für Ereignisse. Blau dargestellte Ereignisse werden vom Zustelldienst, grüne vom empfangenden System erstellt und signiert.
![Statusdiagramm](/images/status/status.svg)
Das Akzeptieren oder Zurückweisen von Einreichungen auf einer rein technischen Ebene und trifft keine Aussage über die fachliche Korrektheit der Einreichungen.
Gründe für technische Rückweisungen wären beispielsweise Probleme bei der Entschlüsselung oder Validierungsfehler der Datenstrukturen.
In der folgenden Tabelle sind die möglichen Ereignisse, ihre Beschreibungen und die Autoren aufgeführt und beschrieben.
| Event | Autor | Bedeutung |
|-----------------------------------------------------------------|---------------------|-------------------------------|
| `https://schema.fitko.de/fit-connect/events/create-submission` | Zustelldienst | Die Einreichung wurde durch den Sender angelegt. |
| `https://schema.fitko.de/fit-connect/events/submit-submission` | Zustelldienst | Die Einreichung wurde durch den Sender abgesendet. |
| `https://schema.fitko.de/fit-connect/events/notify-submission` | Zustelldienst | Der Empfänger wurde per Webhook über die Einreichung informiert. |
| `https://schema.fitko.de/fit-connect/events/forward-submission` | Empfangendes System | Ein nachgelagertes System hat die Einreichung zur Weiterleitung übernommen. |
| `https://schema.fitko.de/fit-connect/events/reject-submission` | Empfangendes System | Die Einreichung wurde durch den Empfänger zurückgewiesen. |
| `https://schema.fitko.de/fit-connect/events/accept-submission` | Empfangendes System | Die Einreichung wurde durch den Empfänger akzeptiert. |
| `https://schema.fitko.de/fit-connect/events/delete-submission` | Zustelldienst | Die Einreichung wurde durch den Zustelldienst gelöscht. |
## Prüfung eines Security-Event-Token (SET) {#set-validation}
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).
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 |
|--------|------------------------------------------------|---------------------------------------------------------------|
| 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. |
| jti | UUID des Token | Die JWT ID ist eine eindeutige ID des SET bzw. JWT. Es wird eine zufällige UUID verwendet. |
| 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. |
| events | JSON-Objekt der Events in diesem Event-Token | Das Objekt "events" beschreibt eine oder mehrere Ereignisse 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. |
| txn | URI, die den Vorgang identifiziert | Als "Transaction Identifier" wird die Vorgangsreferenz `caseId` angegeben. |
:::note SET Beispiel
```json title="SET Header"
{
"typ": "secevent+jwt"
"alg": "PS512",
"kid": "dd0409e5-410e-4d98-85b6-f81a40b8d980",
}
```
```json title="SET Payload"
{
"iss": "https://api.fitko.de/fit-connect/",
"iat": 1622796532,
"jti": "0BF6DBF6-CE7E-44A3-889F-82FE74C3E715",
"sub": "submission:F65FEAB2-4883-4DFF-85FB-169448545D9F",
"events": {
"https://schema.fitko.de/fit-connect/events/accept-submission": {}
},
"txn": "case:F73D30C6-8894-4444-8687-00AE756FEA90"
}
```
:::
Im folgenden Beispiel kann die allgemeine Struktur eines SET über folgenden Code validiert werden.
```java
SignedJWT securityEventToken = SignedJWT.parse(eventToken);
JWTClaimsSet payload = securityEventToken.getJWTClaimsSet();
UUID keyId = UUID.fromString(securityEventToken.getHeader().getKeyID());
validateTokenStructure(securityEventToken);
verifyZustelldienstSignature(securityEventToken, keyId)
// bzw.
verifyClientSignature(securityEventToken, keyId);
```
```java
boolean validateTokenStructure(SignedJWT securityEventToken) {
try {
validateHeader(signedJWT.getHeader());
validatePayload(signedJWT.getJWTClaimsSet());
} catch (ParseException e) {
throw new RuntimeException("The payload of the SET could not get parsed properly.");
}
}
private void validateHeader(JWSHeader header) {
validateTrueOrElseThrow(header.getAlgorithm() == JWSAlgorithm.PS512, "The provided alg in the SET header is not allowed.");
validateTrueOrElseThrow(header.getType().toString().equals("secevent+jwt"), "The provided typ in the SET header is not secevent+jwt");
validateTrueOrElseThrow(header.getKeyID() != null, "The kid the SET was signed with is not set.");
}
private void validatePayload(JWTClaimsSet payload) throws ParseException {
validateTrueOrElseThrow(payload.getClaim("iss") != null, "The claim iss is missing in the payload of th SET.");
validateTrueOrElseThrow(payload.getClaim("iat") != null, "The claim iat is missing in the payload of th SET.");
validateTrueOrElseThrow(payload.getClaim("jti") != null, "The claim jti is missing in the payload of th SET.");
validateTrueOrElseThrow(payload.getClaim("sub") != null, "The claim sub is missing in the payload of th SET.");
validateTrueOrElseThrow(payload.getClaim("txn") != null, "The claim txn is missing in the payload of the SET.");
validateTrueOrElseThrow(payload.getClaim("events") != null, "The claim events is missing in the payload of the SET.");
validateTrueOrElseThrow(payload.getJSONObjectClaim("events").keySet().size() == 1, "Only exactly one event is allowed.");
String uuidPattern = "[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}";
String subject = payload.getStringClaim("sub");
validateTrueOrElseThrow(subject.matches("(submission|case|reply):" + uuidPattern), "The provided subject does not match the allowed pattern.");
String transactionId = payload.getStringClaim("txn");
validateTrueOrElseThrow(transactionId.matches("case:" + uuidPattern), "The provided txn does not match the allowed pattern.");
}
private void validateTrueOrElseThrow(boolean expression, String msg) {
if (!expression) {
throw new RuntimeException(msg);
}
}
```
### Signaturprüfung eines vom Zustelldienst ausgestellten SET
Um die Signatur eines SET zu überprüfen, welches vom Zustelldienst ausgestellt wurde, ist es notwendig auf die verwendeten Schlüssel zugreifen zu können.
Der Zustelldienst stellt ein JSON Web Key (JWK) Set öffentlich zugänglich unter der URL `/.well-known/jwks.json` bereit.
Ein Beispiel für ein JWK Set ist in folgendem Ausschnitt dargestellt:
```json
{
"keys": [
{
"alg": "PS512",
"e": "AQAB",
"key_ops": [
"verify"
],
"kid": "6508dbcd-ab3b-4edb-a42b-37bc69f38fed",
"kty": "RSA",
"n": "65rmDz943SDKYWt8KhmaU…ga16_y9bAdoQJZRpcRr3_v9Q"
},
{
"alg": "PS512",
"e": "AQAB",
"key_ops": [
"verify"
],
"kid": "14a70431-01e6-4d67-867d-d678a3686f4b",
"kty": "RSA",
"n": "wnqKgmQHSqJhvCfdUWWyi8q…yVv3TrQVvGtsjrJVjvJR-s_D7rWoBcJVM"
}
]
}
```
Mit diesem JWK Set kann die Signatur eines Security-Event-Tokens überprüft werden.
Hierfür muss der Schlüssel mit der passenden `kid` aus dem Header des SET’s im JWK Set gesucht werden.
Dann kann man mit diesem und einer entsprechenden Bibliothek eine Signaturprüfung durchführen.
Im folgenden Beispiel wird die Bibliothek [nimbus-jose-jwt](https://connect2id.com/products/nimbus-jose-jwt) für die Prüfung genutzt.
```java
static final ZUSTELLDIENST_BASE_URL = "https://zustelldienst.example.com";
boolean verifyZustelldienstSignature(SignedJWT securityEventToken, String keyId) {
JWKSet jwks = JWKSet.load(ZUSTELLDIENST_BASE_URL + "/.well-known/jwks.json");
JWK publicKey = jwks.getKeyByKeyId(keyId)
if (publicKey.getAlgorithm() != JWSAlgorithm.PS512) {
throw new RuntimeException("The key specified for signature verification doesn't use/specify PS512 as algorithm.")
}
JWSVerifier jwsVerifier = new RSASSAVerifier(publicKey.toRSAKey());
return signedJWT.verify(jwsVerifier);
}
```
### 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.
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
- kid: `dd0409e5-410e-4d98-85b6-f81a40b8d980`
- submissionId: `F65FEAB2-4883-4DFF-85FB-169448545D9F`
```json title="SET Header"
{
"typ": "secevent+jwt"
"alg": "PS512",
"kid": "dd0409e5-410e-4d98-85b6-f81a40b8d980",
}
```
```json title="SET Payload"
{
"iss": "https://api.fitko.de/fit-connect/",
"iat": 1622796532,
"jti": "0BF6DBF6-CE7E-44A3-889F-82FE74C3E715",
"sub": "submission:F65FEAB2-4883-4DFF-85FB-169448545D9F",
"events": {
"https://schema.fitko.de/fit-connect/events/accept-submission": {}
},
"txn": "case:F73D30C6-8894-4444-8687-00AE756FEA90"
}
```
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"
GET /submissions/F65FEAB2-4883-4DFF-85FB-169448545D9F
{
"destinationId": "92f2f581-c89d-44a5-b834-1fe3f6fa48d5",
// ...
}
```
Über diese kann dann das JWK Set der zugehörigen Destination über ein <ApiLink to="/destinations/{destinationId}" /> abgefragt werden.
In dem Attribut `publicKeys` ist das JWK Set abgelegt.
In den darin enthaltenen Schlüsseln kann dann der Schlüssel mit `kid` von oben gesucht und für die Verifikation genutzt werden.
```http title="Abfrage der Destination"
GET /destinations/92f2f581-c89d-44a5-b834-1fe3f6fa48d5
{
"publicKeys": {
"keys": [
// ...
]
},
// ...
}
```
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.
```java
boolean verifyClientSignature(SignedJWT securityEventToken, String keyId) {
JWK publicKey = getKeyForSET(securityEventToken, keyId);
if (publicKey.getAlgorithm() != JWSAlgorithm.PS512) {
throw new RuntimeException("The key specified for signature verification doesn't use/specify PS512 as algorithm.")
}
JWSVerifier jwsVerifier = new RSASSAVerifier(publicKey.toRSAKey());
return signedJWT.verify(jwsVerifier);
}
```
docs/getting-started/receiving/process-and-acknowledge.mdx
+ 121
− 1
View file @ c4186246
---
sidebar_position: 8
title: 🚧 Empfangsbestätigung
title: Empfangsbestätigung
---
import Tabs from '@theme/Tabs'
import TabItem from '@theme/TabItem'
import ApiLink from '@site/src/components/ApiLink'
Der letzte Schritt zum Empfang einer Einreichung ist die Bestätigung des Empfangs und damit auch der Gültigkeit der Einreichung.
Mit Gültigkeit ist hier gemeint, dass alle Informationen erfolgreich heruntergeladen, entschlüsselt und im Falle der Metadaten validiert werden konnten.
Wie auf der [Event Log Übersichtsseite](../event-log.mdx#events) zu sehen, gibt es für ein empfangendes System ein festes Set an Events, die dem Zustelldienst gesendet werden können.
| Event | Autor | Bedeutung |
|-----------------------------------------------------------------|---------------------|-------------------------------|
| `https://schema.fitko.de/fit-connect/events/forward-submission` | | Ein nachgelagertes System hat die Einreichung zur Weiterleitung übernommen. |
| `https://schema.fitko.de/fit-connect/events/reject-submission` | Empfangendes System | Die Einreichung wurde durch den Empfänger zurückgewiesen. |
| `https://schema.fitko.de/fit-connect/events/accept-submission` | Empfangendes System | Die Einreichung wurde durch den Empfänger akzeptiert. |
Um diese Events bzw. ein entsprechendes Event korrekt an den Zustelldienst zu versenden, muss es in Form eines SETs an diesen gesendet werden.
## Erstellung und Versand eines Security-Event-Token (SET)
Um ein SET zu erstellen, MUSS ein JWK verwendet werden, der den [Vorgaben für Signaturschlüssel](../../details/crypto.md#signature-key) entspricht.
Weiterhin ist es notwendig, dass die Id der Einreichung und des zugehörigen Vorgangs bekannt ist.
<Tabs
defaultValue="java"
values={[
{ label: 'Java', value: 'java', },
{ label: 'C#', value: 'csharp', },
]
}>
<TabItem value="java">
```java title=Annahmen
JWK key;
String subject = "submission:f65feab2-4883-4dff-85fb-169448545d9f";
String event ="https://schema.fitko.de/fit-connect/events/accept-submission";
String transactionId = "case:f73d30c6-8894-4444-8687-00ae756fea90";
```
Die Payload- und Header-Attribute des SET müssen wie oben beschrieben definiert werden (siehe markierte Zeilen).
Im dritten markierten Block wird das SET mit dem Schlüssel signiert und danach kann der serialisierte Wert an den [Zustelldienst](../../apis/delivery-service.mdx#post-/submissions/-submissionId-/events) gesendet werden.
```java {3-10,12-16,22-24}
try {
JWSSigner signer = new RSASSASigner(key.toRSAKey());
JWTClaimsSet claimsSet = new JWTClaimsSet.Builder()
.issuer("https://my-custom-identifiable-service.domain")
.issueTime(new Date())
.jwtID(UUID.randomUUID().toString())
.subject(subject)
.claim("events", Map.of(event, Map.of()))
.claim("txn", transactionId)
.build();
JWSHeader header = JWSHeader.parse(Map.of(
"typ", "secevent+jwt",
"kid", key.getKeyID(),
"alg", "PS512"
));
SignedJWT signedJWT = new SignedJWT(
header,
claimsSet);
signedJWT.sign(signer);
String signedAndSerializedSET = signedJWT.serialize(); // => SET, serialized as Base64 encoded string
} catch (JOSEException e) {
throw new RuntimeException("Could not generate SET");
}
```
</TabItem>
</Tabs>
Dies kann dann über ein <ApiLink to="/submissions/{submissionId}/events" withMethod="post" /> erreicht werden.
Hier wird das Event über den Request-Body übertragen und vom Zustelldienst syntaktisch und auf eine korrekte Signatur geprüft.
Sind alle Prüfungen erfolgreich durchlaufen, wird das SET im Event Log abgespeichert und der Zustand der Einreichung abhängig vom Event geändert.
## Event Log abfragen
Der Event Log einer Einreichung kann über <ApiLink to="/submissions/{submissionId}/events" /> abgefragt werden.
Hierbei wird der Event Log der Einreichung zurückgeliefert, der die verschiedenen Statusübergänge bzw. abgelegten Ereignisse beinhaltet.
Das Ergebnis könnte wie folgt aussehen:
```json
{
"eventLog": [
"eyJraWQiOiJkZDA0MDllNS00MTBlLTRkOTgtODViNi1mODFhNDBiOGQ5ODAiLCJ0eXAiOiJzZWNldmVudCtqd3QiLCJhbGciOiJQUzUxMiJ9.ewogICJpc3MiOiAiaHR0cHM6Ly9hcGkuZml0a28uZGUvZml0LWNvbm5lY3QvIiwKICAiaWF0IjogMTYyMjc5NDMxOSwKICAianRpIjogIkVEQ0ZCRjIxLTVCMTYtNEQwNi05OUQwLURDNEMyNkY0RkI5RSIsCiAgInN1YiI6ICJzdWJtaXNzaW9uOkY2NUZFQUIyLTQ4ODMtNERGRi04NUZCLTE2OTQ0ODU0NUQ5RiIsCiAgImV2ZW50cyI6IHsKICAgICJodHRwczovL3NjaGVtYS5maXRrby5kZS9maXQtY29ubmVjdC9ldmVudHMvY3JlYXRlLXN1Ym1pc3Npb24iOiB7fQogIH0sCiAgInR4biI6ICJjYXNlOkY3M0QzMEM2LTg4OTQtNDQ0NC04Njg3LTAwQUU3NTZGRUE5MCIKfQ.TQBR_CBsoULi3cGaGg4oqFelQ9GVn8G-cNokzTVDZgZf4D7x_8wjsDcgTd0aamiy8ErlnV1xoAoDcPw81vajrBCaYgf9KI4sNhsW78jlDi_ywK04YhFbkvloDMioGf_5zCNTBreN9bTnU_VYuWB23R_YrYGi2exONft-ZReN_crEvDaKLdG9hqnaCRFwKJ1t8TbLvIyBKLqQYEqP0Oh6m3WA9IRz3EB41S-PZgJCIzmz_GvXdRvw_1B8A_Q7aHr2SQ6Dc-c406UJ5P_7FuypE6tLyuYf5GkmFZSauQ51H4LLl8pLrsW2PJJ28cMavOEx0AWoRLwB7yKK5bAGtcALWw-0W7Wmw1QEX3DZGTpXbEUM0U_7iXeEFrdtfCCbFPMVbmlK-b66IyKK_6yeaOAEjQvCUOrALfa2sSOS6RWiNOKyA1l1L29VoIBXgQ8np72NMV8-AP7UnQO1NPBghBM6LW6tcXceWeP8ayy4eEaZQ639pqH4TJRRkQqnuoTeADpYL9sX2hM9173O4abWiE-Z8zW2AQ1jhUvVXJ8w9ddtMIyjZJZOqoy3TbHxUYpn4UqbedlDyahpUiKCT7-qU2jOjeXAXEPQvWlSzLigNtFvYCEq-fOe1lpeNktoQQrC3Y-szk2vNj5fT_KmJY1QG1bhyrUMoGbA-pe45c-FcCE7ErQ",
"eyJraWQiOiJkZDA0MDllNS00MTBlLTRkOTgtODViNi1mODFhNDBiOGQ5ODAiLCJ0eXAiOiJzZWNldmVudCtqd3QiLCJhbGciOiJQUzUxMiJ9.ewogICJpc3MiOiAiaHR0cHM6Ly9hcGkuZml0a28uZGUvZml0LWNvbm5lY3QvIiwKICAiaWF0IjogMTYyMjc5NTczMiwKICAianRpIjogIjkwRDlCMjlELUMwNUYtNEYwMy04MUMwLUUyMzMxMTZDNTZEOSIsCiAgInN1YiI6ICJzdWJtaXNzaW9uOkY2NUZFQUIyLTQ4ODMtNERGRi04NUZCLTE2OTQ0ODU0NUQ5RiIsCiAgImV2ZW50cyI6IHsKICAgICJodHRwczovL3NjaGVtYS5maXRrby5kZS9maXQtY29ubmVjdC9ldmVudHMvc3VibWl0LXN1Ym1pc3Npb24iOiB7fQogIH0sCiAgInR4biI6ICJjYXNlOkY3M0QzMEM2LTg4OTQtNDQ0NC04Njg3LTAwQUU3NTZGRUE5MCIKfQ.THmHiZoYEMyyWCu2R4nEJtvgtB5PF0KAqtfu_Z-yVjfjSkXW7TtZnX96UAeCGsjpxkBJvXTXAgSB5n378KjZXebAtI7nbFE0gYgt3fwmxmpJitA-4e8v6KfvhwNcdqJHLKDzYRMq_yw7UiwLx1Cxz6nBiOKfR4piL707muKXTgD7DuP0kv-c6V9dGNQ4KzT_sJP5zDWogEzGWSVaLaJZrmDZHoUZMZ6C9kI7SvC-A7Q0ROkFznU_cpjjEAIG74_YCiICvjr91ueQWTdNyc1DBvxpEBtBWq6nWPTg0d91iQlhPUgNKbmC4QtG_tFctTYhX7stO-JbL-4VnAQjQHD5uw4SvvpPrTN4Z3Wz2IjMm8-ClI9imGKThfAqwTaWtJv7Bn_FDiN_nEuGyN2of-M2vZWa-DlZ2iPFct6ESp9PumaO_pIF5cUrX4IBoe3fcmg788-ClReytCMjD13uPVOVoIb3yimUdupOUROxb3MITowHP2-YG1gWqhQp22XSQXktugDHWezAuN0xuimwAJq_OvyoDxj4lsnn6BQkqZYdqD0hJghwqZIytg8PlIi76Cdvh8NFgVw48xZ0WUOFvBPJO2Qe8PiTSVX_P9CIIWxsKlYwg8vJ226qi0eYfD70ynjBDQIPmsOOSut6bFKgOLBFa9ZvCy6HmhyLa-EsgLhS4uc",
"eyJraWQiOiJkZDA0MDllNS00MTBlLTRkOTgtODViNi1mODFhNDBiOGQ5ODAiLCJ0eXAiOiJzZWNldmVudCtqd3QiLCJhbGciOiJQUzUxMiJ9.ewogICJpc3MiOiAiaHR0cHM6Ly9hcGkuZml0a28uZGUvZml0LWNvbm5lY3QvIiwKICAiaWF0IjogMTYyMjc5NjUzMiwKICAianRpIjogIjBCRjZEQkY2LUNFN0UtNDRBMy04ODlGLTgyRkU3NEMzRTcxNSIsCiAgInN1YiI6ICJzdWJtaXNzaW9uOkY2NUZFQUIyLTQ4ODMtNERGRi04NUZCLTE2OTQ0ODU0NUQ5RiIsCiAgImV2ZW50cyI6IHsKICAgICJodHRwczovL3NjaGVtYS5maXRrby5kZS9maXQtY29ubmVjdC9ldmVudHMvYWNjZXB0LXN1Ym1pc3Npb24iOiB7fQogIH0sCiAgInR4biI6ICJjYXNlOkY3M0QzMEM2LTg4OTQtNDQ0NC04Njg3LTAwQUU3NTZGRUE5MCIKfQ.blxz8Tw_Sl8_tomcqxezamX_DVGyGiu61iYGv3mA3yVLLSDlPscjcHm_MCNm5iq-ODUk-FCW1ljOexN2czZJic8wvLhWhcUt8U2kkkjis-CWz4oqhuB4ynAj7Yyn4H4xkLoH7Y6k9pqW9P2mN7984o_578mJJ4mQSNEGcPr_BDbRc2nUKcupG7iS-hx6VTjrRTP7LGPyOblDB8oL_QyT9qY0US7PT35QgiraUSK3RWhDpj6C0I4bOV5cQeSqlXT2xIfeO3sUPeWLYVmGjuB8QWvDsniKz6JqRN-v39FrAppsOufdiRim36wtBZt9o-3txjtz5wu0_eSfjOueGJbfqAeWsbd2TYwZtL-7Z-MPfoe3XInDNmmTfxo4KXkF1GkRnGnjniwrWBHeh18A04NNHYcX-vsoijEreqDN2lEKwks3pDK5Twe5O9RxJ0cYB8oeKB55rJzs15pfla69qVn9zFvCAc_ji_9WaAa_mIG0zimMucG3qA0KrUww88FaS4heh5-Gs1Ik35QoUOCCa7ZMJMKxYArFCgUqHw-gX60U5mp4hy7tVe3hD-RxIRnlTIkEkHgDGmslVc1t8fC9oPgljQirPcTIeWhVyLmk6rJLgR5nqizujz3hDUCdBuRF43fS6qedmYfHq1MyakJzEFe2ht1rpGw4ftAt0kcOBOf2jyQ"
]
}
```
Im Log dieser Einreichung wurden drei Events aufgezeichnet, wobei das letzte SET das aktuellste ist.
Das letzte SET aus obigem Beispiel hat folgenden Payload.
```json
{
"iss": "https://api.fitko.de/fit-connect/",
"iat": 1622796532,
"jti": "0BF6DBF6-CE7E-44A3-889F-82FE74C3E715",
"sub": "submission:F65FEAB2-4883-4DFF-85FB-169448545D9F",
"events": {
"https://schema.fitko.de/fit-connect/events/accept-submission": {}
},
"txn": "case:F73D30C6-8894-4444-8687-00AE756FEA90"
}
```
In dem SET ist folgende Information abgelegt:
- Er wurde vom Zustelldienst https://api.fitko.de/fit-connect/ ausgestellt (iss = issuer)
- Er wurde am 04.06.2021 um 08:48:52 GMT+0 (Unixzeit 1622796532) aufgezeichnet (iat = issued at)
- Er hat die eindeutige ID `0BF6DBF6-CE7E-44A3-889F-82FE74C3E715` (jti = JWT ID)
- Er betrifft die Einreichung `F65FEAB2-4883-4DFF-85FB-169448545D9F` (sub = subject)
- Die Submission wurde angelegt "accept-submission" (events)
- Die Submission gehört zur Vorgangsreferenz (case) `F73D30C6-8894-4444-8687-00AE756FEA90`
Aus dem Event des SET lässt sich ableiten, dass der aktuelle Status der Einreichung `accepted` ist und der Zeitpunkt des Übergangs der 04.06.2021 um 08:48:52 GMT+0 war.
Da alle SETs im Event Log signiert sind, kann diese Signatur auch noch überprüft werden.
Die Überprüfung ist im Artikel zum [Event Log](../event-log.mdx#set-validation) beschrieben.
docs/getting-started/sending/query-status.mdx
+ 58
− 19
View file @ c4186246
---
title: 🚧 Status abfragen
title: Status abfragen
sidebar_position: 9
---
import Mermaid from '@site/src/components/Mermaid'
import ApiLink from '@site/src/components/ApiLink'
:::caution Hinweis :construction:
Nachdem die Einreichung versendet worden ist, kann der Status dieser abgefragt werden.
Der Status ist für das sendende System relevant, da hierüber das empfangende System mitteilt, ob es die Einreichung technisch korrekt verarbeiten konnte.
Bis zu einer Bestätigung über den Status *Accepted* sollte das System sämtliche Inhalte einer Einreichung vorhalten.
Dies sollte es tun, damit es im Falle eines Fehlers (aufgrund eines inkorrekten Schemas oder eines falschen Public Keys), den Fehler eventuell korrigieren kann und Informationen korrekt übermitteln kann, ohne den Nutzer (bspw. einen Antragssteller) zu einer erneuten Dateneingabe aufzufordern.
Die Abfrage des Status einer Einreichung ist noch unter Bearbeitung, da das Statusmodell gerade überarbeitet wird.
Zukünftig wird es eine Möglichkeit geben, bzgl. Statusänderungen über einen Callback benachrichtigt zu werden.
Zudem stellt der Status in Form des signierten Security-Event-Tokens einen sicheren Nachweis der Übermittlung und des Empfangs dar, der gegenüber Dritten genutzt werden kann.
:::
Das Statusmodell einer Einreichung ist in der folgenden Grafik dargestellt und enthält fünf Zustände (in orange), die in der darunterliegenden Tabelle beschrieben sind.
Nachdem die Einreichung abgeschlossen wurde, kann der Status der Einreichung abgefragt werden.
![Statusdiagramm](/images/status/status.svg)
<Mermaid>
stateDiagram-v2
[*] --> Incomplete
Incomplete --> Submitted
Submitted --> Forwarded
Forwarded --> Rejected
Forwarded --> Accepted
Submitted --> Accepted
Submitted --> Rejected
Accepted --> [*]
Rejected --> [*]
</Mermaid>
| Status | Bedeutung |
|---------------|---------------------------------------------------------------------------------------------------------|
| `incomplete` | Das sendende System hat begonnen, die Einreichung zu übermitteln. Sie jedoch noch nicht abgesendet. |
| `submitted` | Das sendende System hat die Einreichung vollständig übermittelt und abgesendet. |
| `forwarded` | Ein vermittelndes System hat die Einreichung übernommen, sie aber noch nicht dem Zielsystem zugestellt. |
| `rejected` | Die Einreichung wurde durch den Empfänger zurückgewiesen. |
| `accepted` | Die Einreichung wurde durch den Empfänger akzeptiert. |
Der Status wird über <ApiLink to="/submissions/{submissionId}/events" /> abgefragt.
Hierbei wird der Event Log der Einreichung zurückgeliefert, der die verschiedenen Statusübergänge bzw. abgelegten Ereignisse beinhaltet.
Das Ergebnis könnte wie folgt aussehen:
```json
{
"eventLog": [
"eyJraWQiOiJkZDA0MDllNS00MTBlLTRkOTgtODViNi1mODFhNDBiOGQ5ODAiLCJ0eXAiOiJzZWNldmVudCtqd3QiLCJhbGciOiJQUzUxMiJ9.ewogICJpc3MiOiAiaHR0cHM6Ly9hcGkuZml0a28uZGUvZml0LWNvbm5lY3QvIiwKICAiaWF0IjogMTYyMjc5NDMxOSwKICAianRpIjogIkVEQ0ZCRjIxLTVCMTYtNEQwNi05OUQwLURDNEMyNkY0RkI5RSIsCiAgInN1YiI6ICJzdWJtaXNzaW9uOkY2NUZFQUIyLTQ4ODMtNERGRi04NUZCLTE2OTQ0ODU0NUQ5RiIsCiAgImV2ZW50cyI6IHsKICAgICJodHRwczovL3NjaGVtYS5maXRrby5kZS9maXQtY29ubmVjdC9ldmVudHMvY3JlYXRlLXN1Ym1pc3Npb24iOiB7fQogIH0sCiAgInR4biI6ICJjYXNlOkY3M0QzMEM2LTg4OTQtNDQ0NC04Njg3LTAwQUU3NTZGRUE5MCIKfQ.TQBR_CBsoULi3cGaGg4oqFelQ9GVn8G-cNokzTVDZgZf4D7x_8wjsDcgTd0aamiy8ErlnV1xoAoDcPw81vajrBCaYgf9KI4sNhsW78jlDi_ywK04YhFbkvloDMioGf_5zCNTBreN9bTnU_VYuWB23R_YrYGi2exONft-ZReN_crEvDaKLdG9hqnaCRFwKJ1t8TbLvIyBKLqQYEqP0Oh6m3WA9IRz3EB41S-PZgJCIzmz_GvXdRvw_1B8A_Q7aHr2SQ6Dc-c406UJ5P_7FuypE6tLyuYf5GkmFZSauQ51H4LLl8pLrsW2PJJ28cMavOEx0AWoRLwB7yKK5bAGtcALWw-0W7Wmw1QEX3DZGTpXbEUM0U_7iXeEFrdtfCCbFPMVbmlK-b66IyKK_6yeaOAEjQvCUOrALfa2sSOS6RWiNOKyA1l1L29VoIBXgQ8np72NMV8-AP7UnQO1NPBghBM6LW6tcXceWeP8ayy4eEaZQ639pqH4TJRRkQqnuoTeADpYL9sX2hM9173O4abWiE-Z8zW2AQ1jhUvVXJ8w9ddtMIyjZJZOqoy3TbHxUYpn4UqbedlDyahpUiKCT7-qU2jOjeXAXEPQvWlSzLigNtFvYCEq-fOe1lpeNktoQQrC3Y-szk2vNj5fT_KmJY1QG1bhyrUMoGbA-pe45c-FcCE7ErQ",
"eyJraWQiOiJkZDA0MDllNS00MTBlLTRkOTgtODViNi1mODFhNDBiOGQ5ODAiLCJ0eXAiOiJzZWNldmVudCtqd3QiLCJhbGciOiJQUzUxMiJ9.ewogICJpc3MiOiAiaHR0cHM6Ly9hcGkuZml0a28uZGUvZml0LWNvbm5lY3QvIiwKICAiaWF0IjogMTYyMjc5NTczMiwKICAianRpIjogIjkwRDlCMjlELUMwNUYtNEYwMy04MUMwLUUyMzMxMTZDNTZEOSIsCiAgInN1YiI6ICJzdWJtaXNzaW9uOkY2NUZFQUIyLTQ4ODMtNERGRi04NUZCLTE2OTQ0ODU0NUQ5RiIsCiAgImV2ZW50cyI6IHsKICAgICJodHRwczovL3NjaGVtYS5maXRrby5kZS9maXQtY29ubmVjdC9ldmVudHMvc3VibWl0LXN1Ym1pc3Npb24iOiB7fQogIH0sCiAgInR4biI6ICJjYXNlOkY3M0QzMEM2LTg4OTQtNDQ0NC04Njg3LTAwQUU3NTZGRUE5MCIKfQ.THmHiZoYEMyyWCu2R4nEJtvgtB5PF0KAqtfu_Z-yVjfjSkXW7TtZnX96UAeCGsjpxkBJvXTXAgSB5n378KjZXebAtI7nbFE0gYgt3fwmxmpJitA-4e8v6KfvhwNcdqJHLKDzYRMq_yw7UiwLx1Cxz6nBiOKfR4piL707muKXTgD7DuP0kv-c6V9dGNQ4KzT_sJP5zDWogEzGWSVaLaJZrmDZHoUZMZ6C9kI7SvC-A7Q0ROkFznU_cpjjEAIG74_YCiICvjr91ueQWTdNyc1DBvxpEBtBWq6nWPTg0d91iQlhPUgNKbmC4QtG_tFctTYhX7stO-JbL-4VnAQjQHD5uw4SvvpPrTN4Z3Wz2IjMm8-ClI9imGKThfAqwTaWtJv7Bn_FDiN_nEuGyN2of-M2vZWa-DlZ2iPFct6ESp9PumaO_pIF5cUrX4IBoe3fcmg788-ClReytCMjD13uPVOVoIb3yimUdupOUROxb3MITowHP2-YG1gWqhQp22XSQXktugDHWezAuN0xuimwAJq_OvyoDxj4lsnn6BQkqZYdqD0hJghwqZIytg8PlIi76Cdvh8NFgVw48xZ0WUOFvBPJO2Qe8PiTSVX_P9CIIWxsKlYwg8vJ226qi0eYfD70ynjBDQIPmsOOSut6bFKgOLBFa9ZvCy6HmhyLa-EsgLhS4uc",
"eyJraWQiOiJkZDA0MDllNS00MTBlLTRkOTgtODViNi1mODFhNDBiOGQ5ODAiLCJ0eXAiOiJzZWNldmVudCtqd3QiLCJhbGciOiJQUzUxMiJ9.ewogICJpc3MiOiAiaHR0cHM6Ly9hcGkuZml0a28uZGUvZml0LWNvbm5lY3QvIiwKICAiaWF0IjogMTYyMjc5NjUzMiwKICAianRpIjogIjBCRjZEQkY2LUNFN0UtNDRBMy04ODlGLTgyRkU3NEMzRTcxNSIsCiAgInN1YiI6ICJzdWJtaXNzaW9uOkY2NUZFQUIyLTQ4ODMtNERGRi04NUZCLTE2OTQ0ODU0NUQ5RiIsCiAgImV2ZW50cyI6IHsKICAgICJodHRwczovL3NjaGVtYS5maXRrby5kZS9maXQtY29ubmVjdC9ldmVudHMvYWNjZXB0LXN1Ym1pc3Npb24iOiB7fQogIH0sCiAgInR4biI6ICJjYXNlOkY3M0QzMEM2LTg4OTQtNDQ0NC04Njg3LTAwQUU3NTZGRUE5MCIKfQ.blxz8Tw_Sl8_tomcqxezamX_DVGyGiu61iYGv3mA3yVLLSDlPscjcHm_MCNm5iq-ODUk-FCW1ljOexN2czZJic8wvLhWhcUt8U2kkkjis-CWz4oqhuB4ynAj7Yyn4H4xkLoH7Y6k9pqW9P2mN7984o_578mJJ4mQSNEGcPr_BDbRc2nUKcupG7iS-hx6VTjrRTP7LGPyOblDB8oL_QyT9qY0US7PT35QgiraUSK3RWhDpj6C0I4bOV5cQeSqlXT2xIfeO3sUPeWLYVmGjuB8QWvDsniKz6JqRN-v39FrAppsOufdiRim36wtBZt9o-3txjtz5wu0_eSfjOueGJbfqAeWsbd2TYwZtL-7Z-MPfoe3XInDNmmTfxo4KXkF1GkRnGnjniwrWBHeh18A04NNHYcX-vsoijEreqDN2lEKwks3pDK5Twe5O9RxJ0cYB8oeKB55rJzs15pfla69qVn9zFvCAc_ji_9WaAa_mIG0zimMucG3qA0KrUww88FaS4heh5-Gs1Ik35QoUOCCa7ZMJMKxYArFCgUqHw-gX60U5mp4hy7tVe3hD-RxIRnlTIkEkHgDGmslVc1t8fC9oPgljQirPcTIeWhVyLmk6rJLgR5nqizujz3hDUCdBuRF43fS6qedmYfHq1MyakJzEFe2ht1rpGw4ftAt0kcOBOf2jyQ"
]
}
```
Im Log dieser Einreichung wurden drei Events aufgezeichnet.
Das letzte, aktuellste Security-Event-Token hat folgenden Payload.
```json
{
"iss": "https://api.fitko.de/fit-connect/",
"iat": 1622796532,
"jti": "0BF6DBF6-CE7E-44A3-889F-82FE74C3E715",
"sub": "submission:F65FEAB2-4883-4DFF-85FB-169448545D9F",
"events": {
"https://schema.fitko.de/fit-connect/events/accept-submission": {}
},
"txn": "case:F73D30C6-8894-4444-8687-00AE756FEA90"
}
```
In dem SET ist folgende Information abgelegt:
- Er wurde vom Zustelldienst https://api.fitko.de/fit-connect/ ausgestellt (iss = issuer)
- Er wurde am 04.06.2021 um 08:48:52 GMT+0 (Unixzeit 1622796532) aufgezeichnet (iat = issued at)
- Er hat die eindeutige ID `0BF6DBF6-CE7E-44A3-889F-82FE74C3E715` (jti = JWT ID)
- Er betrifft die Einreichung `F65FEAB2-4883-4DFF-85FB-169448545D9F` (sub = subject)
- Die Submission wurde angelegt "accept-submission" (events)
- Die Submission gehört zur Vorgangsreferenz (case) `F73D30C6-8894-4444-8687-00AE756FEA90`
Aus dem Event des SET lässt sich ableiten, dass der aktuelle Status der Einreichung `accepted` ist und der Zeitpunkt des Übergangs der 04.06.2021 um 08:48:52 GMT+0 war.
Da alle SETs im Event Log signiert sind, kann diese Signatur auch noch überprüft werden.
Die Überprüfung ist im Artikel zum [Event Log](../event-log.mdx#set-validation) beschrieben.
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