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

Pull event log document from !34

parent 52ea4620
No related branches found
No related tags found
1 merge request!43Introduce docusaurus
Hide whitespace changes
Inline Side-by-side
.gitignore
+ 2
− 2
View file @ 5ee207e6
......@@ -7,10 +7,10 @@
node_modules/
# Production
/build
build/
# Generated files
.docusaurus
.docusaurus/
.cache-loader
# Misc
......
docs/details/event-log.md 0 → 100644
+ 141
− 0
View file @ 5ee207e6
# 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).
## 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. Die Liste der möglichen Events befndet sich im Kapitel "Events". |
| 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"
}
```
## Ereignisse (Events)
### Ereignisse einer Einreichung (Submission Events)
| Event | Bedeutung |
| ----- | --------- |
| https://schema.fitko.de/fit-connect/events/create-submission | Die Einreichung wurde durch den Sender angelegt. |
| https://schema.fitko.de/fit-connect/events/submit-submission | Die Einreichung wurde durch den Sender abgesendet. |
| https://schema.fitko.de/fit-connect/events/notify-submission | Der Empfänger wurde per Webhook über die Einreichung informiert. |
| 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 | Die Einreichung wurde durch den Empfänger zurückgewiesen. |
| https://schema.fitko.de/fit-connect/events/accept-submission | Die Einreichung wurde durch den Empfänger akzeptiert. |
| https://schema.fitko.de/fit-connect/events/delete-submission | Die Einreichung wurde durch den Zustelldienst gelöscht. |
### Ereignisse einer Antwort (Reply Events)
| Event | Bedeutung |
| ----- | --------- |
| https://schema.fitko.de/fit-connect/events/create-reply | Die Antwort wurde durch den Sender angelegt. |
| https://schema.fitko.de/fit-connect/events/submit-reply | Die Antwort wurde durch den Sender abgesendet. |
| https://schema.fitko.de/fit-connect/events/notify-reply | Der Empfänger wurde per Webhook über die Antwort informiert. |
| https://schema.fitko.de/fit-connect/events/forward-reply | Ein nachgelagertes System hat die Antwort zur Weiterleitung übernommen. |
| https://schema.fitko.de/fit-connect/events/reject-reply | Die Antwort wurde durch den Empfänger zurückgewiesen. |
| https://schema.fitko.de/fit-connect/events/accept-reply | Die Antwort wurde durch den Empfänger akzeptiert. |
| https://schema.fitko.de/fit-connect/events/delete-reply | Die Antwort wurde durch den Zustelldienst gelöscht. |
Das Akzeptieren oder Zurückweisen von Einreichungen oder Antworten passiert 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.
### Ereignisse eines Vorgangs (Case Events)
| Event | Bedeutung |
| ----- | --------- |
| https://schema.fitko.de/fit-connect/events/close-case | Die Vorgangsreferenz wurde geschlossen, es dürfen keine weiteren Replies mehr erfolgen. |
## 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/event-log.mdx deleted 100644 → 0
+ 0
− 5
View file @ 52ea4620
# 🚧 Eventlog
TBD
> Ein neuer Artikel aber nochmal etwas zielgerichteter und knackiger die Verwertung und den Nutzen für die API-Nutzer beschreiben. Ebenfalls sollte man dann auch die Verarbeitung der des Log mit kurzen Beispielen/technischen Erläuterungen beschreiben (Erläuterungen Validierung von einzelner Claims und der Signatur, Hinweis das der Log ein Array aus JWTs mit Compact Serialization mit Base64 ist, weshalb jedes Objekt entnommen und dekodiert werden muss, etc.).
\ No newline at end of file
sidebars.js
+ 1
− 0
View file @ 5ee207e6
......@@ -72,6 +72,7 @@ module.exports = {
label: 'Detailinformationen',
items: [
'details/encryption',
'details/event-log',
{
type: 'category',
label: 'Authentifizierung',
......
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