CodeKitHubChe cos'è questo strumento?
HMAC è l'acronimo di Hash-based Message Authentication Code. Combina una chiave segreta, un messaggio e una funzione hash standard (come SHA-256) per produrre un digest di lunghezza fissa. Chiunque disponga della stessa chiave e dello stesso messaggio otterrà esattamente lo stesso HMAC — ma senza la chiave è computazionalmente impossibile produrre un HMAC valido per un messaggio, anche conoscendo l'algoritmo hash utilizzato.
Questa è la differenza fondamentale rispetto a un semplice hash: un hash normale (MD5, SHA-256, ecc.) prende in input solo il messaggio, quindi chiunque può calcolarlo e non dimostra nulla su chi lo ha creato. Un HMAC prende il messaggio *e* una chiave segreta, quindi un HMAC valido dimostra che il mittente possedeva il segreto — è un meccanismo di autenticazione, non solo un controllo di integrità.
L'HMAC è formalmente standardizzato dal NIST nel FIPS 198-1 ed è definito per i protocolli internet nell'RFC 2104 dell'IETF. Questo strumento calcola gli HMAC tramite la Web Crypto API nativa del browser (`crypto.subtle.sign` con l'algoritmo HMAC), che implementa correttamente l'RFC 2104 anziché una versione JavaScript fatta in casa.
Perché usarlo?
- Il tuo endpoint webhook Stripe restituisce sempre "signature verification failed" in staging e devi capire se il bug è nel tuo codice o nella chiave che stai usando — incolli lo stesso payload e webhook secret qui per vedere subito quale HMAC-SHA256 dovresti aspettarti.
- Stai integrando un'API di terze parti che richiede di firmare ogni richiesta con HMAC-SHA1 e la documentazione fornisce solo un esempio in Python — generi lo stesso HMAC qui con chiave e messaggio identici per confermare che la tua implementazione lato client produce lo stesso risultato prima di scrivere una riga di codice.
- Un collega ti ha mandato un frammento di codice che calcola HMAC-SHA256 in Node.js e vuoi verificare rapidamente che l'output sia corretto senza dover installare Node o avviare un REPL sul tuo computer.
- Devi generare un token HOTP/TOTP per il debug di un sistema di autenticazione a due fattori e vuoi vedere l'HMAC intermedio prima che venga troncato nel codice OTP a 6 cifre finale.
- Stai scrivendo una guida interna su come firmare le richieste verso un microservizio con un segreto condiviso e vuoi includere un esempio verificabile che i colleghi possano riprodurre esattamente incollando gli stessi valori.
- 100% locale: la tua chiave segreta e il tuo messaggio non lasciano mai il browser, quindi puoi testare segreti reali di produzione senza il rischio di inviarli a un server terzo.
Come si usa
- Inserisci la tua chiave segreta nel campo "Chiave segreta".
- Inserisci il messaggio che vuoi autenticare nel campo "Messaggio".
- I risultati HMAC-SHA1, HMAC-SHA256, HMAC-SHA384 e HMAC-SHA512 vengono generati all'istante (spunta "Output maiuscolo" se il sistema di destinazione richiede lettere maiuscole).
- Fai clic su "Copia" accanto all'HMAC che ti serve.
Esempio
Input
Chiave segreta: key
Messaggio: The quick brown fox jumps over the lazy dogRisultato
HMAC-SHA256: f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8
HMAC-SHA1: de7c9b85b8b78aa6bc8a7a36f70a90701c9db4d9Questo è un vettore di test standard pubblicato: con la chiave "key" e questo messaggio esatto, HMAC-SHA256 e HMAC-SHA1 producono sempre questi valori in qualsiasi implementazione corretta, quindi puoi verificare in modo indipendente l'output di questo strumento.
HMAC vs semplice hash: quando serve una chiave
La domanda decisiva è: devi dimostrare chi ha creato questo digest, o solo che il contenuto non è cambiato? Se basta un checksum pubblico — verificare che un file scaricato corrisponda a quanto indicato dall'editore, deduplicare record — un semplice hash funziona e chiunque può verificarlo, senza bisogno di chiave. Se devi dimostrare che il digest può essere stato prodotto solo da chi possiede un segreto specifico — autenticare chi chiama un'API, fidarsi del mittente di un webhook — ti serve l'HMAC, perché un semplice hash darebbe a un attaccante privo di segreto la stessa capacità di falsificare un digest valido che ha il vero mittente.
→ Generatore di hash multi-algoritmo · Decodificatore JWT · Generatore MD5
Confronto tra i quattro algoritmi HMAC
Tutti e quattro usano la stessa costruzione HMAC definita dall'RFC 2104, differendo solo per la funzione hash sottostante e quindi per la lunghezza dell'output.
| Algoritmo | Dimensione output | Uso tipico |
|---|---|---|
| HMAC-SHA1 | 160 bit (40 caratteri esadecimali) | API legacy, vecchie firme OAuth 1.0a |
| HMAC-SHA256 | 256 bit (64 caratteri esadecimali) | Firma di richieste API, JWT HS256, verifica webhook |
| HMAC-SHA384 | 384 bit (96 caratteri esadecimali) | Firme ad affidabilità maggiore dove serve un output più lungo |
| HMAC-SHA512 | 512 bit (128 caratteri esadecimali) | Digest di lunghezza massima per applicazioni ad alta sicurezza |
Casi d'uso comuni
- Firmare le richieste API in uscita con un segreto condiviso in modo che il server possa verificare l'identità di chi chiama.
- Verificare i payload dei webhook in entrata (gli header Stripe-Signature, X-Hub-Signature-256 di GitHub e simili usano tutti HMAC-SHA256).
- Generare e validare la parte di firma di un JWT firmato con HS256/HS384/HS512.
- Verificare che la tua implementazione HMAC lato server o lato client corrisponda all'output atteso prima di metterla in produzione.
Debug di un HMAC che non corrisponde
Quando l'HMAC calcolato dal tuo codice non coincide con quello atteso da un servizio esterno, il problema è quasi sempre nell'input, non nell'algoritmo — questo strumento è utile proprio per isolare la causa.
Costruisci il test partendo dal vettore noto nell'esempio qui sopra per confermare che lo strumento stesso funziona come previsto, poi sostituisci gradualmente chiave e messaggio con i tuoi valori reali finché non individui esattamente dove l'output smette di corrispondere alle tue aspettative — questo isola rapidamente se il problema è nella codifica della chiave, negli spazi bianchi del messaggio o nell'algoritmo scelto.
Domande frequenti
Cos'è l'HMAC?
L'HMAC (Hash-based Message Authentication Code) combina una chiave segreta con un messaggio tramite una funzione hash per produrre un digest che dimostra sia l'integrità del messaggio sia il possesso della chiave da parte del mittente. È definito nel FIPS 198-1 del NIST e nell'RFC 2104 dell'IETF.
Qual è la differenza tra HMAC e un semplice hash?
Un semplice hash (SHA-256, MD5, ecc.) prende in input solo un messaggio — chiunque può calcolarlo, quindi dimostra solo che il messaggio non è stato alterato, non chi lo ha inviato. Un HMAC prende un messaggio più una chiave segreta: se devi dimostrare che un messaggio proviene da chi possiede un segreto specifico (una firma API, il mittente di un webhook), ti serve l'HMAC. Se devi solo verificare che un file o un messaggio non sia cambiato, senza dover provare chi ne è l'autore, un semplice hash è sufficiente.
La mia chiave segreta viene inviata a un server?
No. Questo strumento calcola l'HMAC interamente nel tuo browser usando la Web Crypto API. La tua chiave e il tuo messaggio non vengono mai trasmessi da nessuna parte: puoi testare in tutta sicurezza segreti reali di produzione.
Quale algoritmo dovrei usare — SHA-1, SHA-256, SHA-384 o SHA-512?
Usa HMAC-SHA256 a meno che un sistema specifico non richieda diversamente: è lo standard de facto per la firma delle API (usato da AWS, Stripe, i webhook di GitHub e la maggior parte delle API moderne) e offre un buon margine di sicurezza. HMAC-SHA1 è ancora diffuso nei sistemi legacy (come le vecchie implementazioni OAuth 1.0a), ma l'hash sottostante di SHA-1 è considerato più debole; HMAC-SHA384/512 si usano quando è specificamente richiesto un output più lungo o un margine di sicurezza extra.
HMAC-SHA1 è insicuro, dato che il semplice SHA-1 è compromesso?
Gli attacchi di collisione del 2017 hanno compromesso SHA-1 come semplice funzione hash, ma HMAC-SHA1 è ancora considerato crittograficamente solido, perché la sicurezza dell'HMAC non dipende allo stesso modo dalla resistenza alle collisioni. Detto questo, per i nuovi sistemi è preferibile usare HMAC-SHA256 o superiore: non comporta alcuno svantaggio pratico ed evita del tutto la questione.
Quali sono gli usi comuni dell'HMAC nel mondo reale?
Firmare le richieste API REST in modo che un server possa verificare che chi chiama possiede il segreto API condiviso; verificare i payload dei webhook di servizi come Stripe, GitHub e Shopify per essere certi che una richiesta provenga davvero da loro e non sia stata falsificata; generare password monouso basate sul tempo (TOTP/HOTP) per l'autenticazione a due fattori; e firmare i token JWT con gli algoritmi HS256/HS384/HS512.
Il mio HMAC calcolato non corrisponde a quello atteso dal servizio: quali sono le cause più comuni?
Le cause più frequenti sono: spazi bianchi o caratteri di nuova riga extra nel messaggio (specialmente quando il payload viene copiato da un editor di testo o da un log), la codifica sbagliata della chiave (alcuni servizi si aspettano la chiave decodificata da Base64 anziché usata come stringa letterale), un mismatch tra maiuscole e minuscole nell'output esadecimale atteso, o il fatto che il servizio firmi un payload leggermente diverso da quello che stai testando (per esempio JSON con un ordine di chiavi differente).
Devo codificare la mia chiave segreta in Base64 prima di inserirla, o va bene come testo semplice?
Dipende dal servizio con cui stai lavorando: alcuni trattano la chiave segreta esattamente come la stringa di testo che hai ricevuto, altri richiedono che tu la decodifichi prima da Base64 in bytes grezzi. Controlla la documentazione dell'API specifica — se i valori non corrispondono con la chiave inserita come testo semplice, prova a decodificarla da Base64 prima di incollarla qui.
Perché l'HMAC generato è sempre della stessa lunghezza indipendentemente da quanto è lungo il mio messaggio?
È una proprietà fondamentale delle funzioni hash su cui si basa l'HMAC: l'output ha sempre una dimensione fissa determinata dall'algoritmo (160 bit per SHA-1, 256 per SHA-256, e così via), indipendentemente dal fatto che tu stia firmando una parola o un intero documento JSON. Questo è ciò che rende l'HMAC pratico da trasmettere in un header HTTP di lunghezza prevedibile.
Posso usare questo strumento per verificare la firma di un webhook che ho già ricevuto?
Sì — incolla il corpo grezzo esatto del webhook ricevuto nel campo Messaggio e il tuo segreto webhook nel campo Chiave segreta, poi confronta l'HMAC-SHA256 generato con la firma inclusa nell'header della richiesta (come Stripe-Signature). Se corrispondono, la richiesta è autentica; ricorda che devi usare il corpo grezzo esatto della richiesta, non una versione riformattata o ricodificata del JSON.