From 6dc1719f56913b0cffaae6693721488e18d2bf6a Mon Sep 17 00:00:00 2001
From: David Schwarzmann <david.schwarzmann@codecentric.de>
Date: Tue, 3 Aug 2021 22:46:39 +0200
Subject: [PATCH] docs(event-log): Document how to accept/reject/... a
submission
---
docs/details/crypto.md | 3 +-
.../receiving/process-and-acknowledge.mdx | 114 ++++++++++++++----
docs/getting-started/sending/query-status.mdx | 2 +-
src/css/custom.css | 7 ++
4 files changed, 102 insertions(+), 24 deletions(-)
diff --git a/docs/details/crypto.md b/docs/details/crypto.md
index 3f9bc053e..59e0ffc47 100644
--- a/docs/details/crypto.md
+++ b/docs/details/crypto.md
@@ -84,7 +84,8 @@ Die folgenden Attribute müssen im JOSE-Header bei der Übertragung verschlüsse
| `cty` | *MIME-Type der Inhaltsdaten* | MIME-Type der Inhaltsdaten (Fachdaten, Medatadaten) nach [RFC 7516, Abschnitt 4.1.12](https://tools.ietf.org/html/rfc7516#section-4.1.12) |
## Vorgaben zur Signaturerstellung und -prüfung
-### Vorgaben für JSON Web Keys zur Signaturprüfung
+
+### Vorgaben für JSON Web Keys zur Signaturprüfung {#signature-key}
Eine Signaturprüfung erfolgt in FIT-Connect auf Basis des Standards JSON Web Signature gemäß [RFC 7515](https://tools.ietf.org/html/rfc7515).
diff --git a/docs/getting-started/receiving/process-and-acknowledge.mdx b/docs/getting-started/receiving/process-and-acknowledge.mdx
index 479cbcdd2..7cccdd93c 100644
--- a/docs/getting-started/receiving/process-and-acknowledge.mdx
+++ b/docs/getting-started/receiving/process-and-acknowledge.mdx
@@ -3,31 +3,55 @@ sidebar_position: 8
title: 🚧 Empfangsbestätigung
---
-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.
+import Tabs from '@theme/Tabs'
+import TabItem from '@theme/TabItem'
+
+
+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.md#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.
-- Es sollte grundsätzlich beschrieben werden, welche Optionen für den SET aus Sicht des Empfänger bestehen und welche Folgen das hat (Im Sinne des Statusmodells. Wird können gerne das zusammen durchgehen)
- Die Generierung des SETs und die Ãœbermittlung an die API
-- Der Abruf des Logs. Für die Validierung wird auf diesen Artikel hier verwiesen
-## :construction: Erstellung eines Security-Event-Token (SET)
+## Erstellung und Versand eines Security-Event-Token (SET)
+
+Um ein SET zu erstellen ist es notwendig ein JWK zu haben, dass den [Vorgaben eine Signaturschlüssels](../../details/crypto.md#signature-key)
+entspricht. Weiterhin ist es notwendig, dass die Id der Einreichung und des zugehörigen Vorgangs bekannt ist.
-```java
-private static final InputStream jwksPath = GenerateSignedToken.class.getClassLoader().getResourceAsStream("jwks.json");;
-private static final UUID signatureKeyId = UUID.fromString("6508dbcd-ab3b-4edb-a42b-37bc69f38fed");
+<Tabs
+ defaultValue="java"
+ values={[
+ { label: 'Java', value: 'java', },
+ { label: 'C#', value: 'csharp', },
+ ]
+ }>
+<TabItem value="java">
-private static final String subject = "submission:f65feab2-4883-4dff-85fb-169448545d9f";
-private static final String event = "https://schema.fitko.de/fit-connect/events/accept-submission";
-private static final String transactionId = "case:f73d30c6-8894-4444-8687-00ae756fea90";
-// …
-try {
- JWKSet localKeys = JWKSet.load(jwksPath);
- JWK key = localKeys.getKeyByKeyId(signatureKeyId.toString());
+ ```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";
+ ```
- if (key == null) {
- throw new RuntimeException("Cannot find key with specified Key Id");
- }
+ Hiermit kann dann den markierten Zeilen die Payload und der Header des SET mit den oben beschriebenen Informationen
+ definiert werden. 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")
@@ -51,9 +75,55 @@ try {
signedJWT.sign(signer);
signedJWT.serialize(); // => SET, serialized as Base64 encoded string
-} catch (IOException | ParseException e) {
- throw new RuntimeException("Error during loading of JWK-Set with signature keys.");
-} catch (JOSEException e) {
- throw new RuntimeException("Could not generate SET");
+ } catch (JOSEException e) {
+ throw new RuntimeException("Could not generate SET");
+ }
+ ```
+ </TabItem>
+</Tabs>
+
+Dies kann dann über ein `POST /submissions/<uuid>/events` 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 `GET /submissions/<uuid>/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. 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.md#set-validation) beschrieben.
diff --git a/docs/getting-started/sending/query-status.mdx b/docs/getting-started/sending/query-status.mdx
index 53e22baf0..fd5451e6b 100644
--- a/docs/getting-started/sending/query-status.mdx
+++ b/docs/getting-started/sending/query-status.mdx
@@ -91,6 +91,6 @@ In dem SET ist folgende Information abgelegt:
- 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
+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.md#set-validation) beschrieben.
diff --git a/src/css/custom.css b/src/css/custom.css
index db02f9100..301b267e2 100644
--- a/src/css/custom.css
+++ b/src/css/custom.css
@@ -9,3 +9,10 @@ dl dt {
fill: var(--ifm-font-color-base);
stroke: var(--ifm-font-color-base);
}
+
+.docusaurus-highlight-code-line {
+ background-color: rgba(0,0,0, 0.3);
+ display: block;
+ margin: 0 calc(-1 * var(--ifm-pre-padding));
+ padding: 0 var(--ifm-pre-padding);
+}
--
GitLab