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.