Assinatura de requisição
Toda chamada a https://client.api.corpx.com/v1/** leva, além do token, uma
assinatura feita com a chave privada que ficou no seu servidor.
O token OAuth é um portador: quem o copia do log ou do proxy pode usá-lo até expirar. A assinatura resolve isso porque a chave privada não viaja. Um token vazado sem ela não move dinheiro.
Rotação de chaves e allowlist de IP estão em Chaves e IPs.
Por que o host é outro
Usar a credencial da conta no host antigo devolve 403 signed_host_required.
O host antigo guarda a decisão de autorização em cache por 300s; uma decisão
em cache não pode depender da assinatura daquela requisição. O host assinado
verifica a cada chamada.
O contrário também vale: o host assinado só expõe /v1/** e recusa qualquer
request sem um dos quatro headers (Authorization, X-Request-Timestamp,
X-Content-SHA256, X-Request-Signature) antes de olhar o token, com
401 e sem corpo.
A borda que verifica a assinatura não devolve motivo: uma chamada real
recusada por token, credencial, IP, relógio ou assinatura é um 403 sem
corpo. O motivo está em Testar sem mover dinheiro.
Programas completos em bash, Node.js, Python e Go estão em Exemplos de código.
Passo 1: o par de chaves
O passo a passo — gerar, extrair a pública, conferir a impressão digital e cadastrar no internet banking — está em Gerar o par de chaves. O resumo:
EC P-256 assina com ES256; RSA de 2048 bits ou mais, com PS256. A
pública vai como PEM -----BEGIN PUBLIC KEY-----. Mandar a privada devolve
422 invalid_public_key — trate essa chave como comprometida e gere outra.
O kid
Cada chave recebe um kid derivado do SHA-256 do DER da chave pública,
truncado em 16 bytes (32 hex). Derivado — e não sorteado — para você
conferir offline que cadastrou a chave certa:
O valor tem de ser igual ao kid que a API devolveu. A impressão digital que
a tela do internet banking mostra é o mesmo hash inteiro, com : entre os
bytes.
Passo 2: a string canônica
Cinco campos, nesta ordem, separados por \n (LF, não CRLF):
Exemplo para um POST com corpo {"amount":1000} (os mesmos valores do
vetor de teste):
Num GET com query, a linha do path leva a query e a da chave fica vazia:
O hash do corpo vazio é sempre
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855.
Use-o em GET e DELETE.
Exemplo para consultar uma chave de e-mail — GET, sem Idempotency-Key (a
linha fica vazia) e com o hash do corpo vazio. O @ da chave vai codificado,
igual ao path da requisição:
Passo 3: assinar
A assinatura é uma JWS compacta com payload destacado (RFC 7797):
<protected>..<signature> — note os dois pontos seguidos.
O header protegido é:
O que é assinado é base64url(protected) + "." + base64url(stringCanônica)
— base64url sem padding (=), nos dois pedaços e na assinatura. O hash
é sempre SHA-256:
A assinatura tem de ter exatamente 64 bytes (R e S de 32 bytes cada). A
maioria das bibliotecas emite DER por padrão e a API recusa com
request_signature_invalid. Em Node é dsaEncoding: 'ieee-p1363'; em Go,
monte R||S a partir de ecdsa.Sign; em Python, use
utils.decode_dss_signature e concatene.
Passo 4: enviar
O corpo enviado tem de ser byte a byte o que entrou no hash. Guarde-o
numa variável e mande com --data-binary (-d @arquivo remove as quebras
de linha do arquivo, e o hash deixa de bater):
A função sign que calcula TS, SHA e SIG com openssl está em
Exemplos de código.
O hash do corpo viaja no header — a borda verifica a assinatura sem reler o
corpo. Quem confere que o corpo recebido bate com o hash é a aplicação,
depois da borda. Divergência devolve 400 body_hash_mismatch.
Testar sem mover dinheiro
POST /v1/security/signature/verify devolve a string canônica que nós
montamos, o hash que esperávamos e o resultado. Sempre responde 200 (exceto
corpo malformado), inclusive quando a assinatura é inválida: um 401 aqui
se misturaria com “token expirado”.
É a única rota do host assinado que responde com a assinatura errada, com o
relógio fora da janela ou com a credencial ainda na carência de 18h. Para
chegar nela você ainda precisa de token válido, credencial ativa e IP na
allowlist; sem isso, 403 sem corpo como em qualquer rota.
Quando uma chamada real voltou 403 sem corpo, repita-a aqui: mesmos
headers, e no corpo o method, o path e o body que você tinha assinado.
A resposta traz edgeReason com o que a borda recusou e, se a credencial
ainda não vale, activeFrom com a hora em que passa a valer.
São duas assinaturas: a do PIX que você quer testar (vai no corpo, não é
executado) e a da própria chamada ao autoteste, que também é /v1/**. O
timestamp do PIX passa pela mesma janela de 300s, então assine na hora.
Com a função sign dos exemplos em bash:
Quando valid é false, reason traz o mesmo código da requisição real.
Compare canonicalString caractere a caractere. edgeReason aparece quando
a borda teria recusado esta mesma chamada (request_timestamp_skew,
request_signature_invalid, unknown_kid, credential_not_yet_active);
activeFrom aparece enquanto a credencial está na carência.
Vetor de teste
Use estes valores para validar a implementação offline, sem credencial.
A JWS abaixo confere contra a chave pública com dsaEncoding: 'ieee-p1363'.
Chave pública (SPKI PEM):
String canônica (LF entre as linhas, sem CRLF, sem newline no fim):
JWS:
A assinatura tem 64 bytes (R||S). Se a sua biblioteca emitir DER, o resultado não bate.
Erros mais comuns
- CRLF em vez de LF na string canônica.
- Path sem a query string que foi no request.
- Path assinado numa forma e enviado em outra: chave com
@ou+codificada na URL (%40,%2B) e crua na string canônica, ou o contrário (request_signature_invalid). Biblioteca HTTP que normaliza a URL ao enviar causa o mesmo erro. - Timestamp em milissegundos.
- Hash do vazio como string vazia, em vez do SHA-256 de zero bytes.
- Corpo reserializado depois do hash (
400 body_hash_mismatch). - Assinatura ES256 em DER (
request_signature_invalid). - Relógio fora de 300s (
request_timestamp_skew) — configure NTP. kidainda na carência de 18h ou já aposentado (unknown_kid).- Credencial no host errado (
signed_host_required).
Os itens 1 a 5 e 7 a 9 são recusados já na borda com 403 sem código
no corpo: a borda não diz qual regra falhou. Use o autoteste acima e a
tabela de diagnóstico.
Os códigos de cada erro estão em Erros.
Replay
Uma requisição assinada pode ser repetida dentro da janela de 300s. Isso é aceito de propósito:
- Em mutação,
Idempotency-Keyé obrigatória e entra na string canônica — ela é o nonce. Repetir devolve o resultado da original. - Em leitura, repetir devolve a mesma leitura.
Detalhe: Idempotência.