签名服务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";

联系支持

如有问题，请检查：

服务是否正常启动
端口是否被占用
请求格式是否正确
参数是否完整

API使用说明.md 6.3 KB Permalink History Raw

签名服务API使用说明

服务介绍

启动服务

API接口说明

1. 健康检查接口

2. 签名接口

3. 验签接口

错误响应

快速测试

签名规则说明

注意事项

配置说明

联系支持

API使用说明.md 6.3 KB

Permalink History Raw