Generator HMAC i weryfikator podpisów

Czym jest HMAC?

const crypto = require('crypto');

// HMAC-SHA256 with a UTF-8 text key, hex output
const hmac = crypto
  .createHmac('sha256', 'my-secret-key')
  .update('Hello, World!')
  .digest('hex');

console.log(hmac);
// → 'cf3141611e22ea26a9cac6fe41d941274dd6653622c83cba13972d177bd69699'

// Verify a signature in constant time
function verify(message, key, expectedHex) {
  const actual = crypto.createHmac('sha256', key).update(message).digest();
  const expected = Buffer.from(expectedHex, 'hex');
  return actual.length === expected.length &&
    crypto.timingSafeEqual(actual, expected);
}

Kluczowe funkcje

Przykłady HMAC

Hello, World!

cf3141611e22ea26a9cac6fe41d941274dd6653622c83cba13972d177bd69699

{"id":42,"event":"user.created"}

Cd2f7zTKaJFeG6k+t1FcvDPn51OAZ2f4GrxkCUgMhGs=

what do ya want for nothing?

5bdcc146bf60754e6a042426089575c75a003f089d2739839dec58b964ec3843

The quick brown fox

36f44b125a8a90639dc46733039571792e081e0fd8685ff746784b02ed14aa35629d562c7117cde4a701570551faa5a5e1b7ef1eb5c3bcd4cc1fdb8923fcf14e

Jak wygenerować i zweryfikować HMAC

1. 1

   Wybierz algorytm

   Wybierz HMAC-SHA256 (domyślny i właściwy wybór niemal do wszystkich webhooków, API i JWT) albo przełącz na SHA-1, SHA-384 lub SHA-512, aby dopasować się do systemu, który tego wymaga. Wszystkie cztery działają natywnie w Twojej przeglądarce przez Web Crypto API.

2. 2

   Wpisz tajny klucz i ustaw jego kodowanie

   Wpisz lub wklej swój tajny klucz, a następnie ustaw Kodowanie klucza tak, aby pasowało do sposobu, w jaki serwer go interpretuje: Tekst (UTF-8) dla zwykłego ciągu, Hex dla bloba szesnastkowego lub Base64 dla sekretu base64. Pomyłka tutaj to główna przyczyna niezgodności HMAC, więc w razie wątpliwości wypróbuj wszystkie trzy.

3. 3

   Wpisz wiadomość

   Wklej dokładnie te bajty, które chcesz podpisać — w przypadku webhooka jest to surowe ciało żądania, bajt po bajcie, bez ponownej serializacji ani zmian białych znaków. HMAC przelicza się na żywo podczas edycji, a nic nie jest wysyłane na serwer.

4. 4

   Wybierz format wyjścia i skopiuj

   Wybierz Hex (styl GitHuba), Base64 (styl Stripe/AWS) lub Base64URL (styl JWT), aby pasował do tego, czego oczekuje Twoja integracja, a następnie kliknij Kopiuj, aby pobrać podpis.

5. 5

   Zweryfikuj istniejący podpis

   Przejdź do zakładki Weryfikuj, wklej Oczekiwany HMAC z nagłówka lub tokena, a narzędzie potwierdzi w czasie stałym, czy obliczony przez Ciebie podpis pasuje — dzięki czemu możesz uwierzytelnić ładunek, zanim na nim zadziałasz.

Częste błędy w HMAC

// Server stored a base64 secret but you sign the literal string
createHmac('sha256', 'c2VjcmV0LWtleQ==').update(msg)

// Decode the base64 secret to raw bytes first
createHmac('sha256', Buffer.from('c2VjcmV0LWtleQ==', 'base64')).update(msg)

// Provider sends base64, you compare hex
expected = 'Cd2f7z...=' // base64
actual   = digest('hex') // hex — never matches

// Produce the same encoding the provider uses
actual = digest('base64')

// Re-serialization changes the bytes
body = JSON.stringify(JSON.parse(rawBody))
verify(hmac(body))

// Sign the raw bytes exactly as received
verify(hmac(rawBody))

if (received === computed) { /* trust */ }

if (crypto.timingSafeEqual(receivedBuf, computedBuf)) { /* trust */ }

Do czego służy HMAC

Weryfikuj podpisy webhooków

Dostawcy tacy jak GitHub, Stripe, Slack i Twilio podpisują każdy webhook za pomocą HMAC nad ciałem żądania i sekretem, który dzielisz tylko Ty. Przelicz tag i porównaj go z nagłówkiem (na przykład X-Hub-Signature-256), aby potwierdzić, że zdarzenie jest prawdziwe, zanim na nim zadziałasz. Użyj zakładki Weryfikuj, aby zrobić to bez pisania jednorazowego kodu.

Podpisuj żądania API

Uwierzytelnione API często wymagają, by klient podpisał żądanie za pomocą HMAC (metoda, ścieżka, znacznik czasu, ciało) współdzielonym sekretem, zamiast wysyłać sam sekret. AWS Signature Version 4 to kanoniczny przykład. To narzędzie pozwala odtworzyć i debugować te podpisy krok po kroku.

Zagwarantuj integralność wiadomości

Gdy przekazujesz token, ciasteczko lub wiadomość między usługami, dołączenie HMAC pozwala odbiorcy wykryć każdą manipulację. Ponieważ tag zależy od sekretu, napastnik nie może go przeliczyć po zmodyfikowaniu danych — w przeciwieństwie do zwykłej sumy kontrolnej.

Zrozum podpisywanie JWT HS256

JWT podpisany za pomocą HS256 to po prostu base64url(header) + '.' + base64url(payload), podpisany za pomocą HMAC-SHA256, a wynik emitowany jako Base64URL. Ustaw tutaj algorytm na SHA-256, a wyjście na Base64URL, aby zobaczyć dokładnie, jak powstaje ten podpis, a potem sprawdź to krzyżowo w koderze JWT.

Debuguj niezgodny podpis

Gdy Twój HMAC nie chce pasować do serwera, to narzędzie jest najszybszym sposobem na wyizolowanie przyczyny: wypróbuj klucz jako Tekst, Hex i Base64, przełącz wyjście między Hex a Base64 i upewnij się, że podpisujesz dokładnie te surowe bajty — wszystko bez ponownego wdrażania kodu.

Jak działa HMAC

Konstrukcja RFC 2104

HMAC jest zdefiniowany jako H((K ⊕ opad) ‖ H((K ⊕ ipad) ‖ m)), gdzie ipad to powtarzany bajt 0x36, a opad to powtarzany 0x5c, oba do rozmiaru bloku skrótu. Klucz dłuższy niż rozmiar bloku jest najpierw haszowany; krótszy jest dopełniany zerami. To dwuprzebiegowe zagnieżdżenie daje HMAC jego dowód bezpieczeństwa, który obowiązuje nawet wtedy, gdy bazowy skrót nie jest odporny na kolizje.

Dlaczego skrót z kluczem bije zwykły skrót

Zwykły skrót dowodzi tylko, że dane nie zostały przypadkowo uszkodzone, bo każdy może go przeliczyć dla dowolnej wiadomości — także zmodyfikowanej. HMAC dodaje sekret, więc tylko posiadacze klucza mogą wytworzyć poprawny tag. To zamienia samą integralność w integralność plus autentyczność, czyli właściwość, której naprawdę potrzebują webhooki i podpisane żądania.

Odporność na length-extension

Nagie SHA-1, SHA-256 i SHA-512 to skróty Merkle–Damgård podatne na length-extension: mając H(secret ‖ msg), napastnik może obliczyć H(secret ‖ msg ‖ extra) bez znajomości sekretu. Naiwne schematy „MAC z prefiksem sekretu” są przez to łamane. Zewnętrzny skrót HMAC neutralizuje ten atak, co jest głównym powodem, by używać HMAC zamiast haszowania sekretu i wiadomości razem.

Wybór między SHA-256 a SHA-512

HMAC-SHA256 produkuje 256-bitowy tag (64 znaki hex) i jest domyślnym wyborem dla interoperacyjności — szybki, wszechobecny i obsługiwany wszędzie. HMAC-SHA512 produkuje 512-bitowy tag (128 znaków hex) i często jest szybszy na 64-bitowych CPU, bo SHA-512 używa 64-bitowych słów. Wybierz SHA-256, chyba że specyfikacja lub system partnerski wymaga SHA-512; oba są bezpieczne do uwierzytelniania.

Implementacja Web Crypto

To narzędzie wywołuje crypto.subtle.importKey, aby załadować Twój klucz (zdekodowany z Tekst, Hex lub Base64), oraz crypto.subtle.sign('HMAC', ...), aby obliczyć tag, a następnie koduje surowe bajty jako Hex, Base64 lub Base64URL. To ta sama natywna, zaudytowana implementacja, której przeglądarka używa do TLS, działająca poza silnikiem JavaScript dla szybkości.

Najlepsze praktyki HMAC

Użyj klucza co najmniej tak długiego jak wyjście skrótu

Dla HMAC-SHA256 użyj sekretu o długości co najmniej 32 losowych bajtów (256 bitów); dla SHA-512 użyj 64. Krótki lub niskoentropijny klucz to najsłabsze ogniwo. Generuj klucze z kryptograficznie bezpiecznego źródła losowości — nigdy z hasła ani przewidywalnego ciągu.

Zawsze porównuj tagi w czasie stałym

Weryfikuj podpisy porównaniem w czasie stałym (crypto.timingSafeEqual w Node, hmac.compare_digest w Pythonie) zamiast == lub równości ciągów. Naiwne porównanie kończy się wcześnie na pierwszym różniącym się bajcie, wyciekając czas, który może pozwolić napastnikowi odtworzyć poprawny tag bajt po bajcie. Zakładka Weryfikuj tego narzędzia już porównuje w czasie stałym.

Nigdy nie loguj ani nie ujawniaj tajnego klucza

Trzymaj sekrety podpisujące z dala od logów, komunikatów o błędach, URL-i i kodu po stronie klienta. Przechowuj je w menedżerze sekretów lub zmiennych środowiskowych, rotuj okresowo i ogranicz każdą integrację do własnego klucza, aby jeden wyciek nie skompromitował wszystkiego.

Preferuj HMAC-SHA256 lub mocniejszy

Domyślnie wybieraj HMAC-SHA256; przejdź na SHA-384 lub SHA-512, gdy partner tego wymaga. Unikaj HMAC-SHA1 w nowych systemach i nigdy nie używaj HMAC-MD5. Choć HMAC lepiej toleruje słabszy skrót niż surowy podpis, start od nowoczesnego skrótu daje Ci największy margines.

Podpisuj dokładnie te bajty, włącznie ze znacznikiem czasu

Podpisuj surowy, niezmodyfikowany ładunek — ponowna serializacja JSON lub przycinanie białych znaków zmienia bajty i psuje weryfikację. Przy podpisywaniu żądań włącz znacznik czasu lub nonce do podpisanych danych i odrzucaj nieaktualne podpisy, aby zapobiec atakom powtórzeniowym.

FAQ o HMAC