
Ödeme callback imzalarını RSA-SHA256 ile doğrulama
Suawave callback’lerini Go, Node.js, PHP ve C# ile doğrulayın: baytları koruyun, RSA anahtarını alın, rotasyonu yönetin ve değişmiş mesajı reddedin.
Yayın tarihi , güncelleme
Base64 x-ca-signature başlığını okuyup /pubkey/ RSA açık anahtarını kullanın. GET için tam özgün URL’yi, POST için ham gövdeyi doğrulayın. Siparişi değiştirmeden geçersiz isteği reddedin; ardından ödemeyi eşleştirip UUID tekrarını eleyin.
1. İmzalanan baytları belirleyin
Suawave RSA-SHA256 ve PKCS#1 v1.5 kullanır.
| Taşıma | Doğrulanacak mesaj |
|---|---|
| Varsayılan GET | Şema, host, yol ve özgün sorguyla tam URL |
post=1 form POST |
Geldiği biçimde ham gövde |
json=1 JSON POST |
Geldiği biçimde ham gövde |
GET sorgu sırası mesajın parçasıdır. Ayrıştırıp yeniden üretmek baytları değiştirebilir. POST’ta boşluklar ve JSON alan sırası da önemlidir.
Framework dönüştürmeden özgün istek hedefini ve gövdeyi yakalayın. Proxy arkasında GET URL’sini yapılandırılmış güvenilir dış origin ile özgün hedeften oluşturun. Güvenilmeyen Host veya X-Forwarded-* başlıklarından origin çıkarmayın.
POST gövdeyi imzalar, özel callback parametreleri URL’de kalır. Doğrulamadan sonra sipariş referansını ve nonce değerini kontrol edip ödeme adresi ve coin alanını saklanan siparişe bağlayın. İmza bu karşılaştırmaların yerine geçmez.
2. RSA açık anahtarını alıp saklayın
HTTPS üzerinden GET /pubkey/ çağırın:
curl "https://api.suawave.com/pubkey/"
JSON pubkey alanı PKIX PUBLIC KEY PEM içerir. Alanı çıkarıp doğrulayıcı için saklayın. Özel imzalama anahtarına erişim gerekmez.
Yüklerken en az 2048 bit RSA isteyin ve önbellek kullanın. İmza başarısızsa yapılandırılmış endpoint’ten bir kez yenileyip reddetmeden önce tekrar doğrulayın. Callback’te anahtar kimliği veya zaman damgası yoktur; rotasyon yeniden denemeleri de yeni anahtara geçirir.
API referansı yanıtı ve taşıma parametrelerini açıklar.
3. Dilinizin doğrulayıcısını kullanın
Dört işlev Suawave örneklerinden alınmıştır. Tam HTTP işleyicisi değildir. Saklanan anahtarı, güvenilir origin’i ve ham veriyi geçirin; ödeme işlemeden hatayı ele alın.
Go
*http.Request, PEM baytları ve dış origin’i geçirin. Callback başarısızlıkta hata döndürür; POST gövdesini sonradan ayrıştırılabilmesi için geri koyar.
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
Express’te requestUri için req.originalUrl kullanın. JSON veya form ayrıştırmadan önce express.raw ile POST’u yakalayın; rawBody Buffer olmalıdır. İmza başlığını base64 olarak koruyun.
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
Özgün hedef için $_SERVER['REQUEST_URI'], ham gövde için file_get_contents('php://input') kullanın. x-ca-signature değerini signatureBase64 olarak geçirin.
<?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#
ASP.NET Core’da GetEncodedPathAndQuery() kullanın, model binding öncesi gövde baytlarını alın. Bunları imza, PEM ve güvenilir origin ile Verify işlevine geçirin.
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);
}
}
Örnekler desteklenmeyen yöntemleri reddeder ve POST’u 65.536 baytla sınırlar. Go anahtar türünü ve boyutunu doğrular; diğer dillerde bunu PEM yüklerken uygulayın. Anahtar ve doğrulama istisnalarını HTTP sınırında başarısız sayın, siparişi güncellemeyin.
4. Geçersiz imzayı ele alın
Önbellek anahtarıyla başarısızsa bir kez yenileyip doğrulayın. Hâlâ başarısızsa HTTP 401 döndürün ve ödeme işi yapmayın. Geçersiz isteğe *ok* vermeyin.
| Belirti | Kontrol |
|---|---|
| Proxy arkasında GET başarısız | Dış origin ve özgün kodlanmış hedef |
| JSON POST başarısız | Ayrıştırma veya yeniden üretimin gövdeyi değiştirmesi |
| Rotasyon sonrası başarısız | PEM önbelleğinin bir kez yenilenmesi |
| İmza çözülemiyor | Başlığın varlığı ve base64 biçimi |
Kontrollü denemede gerçek callback’i sipariş değiştirmeden doğrulayın. İmzayı koruyup bir baytı değiştirin; doğrulama başarısız olmalıdır. GET’te URL veya sorguyu, POST’ta gövdeyi değiştirin. POST sorgusunu tek başına değiştirmek gövde imzasının bütünlüğünü test etmez.
5. Ödemeyi doğrulayıp kaydedin
Geçerli imza, imzalanan mesajın kaynağını ve bütünlüğünü kanıtlar. İşleyici ödemenin siparişi karşılayıp karşılamadığına ayrıca karar verir.
Sorgudaki nonce ve referansı, address_in, coin ve onaylı tutarı saklanan siparişle karşılaştırın. Kesin aritmetik kullanana kadar tutarları ondalık dize tutun.
UUID ile sipariş değişikliğini birlikte kalıcı kaydedin. Yeniden denemeler UUID’yi korur; işlenmiş olay başka teslimat yaratmamalıdır. Bekleyen ve onaylı olaylar farklı UUID taşır; geç bekleyen olay onaylı durumu geri almamalıdır.
Yalnızca pending değeri "0" ve tutar yeterliyken teslimatı başlatın. Kaydettikten sonra 30 saniye içinde HTTP 200 ve *ok* döndürün. Callback rehberine bakın.
Sık sorulanlar
Geçerli imza replay’i önler mi?
Olayın yeni olduğunu kanıtlamaz. Genel zaman damgası olmadığından yakalanan mesaj geçerli kalabilir. Kalıcı UUID kayıtları ve sipariş durum kontrolleriyle tekrarlanan etkileri önleyin.
GET parametrelerini sıralamalı mıyım?
Hayır. Özgün sorguyu aynen doğrulayın. Gönderen callback’e alan ekler ve oluşan tam URL’yi imzalar. Yeniden oluşturmak sırayı veya kodlamayı değiştirebilir.
Ayrıştırılmış JSON doğrulanmalı mı?
Hayır. JSON ve form için önce ham gövdeyi doğrulayın, sonra ayrıştırın. Node örneği bu yüzden Buffer ister.
İmza siparişi ödenmiş saymak için yeterli mi?
Hayır. Ödemeyi siparişle eşleştirin, tekrarları eleyin ve onaylı tutarı değerlendirin. Gerçek bekleyen olay hâlâ bekleyendir; onaylı ödeme toplamdan küçük olabilir.