API 参考

REST API 完整接口文档，Base URL、认证方式、SM2/SM3/SM4 接口说明，含请求响应示例和错误码。

版本：v2 · 更新：2025-03-01 · Content-Type: application/json

📡

Base URL：https://crypto.your-domain.com/api/v2
所有请求需携带 Authorization: Bearer <api_key> 请求头，响应为 JSON 格式。

认证

所有 API 请求须在 Header 中携带 API Key：

HTTP Header

Authorization: Bearer dscc_ak_xxxxxxxxxxxxxxxxxx
Content-Type: application/json

SM4 加解密

POST /crypto/sm4/encrypt

使用 SM4 算法加密数据，支持 CBC / GCM / CTR 三种模式。

请求体：

参数	类型	必填	说明
`plaintext`	string	是	明文，Base64 编码
`key_id`	string	是	KMS 密钥 ID
`mode`	string	否	CBC（默认）/ GCM / CTR
`iv`	string	否	IV，Base64，不传则自动生成
`aad`	string	否	附加数据，仅 GCM 模式

Request

POST /api/v2/crypto/sm4/encrypt
{
  "plaintext": "SGVsbG8sIFNNNCE=",
  "key_id": "key-sm4-001",
  "mode": "CBC"
}

Response 200

{
  "code": 0,
  "data": {
    "ciphertext": "a3f8c2e1...",   // Base64
    "iv": "1a2b3c4d...",           // Base64，CBC/CTR 模式返回
    "tag": null,                   // GCM 模式返回认证标签
    "key_id": "key-sm4-001",
    "algorithm": "SM4-CBC",
    "request_id": "req_abc123"
  }
}

POST /crypto/sm4/decrypt

SM4 解密，参数与加密对称，需传入加密时返回的 iv。

SM2 签名验签

POST /crypto/sm2/sign

使用 SM2 算法对数据进行数字签名。

参数	类型	必填	说明
`data`	string	是	待签名数据，Base64
`key_id`	string	是	SM2 密钥对 ID
`hash_algo`	string	否	SM3（默认）/ SHA-256

Response 200

{
  "code": 0,
  "data": {
    "signature": "MEYCIQDx...",   // DER 编码，Base64
    "key_id": "key-sm2-001",
    "algorithm": "SM2withSM3"
  }
}

POST /crypto/sm2/verify

验证 SM2 签名，返回 valid: true/false。

SM3 哈希

POST /crypto/sm3/hash

Request / Response

// Request
{"data": "SGVsbG8="}

// Response
{"code": 0, "data": {"hash": "becbbfaae6548b8bf0cfcad5a27183cd...", "algorithm": "SM3"}}

错误码

code	HTTP 状态	含义	处理建议
0	200	成功	—
1001	401	API Key 无效或过期	检查 Authorization header
1002	403	无权访问该密钥	检查密钥访问控制配置
2001	404	密钥 ID 不存在	检查 key_id 是否正确
2002	400	密钥已禁用	联系管理员重新启用密钥
3001	400	参数格式错误	检查 Base64 编码是否正确
3002	400	明文超过长度限制	单次最大 4MB，分块处理
5001	503	服务暂时不可用	等待后重试，建议指数退避
5002	429	请求频率超限	降低并发或联系支持提额

频率限制

默认每个 API Key 限速：

SM4 加解密：500 次/秒
SM2 签名：200 次/秒
SM3 哈希：1000 次/秒

需要更高并发请联系技术支持，我们会根据部署的硬件密码机配置调整限额。