Skip to content
Snippets Groups Projects

docs(event-log): Start documenting the event log and interaction with signed JWTs

Merged docs(event-log): Start documenting the event log and interaction with signed JWTs
feat/security-event-tokens into main
Merged David Schwarzmann requested to merge feat/security-event-tokens into main
Compare
and
7 files
+ 403
− 212
Compare changes
  • Side-by-side
  • Inline
Files
7
docs/details/event-log.md deleted 100644 → 0
+ 0
− 111
# 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.