Gerador de HMAC

Sobre esta ferramenta

O que um HMAC prova

O HMAC (RFC 2104) combina uma mensagem com uma chave secreta através de uma função de hash e devolve um código curto. Quem tiver a mesma chave pode voltar a calcular esse código. Se os dois códigos forem iguais, a mensagem não foi alterada pelo caminho (integridade) e foi produzida por alguém que conhece a chave (autenticidade).

Um hash simples não consegue fazer isto, porque quem altera a mensagem também pode recalcular o seu hash. Um HMAC não esconde a mensagem, por isso não é encriptação. E, como os dois lados têm a mesma chave, não consegue mostrar qual dos dois escreveu a mensagem. Para isso é preciso uma assinatura digital com uma chave privada.

Assinaturas de webhooks

É frequente encontrar o HMAC num webhook. O fornecedor assina o corpo do pedido com um segredo que partilha consigo e envia o código num cabeçalho, e o seu servidor calcula o mesmo HMAC antes de confiar no pedido. O GitHub envia X-Hub-Signature-256: sha256=… em hex, o Shopify envia X-Shopify-Hmac-SHA256 em Base64, e o Stripe assina o timestamp, um ponto e o corpo, e depois envia o resultado como v1=… dentro de Stripe-Signature.

Assine os bytes em bruto do corpo, exatamente como chegaram. Se uma framework interpretar o JSON e o voltar a serializar, os espaços e a ordem das chaves mudam e o HMAC deixa de coincidir. Quando uma assinatura falha aqui, veja primeiro a codificação da chave (texto, hex ou Base64) e depois se há uma quebra de linha no fim da mensagem.

Porque é que um servidor compara em tempo constante

Uma comparação normal de strings termina no primeiro carácter que difere. Num servidor, isso torna a resposta um pouco mais rápida quando os primeiros bytes de uma assinatura forjada estão errados e um pouco mais lenta quando estão certos, e um atacante que consiga medir essa diferença pode recuperar um código válido byte a byte. Uma comparação em tempo constante lê todos os bytes, seja qual for o resultado. Use a função que a sua plataforma oferece: crypto.timingSafeEqual no Node.js, hmac.Equal em Go, hmac.compare_digest em Python, hash_equals em PHP.

O campo de comparação desta página funciona da mesma forma: descodifica os dois valores para bytes e lê-os todos. Num separador do navegador que já tem os dois valores não há tempos a esconder, por isso aqui serve apenas para saber se o seu próprio código produziu o HMAC certo.

Como funciona

O HMAC é calculado pelo pacote crypto/hmac do Go, compilado para WebAssembly e executado numa thread em segundo plano do seu navegador. A mensagem é lida como UTF-8, sem nada acrescentado nem cortado. Há uma coisa que muda: uma caixa de texto do navegador guarda cada quebra de linha como um único line feed, por isso uma mensagem que chegou com finais de linha CRLF é assinada aqui com LF. A chave é lida como texto UTF-8, ou descodificada de hex ou Base64 quando o indicar. Nenhuma das duas é enviada para lado nenhum. Ainda assim, um segredo de produção fica melhor fora de páginas web: use uma chave de teste sempre que puder.