游戏获取用户信息

1. 架构概述与参与角色

本流程描述了游戏客户端如何通过 SUD OP，在 APP 的授权下，安全地获取用户个人信息。根据 APP 愿意提供的数据敏感度，分为用户基础信息获取和用户敏感信息获取。

• APP: 应用客户端
• SUD OP: 集成在客户端内的通信中间件
• Game: 游戏客户端
• Game SVR: 游戏的服务端
• SUD OP SVR: SUD 的服务端（核心凭证流转与校验中枢）
• APP SVR: 应用的服务端

2. 前置条件

• Login 流程已完成：用户已完成游戏内的 Login 流程。
• 密钥就绪（仅针对用户敏感信息获取）：在 Login 过程中，SUD OP SVR 已为该用户在当前游戏内生成了唯一的会话密钥 sessionKey，且 Game SVR 已经成功获取并在服务端持有了该密钥。

3. 用户基础信息获取（非敏感数据 / 无加密流程）

适用场景：APP 仅向游戏提供公开、非敏感的基础信息（用户昵称、头像）。此类数据即使在网络传输或客户端被截获，也不会造成核心资产泄漏。 优势：链路极短，无需服务端参与复杂的票据流转与加解密，响应极快。

3.1 获取基础信息交互时序图

3.2 关键步骤说明

1. 发起请求：Game 调用 SUD OP 发起请求，透传至 APP。
2. 获取明文数据：APP 识别出当前游戏仅需基础信息，直接从本地缓存提取，或向自己的 APP SVR 发起普通的数据拉取请求。
3. 直接返回：APP 将明文的 userinfo 沿原路返回给 Game，流程结束。

4. 用户敏感信息获取（高安全级别 / 完整加密流程）

适用场景：APP 需要向游戏提供敏感的个人资产数据（如：手机号、真实姓名、APP 内真实 UID 等）。 机制：借助 SUD OP SVR 获取加密的会话密钥 (encrypted_session_key)，并在 APP SVR 侧解密（解密方式）获取真实的 sessionKey用于对用户敏感信息进行加密。

4.1 获取敏感信息交互时序图

4.2 APP SVR 数据处理约束与算法规范

根据安全合规要求，APP SVR 在向 APP 响应用户敏感数据时，必须严格遵循以下算法逻辑完成加密与签名。

1. 算法选型基础

类别	算法	说明
数据加密	AES-128-CBC	密钥必须是 sessionKey 经过 Base64 解码后得到的 16 字节 byte 数组，配合 16 字节的随机 IV。
数据签名	SHA1 (或 SHA256)	使用原文拼接 sessionKey 字符串进行哈希，保障数据传输不被篡改。
填充模式	PKCS7Padding	加密块对齐必须使用此填充方式。

2. 加密机制详细说明 (Encryption)

敏感数据（如手机号、真实姓名等）绝对不能以明文在网络中传输，必须进行 AES 加密。

• 步骤 1：获取密钥。APP SVR 内部解密 encrypted_session_key，获得该会话的 sessionKey（该值通常为一个 24 字符的 Base64 字符串）。
• 步骤 2：生成 IV。由 APP SVR 随机生成一个 16 字节的初始向量（IV）byte 数组。注意：每次加密必须重新生成随机 IV，严禁写死固定值。
• 步骤 3：序列化敏感数据。将需要加密的敏感字段组装为 JSON 字符串，并转为 UTF-8 的 byte 数组。
• 步骤 4：执行加密。将步骤 1 获得的 sessionKey 字符串进行 Base64 解码，得到 16 字节的 AES 秘钥。使用该秘钥和步骤 2 的 IV，通过 AES-128-CBC/PKCS7Padding 算法对步骤 3 的 JSON byte 数组进行加密，得到二进制密文。
• 步骤 5：Base64 编码。对二进制密文和二进制 IV 分别进行 Base64 编码，最终得到输出的 encryptedData 和 iv 字符串。

【加密机制举例】 假设解密得到的 sessionKey 为：tiihtNczf5v6AKRyjwEUhQ==（这是一个标准的 16 字节 Base64 字符串） APP SVR 随机生成的 iv 为：1a2b3c4d5e6f7g8h（转为 byte 数组共 16 字节） 需要加密的敏感数据 JSON 为：{"phoneNumber":"13800138000"}

1. 将 sessionKey 进行 Base64 解码，得到 AES 秘钥 byte[]。
2. 将 iv 进行 Base64 编码，生成返回参数中的 iv：MWEyYjNjNGQ1ZTZmN2c4aA==。
3. 将 JSON 明文转为 byte[]。
4. 使用上述 AES 秘钥和 IV 进行 AES-128-CBC 加密，得到密文 byte[]。
5. 对密文 byte[] 进行 Base64 编码，生成返回参数 encryptedData：k3A8n9/...+aBdE=。

3. 签名机制详细说明 (Signature)

为了确保接口返回用户数据的安全性，APP SVR 必须对明文数据进行签名。

• 步骤 1：准备待签名原文。提取准备返回给客户端的 rawData 字段。
• 步骤 2：拼接密钥。将 rawData 与 16 字节的 sessionKey 直接拼接在一起，形成一个新的长字符串。
  • 拼接格式：拼接字符串 = rawData + sessionKey
• 步骤 3：计算摘要。使用 SHA1（或约定的 SHA256）算法对上述拼接好的长字符串进行哈希运算，得到二进制摘要。
• 步骤 4：Hex 编码。将二进制摘要转换为十六进制（Hex）字符串（小写字母+数字），生成最终的 signature。

【签名机制举例】 假设解密后的 sessionKey 为：5K826NuS40k6289b 需要返回的 rawData 字符串为：{"nickname":"张三","avatarUrl":"https://domain.com/a.png"}

1. 待签名原文：{"nickname":"张三","avatarUrl":"https://domain.com/a.png"}
2. 拼接密钥后的字符串：{"nickname":"张三","avatarUrl":"https://domain.com/a.png"}5K826NuS40k6289b
3. 对上述拼接字符串执行 SHA1 计算，得到二进制摘要。
4. 转为 Hex 字符串，生成最终 signature：1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s0t (示例值)

4.3 APP SVR 响应参数 (Body)

接口返回 Content-Type 必须为 application/json。APP SVR 必须严格按照以下字段返回给 APP：

参数名	类型	必传	说明
userInfo	UserInfo	是	用户信息对象，不包含 openid 等敏感信息
rawData	string	是	不包括敏感信息的原始数据字符串，用于计算签名
encryptedData	string	是	用户敏感信息（如手机号等）经过 AES-128-CBC 加密后生成的 Base64 密文串。
iv	string	是	AES 加密时使用的 16 字节随机初始向量经过 Base64 编码后的字符串。
signature	string	是	使用 rawData 字符串拼接 sessionKey 后，进行 SHA1（或 SHA256）计算得到的 Hex（十六进制） 字符串。

• UserInfo 用户信息说明

参数名	类型	必传	说明
nickname	string	是	用户昵称。
avatarUrl	string	是	用户头像图片的 URL。

4.4 响应示例

{
  "userInfo": {"nickname":"张三","avatarUrl":\"https://res.domain.com/a.png"},
  "rawData": "{\"nickname\":\"张三\",\"avatarUrl\":\"https://res.domain.com/a.png\"}",
  "encryptedData": "C6T9Xp7z8L6mQwZkF1vO9/jR4a...[Base64]...",
  "iv": "MWEyYjNjNGQ1ZTZmN2c4aA==",
  "signature": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}

5. APP 侧安全规范与开发避坑指南

作为提供用户数据的一方，APP SVR 在接入该流程时请务必遵守以下安全与开发规范，以保障数据不被泄露且下游能顺利解密：

5.1 加密材料的绝对随机（防重放）

AES-128-CBC 加密所使用的初始向量（iv）必须在每次请求时动态随机生成（16 字节）。严禁在代码中写死固定值，否则会导致加密丧失随机性，面临严重的重放攻击与频率分析破解风险。

5.2 签名原串的严格一致（防验签失败）

这是联调中最常出现的错误。APP SVR 在计算 HMAC-SHA256 签名时，传入的原文必须与最终响应报文中的 rawData 字段字节级完全一致（包括空格、换行、双引号转义等）。

5.3 解密私钥的安全保管

APP SVR 用于解密 encrypted_session_key 的约定私钥，属于最高级别敏感资产。必须妥善存放在应用服务端的密钥管理系统（如 KMS、Vault）或安全配置中心内，严禁硬编码在代码中，绝对不可下发至 APP 客户端。

5.4 异常阻断与合规

• 解密失败拦截：如果 APP SVR 发现 encrypted_session_key 解密失败（如报文损坏、非法的密钥），必须立即阻断业务，不应返回任何用户数据，可抛出系统约定好的异常错误码。
• 最小化原则：APP SVR 组装 encryptedData 时，应严格遵循隐私合规最小化原则，仅打包当前游戏业务明确声明需要、且用户已授权的敏感字段，避免过度提供数据。