Как проверять подписи callback криптоплатежей с RSA-SHA256

Проверяйте callback Suawave на Go, Node.js, PHP и C#: сохраняйте исходные байты, кешируйте RSA-ключ, учитывайте ротацию и отклоняйте изменённые данные.

Опубликовано , обновлено

Чтобы проверить подпись webhook Suawave с RSA-SHA256, прочитайте заголовок x-ca-signature в base64 и используйте публичный RSA-ключ из /pubkey/. Для GET callback проверяйте точный полный URL, для POST callback проверяйте исходное тело. Отклоняйте некорректные запросы до изменения заказа, затем проверяйте платёж и исключайте повторы его UUID.

1. Определите байты, которые покрывает подпись

Suawave подписывает публичные callback платежей алгоритмом RSA-SHA256 с дополнением PKCS#1 v1.5. Подписанное сообщение определяется транспортом:

Транспорт Сообщение для проверки
GET по умолчанию Полный URL: внешняя схема, хост, путь и исходная строка query-параметров
Form POST при post=1 Исходное тело формы, точно как получено
JSON POST при json=1 Исходное тело JSON, точно как получено

Порядок query-параметров GET является частью сообщения. Разбор параметров в map и повторная сериализация могут изменить байты. Для POST изменения пробелов или порядка свойств при разборе и повторном кодировании JSON также могут нарушить подпись.

Сохраните исходный адрес запроса и исходное тело до преобразований фреймворком. За обратным прокси составляйте GET URL из настроенного доверенного внешнего origin и исходного адреса запроса. Не определяйте origin по недоверенному заголовку Host или X-Forwarded-*.

Подпись POST покрывает тело; ваши query-параметры callback остаются в URL. После проверки сравните идентификатор заказа и nonce с сохранённым заказом и привяжите к нему проверенные адрес приёма и coin. Проверка подписи не заменяет эти сравнения.

2. Получите и сохраните публичный RSA-ключ

Вызовите GET /pubkey/ по HTTPS:

curl "https://api.suawave.com/pubkey/"

Ответ JSON содержит поле pubkey с PKIX PUBLIC KEY PEM. Извлеките поле и сохраните PEM для верификатора. Ключ предназначен для публичной проверки; обработчику не нужен закрытый ключ подписи.

При загрузке ключа в приложение требуйте RSA длиной не менее 2048 бит. Кешируйте его вместо загрузки для каждого callback. Если проверка не проходит, один раз обновите ключ с настроенного публичного эндпоинта и повторите проверку перед отклонением запроса. Callback Suawave не содержат ID ключа или временной метки, а при ротации повторные доставки тоже подписываются новым ключом.

Ответ с публичным ключом и параметры транспорта callback описаны в справочнике API.

3. Используйте верификатор для своего языка

Эти четыре функции скопированы из примеров проверки подписей Suawave. Они проверяют запрос, но не являются полными HTTP-обработчиками. Передавайте сохранённый публичный ключ и доверенный внешний origin, сохраняйте исходные данные запроса и обрабатывайте неудачную проверку до любых действий с платежом.

Go

Передайте входящий *http.Request, байты PEM и настроенный внешний origin. Callback возвращает ошибку при неудаче. Для POST функция восстанавливает сохранённое тело, чтобы обработчик мог разобрать его после проверки.

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 передавайте req.originalUrl как requestUri. Сохраняйте входные данные POST через express.raw до разбора JSON или формы, чтобы rawBody был Buffer. Читайте заголовок подписи без преобразования его представления 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

Используйте $_SERVER['REQUEST_URI'] для исходного адреса запроса и file_get_contents('php://input') для исходного тела POST. Передавайте значение заголовка x-ca-signature как 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#

В ASP.NET Core используйте GetEncodedPathAndQuery() для закодированного адреса запроса и сохраняйте исходные байты тела до model binding. Передайте эти значения в Verify вместе с заголовком подписи, сохранённым PEM и доверенным origin.

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);
    }
}

Примеры отклоняют неподдерживаемые HTTP-методы и ограничивают размер проверяемого тела POST до 65 536 байт. Функция Go сама проверяет тип и размер RSA-ключа; для остальных примеров применяйте это требование при загрузке PEM. Перехватывайте исключения некорректного ключа и другие исключения проверки на уровне HTTP-обработчика и считайте их отказом без изменения заказа.

4. Обработайте неверную подпись webhook RSA-SHA256

Если подпись не проходит проверку с кешированным ключом, один раз загрузите публичный ключ и проверьте снова. Запрос, который всё ещё не проходит проверку, должен получить HTTP 401 без обработки платежа. Не подтверждайте некорректный запрос ответом *ok*.

При отладке сравните сообщение, переданное верификатору, с полученными байтами:

Признак Что проверить
Проверка GET не проходит за прокси Настроенный внешний origin и исходный закодированный адрес запроса
Проверка JSON POST не проходит Не изменили ли разбор или сериализация исходное тело
Проверка не проходит после ротации ключа Обновлялся ли кешированный PEM один раз
Декодирование подписи не удаётся Есть ли заголовок и сохранено ли кодирование base64

Для контролируемой проверки интеграции сохраните подлинный callback и проверьте его без изменения заказов. Оставьте подпись прежней и измените один байт подписанного сообщения. Изменённое сообщение не должно пройти проверку. Для GET измените URL или query-параметры; для POST измените исходное тело. Изменение только query-параметра POST не проверяет целостность подписи тела, поскольку query не входит в это подписанное сообщение.

5. Проверьте и запишите платёж после проверки подписи

Корректная подпись подтверждает источник и целостность подписанного сообщения. Обработчик по-прежнему должен определить, оплачивает ли поступление заказ.

Сравните сохранённые nonce и идентификатор заказа с query-параметрами callback. Проверьте address_in, coin и подтверждённую сумму по сохранённому заказу. Храните суммы как десятичные строки до преобразования с точной арифметикой.

Надёжно сохраняйте UUID события вместе с вызванным им изменением заказа. Повторные доставки используют тот же UUID, поэтому уже обработанное событие не должно запускать выполнение ещё раз. Pending и confirmed callback имеют разные UUID; поздний pending callback не должен отменять подтверждённое состояние.

Выполняйте заказ только при pending, равном "0", после соблюдения правил учёта суммы. Затем ответьте HTTP 200 с обычным текстом *ok* в течение 30 секунд. Повторные попытки, подтверждение получения и поля событий описаны в руководстве по callback.

Частые вопросы о проверке

Предотвращает ли корректная подпись повторное воспроизведение?

Одна подпись не подтверждает свежесть события. Публичные callback не содержат временной метки, и перехваченное подписанное сообщение всё ещё может пройти проверку. Используйте постоянное хранение UUID для исключения дублей и проверку состояния заказа, чтобы повторная обработка события не повторяла его последствия.

Нужно ли сортировать query-параметры GET?

Нет. Проверяйте точную исходную строку query-параметров. Отправитель добавляет свои поля к вашему callback URL, и подпись покрывает полученный полный URL. Восстановление строки из разобранных значений может изменить порядок или кодирование.

Нужно ли проверять разобранный JSON?

Нет. Сначала проверяйте исходное тело POST, затем разбирайте его. Именно поэтому функция Node.js требует Buffer. Соблюдайте тот же порядок для form POST: проверяйте исходное тело до интерпретации полей.

Достаточно ли проверки подписи, чтобы отметить заказ оплаченным?

Нет. Сопоставьте проверенное поступление с сохранённым заказом, исключите повторный UUID и оцените подтверждённую сумму. Подлинный pending callback всё ещё является событием ожидания. Подлинное подтверждённое поступление всё ещё может быть меньше суммы заказа.