一句话定义

API 签名 = 用 mall_id + 业务参数 + 时间戳 + appkey 拼成字符串,再做 md5 哈希。服务器收到请求后用同样的算法算签名,对比客户端传的签名,一致 = 请求合法。

一、为什么需要 API 签名

HTTPS 已经加密传输了,为什么还要签名?

防御目标HTTPSAPI 签名中间人窃听✅ 防御✅ 防御 请求篡改❌ 无法✅ 防御 重放攻击❌ 无法✅ 防御(配合 tm) 身份冒用❌ 无法✅ 防御(配合 appkey)

签名 = 防请求篡改 + 防重放 + 防冒用。HTTPS 只解决"加密传输",不解决"请求完整性"。

二、签名的 3 个核心要素

要素 1:mall_id(商户 ID)

控制台申请,公开传给服务端

类比:门牌号(别人知道也能找到你,但没有钥匙开不了门)

要素 2:appkey(签名密钥)

控制台申请,必须保密

类比:钥匙(只有你知道,别人拿走就能冒充)

要素 3:tm(时间戳)

13 位毫秒时间戳

类比:短信验证码的"5 分钟有效期"

防重放:服务器只接受 ±5 分钟的请求

三、签名生成原理(以银行卡四要素为例)

步骤 1:准备业务参数

参数含义示例 mall_id商户 IDMALL001 realname姓名张三 idcard身份证号110101199001011234 cardnum银行卡号6222021234567890123 bankPreMobile银行预留手机号13800138000 tm13 位毫秒时间戳1700000000000

步骤 2:按固定顺序拼接

sign = md5(mall_id + realname + idcard + cardnum + bankPreMobile + tm + appkey)

拼接顺序固定,不含 + 号。这是 1104 签名错误码最常见的踩坑点。

步骤 3:md5 哈希

import hashlib
raw = "MALL001张三1101011990010112346222021234567890123138001380001700000000000your_appkey" sign = hashlib.md5(raw.encode()).hexdigest()
输出 32 位小写 hex 字符串

步骤 4:HTTP POST + sign 参数

POST /v1/bank/verify HTTP/1.1
Content-Type: application/x-www-form-urlencoded
mall_id=MALL001&realname=张三&idcard=110101199001011234&cardnum=6222021234567890123&bankPreMobile=13800138000&tm=1700000000000&sign=a1b2c3d4e5f6...

步骤 5:服务端验证

服务端用同样的参数 + 算法计算签名,与客户端传的 sign 对比:

一致 → 请求合法,处理业务

不一致 → 拒绝请求,返回 1104

四、5 个常见踩坑

坑 1:拼接顺序错

症状:返回 1104

原因:不是 mall_id + appkey + tm + 业务参数,而是 mall_id + 业务参数 + tm + appkey

修法:严格按官方文档顺序

坑 2:加了 + 号

症状:返回 1104

原因:字符串里把连接符 + 也算进去了

修法:只拼接值,不含 +

坑 3:tm 用了秒级

症状:返回 1107 时间戳不合法

原因:必须 13 位毫秒(1700000000000),不是 10 位秒(1700000000)

修法:

tm = str(int(time.time() * 1000))  # ✅ 13 位

坑 4:appkey 写在客户端代码里

症状:安全漏洞

原因:appkey 一旦泄露,别人可以伪造你的请求(盗刷余额、冒用身份)

修法:

❌ 客户端 JS 代码包含 appkey(任何浏览器都能看到源码)

❌ 公开仓库 commit 含 appkey

✅ appkey 只存在服务端,客户端只调自己服务端接口,服务端再加签

坑 5:tm 时间窗口太宽

症状:重放攻击成功

原因:服务端允许 ±30 分钟内的请求 → 攻击者截获请求后 30 分钟内可重放

修法:

服务端时间窗口收紧到 ±5 分钟

配合 nonce(随机数)防重放

五、与 HTTPS 的关系

维度HTTPSAPI 签名解决什么问题加密传输防篡改 + 防重放 + 防冒用关键依赖SSL/TLS 证书appkey(签名密钥) 性能开销较大(TLS 握手)很小(一次 md5) 是否必须必须(传输安全)强烈推荐(业务安全)

两者不是替代关系,而是互补关系。HTTPS 保证传输安全,签名保证请求完整性。

六、签名机制的局限

不能防所有攻击:服务端代码漏洞(注入、越权)依然需要做业务层防御

md5 不是密码学最强:在 API 签名场景足够(防篡改);但密码存储应使用 bcrypt / argon2

appkey 是"共享密钥":更高级的安全场景用 OAuth 2.0 + JWT,但 99% 的 B 端 API 用 md5 签名足够

七、3 个安全最佳实践

1. appkey 定期轮换

每 3-6 个月轮换一次 appkey

控制台提供"轮换"按钮,新老 appkey 共存一段时间

2. IP 白名单

在控制台配置 appkey 允许的调用 IP 段

防止 appkey 泄露后被任意 IP 调用

3. 调用频率限制

单 mall_id 每秒调用次数限制

防止余额被一次性刷完

关于诺正通

诺正通 API 采用统一签名机制:md5(mall_id + 业务参数 + tm + appkey)。支持 IP 白名单、appkey 轮换、调用频率限制 3 种安全策略。 100 次免费试用,按量计费,具体价格请联系商务。

联系试用

试用入口:(100 次免费)

技术支持:service@nztapi.com

API 签名机制一篇讲透:md5 签名 + mall_id + tm + appkey 的安全原理