接口响应签名

概述

在 API 签名验证通过后，BKJ 系统会在接口响应的 headers 里添加一个签名 x-response-signature，BKJ 确保每一个请求返回的签名都具有唯一性。调用方可以使用 api_key 对该签名进行 ED25519 数字签名校验，以达到验证响应数据合法性，防篡改等。

工作流程

┌─────────┐          ┌──────────┐          ┌─────────┐ 
│  调用方  │  ──1──>  │ 开放平台  │  ──2──>   │调用方    │  
│         │          │(签名验证) │           │验证签名  │  
└─────────┘          └──────────┘          └─────────┘         

1. 调用方使用 api_secret 生成 HMAC-SHA256 请求签名
2. 请求签名验证通过后，生成 ED25519 响应签名，通过 x-response-signature 请求头传递
3. 调用方使用 api_key（或 api_secret) 验证响应签名，并可通过对签名进行唯一性校验，达到防重放攻击的目的

实现细节

1. 响应签名生成（服务端）

当 API 签名验证通过后，系统会：

构造响应数据字符串（简化版）：

使用 api_secret 生成 ED25519 签名：

将签名添加到请求头传递给上游：

请求头名称：x-response-signature

签名格式：Base64 编码的 ED25519 签名（64 字节）

2. 响应签名验证（调用方）

调用方收到响应后：

从响应头获取签名：

构造验证数据（只需要timestamp、nonce和api_key）：

验证签名（使用api_secret）：

优势：调用方只需验证签名的有效性，无需重新构造复杂的请求信息（method、path、query等）。只需要：

自己的 api_key

本地记录的 timestamp 和 nonce

自己的 api_secret

只要签名验证通过，就证明响应来自持有api_secret的服务端，且对应于正确的请求（timestamp、nonce、api_key）。

密钥说明

当前实现

在当前实现中，签名和验证都使用相同的密钥派生：

签名：使用 SHA256(api_secret) 派生 ED25519 签名密钥

验证：使用 SHA256(api_secret) 派生验证密钥

因此，调用方验证时需要使用 相同的 api_secret。

建议改进

为了更好地实现公私钥分离，建议：

使用 api_secret 作为私钥进行签名（服务端）

使用 api_key 作为公钥进行验证（调用方）

在 API Key 生成时，同时生成 ED25519 密钥对

API 示例

请求示例

响应示例

说明：响应签名是对 timestamp|nonce|api_key 的签名。调用方可以使用原始请求的 timestamp、nonce 和自己的 api_key 来验证签名，无需从响应头获取额外信息。

代码示例

调用方验证

安全注意事项

密钥安全：

api_secret 必须安全存储，不能暴露给调用方

建议使用环境变量或密钥管理服务存储

签名有效期：

响应签名绑定了时间戳，建议设置合理的时间窗口

防止重放攻击

签名验证：

调用方必须验证响应签名

验证失败应拒绝处理响应数据

篡改检测：

签名包含请求的关键信息（方法、路径、参数等）

任何篡改都会导致签名验证失败

技术优势

ED25519 算法：

签名速度快

签名长度短（64 字节）

安全性高

确定性签名：

相同输入产生相同签名

便于调试和验证

防篡改：

任何数据修改都会导致签名验证失败

保证响应数据的完整性

接口响应安全校验

接口响应签名

概述

工作流程

实现细节

1. 响应签名生成（服务端）

2. 响应签名验证（调用方）

密钥说明

当前实现

建议改进

API 示例

请求示例

响应示例

代码示例

调用方验证

安全注意事项

技术优势

相关文档

接口响应安全校验

接口响应签名#

概述#

工作流程#

实现细节#

1. 响应签名生成（服务端）#

2. 响应签名验证（调用方）#

密钥说明#

当前实现#

建议改进#

API 示例#

请求示例#

响应示例#

代码示例#

调用方验证#

安全注意事项#

技术优势#

相关文档#

接口响应签名

概述

工作流程

实现细节

1. 响应签名生成（服务端）

2. 响应签名验证（调用方）

密钥说明

当前实现

建议改进

API 示例

请求示例

响应示例

代码示例

调用方验证

安全注意事项

技术优势

相关文档