Ir para o conteúdo principal
Bethemesh
Segurança e privacidade

Gerador e verificador HMAC

Calcule o HMAC de uma mensagem com uma chave secreta, em hexadecimal ou Base64, e compare-o com uma assinatura esperada (prefixo sha256= aceite) para verificar um webhook do GitHub, Stripe ou Shopify.

  • Área de transferência

Integrar este widget

Personalize o resultado, verifique a pré-visualização e copie o código.

Pré-visualização

Tipo de código de integração

Código a copiar

Responsivo e redimensionado automaticamente pela Bethemesh.

Assinatura HMAC

Hexadecimal ou Base64, com ou sem prefixo como sha256=.

Esta ferramenta foi útil?

Como funciona esta ferramenta?

Esta ferramenta calcula o HMAC de uma mensagem com uma chave secreta, com SHA-1, SHA-256, SHA-384 ou SHA-512, e compara-o com uma assinatura esperada. Destina-se sobretudo a programadores que integram ou depuram webhooks do GitHub, Stripe ou Shopify e precisam de saber se a falha vem do segredo, do corpo da mensagem ou do seu código.

Um HMAC (RFC 2104, FIPS 198-1) combina uma função de hash com uma chave secreta: HMAC(K, m) = H((K ⊕ opad) ‖ H((K ⊕ ipad) ‖ m)). Esta dupla passagem torna impossível produzir o valor sem a chave e evita o ataque de extensão de comprimento que afeta um simples SHA-256(chave ‖ mensagem). Com a chave «key» e a mensagem «The quick brown fox jumps over the lazy dog», o HMAC-SHA-256 dá f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8 em hexadecimal, ou seja, 97yD9DBThCSxMpjmqm+xQ+9NWaFJRhdZl0edvC0aPNg= em Base64. A chave é usada tal como é introduzida, mensagem e chave são codificadas em UTF-8 e o cálculo recorre à API Web Crypto do navegador.

A maioria dos fornecedores assina o corpo em bruto do pedido. O GitHub envia X-Hub-Signature-256: sha256=<hex>, a Shopify envia X-Shopify-Hmac-Sha256 em Base64 e a Stripe assina a cadeia «carimbo_temporal.corpo» e coloca o valor hexadecimal após v1= no cabeçalho Stripe-Signature. Escolha, portanto, a saída hexadecimal ou Base64 consoante o fornecedor e cole a assinatura recebida no campo opcional: são aceites prefixos como «sha256=» e o resultado é atualizado à medida que escreve. A comparação é feita em tempo constante, como o GitHub recomenda para o código de servidor.

Como usar esta ferramenta

  1. Introduza a mensagem e a chave

    Cole a mensagem exata a assinar, por exemplo o corpo em bruto de um webhook, e depois a chave secreta partilhada.

  2. Escolha o algoritmo e o formato

    Selecione SHA-1, SHA-256, SHA-384 ou SHA-512 e uma saída hexadecimal ou Base64, consoante o que o serviço espera.

  3. Compare com a assinatura recebida

    Se necessário, cole a assinatura esperada, com ou sem um prefixo como sha256=: o HMAC e o resultado da verificação são atualizados durante a escrita.

Autenticação HMAC

Autenticação HMAC

HMAC(K, m) = H((K' XOR opad) || H((K' XOR ipad) || m)), em que K' é a chave ajustada ao tamanho de bloco da função de hash H e || é a concatenação

Casos de uso

Verificar um webhook do GitHub

Copie o payload em bruto e o cabeçalho X-Hub-Signature-256 a partir do separador Recent Deliveries do webhook, introduza o segredo e compare. Se o valor coincidir aqui mas não no seu servidor, é a sua framework que altera o corpo antes da verificação.

Depurar uma assinatura da Stripe

Reconstrua a cadeia assinada «t.corpo» a partir do cabeçalho Stripe-Signature e do corpo em bruto, calcule o HMAC-SHA-256 com o seu segredo whsec_… e compare-o com o valor v1 para identificar a origem de uma falha de verificação.

Controlar um webhook da Shopify

A Shopify assina o corpo em bruto com HMAC-SHA-256 e envia o resultado em Base64 no cabeçalho X-Shopify-Hmac-Sha256. Escolha a saída Base64 e cole o cabeçalho para confirmar que está a usar o segredo de aplicação correto.

Exemplos

Assinatura HMAC-SHA256 de referência

Entrada

Mensagem: The quick brown fox jumps over the lazy dog; Chave secreta: key; Algoritmo: SHA-256; Codificação: Hexadecimal

Resultado

Assinatura calculada: f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8

Dicas e boas práticas

  • Assine o corpo em bruto exatamente como foi recebido: um JSON reformatado, reindentado ou com as chaves reordenadas dá uma assinatura completamente diferente.
  • Tenha cuidado com espaços e quebras de linha invisíveis à volta do segredo: uma chave copiada com uma quebra de linha final produz outro HMAC.
  • No servidor, compare sempre com uma função de tempo constante (crypto.timingSafeEqual, hmac.compare_digest) e, na Stripe ou no Slack, rejeite carimbos temporais antigos para bloquear ataques de repetição.

Fontes e referências

Perguntas frequentes

Qual é a diferença entre um HMAC e um hash?

Qualquer pessoa pode calcular um hash como o SHA-256: prova a integridade, não a origem. Um HMAC acrescenta uma chave secreta, pelo que só quem detém essa chave consegue produzir o valor correto. Assim, autentica o remetente além de detetar qualquer alteração.

Porque é que a assinatura do meu webhook não coincide?

Na maioria dos casos, o corpo foi alterado antes do cálculo: JSON analisado e novamente serializado pela framework, codificação diferente ou espaços acrescentados. Outras causas frequentes são um segredo errado (o de teste em vez do de produção), um formato de saída incorreto (hex em vez de Base64) ou, na Stripe, esquecer o carimbo temporal na cadeia assinada.

O HMAC-SHA-1 ainda é seguro?

Para autenticar mensagens, sim: as colisões do SHA-1 não permitem falsificar um HMAC-SHA-1 sem a chave, e continua a ser usado, por exemplo, no TOTP. Para qualquer sistema novo, prefira no entanto o HMAC-SHA-256, hoje o padrão dos webhooks. O GitHub mantém o cabeçalho X-Hub-Signature em SHA-1 apenas por compatibilidade.

Que comprimento de chave devo usar?

A RFC 2104 recomenda uma chave pelo menos tão longa como a saída do hash, ou seja, 32 bytes para HMAC-SHA-256. Uma chave mais longa do que o bloco (64 bytes no SHA-256) é primeiro processada pelo hash e, por isso, não acrescenta segurança. Gere-a de forma aleatória em vez de escolher uma palavra-passe.

É possível desencriptar um HMAC para recuperar a mensagem?

Não, um HMAC não é uma encriptação: não contém a mensagem nem permite reconstruí-la. Aliás, a mensagem é normalmente enviada em claro junto da assinatura. Para tornar um conteúdo ilegível, é necessária uma encriptação como o AES-GCM.

É prudente introduzir aqui um segredo de webhook de produção?

O cálculo é feito apenas no seu navegador com a Web Crypto: nem a chave nem a mensagem são transmitidas. Ainda assim, por princípio, prefira um segredo de teste ou renove o segredo após uma sessão de depuração num computador partilhado.

Ferramentas relacionadas

Continue com estas ferramentas

Ferramentas semelhantes ou complementares a esta.

Ferramentas semelhantes

Gerador de hash

Calcule de uma só vez os hashes MD5, SHA-1, SHA-256, SHA-384 e SHA-512 de um texto ou ficheiro.

Segurança e privacidadeEm destaqueUtilizar esta ferramenta

Comparador de hash

Verifique se dois hashes ou somas de verificação coincidem, independentemente de maiúsculas, espaços ou dois-pontos.

Segurança e privacidadeUtilizar esta ferramenta

Gerador de tokens seguros

Gere tokens aleatórios seguros de 8 a 256 bytes em hexadecimal, Base64 ou Base64URL, com prefixo opcional.

Segurança e privacidadeUtilizar esta ferramenta

Leia também