X-ThunderPhone-Signature fejlécben. Állítsa be egyszer helyesen az
ellenőrzést, majd használja ugyanazt a segédfüggvényt minden kezelőben.
Az algoritmus
- Olvassa be a nyers kérési törzset — pontosan azokat a bájtokat, amelyeket POST kéréssel küldtünk Önnek.
- Számítsa ki:
hmac_sha256(secret, body).hexdigest(). - Hasonlítsa össze konstans időben az
X-ThunderPhone-Signatureértékével. (A naiv karakterlánc-összehasonlítás időzítési információkat szivárogtat.)
, és :), UTF-8 kódolással. Ez egy második, teljesen
egyenértékű megoldást ad arra az esetre, ha a keretrendszere csak elemzett JSON-t tesz elérhetővé:
szerializálja újra kanonikusan, és azon számítson HMAC-et.
Melyik titkos kulcs?
Tárolja a titkos kulcsot titkoskulcs-kezelőben vagy környezeti változóban — soha ne commitolja.
Referenciamegvalósítások
Mind a négy a nyers kérési törzset ellenőrzi:Keretrendszerspecifikus bekötés
Eszközhívások ellenőrzése
Amikor az ügynök közvetlenül meghívja valamelyik függvényeszközét (az eszköz rendelkezikendpoint mezővel), a kérés két ThunderPhone-fejlécet tartalmaz az
Ön által konfigurált endpoint.headers mellett:
X-ThunderPhone-Call-ID— az élő hívás numerikus azonosítója.X-ThunderPhone-Signature— HMAC-SHA256, amely az Ön szervezeti szintű webhooktitkával van kulcsolva, és a kérés törzsének pontos bájtjaira van számítva.
verify() segédfüggvény változtatás nélkül működik, két
sajátossággal:
- A
GET/DELETEeszközöknek nincs törzsük. Az argumentumok lekérdezési paraméterekként érkeznek, az aláírás pedig az üres bájtsorozatra van kiszámítva — tehátverify(b"", sig, secret)(Python) vagyverify(Buffer.alloc(0), sig, secret)(Node). Ne hashelje a lekérdezési karakterláncot. - Az örökölt webhookot nem konfiguráló szervezeteknek nincs szervezeti titkuk. Ebben
az esetben az eszközhívások csak
X-ThunderPhone-Call-IDfejlécet tartalmaznak, aláírási fejlécet nem. Konfigurálja az örökölt webhookot (PUT /v1/webhook) aláírási titok beszerzéséhez, vagy hitelesítse az eszközhívásokat saját fejléccel azendpoint.headershasználatával.
endpoint nélküli eszközök,
amelyek telephony.tool / web.tool formában érkeznek az Ön szervezeti
webhookjára) egy szokványos aláírt webhook — a fenti standard eljárás
alkalmazható. Mindkét kérésformátumról lásd:
Függvényeszközök.
Gyakori buktatók
Újraszerializálás alapértelmezett formázással
Újraszerializálás alapértelmezett formázással
A törzs feldolgozása, majd a JSON-könyvtár alapértelmezett
beállításaival történő újrakiírása (szóközök a
, / : után,
beillesztési sorrendben rendezett kulcsok) eltérő bájtokat eredményez,
és érvényteleníti a HMAC-et. Ellenőrizze a nyers törzset — vagy ha
újra kell szerializálnia, pontosan egyezzen a kanonikus formánkkal:
rendezett kulcsok, tömör elválasztók, UTF-8.A keretrendszer automatikusan feldolgozza a JSON-t
A keretrendszer automatikusan feldolgozza a JSON-t
Az Express
express.json() middleware-e felhasználja a törzsfolyamot,
így elveszíti a nyers bájtokat. Kifejezetten a webhook útvonalán
használja az express.raw() függvényt, vagy pufferelje a nyers törzset
egy előzetes middleware-ben. Ugyanez vonatkozik a NestJS-re / Koára is —
tekintse meg a „raw body” dokumentációjukat.Időzítés szempontjából nem biztonságos összehasonlítás
Időzítés szempontjából nem biztonságos összehasonlítás
A JS-ben használt
expected === signature, illetve a Pythonban használt expected == signature
időzítésfüggő összehasonlítás. Használja rendre a crypto.timingSafeEqual
vagy a hmac.compare_digest függvényt. A teljesítménybeli különbség
elhanyagolható.Helytelen titok az eszközvégpontokhoz
Helytelen titok az eszközvégpontokhoz
A közvetlen eszközvégpont-hívások aláírásához a szervezeti szintű webhooktitkot
használjuk (
GET /v1/webhook) — nem pedig a
/v1/developer/webhook-endpoints egyes végpontjaihoz tartozó titkok valamelyikét.
Használja újra ugyanazt a verify() függvényt, de ügyeljen arra, hogy az
eszközútvonalakon a szervezeti titkot adja át neki.A lekérdezési karakterlánc hashelése GET/DELETE eszközöknél
A lekérdezési karakterlánc hashelése GET/DELETE eszközöknél
A törzs nélküli eszközmetódusok esetében az aláírás az üres bájtsorozatra
vonatkozik, így egyetlen univerzális módszer használható: a nyers kérési
törzs HMAC-e, bármi is legyen az. Az URL vagy a lekérdezési karakterlánc
hashelése soha nem fog egyezni.
Nem 401-es válasz visszaadása eltérés esetén
Nem 401-es válasz visszaadása eltérés esetén
Ha sikertelen ellenőrzés esetén 200-as választ ad vissza, a kezelő
visszajátszásos támadások célpontjává válik. Sikertelen ellenőrzés esetén
mindig nem 2xx választ adjon.
Következő lépések
Webhookok áttekintése
Kézbesítési szemantika, újrapróbálkozások, forrás IP-címek.
Webhookvégpontok
Több URL kezelése, titkok rotálása.
Funkcióeszközök
A két eszközmeghívási útvonal és a hozzájuk tartozó kérésformátumok.
Eszközintegrációk
Készítsen teljes, eszközökre épülő integrációt elejétől a végéig.