回调验签

RSA-SHA512 回调验签

I. 目的

为确认回调来自 Setu 且正文未被改动，使用 Setu 的 RSA 公钥和 SHA-512 校验 Signature 请求头（算法名 SHA512withRSA）。

II. 何时需要验签

收到 Setu 回调后，先校验 Signature，通过后再处理业务。验签失败的回调应丢弃。

III. 结构与规则

回调带有 Signature 和 Timestamp。对待验字符串做 SHA512withRSA 验签，公钥为 Setu 的公钥。待验字符串不含请求路径。

验签算法

摘要： SHA-512（512 位安全散列）

签名： RSA，PKCS#1 v1.5

算法名： SHA512withRSA

编码： 标准 Base64

拼接待验字符串

待验字符串：

stringToVerify = sha512Hex(rawBody) + timestamp

说明：

rawBody：收到的回调 JSON 原始字节（UTF-8）。先解析再序列化会改变字段顺序、空格或数字类型，验签会失败。

sha512Hex：对 rawBody 计算 SHA-512，输出小写十六进制，共 128 个字符。

timestamp：Timestamp 请求头的原始字符串，单位为秒。不要改用本机当前时间。

路径、域名、查询串都不参与验签。

示例正文（末尾无换行，只用于演示哈希）：

{"transactionRef":"e50f5496-1316-4fa6-a206-98be03550c4d","merchantRef":"19e5b36d-c9d6-4cb4-8e4e-e6fe0e3a0cb5","currency":"INR","method":"NATIVE","amount":"100.01","paidAmount":"100.01","fee":"5.5","status":"Success"}

对应的小写十六进制 SHA-512：

9e0fa54a47570bf67f9bff06fbabc2a1a220863dfa5f50514e220287ad5bcdeb46f07090e1bf2180cba4360a45a35cb0cf9dd705401bddfdaa18c275ecbb8688

Timestamp 为：

1699447297

待验字符串为：

9e0fa54a47570bf67f9bff06fbabc2a1a220863dfa5f50514e220287ad5bcdeb46f07090e1bf2180cba4360a45a35cb0cf9dd705401bddfdaa18c275ecbb86881699447297

使用公钥验签

使用 Setu 的 RSA 公钥，对 stringToVerify 的 UTF-8 字节做 SHA512withRSA 验签。

验签前将 Signature 按标准 Base64 解码。Base64 区分大小写，不要使用 URL-safe 解码。

公钥为 X.509（-----BEGIN PUBLIC KEY-----）。

验签通过表示该正文和时间戳由 Setu 私钥签过，且之后没有被改动。

回调请求头：

请求头	值
`Timestamp`	Unix 秒级时间戳，与拼入待验字符串的值相同
`Signature`	Setu 私钥签名的标准 Base64
`Content-Type`	`application/json`

IV. 安全说明

Setu 使用自己的私钥对回调签名，商户使用 Setu 公钥验签。
待验字符串是 sha512Hex + timestamp，不含路径。商户请求 Setu 时的 path + sha512Hex + timestamp 不能用在回调上。
正文哈希和时间戳都在签名范围内。验签通过后仍应只使用原始正文里的字段，不要改用另一份重新序列化的 JSON。

V. 注意事项

待验字符串区分大小写，必须逐字节一致。正文哈希必须是小写十六进制。
哈希的必须是 HTTP 正文原始字节，不能格式化、重排字段或增删空格。
Timestamp 从请求头读取，单位是秒，并且与 Setu 签名时使用的值相同。
Signature 使用标准 Base64（字母表含 +、/、=），验签前先解码。
示例正文只说明哈希算法。正式回调的字段以接口文档为准，验签时仍对收到的原始正文计算哈希。

VI. 代码示例

Java

Python

PHP

C#(.NET Core)

RSA-SHA512 回调验签#

I. 目的#

II. 何时需要验签#

III. 结构与规则#

IV. 安全说明#

V. 注意事项#