diff --git a/docs/details/callbacks.mdx b/docs/details/callbacks.mdx index 4f5837c5d43957c3d75354321ef7fe3c67b9a8e8..645a01ffb42825f8283b8765409a7e3c43c6a67f 100644 --- a/docs/details/callbacks.mdx +++ b/docs/details/callbacks.mdx @@ -2,11 +2,13 @@ title: Verwendung von Callbacks --- -import ApiLink from '@site/src/components/ApiLink' +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import ApiLink from '@site/src/components/ApiLink'; Der FIT-Connect Zustelldienst informiert sendende und empfangende Systeme (API-Clients) aktiv über [neue Einreichungen](../getting-started/receiving/query.mdx) oder [Statusupdates](../getting-started/sending/query-status.mdx). Hierzu werden HTTP-Callbacks genutzt, die auch als [Webhooks](https://de.wikipedia.org/wiki/WebHooks) bezeichnet werden. -Webhooks ermöglichen es, API-Clients aktiv über diese Ereignisse zu informieren ohne dass eine regelmäßige Abfrage ([Polling](https://de.wikipedia.org/wiki/Polling_(Informatik))) nötig wäre. +Webhooks ermöglichen es, API-Clients aktiv über diese Ereignisse zu informieren, ohne dass eine regelmäßige Abfrage ([Polling](https://de.wikipedia.org/wiki/Polling_(Informatik))) nötig wäre. Technisch werden Webhooks als HTTP-POST-Request realisiert. Im Folgenden verwenden wir die Begriffe *Callback* und *Webhook* synonym. @@ -41,13 +43,13 @@ Die Einrichtung von Callbacks im Self-Service-Portal wird im Artikel `TODO: Link ### Konfiguration von Callbacks für Zustellpunkte Über die API können Callbacks für Zustellpunkte wie folgt konfiguriert werden: <Tabs -defaultValue="curl" -values={[ - {label: 'curl', value: 'curl',}, - {label: 'Java', value: 'java',}, - {label: 'JavaScript', value: 'javascript',}, -]}> -<TabItem value="curl" label="curl"> + defaultValue="curl" + values={[ + {label: 'curl', value: 'curl',}, + {label: 'Java', value: 'java',}, + {label: 'JavaScript', value: 'javascript',}, + ]}> + <TabItem value="curl"> ```bash $ SERVICE_URL=... @@ -61,27 +63,30 @@ $ curl -X PATCH \ --data "{ \"callback\": { \"url\": \"$CALLBACK_URL\", \"secret\": \"$CALLBACK_SECRET\" }}" \ "$SERVICE_URL/v1/destinations/$DESTINATION_ID" ``` + </TabItem> + + <TabItem value="java"> -</TabItem> -<TabItem value="java" label="Java"> :::caution TODO TODO: Codebeispiel ergänzen ::: -</TabItem> -<TabItem value="JavaScript" label="JavaScript"> + </TabItem> + + <TabItem value="javascript"> + :::caution TODO TODO: Codebeispiel ergänzen ::: -</TabItem> + </TabItem> </Tabs> ## Prüfung von Callbacks API-Clients, die Callbacks empfangen, **MÜSSEN** zwingend sicherstellen, dass ausgelöste Callbacks von einem vertrauenswürdigen Zustelldienst stammen. Hierzu enthalten Callbacks einen Message Authentication Code (HMAC) gemäß [RFC 2104](https://datatracker.ietf.org/doc/html/rfc2104) auf Basis des angegebenen *Callback-Secrets*. -Ein Message Athentication Code kann als „symmetrische Signatur“ verstanden werden und ermöglicht die Prüfung der Herkunft und Integrität eines eingehende Callbacks. +Ein HMAC kann als „symmetrische Signatur“ verstanden werden und ermöglicht die Prüfung der Herkunft und Integrität eines eingehenden Callbacks. -Der Message Authentication Code wird im HTTP-Header `callback-authentication` übertragen. -Um [Replay-Angriffe](https://de.wikipedia.org/wiki/Replay-Angriff) zu vermeiden, enthält der Message Authentication Code einen aktuellen Timestamp. +Der HMAC wird im HTTP-Header `callback-authentication` übertragen. +Um [Replay-Angriffe](https://de.wikipedia.org/wiki/Replay-Angriff) zu vermeiden, enthält er einen aktuellen Timestamp. Dieser Timestamp wird im HTTP-Header `callback-timestamp` übertragen. Bei der Prüfung der Echtheit des ausgelösten Callbacks **MÜSSEN** API-Clients prüfen, dass der angegebene Timestamp nicht älter als **5 Minuten** ist. @@ -100,7 +105,7 @@ Als Hash-Algorithmus wird SHA-512 verwendet. callback-authentication = BASE64(HMAC(key={callback-secret}, message={timestamp}.{http-body})) ``` -Um den Message Authentication Code (HMAC) zu verifizieren, bildet der API-Client mit Hilfe des *Callback Secret* den HMAC nach und vergleicht diesen mit dem im HTTP-Header `callback-authentication` übertragenen HMAC. +Um den HMAC zu verifizieren, bildet der API-Client mithilfe des *Callback Secret* den HMAC nach und vergleicht diesen mit dem im HTTP-Header `callback-authentication` übertragenen HMAC. Bei der Prüfung **MÜSSEN** die folgenden Implementierungshinweise zwingend zu beachten: - Das Callback Secret **MUSS** in API-Clients konfigurierbar sein und **DARF NICHT** fest im Quellcode eines API-Clients einprogrammiert sein. @@ -110,9 +115,12 @@ Bei der Prüfung **MÜSSEN** die folgenden Implementierungshinweise zwingend zu - Beim Vergleich des übertragenen HMAC und des vom API-Client gebildeteten HMAC **MUSS** ein zeitlich konstanter Zeichenfolgenvergleich (*constant time string comparison*) verwendet werden. - In Python kann dies über die Verwendung der Methode [`hmac.compare_digest`](https://docs.python.org/2/library/hmac.html#hmac.compare_digest) erreicht werden. - In Ruby kann dies über die Verwendung der Methode [`secure_compare`](https://rubydoc.info/github/rack/rack/master/Rack/Utils:secure_compare) erreicht werden. -- Callbacks mit ungültigem Message Authentication Code **MÜSSEN** von API-Clients ignoriert/verworfen werden. +- Callbacks mit ungültigem HMAC **MÜSSEN** von API-Clients ignoriert werden. -Dabei ist zunächst der Zeitstempel (`callback-timestamp`-Header) und anschließend der HMAC (`callback-authentication`-Header) zu prüfen: +Dabei ist zunächst +* der Zeitstempel (`callback-timestamp`-Header) und anschließend +* der HMAC (`callback-authentication`-Header) +zu prüfen: ```python # 1. Timestamp überprüfen @@ -140,4 +148,4 @@ else: print('hmac ok') ``` -Das dargestellte Script findet sich auch zur freien Verwendung im [FIT-Connect-Tools-Repository](https://git.fitko.de/fit-connect/fit-connect-tools/-/blob/main/validate-callback.py). +Das vollständige Script findet sich auch zur freien Verwendung im [FIT-Connect-Tools-Repository](https://git.fitko.de/fit-connect/fit-connect-tools/-/blob/main/validate-callback.py). diff --git a/docs/details/destination-management.mdx b/docs/details/destination-management.mdx index bbdf1dea9d6d1aced2400775bae52bb2a2447d71..fd06ea44e31febfc6bdc3bd1f0fe04ac5aeffaf1 100644 --- a/docs/details/destination-management.mdx +++ b/docs/details/destination-management.mdx @@ -30,7 +30,7 @@ Die Details sind der API-Spec zu entnehmen. {label: 'curl', value: 'curl',}, {label: 'Self-Service-Portal', value: 'ssp',}, ]}> - <TabItem value="curl" label="foo"> + <TabItem value="curl"> #### Aktualisierung des Verschlüsselungsschlüssels eines Zustellpunktes diff --git a/docs/getting-started/receiving/destination.mdx b/docs/getting-started/receiving/destination.mdx index 7f310080e6bace15a4be7e5e65738713a1c98dc1..5921d6bc5a56fca859087648f2ce753f022489a1 100644 --- a/docs/getting-started/receiving/destination.mdx +++ b/docs/getting-started/receiving/destination.mdx @@ -39,17 +39,17 @@ Es ist jedoch möglich einem empfangenden System (API-Client) multiple Zustellpu Ein Zustellpunkt benötigt zur Erstellung eine Vielzahl von Angaben, die sich im Wesentlichen auf Kontaktdaten, technische Angaben und Service aufteilen. -Unter den unter dem Punkt Kontaktdaten abgefragten Informationen werden Details zum antragsempfangenden System erfasst. +Unter <b>Kontaktdaten</b> werden Details zum antragsempfangenden System erfasst. Sämtliche Felder sind dabei aktuell noch Fließtext. Unter der Funktionspostfachadresse wird eine E-Mail-Adresse erwartet. -Unter den unter dem Punkt „Technische Angaben“ abgefragten Informationen werden neben einer Callback-URL auch öffentliche Schlüssel zur Signaturprüfung und Verschlüsselung erwartet. +Unter <b>Technische Angaben</b> werden neben einem Callback auch öffentliche Schlüssel zur Signaturprüfung und Verschlüsselung erwartet. Beide Schlüssel müssen im JSON-Format vorliegen und den Anforderungen aus [Vorgaben für kryptographische Verfahren](https://docs.fitko.de/fit-connect/docs/details/crypto) entsprechen. Ein Tool und die zugehörige Anleitung um schnell und einfach passende Schlüssel für Testzwecke zu generieren finden Sie unter [Tool zur Erstellung von JSON Web Keys](https://docs.fitko.de/fit-connect/docs/details/jwk-creation/). -Unter den unter dem Punkt „Service“ abgefragten Informationen werden ein eindeutiger Leistungsindikator, eine Region aus der eine Anfrage zulässig ist sowie die URI des verwendeten Fachschemas erwartet. +Unter <b>Service</b> werden ein eindeutiger Leistungsindikator, eine Region aus der eine Anfrage zulässig ist sowie die URI des verwendeten Fachschemas erwartet. <div class="center"> <img width="800" alt="Zustellpunkt mit Beispieldaten befüllt" @@ -64,7 +64,7 @@ Wurden alle Informationen und Schlüssel in korrekter Form übergeben wird der Z </div> :::caution -Alle neu angelegten Zustellpunkte haben nach der Erstellung den Status `created` und sind für sendende Systeme nicht sichtbar und adressierbar. +Neu angelegte Zustellpunkte haben nach der Erstellung den Status `created` und sind für sendende Systeme weder sichtbar noch adressierbar. Hiermit soll verhindert werden, dass Einreichungen an den Zustellpunkt übersendet werden, ohne das ein empfangsbereites System vorliegt, dass die Einreichungen für diesen Zustellpunkt an der API abrufen kann. Daher ist zwingend vor der Aktivierung eines Zustellpunktes [ein API-Client anzulegen](https://docs.fitko.de/fit-connect/docs/account) und diesem Zustellpunkt zuzuweisen (siehe nächster Abschnitt). diff --git a/docs/getting-started/receiving/query.mdx b/docs/getting-started/receiving/query.mdx index aebabbc6d1b30269d0d5680412f1a725f80485b2..377dc61daeb86d6410ada34cd66d127695cc038f 100644 --- a/docs/getting-started/receiving/query.mdx +++ b/docs/getting-started/receiving/query.mdx @@ -9,7 +9,7 @@ Empfangende Systeme können sich über den Eingang neuer Einreichungen entweder Letzteres stellt die empfohlene Umsetzungsvariante dar, da hierdurch unnötige Anfragen vermieden werden können, was zu einer insgesamt besseren Performance und zu einer schnelleren Benachrichtigung empfangender Systeme führt. ## Callback -Wenn eine Callback-URL im Zustellpunkt hinterlegt ist, kann der Zustelldienst den Zustellpunkt aktiv via Callback über neue Einreichungen informieren. +Wenn ein Callback im Zustellpunkt hinterlegt ist, kann der Zustelldienst den Zustellpunkt aktiv via Callback über neue Einreichungen informieren. Das Format, in welchem der Callback übertragen wird, ist im Endpunkt <ApiLink to="/v1/destinations/{destinationId}" withMethod="put" /> definiert. Die Konfiguration und Prüfung von Callbacks ist im Artikel [Verwendung von Callbacks](../../details/callbacks.mdx) beschrieben.