回调签名加密
前言
本文为回调接口(SUD OP SVR → APP 服务端)的签名与加密要求说明。密钥配置、算法参数、计算示例等完整流程,见《服务端 API 签名加密》。
回调方向不涉及任何新增密钥:回调请求用 SUD OpenPaaS 证书验签、用《服务端 API 签名加密》第二章配置的对称密钥解密;回调响应用应用私钥签名、用对称密钥加密。
强制要求:回调接口不存在明文模式。所有回调请求都必须先验签、再解密,任何一步失败都应直接拒绝,不得进入业务逻辑。
一、角色与密钥
调用接口由 APP 服务端加密并签名请求、验签并解密响应;回调方向反过来——同一套密钥,签名方与验签方互换。
| 环节 | 使用的密钥/证书 | 对端用什么校验 |
|---|---|---|
| 回调请求验签 | SUD OpenPaaS 证书中的公钥 | — |
| 回调请求解密 | 对称密钥 | — |
| 回调响应加密 | 对称密钥 | SUD OP SVR 用对称密钥解密 |
| 回调响应签名 | 应用私钥 | SUD OP SVR 用应用公钥验签 |
二、回调请求处理
按 验签 → 解密 → 业务校验 的顺序处理。验签或解密失败一律返回非 200,不要返回业务结果。
2.1 请求头
| 请求头名 | 必填 | 说明 |
|---|---|---|
| X-Sud-AppId | 是 | 当前 AppId,与解密后明文中的 _appid 一致 |
| X-Sud-Timestamp | 是 | 平台生成回调请求的时间戳(秒级) |
| X-Sud-Signature | 是 | 平台签名结果,Base64 编码 |
待验签串的公式、分隔符与 data 的取法见《服务端 API 签名加密》3.2.1,回调接口只有 urlpath 不同:
urlpath取回调地址本身的完整 URL(含协议与域名、不含 URL Query),须与 SUD OP 控制台配置值逐字符一致;data取 HTTP Body 的原始字节(密文报文),不得反序列化后重新序列化。
2.2 解密与验签
请求体的解密验签规范沿用《服务端 API 签名加密》第三章。
三、回调响应签发
响应同样需要加密 + 签名,校验方是 SUD OP SVR,响应头中的签名相关字段取的都是 APP 服务端自身的值。
3.1 响应头
| 响应头名 | 必填 | 说明 |
|---|---|---|
| X-Sud-AppId | 是 | 应用ID |
| X-Sud-Timestamp | 是 | APP 服务端生成响应的时间戳(秒级) |
| X-Sud-Serial | 是 | 应用非对称密钥编号,用于平台选择对应的应用公钥验签 |
| X-Sud-Signature | 是 | 用应用私钥对响应报文生成的签名,Base64 编码 |
| X-Sud-Serial-Deprecated | 否 | 即将失效的应用密钥编号(应用密钥轮换期返回) |
| X-Sud-Signature-Deprecated | 否 | 即将失效的应用密钥签名数据,Base64 编码(应用密钥轮换期返回) |
这组字段与开放接口响应的字段名相同但来源不同:开放接口响应由 SUD OP SVR 用平台证书签发,回调响应由 APP 服务端用应用密钥签发。不要因为字段名相同而误用证书编号和平台签名。
3.2 加密与签名
响应体的加密签名规范沿用《服务端 API 签名加密》第三章。
