HMAC-generator

Slik fungerer HMAC

HMAC (hash-based message authentication code, RFC 2104) kombinerer en kryptografisk hashfunksjon med en hemmelig nøkkel. Bare den som kjenner nøkkelen, kan lage riktig verdi for en melding, så en HMAC som samsvarer, beviser to ting på en gang: meldingen er ikke endret, og den kommer fra noen som har nøkkelen.

Konstruksjonen er H((K ⊕ opad) ‖ H((K ⊕ ipad) ‖ message)). Nøkkelen hashes først hvis den er lengre enn blokkstørrelsen til hashfunksjonen (64 byte for MD5, SHA-1 og SHA-256, 128 for SHA-384 og SHA-512), fylles deretter ut med nuller til denne størrelsen og XOR-es med ipad (byte med verdien 0x36) for en indre hash over meldingen og med opad (byte med verdien 0x5c) for en ytre hash over det indre resultatet. En naiv SHA-256(key ‖ message) har ingen ytre hash, så alle som ser én slik kode, kan legge til data i meldingen og beregne en ny gyldig kode uten nøkkelen (et lengdeutvidelsesangrep, length extension attack).

Utdataene har samme lengde som den underliggende hashen: 32 byte, eller 64 hex-tegn, for HMAC-SHA256. RFC 2104 anbefaler en nøkkel som er minst så lang, og generatoren for tilfeldig Base64 lager egnede nøkler.

Hvor HMAC-signaturer brukes

• GitHub-webhooks. Headeren X-Hub-Signature-256 består av sha256= etterfulgt av HMAC-SHA256 i hex av den rå forespørselskroppen, med webhook-hemmeligheten som nøkkel. Du kan lime inn hele headerverdien i Sammenlign med. Prefikset sha256= ignoreres.
• Stripe-webhooks. Headeren Stripe-Signature inneholder et tidsstempel t og en signatur v1: HMAC-SHA256 i hex av tidsstempelet, et punktum og den rå kroppen, med endepunktshemmeligheten (whsec_...) brukt som tekstnøkkel.
• Shopify-webhooks. X-Shopify-Hmac-Sha256 inneholder HMAC-SHA256 av den rå kroppen i Base64, med appens klienthemmelighet som nøkkel, så velg Base64 som utdata eller lim inn headerverdien i Sammenlign med.
• AWS Signature Version 4. Signeringsnøkkelen utledes ved å kjede HMAC-SHA256: først datoen med AWS4 pluss den hemmelige tilgangsnøkkelen som nøkkel, deretter regionen, tjenesten og aws4_request, hver med det forrige resultatet som nøkkel. Sett Nøkkelformat til Hex for å bruke utdataene fra ett trinn i det neste.
• JSON Web Tokens. HS256, HS384 og HS512 er HMAC-SHA256, -384 og -512 over den kodede headeren, et punktum og den kodede payloaden. Den tredje delen av tokenet er denne HMAC-verdien i URL-sikker Base64, som Sammenlign med godtar slik den er. JWT-dekoderen verifiserer hele tokener.

Beregn alltid HMAC over den rå kroppen nøyaktig slik den ble mottatt. Hvis du parser JSON og serialiserer den på nytt, endres mellomrom eller rekkefølgen på nøklene, og selv ett ekstra linjeskift gir en helt annen HMAC.

HMAC i kode

# Python
import hmac, hashlib
sig = hmac.new(b'key', b'message', hashlib.sha256).hexdigest()
hmac.compare_digest(sig, received)        # sammenligning i konstant tid

// Node.js
const crypto = require('crypto');
const sig = crypto.createHmac('sha256', 'key').update('message').digest('hex');
// timingSafeEqual kaster en feil hvis lengdene er ulike, så sjekk dem først
crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(received));

// PHP: meldingen kommer før nøkkelen
$sig = hash_hmac('sha256', 'message', 'key');
hash_equals($sig, $received);

# OpenSSL: en tekstnøkkel, deretter samme nøkkel angitt som hex
printf '%s' 'message' | openssl dgst -sha256 -hmac 'key'
printf '%s' 'message' | openssl dgst -sha256 -mac HMAC -macopt hexkey:6b6579

# Testvektor: nøkkel "key", melding "The quick brown fox jumps over the lazy dog"
# HMAC-SHA256 = f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8

Når du verifiserer en signatur i din egen kode, bør du bruke en sammenligning i konstant tid som i eksemplene over. En vanlig == stopper ved det første tegnet som er ulikt, og den tidsforskjellen kan la en angriper finne en gyldig signatur byte for byte. For ordninger med tidsstempel, som den Stripe bruker, bør du også avvise forespørsler der tidsstempelet er mer enn noen minutter gammelt. Det hindrer replay-angrep.