Oblicz HMAC albo sprawdź ten, który przysłał webhook
Ten generator HMAC podpisuje wiadomość tajnym kluczem przy użyciu HMAC-SHA256, HMAC-SHA1, HMAC-SHA384 lub HMAC-SHA512 i pokazuje podpis jednocześnie jako hex małymi literami, hex wielkimi literami, Base64 i Base64url. Klucz i wiadomość możesz wpisać jako zwykły tekst, hex lub Base64, więc narzędzie działa zarówno z surowymi binarnymi sekretami, jak i z hasłami. Wklej otrzymany podpis — <code>sha256=…</code> z GitHuba, nagłówek Stripe <code>t=…,v1=…</code> albo zwykły Base64 — a dowiesz się, czy się zgadza. Obliczenia wykonuje Web Crypto API Twojej przeglądarki; klucz i wiadomość nigdy nie opuszczają strony.
Jak wygenerować lub zweryfikować HMAC
- 1Wybierz funkcję skrótu: SHA-256 używa większość API i webhooków.
- 2Wpisz lub wklej tajny klucz i wybierz jego zapis: tekst, hex lub Base64. Przycisk Losowy klucz tworzy nowy sekret o odpowiedniej długości.
- 3Wklej wiadomość — w przypadku webhooka surowe body żądania dokładnie w takiej postaci, w jakiej dotarło, bajt w bajt.
- 4Skopiuj podpis w potrzebnym kodowaniu. Aby sprawdzić podpis, wklej go w pole Oczekiwany podpis; prefiks taki jak
sha256=jest rozpoznawany i pomijany.
Czym jest HMAC?
HMAC (hash-based message authentication code, RFC 2104) to krótka wartość obliczana z wiadomości i tajnego klucza. Każdy, kto zna klucz, może obliczyć tę samą wartość i w ten sposób sprawdzić naraz dwie rzeczy: że wiadomość nie została zmieniona po drodze i że utworzył ją ktoś, kto ma klucz. Bez klucza atakujący nie może ani podrobić poprawnego HMAC dla nowej wiadomości, ani dopasować istniejącego po zmianie wiadomości.
To nie jest po prostu skrót z połączonego klucza i wiadomości. HMAC haszuje dwukrotnie, mieszając klucz z wewnętrznym i zewnętrznym dopełnieniem: H((K ⊕ opad) ‖ H((K ⊕ ipad) ‖ message)). Właśnie ta konstrukcja czyni go bezpiecznym z SHA-256 i SHA-512, które same w sobie są podatne na ataki przedłużenia wiadomości (length extension), gdy używa się ich jako H(key ‖ message).
Weryfikacja podpisów webhooków
Większość dostawców webhooków podpisuje każde żądanie HMAC z body i umieszcza wynik w nagłówku. Aby go zweryfikować, oblicz HMAC z surowego body swoim sekretem podpisu i porównaj z wartością nagłówka. Najczęstszy błąd to haszowanie ponownie zserializowanego obiektu JSON zamiast bajtów, które przyszły: inna kolejność kluczy albo brakująca spacja całkowicie zmienia podpis.
Niektórzy dostawcy podpisują więcej niż samo body. Stripe podpisuje timestamp.body — wartość t z nagłówka, kropkę, a potem payload — a Slack podpisuje v0:timestamp:body. Zbuduj tutaj dokładnie taki ciąg jako wiadomość i wklej cały nagłówek w pole weryfikacji; wartość v1= lub v0= zostanie z niego wyciągnięta.
- GitHub
- <code>X-Hub-Signature-256: sha256=<hex></code>, HMAC-SHA256 z body z sekretem webhooka jako tekstem.
- Stripe
- <code>Stripe-Signature: t=…,v1=<hex></code>, HMAC-SHA256 z <code>t.body</code>.
- Shopify
- <code>X-Shopify-Hmac-Sha256: <Base64></code>, HMAC-SHA256 z body.
- Slack
- <code>X-Slack-Signature: v0=<hex></code>, HMAC-SHA256 z <code>v0:timestamp:body</code>.
Klucze tekstowe, hex i Base64
Klucz to ciąg bajtów i ma znaczenie, jak jest zapisany. Tekst abc123 to sześć bajtów; hex abc123 to trzy zupełnie inne bajty. Wiele usług wydaje sekrety jako ciągi hex lub Base64, ale oczekuje, że użyjesz samego ciągu jako klucza tekstowego — tak robią GitHub i Stripe — podczas gdy inne, np. łańcuchy podpisów w stylu AWS i app proxy Shopify, używają zdekodowanych bajtów. Jeśli podpis się nie zgadza, najpierw spróbuj zmienić kodowanie klucza.
Dla nowego klucza użyj losowych bajtów co najmniej tak długich jak wynik skrótu: 32 bajty dla HMAC-SHA256, 64 dla HMAC-SHA512. Dłuższe klucze nic nie dają — wszystko powyżej rozmiaru bloku funkcji skrótu jest najpierw haszowane.
Porównanie w stałym czasie
Gdy Twój serwer sprawdza podpis, porównuj go funkcją działającą w stałym czasie, taką jak crypto.timingSafeEqual w Node.js, hmac.compare_digest w Pythonie czy hash_equals w PHP. Zwykłe porównanie ciągów zatrzymuje się na pierwszym różniącym się znaku, a czas tej operacji może zdradzić, jaka część podrobionego podpisu była poprawna. Ta strona używa tego samego wzorca stałego czasu, więc kod jest zarówno wzorem, jak i narzędziem do sprawdzania.
Jeśli potrzebujesz tylko zwykłej sumy kontrolnej pliku lub tekstu, bez klucza, użyj generatora hashy. Do podpisywania tokenów generator sekretu JWT tworzy klucze HS256 o właściwym rozmiarze.
Najczęstsze pytania
- Czym różni się hash od HMAC?
- Hash taki jak SHA-256 zależy tylko od danych, więc każdy może go przeliczyć. HMAC zależy też od tajnego klucza, więc wygenerować lub sprawdzić go może tylko ktoś, kto ma klucz. Dlatego HMAC dowodzi autentyczności, a nie tylko integralności.
- Dlaczego mój HMAC nie zgadza się z tym z API?
- Prawie zawsze różnią się dane wejściowe: wiadomość nie jest bajt w bajt surowym body (ponownie zserializowany JSON, znak nowej linii na końcu, inne końce linii), klucz jest czytany jako tekst, choć usługa ma na myśli bajty hex lub Base64, albo odwrotnie, lub dostawca podpisuje znacznik czasu razem z body zamiast samego body.
- Którego algorytmu HMAC użyć?
- HMAC-SHA256 to standardowy wybór, używany przez prawie każde API. HMAC-SHA512 jest równie dobry i szybszy na serwerach 64-bitowych. HMAC-SHA1 wciąż jest bezpieczny jako HMAC, mimo kolizji SHA-1, ale używaj go tylko tam, gdzie wymaga tego protokół.
- Czy HMAC-SHA1 jest złamany?
- Nie. Kolizje SHA-1 nie dają sposobu na podrobienie HMAC-SHA1 bez klucza i nie jest znany żaden praktyczny atak na HMAC-SHA1. Nie zaleca się go w nowych projektach, ale weryfikowanie starszych podpisów HMAC-SHA1 jest bezpieczne.
- Czy mogę tu obliczyć HMAC-MD5?
- Nie. Web Crypto API przeglądarki, z którego korzysta ta strona, nie obsługuje MD5. HMAC-MD5 przetrwał tylko w starych protokołach; do wszystkiego nowego używaj HMAC-SHA256.
- Jak długi powinien być klucz HMAC?
- Co najmniej tak długi jak wynik skrótu: 32 losowe bajty dla HMAC-SHA256, 48 dla SHA-384, 64 dla SHA-512. Przycisk Losowy klucz generuje dokładnie tyle za pomocą bezpiecznego generatora liczb losowych Twojej przeglądarki.
- Czy mogę użyć pustego klucza?
- HMAC na to pozwala, a wynik jest dobrze zdefiniowany, więc narzędzie go pokazuje, ale pusty lub krótki klucz nie daje żadnego bezpieczeństwa. Każdy mógłby obliczyć ten sam podpis.
- Czy mój tajny klucz jest gdzieś wysyłany?
- Nie. HMAC oblicza Web Crypto API Twojej przeglądarki na tej stronie. Nic, co wpisujesz, nie jest przesyłane ani zapisywane.