
Como verificar assinaturas de callbacks de pagamento com RSA-SHA256
Verifique callbacks da Suawave em Go, Node.js, PHP e C#: preserve bytes, obtenha a chave RSA, trate rotação e rejeite mensagens alteradas.
Publicado em , atualizado em
Leia x-ca-signature em base64 e use a chave pública RSA de /pubkey/. Em GET, verifique a URL completa exata; em POST, o corpo bruto. Rejeite requisições inválidas antes de alterar pedidos e, depois, valide o pagamento e deduplique o UUID.
1. Identifique os bytes assinados
A Suawave usa RSA-SHA256 com PKCS#1 v1.5.
| Transporte | Mensagem a verificar |
|---|---|
| GET padrão | URL completa: esquema, host, caminho e consulta original |
POST de formulário com post=1 |
Corpo bruto, exatamente como recebido |
POST JSON com json=1 |
Corpo bruto, exatamente como recebido |
A ordem dos parâmetros GET faz parte da mensagem. Interpretar e serializar novamente pode alterar bytes. No POST, espaços e ordem das propriedades JSON também importam.
Capture destino original e corpo antes de transformações do framework. Atrás de proxy, componha a URL GET com uma origem externa confiável configurada e o destino original. Não derive a origem de Host ou X-Forwarded-* não confiáveis.
POST assina o corpo, enquanto seus parâmetros de callback ficam na URL. Depois de verificar, confira referência e nonce e vincule endereço de depósito e coin ao pedido salvo. A assinatura não substitui essas comparações.
2. Obtenha e armazene a chave pública
Chame GET /pubkey/ por HTTPS:
curl "https://api.suawave.com/pubkey/"
O campo JSON pubkey contém um PEM PKIX PUBLIC KEY. Extraia-o e guarde-o para o verificador. Não é necessário acesso à chave privada.
Ao carregar, exija RSA de pelo menos 2048 bits e use cache. Se a assinatura falhar, atualize a chave uma vez pelo endpoint configurado e repita a verificação antes de rejeitar. Callbacks não têm ID de chave nem timestamp; a rotação também usa a nova chave nas novas tentativas.
A referência da API documenta a resposta e os parâmetros de transporte.
3. Use o verificador da sua linguagem
As quatro funções abaixo vêm dos exemplos da Suawave. São verificadores, não handlers HTTP completos. Passe chave armazenada, origem confiável e dados brutos; trate falhas antes de processar pagamentos.
Go
Passe *http.Request, bytes PEM e origem externa. Callback retorna erro em caso de falha e restaura o corpo POST capturado para interpretação posterior.
package verify
import (
"bytes"
"crypto"
"crypto/rsa"
"crypto/sha256"
"crypto/x509"
"encoding/base64"
"encoding/pem"
"errors"
"io"
"net/http"
)
func Callback(r *http.Request, publicPEM []byte, trustedOrigin string) error {
block, _ := pem.Decode(publicPEM)
if block == nil {
return errors.New("invalid public key PEM")
}
parsed, err := x509.ParsePKIXPublicKey(block.Bytes)
if err != nil {
return err
}
key, ok := parsed.(*rsa.PublicKey)
if !ok || key.N.BitLen() < 2048 {
return errors.New("invalid RSA public key")
}
var signed []byte
switch r.Method {
case http.MethodGet:
signed = []byte(trustedOrigin + r.RequestURI)
case http.MethodPost:
signed, err = io.ReadAll(io.LimitReader(r.Body, 65537))
if err != nil {
return err
}
if len(signed) > 65536 {
return errors.New("callback body too large")
}
r.Body = io.NopCloser(bytes.NewReader(signed))
default:
return errors.New("unsupported callback method")
}
signature, err := base64.StdEncoding.DecodeString(r.Header.Get("x-ca-signature"))
if err != nil {
return err
}
digest := sha256.Sum256(signed)
return rsa.VerifyPKCS1v15(key, crypto.SHA256, digest[:], signature)
}
Node.js
No Express, passe req.originalUrl como requestUri e capture POST com express.raw antes de interpretar JSON ou formulário. rawBody deve ser Buffer. Preserve o cabeçalho em base64.
const crypto = require('crypto');
function verifyCallback({ method, requestUri, rawBody, signature }, publicKeyPem, trustedOrigin) {
let signed;
if (method === 'GET') {
signed = Buffer.from(trustedOrigin + requestUri, 'utf8');
} else if (method === 'POST') {
if (!Buffer.isBuffer(rawBody) || rawBody.length > 65536) return false;
signed = rawBody;
} else {
return false;
}
if (!signature || !/^[A-Za-z0-9+/]+={0,2}$/.test(signature)) return false;
const verifier = crypto.createVerify('RSA-SHA256');
verifier.update(signed);
return verifier.verify(publicKeyPem, signature, 'base64');
}
module.exports = { verifyCallback };
PHP
Use $_SERVER['REQUEST_URI'] para o destino original e file_get_contents('php://input') para o corpo bruto. Passe x-ca-signature como signatureBase64.
<?php
function verify_callback(string $method, string $requestUri, string $rawBody, string $signatureBase64, string $publicKeyPem, string $trustedOrigin): bool
{
if ($method === 'GET') {
$signed = $trustedOrigin . $requestUri;
} elseif ($method === 'POST') {
if (strlen($rawBody) > 65536) {
return false;
}
$signed = $rawBody;
} else {
return false;
}
$signature = base64_decode($signatureBase64, true);
if ($signature === false) {
return false;
}
return openssl_verify($signed, $signature, $publicKeyPem, OPENSSL_ALGO_SHA256) === 1;
}
C#
No ASP.NET Core, use GetEncodedPathAndQuery() e capture bytes do corpo antes do model binding. Passe esses dados a Verify com assinatura, PEM e origem confiável.
using System;
using System.Security.Cryptography;
using System.Text;
public static class CallbackVerifier
{
public static bool Verify(string method, string requestUri, byte[] rawBody,
string signatureBase64, string publicKeyPem, string trustedOrigin)
{
byte[] signed;
if (method == "GET")
{
signed = Encoding.UTF8.GetBytes(trustedOrigin + requestUri);
}
else if (method == "POST" && rawBody.Length <= 65536)
{
signed = rawBody;
}
else
{
return false;
}
byte[] signature;
try
{
signature = Convert.FromBase64String(signatureBase64);
}
catch (FormatException)
{
return false;
}
using var rsa = RSA.Create();
rsa.ImportFromPem(publicKeyPem);
return rsa.VerifyData(signed, signature, HashAlgorithmName.SHA256, RSASignaturePadding.Pkcs1);
}
}
Os exemplos rejeitam métodos não suportados e limitam POST a 65.536 bytes. Go valida tipo e tamanho da chave; nas demais linguagens, faça isso ao carregar o PEM. Trate exceções de chave e verificação na entrada HTTP como falha, sem atualizar pedidos.
4. Trate uma assinatura inválida
Se falhar com a chave em cache, atualize uma vez e verifique novamente. Se continuar inválida, retorne HTTP 401 e não processe o pagamento. Não envie *ok* para uma requisição inválida.
| Sintoma | O que conferir |
|---|---|
| GET falha atrás de proxy | Origem externa configurada e destino codificado original |
| JSON POST falha | Alterações no corpo por interpretação ou serialização |
| Falha após rotação | Atualização única do PEM em cache |
| Erro ao decodificar assinatura | Presença do cabeçalho e codificação base64 |
Em um teste controlado, capture um callback legítimo e verifique sem atualizar pedidos. Mantenha a assinatura e altere um byte: a verificação precisa falhar. Em GET, altere URL ou consulta; em POST, altere o corpo. Mudar só a consulta de um POST não testa a integridade da assinatura do corpo.
5. Valide e registre o pagamento
Uma assinatura válida comprova origem e integridade da mensagem assinada. O handler ainda precisa decidir se o depósito quita o pedido.
Confira nonce e referência na consulta, address_in, coin e valor confirmado com o pedido salvo. Preserve strings decimais até usar aritmética exata.
Salve UUID e mudança do pedido juntos. Novas tentativas reutilizam UUID; um evento processado não pode gerar outra entrega. Pendente e confirmado têm UUIDs distintos, e um pendente atrasado não pode desfazer o estado confirmado.
Entregue apenas com pending igual a "0" e valor suficiente. Responda HTTP 200 com *ok* em até 30 segundos após persistir. Veja o guia de callbacks.
Dúvidas frequentes
Uma assinatura válida impede replay?
Não comprova que o evento é recente. Sem timestamp público, uma mensagem capturada pode continuar válida. Use UUIDs persistidos e verificações de estado para impedir efeitos repetidos.
Devo ordenar os parâmetros GET?
Não. Verifique a consulta original exata. O remetente adiciona campos ao callback e assina a URL completa resultante. Reconstruí-la pode alterar ordem ou codificação.
Devo verificar o JSON já interpretado?
Não. Verifique o corpo bruto antes de interpretar, tanto em JSON quanto em formulário. Por isso o exemplo Node exige Buffer.
A assinatura basta para marcar como pago?
Não. Vincule o depósito ao pedido, elimine duplicatas e avalie o valor confirmado. Um evento pendente legítimo continua pendente; um depósito confirmado pode ser menor que a compra.