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