CodeKitHubCzym jest to narzędzie?
HMAC to skrót od Hash-based Message Authentication Code. Łączy klucz tajny z wiadomością i standardową funkcją skrótu (np. SHA-256), by wygenerować digest o stałej długości. Każdy, kto zna ten sam klucz i wiadomość, obliczy identyczny HMAC — ale bez klucza obliczeniowo niewykonalne jest wygenerowanie poprawnego HMAC dla wiadomości, nawet jeśli znasz użyty algorytm skrótu.
To kluczowa różnica względem zwykłego hasha: zwykły hash (MD5, SHA-256 itd.) przyjmuje na wejściu tylko wiadomość, więc każdy może go obliczyć i nie dowodzi on niczego o tym, kto go stworzył. HMAC przyjmuje wiadomość *oraz* klucz tajny, więc poprawny HMAC dowodzi, że nadawca posiadał ten sekret — to mechanizm uwierzytelniania, a nie tylko kontrola integralności.
HMAC jest formalnie ustandaryzowany przez NIST w FIPS 198-1 i zdefiniowany dla protokołów internetowych w IETF RFC 2104. To narzędzie oblicza HMAC za pomocą natywnego Web Crypto API twojej przeglądarki (`crypto.subtle.sign` z algorytmem HMAC), które poprawnie implementuje RFC 2104, zamiast ręcznie napisanej wersji w JavaScripcie.
Dlaczego warto go używać?
- Twój endpoint webhooka Stripe wciąż zwraca „signature verification failed” na środowisku testowym i musisz ustalić, czy błąd jest w kodzie, czy w kluczu — wklejasz ten sam payload i webhook secret tutaj, żeby od razu zobaczyć, jakiego HMAC-SHA256 powinieneś się spodziewać.
- Integrujesz zewnętrzne API, które wymaga podpisywania każdego żądania HMAC-SHA1, a dokumentacja podaje przykład tylko w Pythonie — generujesz ten sam HMAC tutaj z identycznym kluczem i wiadomością, żeby potwierdzić, że Twoja implementacja po stronie klienta da ten sam wynik, zanim napiszesz linijkę kodu.
- Kolega przesłał Ci fragment kodu obliczający HMAC-SHA256 w Node.js i chcesz szybko zweryfikować, że wynik jest poprawny, bez instalowania Node.js czy uruchamiania REPL-a na swoim komputerze.
- Musisz wygenerować token HOTP/TOTP na potrzeby debugowania systemu uwierzytelniania dwuskładnikowego i chcesz zobaczyć pośredni HMAC, zanim zostanie skrócony do finalnego 6-cyfrowego kodu OTP.
- Piszesz wewnętrzny poradnik o podpisywaniu żądań do mikroserwisu współdzielonym sekretem i chcesz dodać przykład, który koledzy mogą dokładnie odtworzyć, wklejając te same wartości.
- 100% lokalnie: Twój klucz tajny i wiadomość nigdy nie opuszczają przeglądarki, więc możesz bezpiecznie testować prawdziwe sekrety produkcyjne bez ryzyka wysłania ich do zewnętrznego serwera.
Jak używać
- Wpisz swój klucz tajny w polu "Secret Key".
- Wpisz wiadomość, którą chcesz uwierzytelnić, w polu "Message".
- Wyniki HMAC-SHA1, HMAC-SHA256, HMAC-SHA384 i HMAC-SHA512 generowane są natychmiast (zaznacz "Uppercase output", jeśli twój system docelowy oczekuje wielkich liter).
- Kliknij "Copy" przy interesującym cię wyniku HMAC.
Przykład
Wejście
Secret Key: key
Message: The quick brown fox jumps over the lazy dogWynik
HMAC-SHA256: f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8
HMAC-SHA1: de7c9b85b8b78aa6bc8a7a36f70a90701c9db4d9To standardowy, opublikowany wektor testowy: dla klucza "key" i dokładnie tej wiadomości HMAC-SHA256 i HMAC-SHA1 zawsze dają te wartości w każdej poprawnej implementacji, więc możesz niezależnie zweryfikować wynik tego narzędzia.
HMAC a zwykły hash: kiedy potrzebny jest klucz
Kluczowe pytanie brzmi: czy musisz udowodnić, kto stworzył ten digest, czy tylko że treść się nie zmieniła? Jeśli wystarczy publiczna suma kontrolna — weryfikacja, że pobrany plik zgadza się z tym, co podał wydawca, deduplikacja rekordów — wystarczy zwykły hash, który każdy może sprawdzić bez żadnego klucza. Jeśli musisz udowodnić, że digest mógł powstać wyłącznie u kogoś, kto posiada konkretny sekret — uwierzytelnianie klienta API, zaufanie do nadawcy webhooka — potrzebujesz HMAC, bo zwykły hash daje atakującemu bez sekretu taką samą możliwość sfałszowania poprawnego digestu, jaką ma prawdziwy nadawca.
→ Generator hashy dla wielu algorytmów · Dekoder JWT · Generator MD5
Porównanie czterech algorytmów HMAC
Wszystkie cztery używają tej samej konstrukcji HMAC z RFC 2104, różniąc się jedynie funkcją skrótu leżącą u podstaw, a co za tym idzie — długością wyniku.
| Algorytm | Rozmiar wyniku | Typowe zastosowanie |
|---|---|---|
| HMAC-SHA1 | 160 bitów (40 znaków hex) | Starsze API, dawne podpisy OAuth 1.0a |
| HMAC-SHA256 | 256 bitów (64 znaki hex) | Podpisywanie żądań API, JWT HS256, weryfikacja webhooków |
| HMAC-SHA384 | 384 bity (96 znaków hex) | Podpisy o wyższym poziomie zaufania, gdzie wymagany jest dłuższy wynik |
| HMAC-SHA512 | 512 bitów (128 znaków hex) | Digesty maksymalnej długości dla zastosowań o wysokim poziomie bezpieczeństwa |
Typowe zastosowania
- Podpisywanie wychodzących żądań API współdzielonym sekretem, aby serwer mógł zweryfikować tożsamość klienta.
- Weryfikacja przychodzących payloadów webhooków (nagłówki Stripe-Signature, GitHub X-Hub-Signature-256 i podobne — wszystkie wykorzystują HMAC-SHA256).
- Generowanie i walidacja części podpisowej tokenu JWT podpisanego HS256/HS384/HS512.
- Testowanie, czy twoja implementacja HMAC po stronie serwera lub klienta zwraca oczekiwany wynik, zanim wdrożysz ją produkcyjnie.
Debugowanie niezgodnego HMAC
Gdy HMAC obliczony przez Twój kod nie zgadza się z tym, którego oczekuje zewnętrzna usługa, problem prawie zawsze leży w danych wejściowych, nie w algorytmie — to narzędzie jest przydatne właśnie do izolowania przyczyny.
Zbuduj test, zaczynając od znanego wektora z przykładu powyżej, żeby potwierdzić, że samo narzędzie działa zgodnie z oczekiwaniami, a następnie stopniowo zastępuj klucz i wiadomość swoimi rzeczywistymi wartościami, aż znajdziesz dokładny moment, w którym wynik przestaje się zgadzać z oczekiwaniami — to szybko izoluje, czy problem leży w kodowaniu klucza, białych znakach w wiadomości, czy w wybranym algorytmie.
Najczęściej zadawane pytania
Czym jest HMAC?
HMAC (Hash-based Message Authentication Code) łączy klucz tajny z wiadomością za pomocą funkcji skrótu, tworząc digest, który dowodzi zarówno integralności wiadomości, jak i posiadania klucza przez nadawcę. Jest zdefiniowany w NIST FIPS 198-1 oraz IETF RFC 2104.
Jaka jest różnica między HMAC a zwykłym hashem?
Zwykły hash (SHA-256, MD5 itd.) przyjmuje na wejściu tylko wiadomość — każdy może go obliczyć, więc dowodzi jedynie, że wiadomość nie została uszkodzona, a nie kto ją wysłał. HMAC przyjmuje wiadomość plus klucz tajny: jeśli musisz udowodnić, że wiadomość pochodzi od kogoś, kto posiada konkretny sekret (podpis API, nadawca webhooka), potrzebujesz HMAC. Jeśli chcesz tylko sprawdzić, czy plik lub wiadomość się nie zmieniły, i nie zależy ci na dowodzie autorstwa, wystarczy zwykły hash.
Czy mój klucz tajny jest wysyłany na serwer?
Nie. To narzędzie oblicza HMAC w całości w twojej przeglądarce, korzystając z Web Crypto API. Twój klucz i wiadomość nigdy nigdzie nie są przesyłane — możesz bezpiecznie testować prawdziwe sekrety produkcyjne.
Którego algorytmu użyć — SHA-1, SHA-256, SHA-384 czy SHA-512?
Używaj HMAC-SHA256, chyba że konkretny system wymaga inaczej — to de facto standard podpisywania API (stosowany przez AWS, Stripe, webhooki GitHuba i większość nowoczesnych API) i oferuje solidny margines bezpieczeństwa. HMAC-SHA1 wciąż spotyka się w starszych systemach (np. w dawnych implementacjach OAuth 1.0a), ale sam algorytm SHA-1 uznaje się za słabszy; HMAC-SHA384/512 stosuje się tam, gdzie potrzebny jest dłuższy wynik lub dodatkowy margines bezpieczeństwa.
Czy HMAC-SHA1 jest niebezpieczny, skoro zwykły SHA-1 został złamany?
Ataki na kolizje z 2017 roku złamały SHA-1 jako zwykłą funkcję skrótu, ale HMAC-SHA1 wciąż uznaje się za kryptograficznie bezpieczny, ponieważ bezpieczeństwo HMAC nie zależy od odporności na kolizje w ten sam sposób. Mimo to w nowych systemach lepiej sięgać po HMAC-SHA256 lub wyższy — nie ma to praktycznych wad, a temat przestaje być dyskusyjny.
Jakie są typowe zastosowania HMAC w praktyce?
Podpisywanie żądań REST API, aby serwer mógł zweryfikować, że nadawca posiada współdzielony sekret API; weryfikacja payloadów webhooków od usług takich jak Stripe, GitHub i Shopify, dzięki czemu wiesz, że żądanie faktycznie od nich pochodzi i nie zostało sfałszowane; generowanie haseł jednorazowych opartych na czasie (TOTP/HOTP) do uwierzytelniania dwuskładnikowego; oraz podpisywanie tokenów JWT algorytmami HS256/HS384/HS512.
Mój obliczony HMAC nie zgadza się z tym, którego oczekuje usługa — jakie są najczęstsze przyczyny?
Najczęstsze przyczyny to: dodatkowe białe znaki lub znaki nowej linii w wiadomości (zwłaszcza gdy payload jest kopiowany z edytora tekstu lub logu), niewłaściwe kodowanie klucza (niektóre usługi oczekują klucza zdekodowanego z Base64, a nie użytego jako dosłowny ciąg znaków), niezgodność wielkości liter w oczekiwanym wyniku szesnastkowym, lub fakt, że usługa podpisuje nieco inny payload niż ten, który testujesz (np. JSON z inną kolejnością kluczy).
Czy muszę zakodować swój klucz tajny w Base64 przed wpisaniem, czy zwykły tekst wystarczy?
Zależy od usługi, z którą pracujesz: niektóre traktują klucz tajny dokładnie jako otrzymany ciąg tekstowy, inne wymagają najpierw zdekodowania go z Base64 do surowych bajtów. Sprawdź dokumentację konkretnego API — jeśli wartości nie zgadzają się przy kluczu wpisanym jako zwykły tekst, spróbuj zdekodować go z Base64 przed wklejeniem tutaj.
Dlaczego wygenerowany HMAC ma zawsze tę samą długość, niezależnie od długości mojej wiadomości?
To podstawowa właściwość funkcji skrótu, na których opiera się HMAC: wynik ma zawsze stały rozmiar określony przez algorytm (160 bitów dla SHA-1, 256 dla SHA-256 itd.), niezależnie od tego, czy podpisujesz pojedyncze słowo, czy cały dokument JSON. To właśnie sprawia, że HMAC jest praktyczny do przesyłania w nagłówku HTTP o przewidywalnej długości.
Czy mogę użyć tego narzędzia do zweryfikowania podpisu webhooka, który już otrzymałem?
Tak — wklej dokładną, surową treść otrzymanego webhooka w pole Message, a swój sekret webhooka w pole Secret Key, a następnie porównaj wygenerowany HMAC-SHA256 z podpisem zawartym w nagłówku żądania (np. Stripe-Signature). Jeśli się zgadzają, żądanie jest autentyczne; pamiętaj, że musisz użyć dokładnej, surowej treści żądania, a nie przeformatowanej czy ponownie zakodowanej wersji JSON-a.