会话密钥解密指引
用户在游戏内完成登录后,SUD OP SVR 会为当前用户的登录态生成一个会话密钥(sessionKey),并将其加密为 encrypted_session_key,经由客户端(APP)传递给 APP 服务端(APP SVR)。由于传递链路会经过端侧,因此 sessionKey 必须以密文形式传输以确保安全。
APP SVR 收到 encrypted_session_key 后,需按照本文指引进行解密,获取真实的 sessionKey。该密钥将在后续业务流程中用于对用户敏感信息进行加密,具体请参考:
一、前置准备
在开始集成前,请确保完成以下准备工作:
- 配置数据对称加密密钥:需在 SUD OpenPaaS 管理后台完成对称密钥的配置(详见 数据安全密钥说明)。当前采用 AES-256-GCM 算法,密钥为 32 字节(256 位),配置为 Base64 编码。请妥善保管该密钥。
二、解密与校验流程
1. 对数据进行Base64解码
将获取到的 encrypted_session_key(Base64 字符串)解码为二进制数据 (byte array / Buffer)。
2. 拆分数据
解码后的二进制密文数据结构固定为以下拼接格式:
text
+----------------+-------------------+-------------------+
| IV (12 字节) | 密文 (变长) | 认证标签 (16 字节) |
+----------------+-------------------+-------------------+IV:初始化向量,12 字节
密文:加密后的载荷数据,长度可变
认证标签:GCM 模式的认证信息,16 字节
3. 解密与认证
使用相同的数据对称加密密钥、IV、认证标签对密文进行 AES-256-GCM 解密。
解密成功时,返回原始 JSON 字符串载荷。
解密失败时,说明数据无效或被篡改。
4. 校验载荷内容
解密后得到 JSON 字符串,其中包含以下字段:
json
{"user_id":"xxx","session_key":"xxx"}| 参数名 | 必填 | 类型 | 说明 |
|---|---|---|---|
| user_id | 是 | string | 用户的唯一标识 ID |
| session_key | 是 | string | 会话密钥 |
参数校验规则:
user_id校验解密得到的user_id是否与当前请求的用户 ID 一致;session_key为后续业务交互的会话密钥,需在服务端安全存储,不可下发至客户端。
三、示例代码
完整示例代码(包含 Base64 解码、IV/密文/标签拆分、AES-256-GCM 解密与载荷字段校验)见 示例代码 下各语言版本的 「2. sessionKey 解密」 章节。
四、常见问题排查
解密失败常见原因
- 密钥不匹配:解密使用的密钥与加密时不一致。
- 数据格式错误:Base64 解码失败,或数据长度不足 12+16 字节。
- 认证标签错误:数据被篡改、标签提取位置错误或 GCM 认证失败。
- IV 长度不一致:未按 12 字节拆分。
- 跨语言兼容性问题:拼接顺序必须严格为 IV + 密文 + 标签。
