Sicherheitsvorgaben für Webhooks

Für FIT-Connect und weitere APIs werden einheitliche Designvorgaben für sichere Umsetzungen gebaucht, die sich an gängigen Good Practices orientieren. (bspw. https://code.likeagirl.io/best-practice-to-secure-your-webhooks-618684813723, https://workos.com/blog/building-webhooks-into-your-application-guidelines-and-best-practices, https://www.easywebhooks.com/how-to-secure-a-webhooks-api) Diese Designvorgaben sollte konsistent zu den sonstigen Kryptographievorgaben in FIT-Connect sein.

Insbesondere IP/Domain Whitelisting (https://stripe.com/docs/ips#stripe-domains) könnte wichtig sein, da die Erfahrungen aus dem PoC letztes Jahr gezeigt haben, dass das öffnen der RZ Infrastruktur für Webhook zwar machbar, aber doch sensibel war.

Akzeptanzkriterien

• Der Callback soll nur die minimal notwendigen Daten für die Benachrichtigung beinhalten, damit der Client korrekt reagieren kann. Der eigentliche Status ist nicht Teil der Benachrichtigung.
• Für Sender und Subscriber gelten die selben Sicherheitsvorgaben.
• Zustelldienst muss Zugriff haben
• HTTPS-only
• Callback-Adressen müssen mit Status-Code 200 antworten

marked this issue as related to #61 (closed)

assigned to @Lilith_Wittmann

@Lilith_Wittmann : Ich hatte mit Marco gestern über meine Überlegungen gesprochen. Wäre es für dich in Ordnung, dass mit zu übernehmen? (Ist relevant für das entsprechende Issue 61)

Wenn wir dazu übergehen sollten, die Antworten des Zustelldienstes zu signieren (hab mir hier deine Vorschläge noch nicht angeschaut), wäre vermutlich eine gleichartige Nutzung der Signatur einschließlich Zertifikaten bei Webhooks sinnvoll, oder?

changed the description

@Alexander_Hoose ja das ergibt total Sinn. Habe für Signaturen auf schon angefangen, das ein bisschen auszudefinieren und kümmere mich da gerne weiter drum.

Und was man sich bzgl der Daten bei den Webhooks noch überlegen muss, ist ob es wirklich reine Statusupdates mit festgelegten Enums sind oder ob es auch Payload gibt. Den müsste man dann ja konsequenterweise auch verschlüsseln.

Tip, top. Also nach meinen Überlegungen sehe aktuell drei Anwendungsbereiche mit Webhooks:

• Updates an empfangende Systeme für neue Anträge
• Updates an sendende Systeme für einen neuen Status
• Updates an beide Seite über neue Nachrichten, wenn wir die API um einen Rückkanal erweitern

In allen Fällen würde ich gerne der Empfehlung folgen, dass auf die Versendung von Payloads mit sensiblen Daten oder Angriffspotentialen verzichtet wird. In allen Fällen müssten sich also die Systeme mit einem Request dann nochmal die Daten beim eigentlichen Endpunkt abholen.

• Wenn Designüberlegungen aber zum Schluss kommen, dass wir den Payload in manchen Fällen doch lieber direkt über den Webhook versenden sollten und einfach E2E verschlüsseln, dann ist es auch in Ordnung. (Ich vermute, dass wir für die Rückkanalerweiterung irgendwo vorsehen werden, dass das sendende System für den Antragsprozess einen Public Key hinterlegt. Design des Rückkanals ist aber aktuell kein Sprint Thema)

Ich habe mal versucht die Wege des Rückkanals zum User zusammenzufassen um nichts zu vergessen:

• Es gibt die Grundentscheidung beim übermitteln des Antrags, ob ein verschlüsselter Rückkanal aufgebaut werden soll oder nicht.
• Es gibt die Möglichkeit anonym einen webhook/app-id zu konfigurieren, auf der Benachrichtigt wird wenn sich der Status des Antrags ändert (Enum + Zusatzattribute wie schemaID bei Rückfragen - wenn KEIN public key übergeben).
• Es gibt die Möglichkeit, verschlüsselt Kontaktmöglichkeiten mitzusenden. Um die Benachrichtigung muss sich dann allerdings die Empfangende Behörde kümmern.
• Wenn ein verschlüsselter Rückkanal aufgebaut wird, dann muss ein Public Key mitgeschickt werden und ein ENUM für eine Message, was der User tun muss, um zu entschlüsseln (e.g. bitte scannen sie den QR-Code auf ihrem Antrag) mitgegeben werden. Sollte das passieren, dann gibt es nur noch Benachrichtigungen per Webhooks, mit Verweis das es eine neue Nachricht gibt, die man bitte mit $OPTION abrufen soll. Die abrufbare Nachricht selbst, ist dann eine Text/Richt Text Nachricht, die Verweise auf Dokumente und Schemas im fitconnect Stil enthalten kann. Der public key aus Antrag 1 ermöglicht sicherzustellen, das auch Antrag 2 aus der selben Quelle wie Antrag 1 kommt.
• Sollte der User keine Verschlüsselungskey hinterlegen, dann hat man die Möglichkeit ihn über einen Standard-Enums mit angehängtem Schema zu benachrichtigen. erhält er einen langlebigen JWT Token der ihn Antrag 1 zuordnet (?).

Wäre super wenn ihr das nochmal gegenchecken könnten

Zwei Punkte dazu:

• Um hier etwas die Komplexität rauszunehmen, würde ich die Option eines Rückkanals ohne Hinterlegung eines Public Keys gerne streichen. Bei einem Rückkanal ohne Public Keys liegen Bescheide etc. unverschlüsselt im Zustelldienst (und ggf. in einem Onlinedienst).
• Wenn wir tatsächlich die Hinterlegung einer AppId zur Benachrichtigung von Apps via Push-Notification unterstützen wollen, dann sollten wir hierbei die Verwendung des Web Push Protocol in Erwägung ziehen. Insgesamt ist das Thema aber aus meiner Sicht eher etwas für frühestens H2/2021.

marked this issue as related to #56 (closed)

added 1 deleted label

added 1 deleted label

mentioned in issue docs#11 (moved)

unassigned @Lilith_Wittmann

assigned to @Marco_Holz

Sicherheitsvorgaben für Webhooks

Schutzziele

• Ziel A: API-Clients müssen prüfen können, ob eingehende Callbacks valide sind, d.h. ob diese tatsächlich vom Zustelldienst kommen. Anders ausgedrückt: Sender des Callbacks (Zustelldienst) muss authentisiert sein
• Ziel B: Vertraulichkeit des Payloads muss gewährleistet sein
• Ziel C: Vermeidung von Replay-Angriffen

Weitere Anforderungen

• Anforderung 1: Sender können Callbacks von verschiedenen Zustelldiensten erhalten und müssen Zustelldienste unterscheiden können.
  • Lösungsmöglichkeit: Callback enthält submissionID. Client kann eine submissionID einem Zustelldienst zuordnen.

Sicherheitsmechanismen

Einfaches Shared Secret

POST /callback
Authorization: {shared-secret}

• Shared Secret wird via HTTP-Header in jedem Callback übergeben
• Zoom verwendet authorization-Header: Authorization: {shared_secret}
• siehe https://marketplace.zoom.us/docs/api-reference/webhook-reference
• Vorteile
  • Zustelldienst ist authentisiert (Ziel A)
  • Einfach, erfodert keine kryptographischen Operationen
• Nachteile
  • Shared Secret wird mit jedem Aufruf übermittelt
  • Timestamp zur Verhinderung von Replay-Angriffen nicht möglich (Ziel C)
  • Keine Vertraulichkeit des Payloads (Ziel B)
• Wichtig: Using a plain == operator is not advised. A method like secure_compare performs a "constant time" string comparison, which helps mitigate certain timing attacks against regular equality operators. -- siehe https://docs.github.com/en/developers/webhooks-and-events/webhooks/securing-your-webhooks

Keyed-Hash Message Authentication Code (HMAC)

POST /callback
Authorization: HMAC(key={shared-secret}, message={timestamp}.{http-body})

• HMAC über Shared Secret, Payload und Timestamp wird via HTTP-Header in jedem Callback übergeben
• Stripe verwendet Stripe=Signature-Header: Stripe-Signature: HMAC{shared_secret}({payload})
• siehe https://stripe.com/docs/webhooks/signatures (hier werden keine Signaturen, sondern ein symmetrischer HMAC verwendet!)
• siehe auch https://docs.github.com/en/developers/webhooks-and-events/webhooks/securing-your-webhooks
• Vorteile
  • Zustelldienst ist authentisiert (Ziel A)
  • Relativ einfach, weit verbreitet
  • Replay-Angriffe können verhindert werden (Ziel C)
• Nachteil
  • Keine Vertraulichkeit des Payloads (Ziel B)
• Wichtig: Timestamp zur Vermeidung von Replay-Angriffen
• Wichtig: Using a plain == operator is not advised. A method like secure_compare performs a "constant time" string comparison, which helps mitigate certain timing attacks against regular equality operators. -- siehe https://docs.github.com/en/developers/webhooks-and-events/webhooks/securing-your-webhooks

Asymmetrische Signatur (JWS) im HTTP-Header

POST /callback
jws-signature: JWS(key={sk_server}, message={timestamp}.{http-body})

• Callbacks werden vom Zustelldienst signiert
• Z.B. https://docs.sendgrid.com/for-developers/tracking-events/getting-started-event-webhook-security-features#manage-the-signed-event-webhook-using-the-api https://developer.paypal.com/docs/api-basics/notifications/webhooks/notification-messages/
• Vorteile
  • Zustelldienst ist authentisiert (Ziel A)
  • Timestamp zur Vermeidung von Replay-Angriffen möglich (Ziel C)
• Nachteile
  • Keine Vertraulichkeit des Payloads (Ziel B)
  • Komplex(er) als symmetrisches Token, wenig(er) verbreitet

Asymmetrische Signatur (JWS) im HTTP-Body

POST /callback

JWS(key={sk_server}, message={timestamp}.{http-body})

• Callbacks werden vom Zustelldienst signiert
• Vorteile
  • Zustelldienst ist authentisiert (Ziel A)
  • Timestamp zur Vermeidung von Replay-Angriffen möglich (Ziel C)
• Nachteile
  • Keine Vertraulichkeit des Payloads (Ziel B)
  • Komplex(er) als symmetrisches Token, wenig(er) verbreitet
• siehe auch: Push-Based Security Event Token (SET) Delivery Using HTTP - https://tools.ietf.org/html/rfc8935

Asymmetrisch verschlüsselter Payload (JWE mit RSA-OAEP-256)

POST /callback

JWE(key={pk_client}, message={timestamp}.{http-body})

• Callbacks werden vom Zustelldienst mit Public Key des API-Clients verschlüsselt
• Z.B. https://www.useanvil.com/docs/api/webhooks
• Vorteile
  • Vertraulichkeit des Payloads garantiert (Ziel B)
  • Wir verschlüsseln bereits Inhalte auf diese Weise für Subscriber
• Nachteil
  • Replay-Angriffe möglich (Ziel C)
  • Verschlüsselung alleine bietet keine Authentisierung des Zustelldienstes (Ziel A)

Asymmetrisch verschlüsselter und authentisierter Payload (Public-key authenticated encryption)

POST /callback

AEnc(sk={sk_server}, pk={pk_client}, message={timestamp}.{http-body})

• Callbacks werden vom Zustelldienst mit Public-Key-Authenticated-Encryption-Verfahren verschlüsselt und authentisiert
• z.B. mit https://github.com/dchest/tweetnacl-js
• Vorteile
  • Zustelldienst ist authentisiert (Ziel A)
  • Vertraulichkeit des Payloads garantiert (Ziel B)
  • Timestamp zur Vermeidung von Replay-Angriffen möglich (Ziel C)
  • Die besten kryptographischen Eigenschaften (Public-Key-Crypto, Authentisierung + Vertraulichkeit)
• Nachteil
  • Neue Abhängigkeit zu weiterer Crypto-Library

Symmetrisch verschlüsselter Payload (JWE mit A256GCM)

POST /callback

JWE(key={shared-key}, message={timestamp}.{http-body})

• Callbacks werden vom Zustelldienst mit shared secret (AES-Key) verschlüsselt
• Vorteile
  • Zustelldienst ist authentisiert (Ziel A)
  • Vertraulichkeit des Payloads (Ziel B)
  • Timestamp zur Vermeidung von Replay-Angriffen möglich (Ziel C)
  • Authentisierung und Vertraulichkeit erzwungen (unabhängig von Implementierung des API-Client gewährleistet)
• Nachteile
  • wenig verbreitet
  • Clients müssen symmetrische Entschlüsselung implementieren (ähnlicher Aufwand wie Signatur-/HMAC-Prüfung)

Mutal TLS

• Zustelldienst und API-Client prüfen gegenseitig hinterlegte TLS-Zertifikate
• Vorteile
  • Zustelldienst ist authentisiert (Ziel A)
  • Vertraulichkeit des Payload (Ziel B)
  • Timestamp zur Vermeidung von Replay-Angriffen möglich (Ziel C)
  • Prüfung des Webhooks wird durch TLS erzwungen
• Nachteile
  • Basiert auf Client-Zertifikaten, für viele API-Clients eher ungeeignet
  • Komplexe Implementierung, aufwändiges Keyhandling

Certificate pinning‍ (HSTS)

• Zustelldienst prüft Zertifikats-Fingerprint des vom API-Client bereitgestellten HTTPS-Endpunktes
• Vorteil
  • Vertraulichkeit des Payload (Ziel B)
• Nachteile
  • Brint allein keine Authentisierung des Zustelldienstes (Ziel A)
  • Spezielle Konfiguration der Endpunkte des API-Clients nötig, potenziell aufwändig und fehleranfällig

Minimale Payloads / „Don’t send sensitive data through webhooks‍“

• Wir können mit vielen Mechanismen nicht erzwingen, dass Webhooks korrekt geprüft werden
• Minimale Payloads zahlen auf Ziel B ein (Vertraulichkeit des Payloads)

Weitere Sicherheitsvorgaben

• HTTPS erzwingen: Webhooks von Clients dürfen nur via HTTPS erreichbar sein
• IP/Domain Whitelisting: z.B. https://stripe.com/docs/ips#webhook-notifications

Übersicht

Mechanismus	Ziel A	Ziel B	Ziel C	Prüfung kann erzwungen werden
Einfaches Shared Secret	x
Shared Secret mit HMAC	x		x
Asymmetrische Signatur	x		x
Asymmetrisch verschlüsselter Payload		x		~
Asymmetrisch verschlüsselter und authentisierter Payload	x	x	x	x
Symmetrisch verschlüsselter Payload	x	x	x	x
Mutal TLS	x	x	x	x
Certificate pinning‍		x		~
Minimale Payloads		x		~

Handlungsoptionen:

• Option A: HMAC und Timestamp + minimale Payloads
  • Vorteil: relativ einfach, sehr weit verbreitet
  • Nachteile: komplexere Payloads nicht möglich, korrekte Prüfung kann nicht erzwungen werden
• Option B: Asymmetrische Signatur (JWS) im HTTP-Body + minimale Payloads
  • Vorteil: Clients müssen ohnehin bereits Signaturen des Zustelldienstes prüfen (-> SET)
  • Nachteil: keine Vorteile gegenüber Option A, aber komplexer
• Option C: Symmetrisch verschlüsselter Payload (JWS)
  • Vorteil: auch komplexe Payloads möglich, Prüfung wird technisch erzwungen
  • Nachteil: komplexer als HMAC, ähnlich komplex wie asymmetrische Signatur

marked this issue as related to docs#11 (moved)

mentioned in issue #61 (closed)

Zum Thema "constant time string compare"

Firstly, we cannot rely on arguments that the "compiler isn't smart enough to do that" because that may change tomorrow. We need to base our assessment of the code on what the compiler is and isn't allowed to do.

added 1 deleted label

changed the description

mentioned in issue #56 (closed)

added 1 deleted label

MRs:

• https://git.fitko.de/fit-connect/api/-/merge_requests/98
• https://git.fitko.de/fit-connect/api/-/merge_requests/102
• docs!33 (merged)
• fit-connect-tools!3 (merged)

added workflow::In Progress label and removed 1 deleted label

mentioned in merge request !98 (merged)

marked the checklist item Der Callback soll nur die minimal notwendigen Daten für die Benachrichtigung beinhalten, damit der Client korrekt reagieren kann. Der eigentliche Status ist nicht Teil der Benachrichtigung. as completed

marked the checklist item Für Sender und Subscriber gelten die selben Sicherheitsvorgaben. as completed

marked the checklist item Zustelldienst muss Zugriff haben as completed

marked the checklist item HTTPS-only as completed

marked the checklist item Callback-Adressen müssen mit Status-Code 200 antworten as completed

changed the description

added workflow::Peer Review label and removed workflow::In Progress label

added 1 deleted label

removed 1 deleted label

mentioned in commit 692e9e8d

closed with merge request !98 (merged)

mentioned in issue planning#121 (closed)

changed milestone to %Submission API V1.0