HMAC-generator

Så fungerar HMAC

HMAC (hash-based message authentication code, RFC 2104) kombinerar en kryptografisk hashfunktion med en hemlig nyckel. Bara den som känner till nyckeln kan ta fram rätt värde för ett meddelande, så ett HMAC-värde som stämmer bevisar två saker på en gång: meddelandet har inte ändrats, och det kommer från någon som har nyckeln.

Konstruktionen är H((K ⊕ opad) ‖ H((K ⊕ ipad) ‖ message)). Nyckeln hashas först om den är längre än hashfunktionens blockstorlek (64 byte för MD5, SHA-1 och SHA-256, 128 för SHA-384 och SHA-512), fylls ut med nollor till den storleken och XOR:as sedan med ipad (byte med värdet 0x36) för en inre hashning av meddelandet och med opad (byte med värdet 0x5c) för en yttre hashning av det inre resultatet. En naiv SHA-256(key ‖ message) saknar den yttre hashningen, så den som ser en enda tagg kan lägga till data i meddelandet och beräkna en ny giltig tagg utan att känna till nyckeln (en så kallad längdförlängningsattack, length extension).

Utdatan är lika lång som den underliggande hashfunktionens: 32 byte, eller 64 hextecken, för HMAC-SHA256. RFC 2104 rekommenderar en nyckel som är minst lika lång, och generatorn för slumpmässig Base64 skapar lämpliga nycklar.

Här används HMAC-signaturer

• Webhooks från GitHub. Headern X-Hub-Signature-256 består av sha256= följt av HMAC-SHA256 i hex för den råa anropskroppen, med webhookens hemlighet som nyckel. Du kan klistra in hela headervärdet i Jämför med; prefixet sha256= ignoreras.
• Webhooks från Stripe. Headern Stripe-Signature innehåller en tidsstämpel t och en signatur v1: HMAC-SHA256 i hex för tidsstämpeln, en punkt och den råa anropskroppen, med slutpunktens hemlighet (whsec_...) som nyckel i textform.
• Webhooks från Shopify. X-Shopify-Hmac-Sha256 innehåller HMAC-SHA256 för den råa anropskroppen i Base64, med appens klienthemlighet som nyckel, så välj Base64 under Utdata som eller klistra in headervärdet i Jämför med.
• AWS Signature Version 4. Signeringsnyckeln härleds genom att HMAC-SHA256 kedjas: först datumet med AWS4 plus den hemliga åtkomstnyckeln som nyckel, sedan regionen, tjänsten och aws4_request, var och en med föregående resultat som nyckel. Ställ in Nyckelformat på Hex för att mata in utdatan från ett steg i nästa.
• JSON Web Tokens. HS256, HS384 och HS512 är HMAC-SHA256, -384 och -512 över det kodade huvudet, en punkt och den kodade nyttolasten. Tokenens tredje del är detta HMAC-värde i URL-säker Base64, som Jämför med godtar som det är. JWT-avkodaren verifierar hela tokens.

Beräkna alltid HMAC över den råa anropskroppen exakt som den togs emot. Om du tolkar JSON och serialiserar den igen ändras blanksteg eller nyckelordning, och redan en extra radbrytning ger ett helt annat HMAC-värde.

HMAC i kod

# Python
import hmac, hashlib
sig = hmac.new(b'key', b'message', hashlib.sha256).hexdigest()
hmac.compare_digest(sig, received)        # jämförelse i konstant tid

// Node.js
const crypto = require('crypto');
const sig = crypto.createHmac('sha256', 'key').update('message').digest('hex');
// timingSafeEqual kastar ett fel om längderna skiljer sig, så kontrollera dem först
crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(received));

// PHP: meddelandet kommer före nyckeln
$sig = hash_hmac('sha256', 'message', 'key');
hash_equals($sig, $received);

# OpenSSL: en nyckel som text, sedan samma nyckel angiven som hex
printf '%s' 'message' | openssl dgst -sha256 -hmac 'key'
printf '%s' 'message' | openssl dgst -sha256 -mac HMAC -macopt hexkey:6b6579

# Testvektor: nyckeln "key", meddelandet "The quick brown fox jumps over the lazy dog"
# HMAC-SHA256 = f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8

När du verifierar en signatur i din egen kod ska du använda en jämförelse i konstant tid, som i exemplen ovan. En vanlig == avbryter vid det första tecknet som skiljer sig, och den tidsskillnaden kan låta en angripare hitta en giltig signatur byte för byte. För system med tidsstämplar, som Stripes, bör du också avvisa anrop vars tidsstämpel är äldre än några minuter, vilket stoppar återuppspelningsattacker (replay).