RSA-SHA256으로 암호화폐 결제 콜백 서명 검증하기

Go, Node.js, PHP, C#에서 Suawave 콜백 서명을 검증하세요. 서명된 바이트 보존, RSA 공개 키 조회와 교체, 변조된 페이로드 거부 방법을 설명합니다.

게시일 , 수정일

RSA-SHA256으로 Suawave 웹훅 서명을 검증하려면 base64 x-ca-signature 헤더를 읽고 /pubkey/의 RSA 공개 키를 사용하세요. GET 콜백은 정확한 전체 URL을, POST 콜백은 원본 본문을 검증합니다. 주문 변경 전에 유효하지 않은 요청을 거부하고, 이후 결제 내용을 확인하며 UUID 중복을 제거하세요.

1. 서명이 포함하는 바이트 식별하기

Suawave는 PKCS#1 v1.5 패딩을 사용하는 RSA-SHA256으로 공개 결제 콜백에 서명합니다. 전송 방식에 따라 서명 대상 메시지가 달라집니다.

전송 방식 검증할 메시지
기본 GET 외부 스킴, 호스트, 경로, 원본 쿼리 문자열을 포함한 전체 URL
post=1로 선택한 form POST 수신한 그대로의 원본 폼 본문
json=1로 선택한 JSON POST 수신한 그대로의 원본 JSON 본문

GET 쿼리의 순서도 메시지의 일부입니다. 파라미터를 맵으로 파싱하고 다시 직렬화하면 바이트가 바뀔 수 있습니다. POST에서도 JSON 파싱과 재인코딩으로 공백이나 속성 순서가 바뀌면 서명이 맞지 않을 수 있습니다.

프레임워크가 변환하기 전에 원본 요청 대상과 원본 본문을 확보하세요. 리버스 프록시 뒤에서는 설정된 신뢰 가능한 외부 origin과 원본 요청 대상을 결합해 GET URL을 구성합니다. 신뢰할 수 없는 Host나 X-Forwarded-* 헤더에서 origin을 가져오지 마세요.

POST 서명은 본문을 포함하며 사용자 지정 콜백 쿼리 파라미터는 URL에 남습니다. 검증 후 주문 참조값과 nonce를 저장된 주문과 대조하고, 검증된 입금 주소와 coin도 해당 주문에 연결하세요. 서명 검증이 이러한 비교를 대신하지는 않습니다.

2. RSA 공개 키를 가져와 저장하기

HTTPS로 GET /pubkey/를 호출하세요.

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

JSON 응답의 pubkey 필드에는 PKIX PUBLIC KEY PEM이 들어 있습니다. 해당 필드를 추출하고 검증기에 사용할 PEM을 저장하세요. 이 키는 공개 검증 자료이며 핸들러에는 서명용 개인 키가 필요하지 않습니다.

애플리케이션에 키를 등록할 때 2048비트 이상의 RSA 키인지 확인하세요. 콜백마다 가져오지 말고 캐시합니다. 검증에 실패하면 설정된 공개 키 엔드포인트에서 한 번 갱신하고, 거부하기 전에 다시 검증하세요. Suawave 콜백에는 키 ID나 타임스탬프가 없으며 키 교체 후에는 재시도에도 새 키를 사용합니다.

공개 키 응답과 콜백 전송 파라미터는 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에서는 requestUri에 req.originalUrl을 전달하세요. JSON이나 폼을 파싱하기 전에 express.raw로 POST 입력을 확보해 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']를, 원본 POST 본문에는 file_get_contents('php://input')을 사용하세요. 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()를 사용하고 모델 바인딩 전에 원본 본문 바이트를 확보하세요. 서명 헤더, 저장된 PEM, 신뢰할 수 있는 origin과 함께 이 값들을 Verify에 전달합니다.

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. 유효하지 않은 RSA-SHA256 웹훅 서명 처리하기

캐시된 키로 서명을 검증하지 못하면 공개 키를 한 번 가져와 다시 검증하세요. 그래도 실패하는 요청에는 HTTP 401을 반환하고 결제 작업을 수행하면 안 됩니다. 유효하지 않은 요청에 *ok*로 수신 확인하지 마세요.

디버깅할 때는 검증기에 전달한 메시지와 실제 수신한 바이트를 비교하세요.

증상 확인할 항목
프록시 뒤에서 GET 검증 실패 설정된 외부 origin과 원래 인코딩된 요청 대상
JSON POST 검증 실패 파싱이나 직렬화로 원본 본문이 바뀌었는지
키 교체 후 검증 실패 캐시된 PEM을 한 번 갱신했는지
서명 디코딩 실패 헤더가 존재하고 base64 인코딩을 유지하는지

통제된 연동 점검에서는 실제 콜백을 확보하고 주문 업데이트 없이 검증하세요. 서명은 그대로 두고 서명 대상 메시지의 바이트 하나를 바꿉니다. 변경된 메시지는 반드시 검증에 실패해야 합니다. GET에서는 URL이나 쿼리를, POST에서는 원본 본문을 변경하세요. POST 쿼리 파라미터만 바꾸는 것은 본문 서명의 무결성 점검이 아닙니다. 쿼리는 해당 서명 메시지에 포함되지 않기 때문입니다.

5. 검증 후 결제를 확인하고 기록하기

유효한 서명은 서명된 메시지의 출처와 무결성을 확인해 줍니다. 해당 입금이 주문 대금을 충족하는지는 핸들러에서 별도로 판단해야 합니다.

저장된 nonce와 주문 참조값을 콜백 쿼리와 대조하세요. address_in, coin, 확정 금액도 저장된 주문과 확인합니다. 금액은 정확한 연산으로 변환하기 전까지 십진수 문자열로 보존하세요.

이벤트 UUID를 그에 따른 주문 변경과 함께 영구 저장하세요. 재전달은 같은 UUID를 사용하므로 이미 처리한 이벤트가 추가 이행을 유발하면 안 됩니다. pending 콜백과 확정 콜백은 UUID가 다릅니다. 늦게 온 pending 콜백이 확정 상태를 되돌리지 못하게 하세요.

금액 정책을 충족하고 pending이 "0"일 때만 주문을 이행하세요. 이후 30초 안에 HTTP 200과 일반 텍스트 본문 *ok*로 응답합니다. 재시도, 수신 확인, 이벤트 필드는 콜백 가이드에 설명되어 있습니다.

서명 검증에 관한 자주 묻는 질문

유효한 서명만으로 재전송 공격을 막을 수 있나요?

서명만으로 요청의 최신성을 입증할 수는 없습니다. 공개 콜백에는 타임스탬프가 없으며 캡처한 서명 메시지도 검증을 통과할 수 있습니다. 영속적인 UUID 중복 제거와 주문 상태 확인으로 같은 이벤트를 다시 처리해도 효과가 반복되지 않게 하세요.

핸들러에서 GET 쿼리 파라미터를 정렬해야 하나요?

아니요. 정확한 원본 쿼리 문자열을 검증하세요. 송신자는 콜백 URL에 필드를 추가하고 그 결과인 전체 URL에 서명합니다. 파싱된 값으로 쿼리를 다시 구성하면 순서나 인코딩이 바뀔 수 있습니다.

파싱된 JSON을 검증해야 하나요?

아니요. 원본 POST 본문을 먼저 검증한 뒤 파싱하세요. Node.js 함수가 Buffer를 요구하는 이유도 이것입니다. form POST도 같은 순서를 따르세요. 필드를 해석하기 전에 원본 본문을 검증해야 합니다.

서명 검증만으로 주문을 결제 완료 처리해도 되나요?

아니요. 검증된 입금을 저장된 주문과 대조하고 UUID 중복을 제거한 뒤 확정 금액을 판단하세요. 정상 pending 콜백도 여전히 대기 이벤트입니다. 정상적으로 확정된 입금도 주문 합계보다 적을 수 있습니다.