接口/快捷签署v1签名

1. 接口签名安全机制概述

所有受保护的 API 请求都需要在 HTTP 请求头中携带数字签名信息。签名采用 SM2 国密算法，确保请求的完整性和不可否认性。

1.1 签名流程

构建待签名原文字符串

使用私钥对原文进行 SM2 签名

将签名结果进行 Base64 编码

将签名值和相关参数添加到请求头中

2. 请求头要求

每个需要签名的请求必须包含以下 HTTP 请求头：

请求头名称	说明	示例
`Authorization`	客户端访问Token	`bd84a48615f04de0ae6d956966da07d5`
`X-DJQ-Timestamp`	请求时间戳（毫秒）	`1709876543210`
`X-DJQ-Nonce`	应用侧随机字符串	`550e8400-e29b-41d4-a716-446655440000`
`X-DJQ-Signature`	SM2 签名后的 Base64 编码值	`MEUC...`

3. 待签名原文构建规则

待签名原文由多个部分按顺序拼接而成，每部分之间用换行符 \n 分隔。

3.1 原文结构

HTTP 方法\n
URL 路径\n
查询参数（可选）\n
请求时间戳\n
随机数\n
请求数据排序字符串\n

3.2 各部分详细说明

3.2.1 HTTP 方法

请求的 HTTP 方法，使用大写形式，如：POST、GET。

3.2.2 URL 路径

请求的 URI 路径（不包含域名和查询参数），如：/api/v1/resource。

3.2.3 查询参数（可选）

如果 URL 包含查询参数，需要将所有参数按字典序排序后拼接成 key1=value1&key2=value2 格式。

3.2.4 请求时间戳

与请求头 X-DJQ-Timestamp 相同的毫秒时间戳值。

3.2.5 随机数

与请求头 X-DJQ-Nonce 相同的应用侧随机字符串。

3.2.6 请求数据排序字符串

根据请求的 Content-Type 不同，处理方式如下：

场景 1：application/json

将 JSON 请求体解析为 Map，按 key 的字典序排序后拼接成 k1=v1&k2=v2&k3=v3 格式。

场景 2：multipart/form-data

将string类型表单参数按 key 的字典序排序后拼接成 k1=v1&k2=v2 格式。

4. 签名生成示例

4.1 Java 代码示例

            <dependency>
                <groupId>com.sheca.esframework</groupId>
                <artifactId>es-util-crypto</artifactId>
                <version>0.15.2</version>
            </dependency>

4.2 完整签名示例

假设有一个 POST 请求：

请求信息：

HTTP 方法：POST

URL 路径：/api/v1/example

请求体：{"param2":"v2","param1":"v1"}

时间戳：1709876543210

随机数：550e8400-e29b-41d4-a716-446655440000

待签名原文：

POST
/api/v1/example
1709876543210
550e8400-e29b-41d4-a716-446655440000
param1=v1&param2=v2

最终请求头：

Content-Type: application/json
Authorization: Bearer {{access token}}
X-DJQ-Timestamp: 1709876543210
X-DJQ-Nonce: 550e8400-e29b-41d4-a716-446655440000
X-DJQ-Signature: {{SM2 签名后的 Base64 值}}

5. 注意事项

5.1 时间戳有效性

时间戳应为当前时间的毫秒值

建议使用系统当前时间，避免手动设置

服务器可能会验证时间戳的有效性（如前后 5 分钟内）

5.2 随机数唯一性

每次请求应使用唯一的随机字符串作为随机数

防止重放攻击

5.3 参数排序规则

所有参数（JSON 字段、查询参数、表单参数）必须按字典序排序

使用 TreeMap 或类似工具可自动排序

5.4 空值处理

空请求体时，请求数据排序字符串部分可以为空

null 值在拼接时应转换为空字符串

5.5 字符编码

所有内容使用 UTF-8 编码

确保请求体编码与签名时使用一致

6. 错误处理

如果签名验证失败，服务器将返回相应的错误信息。请检查：

待签名原文的构建是否正确

参数排序是否符合字典序

时间戳和随机数是否与请求头一致

SM2 私钥是否正确

Base64 编码是否正确

9. 安全建议

私钥保护：SM2 私钥应存储在安全的环境中，避免泄露

私钥泄露：若私钥不慎泄露，务必及时联系平台方申请更换

1. 接口签名安全机制概述#

1.1 签名流程#

2. 请求头要求#

3. 待签名原文构建规则#

3.1 原文结构#

3.2 各部分详细说明#

3.2.1 HTTP 方法#

3.2.2 URL 路径#

3.2.3 查询参数（可选）#

3.2.4 请求时间戳#

3.2.5 随机数#

3.2.6 请求数据排序字符串#

4. 签名生成示例#

4.1 Java 代码示例#

4.2 完整签名示例#

5. 注意事项#

5.1 时间戳有效性#

5.2 随机数唯一性#

5.3 参数排序规则#

5.4 空值处理#

5.5 字符编码#

6. 错误处理#

9. 安全建议#