API使用说明.md 6.3 KB
签名服务API使用说明
服务介绍
这是一个基于SM2算法的HTTP签名服务，提供数据签名和验签功能。
启动服务
cd /Users/light/www/pros/xingfutong-java
java -cp "bin:lib/*" demo.com.SignServer
服务启动后将监听 8888端口
API接口说明
1. 健康检查接口
接口地址: GET http://localhost:8888/api/health
功能: 检查服务是否正常运行
响应示例:
{
"status": "ok",
"timestamp": 1761288550040
}
2. 签名接口
接口地址: POST http://localhost:8888/api/sign
功能: 对传入的数据进行SM2签名
请求头:
Content-Type: application/json
请求参数:
{
"data": {
"key1": "value1",
"key2": "value2",
...
},
"priKey": "您的SM2私钥（可选）",
"reqOrgNo": "机构号（可选）"
}
参数说明:
data: 对象类型，必填，包含需要签名的所有键值对priKey: 字符串类型，可选，SM2私钥（十六进制格式）。如不提供则使用服务器配置的默认私钥reqOrgNo: 字符串类型，可选，请求机构号。如不提供则使用服务器配置的默认机构号- 系统会自动将key转为大写，并按字母顺序排序
- 空值字段会被自动过滤
响应示例:
{
"success": true,
"signData": "KEY1=value1|KEY2=value2",
"sign": "304402206FC7DE55665BE3C062355D88A9A77AE5877FE3D5B42EBB3EAA46AF50E08DB53A0220105E6C4399B50825E98D6816FBF9B6D2E4603EB5EB6F5440F60728EDD8D0BA46",
"timestamp": 1761288550594
}
响应字段说明:
success: 是否成功signData: 实际签名的数据串（按KEY升序排列）sign: 十六进制签名结果timestamp: 时间戳
使用示例1 - 使用默认私钥:
curl -X POST http://localhost:8888/api/sign \
-H "Content-Type: application/json" \
-d '{
"data": {
"version": "1.0",
"txnType": "20250",
"reqOrgId": "201811200001003",
"cardNo": "9206068000000010425"
}
}'
使用示例2 - 传入自定义私钥:
curl -X POST http://localhost:8888/api/sign \
-H "Content-Type: application/json" \
-d '{
"data": {
"version": "1.0",
"txnType": "20250",
"reqOrgId": "201811200001003"
},
"priKey": "您的SM2私钥（64位十六进制字符串）",
"reqOrgNo": "您的机构号"
}'
3. 验签接口
接口地址: POST http://localhost:8888/api/verify
功能: 验证签名是否正确
请求头:
Content-Type: application/json
请求参数:
{
"data": {
"key1": "value1",
"key2": "value2",
...
},
"sign": "签名字符串",
"pubKey": "公钥（可选）",
"reqOrgNo": "机构号（可选）"
}
参数说明:
data: 对象类型，必填，包含需要验签的所有键值对sign: 字符串类型，必填，待验证的签名（十六进制格式）pubKey: 字符串类型，可选，SM2公钥（十六进制格式）。如不提供则使用服务器配置的默认公钥reqOrgNo: 字符串类型，可选，请求机构号。如不提供则使用服务器配置的默认机构号
响应示例:
{
"success": true,
"valid": true,
"signData": "KEY1=value1|KEY2=value2",
"timestamp": 1761288550803
}
响应字段说明:
success: 请求是否成功valid: 签名是否有效signData: 实际验签的数据串timestamp: 时间戳
使用示例1 - 使用默认公钥:
curl -X POST http://localhost:8888/api/verify \
-H "Content-Type: application/json" \
-d '{
"data": {
"version": "1.0",
"txnType": "20250",
"reqOrgId": "201811200001003"
},
"sign": "304402206FC7DE55665BE3C062355D88A9A77AE5877FE3D5B42EBB3EAA46AF50E08DB53A..."
}'
使用示例2 - 传入自定义公钥:
curl -X POST http://localhost:8888/api/verify \
-H "Content-Type: application/json" \
-d '{
"data": {
"version": "1.0",
"txnType": "20250",
"reqOrgId": "201811200001003"
},
"sign": "304402206FC7DE55665BE3C062355D88A9A77AE5877FE3D5B42EBB3EAA46AF50E08DB53A...",
"pubKey": "您的SM2公钥（130位十六进制字符串）",
"reqOrgNo": "您的机构号"
}'
错误响应
当发生错误时，返回格式如下：
{
"success": false,
"error": "错误信息",
"timestamp": 1761288550848
}
常见错误:
data参数不能为空- 签名/验签时data对象为空data和sign参数不能为空- 验签时缺少必要参数只支持POST请求- 使用了错误的HTTP方法
快速测试
项目提供了测试脚本，可以快速测试所有接口：
./test_sign_api.sh
测试脚本会自动执行以下测试：
- 健康检查
- 简单参数签名
- 完整参数签名
- 签名验证
- 错误处理测试
签名规则说明
字段处理:
- 所有key会转换为大写
- 空值字段会被过滤
- 按key的字母顺序升序排列
签名串生成:
- 格式:
KEY1=value1|KEY2=value2|KEY3=value3 - 使用竖线(|)分隔各字段
- 使用等号(=)连接key和value
- 格式:
签名算法:
- 使用SM2国密算法
- 编码方式: UTF-8
- 输出格式: 十六进制字符串
注意事项
- 服务默认监听8888端口，如端口被占用请修改
SignServer.java中的端口配置 - 签名使用的私钥和机构号已在代码中配置
- 验签使用的是平台公钥，与签名私钥不是配对的，所以验签测试会返回false（这是正常现象）
- 如需在生产环境使用，请修改配置并确保密钥安全
配置说明
在 SignServer.java 中可以配置：
// 请求机构号
private static String reqOrgNo = "201811200001003";
// 请求机构的私钥
private static String priKey = "3164EE0DF2BCA7A12309383E3305DD6563A28DFE53F65BBD60B3A1D7F80AC275";
// 平台给商户的公钥
private static String sltPubKey = "046875695CDF1EF046ABB231FDAFA6DCA2AF1E5719EAC00DE80D65FEF03F8485DC9DCBBC10A9A46D565B4CDCEE3510F276209657CAE5BAC10C9678583A44F7F100";
联系支持
如有问题，请检查：
- 服务是否正常启动
- 端口是否被占用
- 请求格式是否正确
- 参数是否完整