Gerador de HMAC e Verificador de Assinatura

O Que É um 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);
}

Principais Recursos

Exemplos de HMAC

Hello, World!

cf3141611e22ea26a9cac6fe41d941274dd6653622c83cba13972d177bd69699

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

Cd2f7zTKaJFeG6k+t1FcvDPn51OAZ2f4GrxkCUgMhGs=

what do ya want for nothing?

5bdcc146bf60754e6a042426089575c75a003f089d2739839dec58b964ec3843

The quick brown fox

36f44b125a8a90639dc46733039571792e081e0fd8685ff746784b02ed14aa35629d562c7117cde4a701570551faa5a5e1b7ef1eb5c3bcd4cc1fdb8923fcf14e

Como Gerar e Verificar um HMAC

1. 1

   Escolha o algoritmo

   Escolha HMAC-SHA256 (o padrão e a escolha certa para quase todos os webhooks, APIs e JWTs), ou mude para SHA-1, SHA-384 ou SHA-512 para casar com um sistema que exija isso. Todos os quatro rodam nativamente no seu navegador via Web Crypto API.

2. 2

   Informe a chave secreta e defina sua codificação

   Digite ou cole sua chave secreta, depois ajuste a Codificação da chave para casar com a forma como o servidor a interpreta: Texto (UTF-8) para uma string simples, Hex para um blob hexadecimal ou Base64 para um segredo em base64. Errar isso é a principal causa de divergências de HMAC, então na dúvida teste as três.

3. 3

   Informe a mensagem

   Cole os bytes exatos que você quer assinar — para um webhook isto é o corpo bruto da requisição, byte a byte, sem re-serialização ou mudanças de espaço em branco. O HMAC é recalculado ao vivo enquanto você edita, sem nada enviado a um servidor.

4. 4

   Escolha o formato de saída e copie

   Selecione Hex (estilo GitHub), Base64 (estilo Stripe/AWS) ou Base64URL (estilo JWT) para casar com o que sua integração espera, depois clique em Copiar para pegar a assinatura.

5. 5

   Verifique uma assinatura existente

   Mude para a aba Verificar, cole o HMAC esperado de um cabeçalho ou token e a ferramenta confirma em tempo constante se a sua assinatura calculada confere — assim você pode autenticar um payload antes de agir sobre ele.

Erros Comuns de 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 */ }

Para Que o HMAC É Usado

Verificar assinaturas de webhook

Provedores como GitHub, Stripe, Slack e Twilio assinam cada webhook com HMAC sobre o corpo da requisição e um segredo que só você compartilha. Recalcule a tag e compare-a com o cabeçalho (por exemplo X-Hub-Signature-256) para confirmar que o evento é genuíno antes de agir sobre ele. Use a aba Verificar para fazer isso sem escrever código descartável.

Assinar requisições de API

APIs autenticadas muitas vezes exigem que o cliente assine a requisição com HMAC (método, caminho, timestamp, corpo) com um segredo compartilhado em vez de enviar o próprio segredo. O AWS Signature Version 4 é o exemplo canônico. Esta ferramenta permite reproduzir e depurar essas assinaturas passo a passo.

Garantir a integridade da mensagem

Quando você passa um token, cookie ou mensagem entre serviços, anexar um HMAC permite que o receptor detecte qualquer adulteração. Como a tag depende de um segredo, um atacante não consegue recalculá-la após modificar os dados — diferente de um checksum simples.

Entender a assinatura HS256 do JWT

Um JWT assinado com HS256 é apenas base64url(cabeçalho) + '.' + base64url(payload), assinado com HMAC-SHA256 e o resultado emitido como Base64URL. Defina o algoritmo para SHA-256 e a saída para Base64URL aqui para ver exatamente como essa assinatura é produzida, depois confira de novo no codificador JWT.

Depurar uma assinatura que não bate

Quando seu HMAC não bate com o do servidor, esta ferramenta é a forma mais rápida de isolar o porquê: teste a chave como Texto, Hex e Base64, alterne a saída entre Hex e Base64 e confirme que está assinando exatamente os bytes brutos — tudo sem reimplantar nenhum código.

Como o HMAC Funciona

Construção da RFC 2104

O HMAC é definido como H((K ⊕ opad) ‖ H((K ⊕ ipad) ‖ m)), onde ipad é o byte 0x36 repetido e opad é o 0x5c repetido, ambos até o tamanho de bloco do hash. Uma chave maior que o tamanho de bloco é primeiro submetida a hash; uma chave menor é preenchida com zeros. Esse aninhamento de duas passagens é o que dá ao HMAC sua prova de segurança, que vale mesmo se o hash subjacente não for resistente a colisões.

Por que um hash com chave supera um hash simples

Um hash simples prova apenas que os dados não foram corrompidos por acidente, porque qualquer um pode recalculá-lo para qualquer mensagem — inclusive uma adulterada. O HMAC mistura um segredo, então apenas quem possui a chave pode produzir uma tag válida. Isso converte só-integridade em integridade mais autenticidade, que é a propriedade de que webhooks e requisições assinadas realmente precisam.

Resistência à extensão de comprimento

Os SHA-1, SHA-256 e SHA-512 puros são hashes de Merkle–Damgård vulneráveis à extensão de comprimento: dado H(segredo ‖ msg) um atacante pode calcular H(segredo ‖ msg ‖ extra) sem conhecer o segredo. Esquemas ingênuos de 'MAC com prefixo de segredo' são quebrados por isso. O hash externo do HMAC neutraliza o ataque, que é o principal motivo para usar HMAC em vez de submeter um segredo e uma mensagem a hash juntos.

Escolhendo SHA-256 vs SHA-512

O HMAC-SHA256 produz uma tag de 256 bits (64 caracteres hex) e é o padrão de interoperabilidade — rápido, onipresente e suportado em toda parte. O HMAC-SHA512 produz uma tag de 512 bits (128 caracteres hex) e costuma ser mais rápido em CPUs de 64 bits porque o SHA-512 usa palavras de 64 bits. Escolha SHA-256 a não ser que uma especificação ou um sistema parceiro exija SHA-512; ambos são seguros para autenticação.

Implementação com Web Crypto

Esta ferramenta chama crypto.subtle.importKey para carregar sua chave (decodificada de Texto, Hex ou Base64) e crypto.subtle.sign('HMAC', ...) para calcular a tag, depois codifica os bytes brutos como Hex, Base64 ou Base64URL. É a mesma implementação nativa e auditada que o navegador usa para TLS, rodando fora do motor JavaScript em prol da velocidade.

Boas Práticas de HMAC

Use uma chave pelo menos tão longa quanto a saída do hash

Para HMAC-SHA256 use um segredo de pelo menos 32 bytes aleatórios (256 bits); para SHA-512 use 64. Uma chave curta ou de baixa entropia é o elo mais fraco. Gere chaves de uma fonte aleatória criptograficamente segura — nunca uma senha ou uma string previsível.

Sempre compare as tags em tempo constante

Verifique assinaturas com uma comparação de tempo constante (crypto.timingSafeEqual no Node, hmac.compare_digest no Python) em vez de == ou igualdade de strings. Uma comparação ingênua retorna cedo no primeiro byte diferente, vazando tempo que pode permitir a um atacante recuperar uma tag válida byte a byte. A aba Verificar desta ferramenta já compara em tempo constante.

Nunca registre nem exponha a chave secreta

Mantenha os segredos de assinatura fora de logs, mensagens de erro, URLs e código do lado do cliente. Armazene-os em um gerenciador de segredos ou variáveis de ambiente, rotacione-os periodicamente e dê a cada integração sua própria chave para que um vazamento não comprometa tudo.

Prefira HMAC-SHA256 ou mais forte

Use HMAC-SHA256 como padrão; suba para SHA-384 ou SHA-512 quando um parceiro exigir. Evite HMAC-SHA1 em sistemas novos e nunca use HMAC-MD5. Mesmo que o HMAC tolere um hash mais fraco melhor do que uma assinatura pura toleraria, partir de um hash moderno lhe dá a maior margem.

Assine os bytes exatos, incluindo um timestamp

Assine o payload bruto e inalterado — re-serializar JSON ou aparar espaços em branco muda os bytes e quebra a verificação. Para assinar requisições, inclua um timestamp ou nonce nos dados assinados e rejeite assinaturas antigas para evitar ataques de repetição.

Perguntas Frequentes sobre HMAC