Calcule um HMAC ou confira o que um webhook enviou para você
Este gerador HMAC assina uma mensagem com uma chave secreta usando HMAC-SHA256, HMAC-SHA1, HMAC-SHA384 ou HMAC-SHA512 e mostra a assinatura em hex minúsculo, hex maiúsculo, Base64 e Base64url ao mesmo tempo. A chave e a mensagem podem ser digitadas como texto simples, hex ou Base64, então funciona tanto com segredos binários quanto com senhas. Cole a assinatura que você recebeu — <code>sha256=…</code> do GitHub, um cabeçalho do Stripe <code>t=…,v1=…</code> ou Base64 simples — e ele diz se ela confere. O cálculo usa a Web Crypto API do seu navegador; a chave e a mensagem nunca saem da página.
Como gerar ou verificar um HMAC
- 1Escolha a função hash: SHA-256 é a usada pela maioria das APIs e webhooks.
- 2Digite ou cole a chave secreta e escolha como ela está escrita: texto, hex ou Base64. Use Chave aleatória para criar um novo segredo com o tamanho certo.
- 3Cole a mensagem — em um webhook, o corpo bruto da requisição exatamente como chegou, byte a byte.
- 4Copie a assinatura na codificação de que você precisa. Para conferir uma assinatura, cole-a em Assinatura esperada; um prefixo como
sha256=é reconhecido e ignorado.
O que é um HMAC?
Um HMAC (hash-based message authentication code, RFC 2104) é um valor curto calculado a partir de uma mensagem e de uma chave secreta. Quem conhece a chave consegue calcular o mesmo valor e, assim, verificar duas coisas de uma vez: que a mensagem não foi alterada no caminho e que ela foi produzida por alguém que tem a chave. Sem a chave, um atacante não consegue forjar um HMAC válido para uma nova mensagem nem ajustar um depois de alterar a mensagem.
Não é simplesmente um hash da chave e da mensagem juntas. O HMAC aplica o hash duas vezes, com a chave misturada em um padding interno e outro externo: H((K ⊕ opad) ‖ H((K ⊕ ipad) ‖ message)). É essa construção que o torna seguro com SHA-256 e SHA-512, que sozinhos ficam vulneráveis a ataques de extensão de comprimento quando usados como H(key ‖ message).
Verificando assinaturas de webhook
A maioria dos provedores de webhook assina cada requisição com um HMAC do corpo e coloca o resultado em um cabeçalho. Para verificar, calcule o HMAC do corpo bruto com o seu segredo de assinatura e compare com o valor do cabeçalho. O erro mais comum é aplicar o hash a um objeto JSON reserializado em vez dos bytes que chegaram: uma ordem de chaves diferente ou um espaço faltando muda a assinatura por completo.
Alguns provedores assinam mais do que o corpo. O Stripe assina timestamp.body — o valor t do cabeçalho, um ponto e depois o payload — e o Slack assina v0:timestamp:body. Monte exatamente essa string como mensagem aqui e cole o cabeçalho completo na caixa de verificação; o valor v1= ou v0= é extraído dele.
- GitHub
- <code>X-Hub-Signature-256: sha256=<hex></code>, HMAC-SHA256 do corpo com o segredo do webhook como texto.
- Stripe
- <code>Stripe-Signature: t=…,v1=<hex></code>, HMAC-SHA256 de <code>t.body</code>.
- Shopify
- <code>X-Shopify-Hmac-Sha256: <Base64></code>, HMAC-SHA256 do corpo.
- Slack
- <code>X-Slack-Signature: v0=<hex></code>, HMAC-SHA256 de <code>v0:timestamp:body</code>.
Chaves em texto, hex e Base64
Uma chave é uma sequência de bytes, e a forma como ela é escrita importa. O texto abc123 tem seis bytes; o hex abc123 são três bytes completamente diferentes. Muitos serviços entregam segredos como strings hex ou Base64, mas esperam que você use a própria string como chave de texto — GitHub e Stripe fazem isso — enquanto outros, como as cadeias de assinatura no estilo AWS e os app proxies do Shopify, usam os bytes decodificados. Se uma assinatura não confere, trocar a codificação da chave é a primeira coisa a tentar.
Para uma chave nova, use bytes aleatórios com pelo menos o tamanho da saída do hash: 32 bytes para HMAC-SHA256 e 64 para HMAC-SHA512. Chaves maiores não acrescentam nada — o que passar do tamanho de bloco do hash é reduzido com hash primeiro.
Comparação em tempo constante
Quando o seu servidor verificar uma assinatura, compare-a com uma função de tempo constante como crypto.timingSafeEqual no Node.js, hmac.compare_digest no Python ou hash_equals no PHP. Uma comparação de strings comum para no primeiro caractere diferente, e o tempo que isso leva pode revelar quanto de uma assinatura forjada estava certo. Esta página usa o mesmo padrão de tempo constante, então o código serve de referência além de verificação.
Se você só precisa de um checksum comum de um arquivo ou texto, sem chave, use o Gerador de Hash. Para assinar tokens, o Gerador de JWT Secret cria chaves HS256 do tamanho certo.
Perguntas frequentes
- Qual é a diferença entre um hash e um HMAC?
- Um hash como o SHA-256 depende só dos dados, então qualquer um pode recalculá-lo. Um HMAC também depende de uma chave secreta, então só quem tem a chave consegue gerá-lo ou verificá-lo. Por isso o HMAC é prova de autenticidade, e não apenas de integridade.
- Por que o meu HMAC não bate com o da API?
- Quase sempre a entrada é diferente: a mensagem não é byte a byte o corpo bruto (JSON reserializado, uma quebra de linha no final, finais de linha diferentes), a chave está sendo lida como texto quando o serviço quer bytes hex ou Base64 ou vice-versa, ou o provedor assina um timestamp mais o corpo em vez de só o corpo.
- Qual algoritmo HMAC devo usar?
- HMAC-SHA256 é a escolha padrão e o que quase toda API usa. HMAC-SHA512 é igualmente bom e mais rápido em servidores de 64 bits. HMAC-SHA1 continua seguro como HMAC, apesar das colisões do SHA-1, mas use-o só quando um protocolo exigir.
- O HMAC-SHA1 está quebrado?
- Não. As colisões do SHA-1 não permitem forjar um HMAC-SHA1 sem a chave, e não se conhece nenhum ataque prático ao HMAC-SHA1. Ele não é recomendado para projetos novos, mas verificar assinaturas HMAC-SHA1 legadas é seguro.
- Posso calcular HMAC-MD5 aqui?
- Não. A Web Crypto API do navegador, usada por esta página, não implementa MD5. O HMAC-MD5 só sobrevive em protocolos antigos; use HMAC-SHA256 para qualquer coisa nova.
- Qual deve ser o tamanho de uma chave HMAC?
- Pelo menos o tamanho da saída do hash: 32 bytes aleatórios para HMAC-SHA256, 48 para SHA-384 e 64 para SHA-512. O botão Chave aleatória gera exatamente isso com o gerador de números aleatórios seguro do seu navegador.
- Posso usar uma chave vazia?
- O HMAC permite e o resultado é bem definido, então a ferramenta o mostra, mas uma chave vazia ou curta não oferece segurança nenhuma. Qualquer pessoa poderia calcular a mesma assinatura.
- Minha chave secreta é enviada para algum lugar?
- Não. O HMAC é calculado pela Web Crypto API do seu navegador nesta página. Nada do que você digita é enviado ou armazenado.