Construtor de Canonical Request AWS SigV4｜A string intermediária e os dois hashes SHA-256

Informe um método HTTP, uma URI, uma query, cabeçalhos e payload, e esta ferramenta monta a Canonical Request do AWS Signature Version 4, a lista SignedHeaders, o SHA-256 do payload e o SHA-256 da própria canonical request. Ela mostra a string intermediária que a maioria dos tutoriais de SigV4 pula, então quando o seu SDK retorna um erro de assinatura você alinha cada valor em uma só tela. Sem backend: cole e leia.

💡 Sobre esta ferramenta

Toda assinatura SigV4 passa por uma Canonical Request antes de a Signature final existir. Essa canonical request é uma string de formato rígido: o método, a URI normalizada, a query normalizada, o bloco de cabeçalhos canônicos, a lista SignedHeaders e o hash do payload, tudo unido por quebras de linha. Os SDKs da AWS e o boto3 a constroem e a hasheiam internamente, mas no momento em que você escreve o seu próprio assinador, um único caractere fora do lugar nessa string retorna SignatureDoesNotMatch — e o corpo do erro só mostra o hash final, nunca onde as strings divergiram.

Esta ferramenta constrói a canonical request exatamente como o SigV4 exige. A URI e a query recebem percent-encoding da RFC 3986 (tudo exceto o conjunto unreserved A-Z a-z 0-9 - . _ ~), os pares da query são ordenados por chave, e os nomes de cabeçalho ficam em minúsculas com os espaços internos colapsados antes de serem ordenados por nome. Ela emite o corpo da canonical request, SignedHeaders, o SHA-256 do payload e o SHA-256 da canonical request ao mesmo tempo, para você comparar a saída do seu assinador com os quatro valores e localizar qual passo de normalização desviou.

É feita para quem escreve assinadores sem o SDK: Lambda@Edge, assinatura para IoT, fluxos de baixo nível com CloudFront — onde é preciso inspecionar cada valor intermediário do SigV4. Cole uma cópia dos seus cabeçalhos reais e trate a saída como a referência que o seu código deve reproduzir.

🧐 Perguntas frequentes

Qual a diferença entre a Canonical Request e o StringToSign? A canonical request é a string da requisição normalizada — é o que esta ferramenta produz. O StringToSign é a etapa seguinte: ele envolve o hash da canonical request com o nome do algoritmo, a data e o credential scope, e é o que recebe HMAC com a chave de assinatura. Esta ferramenta vai até a canonical request e seu SHA-256.

Como os cabeçalhos são normalizados? Os nomes ficam em minúsculas, os valores são aparados e as sequências de espaços internos colapsam para um só, e depois são ordenados por nome. Nomes de cabeçalho duplicados são unidos por vírgula. SignedHeaders são os nomes ordenados unidos por ponto e vírgula.

Que hash um payload vazio produz? O SHA-256 da string vazia: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855. Requisições GET e DELETE sem corpo usam esse valor, e a ferramenta o mostra por padrão.

Como a query é ordenada? Os pares são ordenados de forma crescente pela chave codificada, e empates são resolvidos pelo valor. Uma chave sem valor (key) é tratada como key= com valor vazio. Essa ordem é um requisito do SigV4: se estiver errada, a assinatura não confere.

Algo que eu informo sai da minha máquina? Não. Cada entrada — método, cabeçalhos e payload incluídos — é processada no seu navegador, e o SHA-256 é calculado localmente com a Web Crypto API. Você pode colar uma requisição real que está tentando assinar e nada é enviado a um servidor.

📚 Por que o SigV4 normaliza antes de assinar

A razão pela qual o SigV4 se dá ao trabalho de uma canonical request é que uma mesma requisição lógica pode ter muitas representações de bytes. A query b=2&a=1 e a=1&b=2 significam o mesmo, mas geram hashes diferentes, e a caixa dos cabeçalhos ou um espaço sobrando podem mudar em trânsito. Uma assinatura é apenas o hash de uma string, então uma diferença de um caractere produz um hash completamente diferente e o verificador a rejeita. Ao forçar os dois lados pela mesma normalização fixa — ordenar a query, colocar em minúsculas e colapsar os cabeçalhos, codificar a URI — o SigV4 garante que o emissor e a AWS cheguem à string idêntica antes de qualquer um hashear. O engenhoso não é a assinatura; é que fixar a requisição em uma forma canônica antes de assinar é o que torna possível um verificador sem estado, e é exatamente onde os assinadores feitos à mão costumam quebrar.