Generator HMAC

Jak działa HMAC

HMAC (hash-based message authentication code, czyli kod uwierzytelniania wiadomości oparty na funkcji hashującej, RFC 2104) łączy kryptograficzną funkcję hashującą z kluczem tajnym. Tylko ktoś, kto zna klucz, może obliczyć prawidłową wartość dla danej wiadomości, więc zgodny HMAC dowodzi jednocześnie dwóch rzeczy: wiadomość nie została zmieniona i pochodzi od posiadacza klucza.

Konstrukcja ma postać H((K ⊕ opad) ‖ H((K ⊕ ipad) ‖ message)). Klucz dłuższy niż rozmiar bloku funkcji hashującej (64 bajty dla MD5, SHA-1 i SHA-256, 128 dla SHA-384 i SHA-512) jest najpierw hashowany, potem dopełniany zerami do tego rozmiaru, a następnie poddawany operacji XOR z ipad (bajty 0x36) na potrzeby wewnętrznego hasha obliczanego z wiadomości oraz z opad (bajty 0x5c) na potrzeby zewnętrznego hasha obliczanego z wyniku wewnętrznego. Naiwna konstrukcja SHA-256(key ‖ message) nie ma zewnętrznego hasha, więc każdy, kto zobaczy jeden taki kod, może dopisać dane do wiadomości i bez znajomości klucza obliczyć nowy prawidłowy kod (atak przedłużenia wiadomości, ang. length extension).

Wynik ma taką samą długość jak wynik bazowej funkcji hashującej: dla HMAC-SHA256 to 32 bajty, czyli 64 znaki hex. RFC 2104 zaleca klucz co najmniej tej długości, a odpowiednie klucze tworzy generator losowego Base64.

Gdzie używa się podpisów HMAC

• Webhooki GitHub. Nagłówek X-Hub-Signature-256 to sha256=, po którym następuje HMAC-SHA256 w postaci hex obliczony z surowej treści żądania, z sekretem webhooka jako kluczem. Całą wartość nagłówka można wkleić w pole „Porównaj z”; prefiks sha256= jest ignorowany.
• Webhooki Stripe. Nagłówek Stripe-Signature zawiera znacznik czasu t i podpis v1: HMAC-SHA256 w postaci hex obliczony ze znacznika czasu, kropki i surowej treści, z sekretem punktu końcowego (whsec_...) użytym jako klucz tekstowy.
• Webhooki Shopify. X-Shopify-Hmac-Sha256 zawiera HMAC-SHA256 surowej treści w Base64, obliczony z sekretem klienta aplikacji (client secret) jako kluczem, więc wybierz wyjście „Base64” albo wklej wartość nagłówka w pole „Porównaj z”.
• AWS Signature Version 4. Klucz podpisujący powstaje przez łańcuch operacji HMAC-SHA256: najpierw obliczany jest HMAC daty z kluczem AWS4 połączonym z tajnym kluczem dostępu, potem regionu, usługi i aws4_request, za każdym razem z poprzednim wynikiem jako kluczem. Ustaw „Format klucza” na „Hex”, aby przekazać wynik jednego kroku do następnego.
• JSON Web Token. HS256, HS384 i HS512 to HMAC-SHA256, -384 i -512 obliczone z zakodowanego nagłówka, kropki i zakodowanego ładunku. Trzecia część tokena to ten HMAC w Base64 bezpiecznym dla URL, który pole „Porównaj z” przyjmuje bez zmian. Całe tokeny weryfikuje dekoder JWT.

Zawsze obliczaj HMAC z surowej treści dokładnie w takiej postaci, w jakiej została odebrana. Parsowanie JSON i ponowna serializacja zmieniają odstępy lub kolejność kluczy, a nawet jeden dodatkowy znak nowego wiersza daje zupełnie inny HMAC.

HMAC w kodzie

# Python
import hmac, hashlib
sig = hmac.new(b'key', b'message', hashlib.sha256).hexdigest()
hmac.compare_digest(sig, received)        # porównanie w stałym czasie

// Node.js
const crypto = require('crypto');
const sig = crypto.createHmac('sha256', 'key').update('message').digest('hex');
// timingSafeEqual zgłasza błąd, gdy długości się różnią, więc najpierw je sprawdź
crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(received));

// PHP: wiadomość podaje się przed kluczem
$sig = hash_hmac('sha256', 'message', 'key');
hash_equals($sig, $received);

# OpenSSL: klucz tekstowy, a potem ten sam klucz podany jako hex
printf '%s' 'message' | openssl dgst -sha256 -hmac 'key'
printf '%s' 'message' | openssl dgst -sha256 -mac HMAC -macopt hexkey:6b6579

# Wektor testowy: klucz "key", wiadomość "The quick brown fox jumps over the lazy dog"
# HMAC-SHA256 = f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8

Weryfikując podpis we własnym kodzie, używaj porównania w stałym czasie, takiego jak w przykładach powyżej. Zwykłe == kończy porównanie na pierwszym różniącym się znaku, a ta różnica w czasie wykonania może pozwolić atakującemu odgadnąć prawidłowy podpis bajt po bajcie. W schematach ze znacznikiem czasu, takich jak schemat Stripe, odrzucaj też żądania, których znacznik czasu jest starszy niż kilka minut – to blokuje ataki powtórzeniowe.