解密指南

本文说明接入方服务端如何解密平台接口返回的加密数据。对于采用平台客户端公钥加密机制的接口，平台会使用 API Key 配置中的 clientEncryptionPublicKey 加密业务 JSON，并返回密钥指纹和 Base64 编码的 RSA 密文；接入方使用与该公钥配对的私钥完成解密。

下文以 Reveal Sensitive Card 接口返回的卡敏感信息作为完整示例，覆盖 PHP、Java、Python 和 Node.js。其他返回加密数据的接口可以复用相同的密钥选择、Base64 解码和 RSA-OAEP 解密步骤；响应字段名及明文结构以具体接口说明为准。

仅限受控的服务端环境。 不要在浏览器、移动端、前端脚本或不受信任的终端中保存、传输或使用解密私钥。解密后的业务数据均应按敏感数据处理，不得写入应用日志、错误追踪、Apifox 报告或长期存储。下文卡示例中的 PAN、CVV 和有效期尤其不得记录或外泄。

1. 平台加密与解密契约

项目	值
平台加密公钥	API Key 配置中的 `clientEncryptionPublicKey`
接入方解密私钥	与 `clientEncryptionPublicKey` 配对、仅由接入方持有的私钥
RSA 密钥长度	2048 bit
加密算法	RSA-OAEP
OAEP 摘要	SHA-256
MGF	MGF1，摘要为 SHA-256
OAEP Label	空值
密文编码	Base64；解码后固定为 256 字节
明文编码	UTF-8 JSON
示例私钥格式	PKCS#8 PEM：`-----BEGIN PRIVATE KEY-----`

平台先将业务明文编码为 UTF-8 JSON，再使用 RSA-OAEP、SHA-256、MGF1-SHA-256 和空 Label 加密，最后以 Base64 输出密文。响应中的 keyFingerprint 用于让接入方确认当前密文对应哪一把客户端加密公钥。

解密使用的私钥必须与 clientEncryptionPublicKey 配对。它与 API 请求签名使用的 clientSigningPublicKey 是两个用途；除非接入方明确为两种用途配置了同一密钥对，否则不要使用签名私钥解密。

不同接口的响应字段名可能不同。以下成功响应结构以 Reveal Sensitive Card 接口为例：

{
  "success": true,
  "data": {
    "keyFingerprint": "SHA256:<64 位小写十六进制字符>",
    "encryptedPayload": "<Base64 编码的 RSA 密文>"
  }
}

该卡敏感信息示例解密后的 JSON 结构如下：

{
  "pan": "<12 至 19 位卡号>",
  "cvv": "<3 至 4 位安全码>",
  "expiryMonth": 12,
  "expiryYear": 2028
}

2. 平台通用解密流程

按具体接口契约确认 HTTP 状态和业务成功标识；下文示例要求 HTTP 200 且响应中的 success 为 true。

将响应中的密钥指纹与接入方可信配置保存的加密公钥指纹比较，避免选错私钥或密钥版本。

严格 Base64 解码密文字段；在本文的 RSA-2048 契约下，解码后的密文应为 256 字节。

使用 RSA-OAEP、SHA-256、MGF1-SHA-256 和空 Label 解密。

按 UTF-8 读取明文、解析 JSON，并根据当前接口的明文 Schema 校验字段格式。

仅在完成当前业务所需的最短时间内持有解密结果；不得打印明文或把明文放入异常信息。

以下示例中的 expectedFingerprint 应来自接入方可信配置，不能直接使用同一响应里的值作为期望值。四段代码均以 Reveal Sensitive Card 的 keyFingerprint、encryptedPayload 和卡字段校验为例；接入其他加密接口时，应替换响应取值和业务字段校验，不能改变接口声明的密码学参数。

3. PHP（卡敏感信息示例）

适用于 PHP 8.1+，使用 phpseclib 3：

如果私钥 PEM 使用口令保护，请通过 PublicKeyLoader::loadPrivateKey($privateKeyPem, $password) 加载，口令同样应由密钥管理系统提供。

4. Java（卡敏感信息示例）

适用于 Java 17+，解密部分只使用 JDK 标准库。示例接收 PKCS#8 PEM 私钥并返回明文 JSON；请再使用项目已有的 JSON 库解析。

调用方式：

不要省略显式的 OAEPParameterSpec。部分 Java Provider 对 MGF1 的默认摘要设置不同，仅在算法名称中写 OAEPWithSHA-256 不能充分表达本接口要求的 MGF1-SHA-256。

5. Python（卡敏感信息示例）

适用于 Python 3.10+，使用 cryptography：

如果私钥有口令，将 password=None 改为从密钥管理系统读取的 bytes 口令。

6. Node.js（卡敏感信息示例）

适用于 Node.js 18+，只使用内置 node:crypto：

oaepHash: 'sha256' 同时指定 OAEP 和 MGF1 使用 SHA-256。若私钥有口令，请在传给 privateDecrypt 的同一个选项对象中增加 passphrase 字段。

7. 通用错误与示例接口错误

现象	常见原因	处理方式
`keyFingerprint` 不匹配	使用了错误的 API Key、加密私钥或密钥版本	根据可信配置选择与 `clientEncryptionPublicKey` 配对的私钥
OAEP 解密失败	私钥不匹配；库默认使用 SHA-1；MGF1 摘要不是 SHA-256；密文损坏	显式设置 OAEP-SHA-256、MGF1-SHA-256 和空 Label
Base64 解码后不是 256 字节	响应被截断、复制错误或不是 RSA-2048 密文	不要继续解密，检查原始响应传输链路
解密成功但 JSON 解析失败	参数不一致、密文损坏或解密的不是本接口负载	拒绝处理，不要把原始明文写入日志
Reveal Sensitive Card 示例接口返回 `SLASH.REMOTE_ERROR`	上游卡服务请求失败，尚未进入本地解密阶段	按接口响应中的请求标识排查服务端日志

8. Apifox 调试注意事项

在 Apifox 中调试平台加密响应时，可把 PKCS#8 私钥放入仅本地可见的敏感变量 rsa_private_key。不要提交、共享或导出包含真实私钥的环境。

将解密后的 JSON 写回响应体（例如 pm.response.setBody(plaintext)）会使明文进入 Apifox 结果和测试报告。对于本文的卡敏感信息示例，这还会直接暴露 PAN 和 CVV。只可在已授权、隔离且报告不会留存或共享的临时调试中使用；常规测试应删除该语句，只断言解密成功和字段格式。