Generatore HMAC e Verificatore di Firma

Cos'è un 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);
}

Caratteristiche Principali

Esempi di HMAC

Hello, World!

cf3141611e22ea26a9cac6fe41d941274dd6653622c83cba13972d177bd69699

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

Cd2f7zTKaJFeG6k+t1FcvDPn51OAZ2f4GrxkCUgMhGs=

what do ya want for nothing?

5bdcc146bf60754e6a042426089575c75a003f089d2739839dec58b964ec3843

The quick brown fox

36f44b125a8a90639dc46733039571792e081e0fd8685ff746784b02ed14aa35629d562c7117cde4a701570551faa5a5e1b7ef1eb5c3bcd4cc1fdb8923fcf14e

Come Generare e Verificare un HMAC

1. 1

   Scegli l'algoritmo

   Scegli HMAC-SHA256 (il valore predefinito e la scelta giusta per quasi tutti i webhook, le API e i JWT), oppure passa a SHA-1, SHA-384 o SHA-512 per corrispondere a un sistema che lo richiede. Tutti e quattro girano nativamente nel tuo browser tramite la Web Crypto API.

2. 2

   Inserisci la chiave segreta e imposta la sua codifica

   Digita o incolla la tua chiave segreta, poi imposta la Codifica della chiave in modo che corrisponda a come il server la interpreta: Testo (UTF-8) per una stringa semplice, Hex per un blob esadecimale o Base64 per un segreto in base64. Sbagliare questo è la causa principale delle discrepanze HMAC, quindi nel dubbio provale tutte e tre.

3. 3

   Inserisci il messaggio

   Incolla i byte esatti che vuoi firmare — per un webhook questo è il corpo grezzo della richiesta, byte per byte, senza ri-serializzazione né modifiche agli spazi. L'HMAC si ricalcola in tempo reale mentre modifichi, senza che nulla venga inviato a un server.

4. 4

   Scegli il formato di output e copia

   Seleziona Hex (stile GitHub), Base64 (stile Stripe/AWS) o Base64URL (stile JWT) per corrispondere a ciò che la tua integrazione si aspetta, poi clicca su Copia per prendere la firma.

5. 5

   Verifica una firma esistente

   Passa alla scheda Verifica, incolla l'HMAC atteso da un header o token e lo strumento conferma in tempo costante se la tua firma calcolata corrisponde — così puoi autenticare un payload prima di agire su di esso.

Errori Comuni con l'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 */ }

A Cosa Serve l'HMAC

Verificare le firme dei webhook

Provider come GitHub, Stripe, Slack e Twilio firmano ogni webhook con HMAC sul corpo della richiesta e un segreto che solo tu condividi. Ricalcola il tag e confrontalo con l'header (per esempio X-Hub-Signature-256) per confermare che l'evento è autentico prima di agire su di esso. Usa la scheda Verifica per farlo senza scrivere codice usa e getta.

Firmare le richieste API

Le API autenticate spesso richiedono che il client firmi la richiesta con HMAC (metodo, percorso, timestamp, corpo) con un segreto condiviso invece di inviare il segreto stesso. AWS Signature Version 4 è l'esempio canonico. Questo strumento ti permette di riprodurre e fare il debug di quelle firme passo dopo passo.

Garantire l'integrità del messaggio

Quando passi un token, un cookie o un messaggio tra servizi, allegare un HMAC permette al destinatario di rilevare qualsiasi manomissione. Poiché il tag dipende da un segreto, un attaccante non può ricalcolarlo dopo aver modificato i dati — a differenza di un semplice checksum.

Capire la firma HS256 del JWT

Un JWT firmato con HS256 è semplicemente base64url(header) + '.' + base64url(payload), firmato con HMAC-SHA256 e il risultato emesso come Base64URL. Imposta l'algoritmo su SHA-256 e l'output su Base64URL qui per vedere esattamente come viene prodotta quella firma, poi ricontrolla nel codificatore JWT.

Fare il debug di una firma che non corrisponde

Quando il tuo HMAC non corrisponde a quello del server, questo strumento è il modo più rapido per isolare il perché: prova la chiave come Testo, Hex e Base64, alterna l'output tra Hex e Base64 e conferma di star firmando esattamente i byte grezzi — il tutto senza ridistribuire alcun codice.

Come Funziona l'HMAC

Costruzione della RFC 2104

L'HMAC è definito come H((K ⊕ opad) ‖ H((K ⊕ ipad) ‖ m)), dove ipad è il byte 0x36 ripetuto e opad è 0x5c ripetuto, entrambi fino alla dimensione del blocco dell'hash. Una chiave più lunga della dimensione del blocco viene prima sottoposta a hash; una chiave più corta viene riempita con zeri. Questo annidamento a due passaggi è ciò che dà all'HMAC la sua prova di sicurezza, che vale anche se l'hash sottostante non è resistente alle collisioni.

Perché un hash con chiave batte un hash semplice

Un hash semplice dimostra solo che i dati non sono stati corrotti per caso, perché chiunque può ricalcolarlo per qualsiasi messaggio — incluso uno manomesso. L'HMAC mescola un segreto, così solo chi possiede la chiave può produrre un tag valido. Questo converte la sola integrità in integrità più autenticità, che è la proprietà di cui i webhook e le richieste firmate hanno effettivamente bisogno.

Resistenza all'estensione della lunghezza

SHA-1, SHA-256 e SHA-512 nudi sono hash di Merkle–Damgård vulnerabili all'estensione della lunghezza: dato H(segreto ‖ msg) un attaccante può calcolare H(segreto ‖ msg ‖ extra) senza conoscere il segreto. Gli schemi ingenui di 'MAC con prefisso segreto' vengono rotti da questo. L'hash esterno dell'HMAC neutralizza l'attacco, ed è il motivo principale per usare l'HMAC invece di sottoporre a hash un segreto e un messaggio insieme.

Scegliere SHA-256 vs SHA-512

L'HMAC-SHA256 produce un tag di 256 bit (64 caratteri hex) ed è il valore predefinito per l'interoperabilità — veloce, onnipresente e supportato ovunque. L'HMAC-SHA512 produce un tag di 512 bit (128 caratteri hex) ed è spesso più veloce su CPU a 64 bit perché SHA-512 usa parole a 64 bit. Scegli SHA-256 a meno che una specifica o un sistema partner richieda SHA-512; entrambi sono sicuri per l'autenticazione.

Implementazione con Web Crypto

Questo strumento chiama crypto.subtle.importKey per caricare la tua chiave (decodificata da Testo, Hex o Base64) e crypto.subtle.sign('HMAC', ...) per calcolare il tag, poi codifica i byte grezzi come Hex, Base64 o Base64URL. È la stessa implementazione nativa e sottoposta ad audit che il browser usa per il TLS, eseguita al di fuori del motore JavaScript per la velocità.

Buone Pratiche per l'HMAC

Usa una chiave lunga almeno quanto l'output dell'hash

Per HMAC-SHA256 usa un segreto di almeno 32 byte casuali (256 bit); per SHA-512 usane 64. Una chiave corta o a bassa entropia è l'anello più debole. Genera le chiavi da una fonte casuale crittograficamente sicura — mai una password o una stringa prevedibile.

Confronta sempre i tag in tempo costante

Verifica le firme con un confronto a tempo costante (crypto.timingSafeEqual in Node, hmac.compare_digest in Python) invece di == o dell'uguaglianza tra stringhe. Un confronto ingenuo si ferma presto al primo byte diverso, rivelando una temporizzazione che può permettere a un attaccante di recuperare un tag valido byte per byte. La scheda Verifica di questo strumento confronta già in tempo costante.

Non registrare né esporre mai la chiave segreta

Tieni i segreti di firma fuori dai log, dai messaggi di errore, dagli URL e dal codice lato client. Conservali in un gestore di segreti o in variabili d'ambiente, ruotali periodicamente e assegna a ogni integrazione la propria chiave così che una fuga non comprometta tutto.

Preferisci HMAC-SHA256 o più forte

Usa HMAC-SHA256 come default; sali a SHA-384 o SHA-512 quando un partner lo richiede. Evita HMAC-SHA1 nei sistemi nuovi e non usare mai HMAC-MD5. Anche se l'HMAC tollera un hash più debole meglio di quanto farebbe una firma pura, partire da un hash moderno ti dà il massimo margine.

Firma i byte esatti, incluso un timestamp

Firma il payload grezzo e non modificato — ri-serializzare il JSON o togliere gli spazi cambia i byte e rompe la verifica. Per firmare le richieste, includi un timestamp o un nonce nei dati firmati e rifiuta le firme datate per prevenire gli attacchi di replay.

Domande Frequenti sull'HMAC