Skip to content

回调签名加密 ​

前言 ​

本文为回调接口(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 签名加密》第三章。