密码学与证书 / 系统课时

使用 HMAC 保护接口完整性

使用 HMAC 保护接口完整性

假设你的系统接收第三方支付回调:

json
{
  "orderId": "10001",
  "amount": 100,
  "status": "SUCCESS"
}

服务端必须判断两件事:

  1. 内容有没有被修改;
  2. 请求是不是知道共享密钥的可信方发来的。

只做 SHA-256 不够,因为攻击者也会算 SHA-256。

这时就可以理解 HMAC 的价值。

HMAC 比普通 Hash 多了一份秘密

普通 Hash:

text
message
   ↓
SHA-256
   ↓
digest

HMAC:

text
message + secret key
        ↓
       HMAC
        ↓
       mac

发送方和接收方持有同一把共享密钥。

攻击者即使知道算法和消息,也缺少 secret,无法轻易生成合法 MAC。

API 请求使用 HMAC 认证的完整链路

HMAC 不是简单的 Hash(secret + message)

不要自己发明:

text
SHA256(secret + body)

或者:

text
SHA256(body + secret)

标准 HMAC 有明确构造方式,用来避免一些直接拼接方案的安全问题。

工程中直接使用成熟库:

java
Mac mac = Mac.getInstance("HmacSHA256");

不要自己重新实现 HMAC 内部结构。

真正难的是“签什么”

很多接口验签失败并不是 HMAC 算法问题,而是双方消息不一致。

例如到底签:

text
amount=100&orderId=10001

还是:

text
orderId=10001&amount=100

结果完全不同。

所以接口需要先定义 canonical string,也就是规范化后的待认证文本。

例如:

text
POST
/api/payment/callback
1700000000
abc123
SHA256(body)

再对这份稳定数据做 HMAC。

为什么要加入 timestamp 和 nonce

如果只签 body:

text
HMAC(secret, body)

攻击者截获一条完全合法的请求后,可能原样发送第二次。

HMAC 仍然正确。

所以防重放通常还会加入:

text
timestamp
nonce / requestId

并让它们一起参与 MAC。

服务端验证时:

text
先检查时间窗口
     ↓
检查 nonce 是否已使用
     ↓
重新计算 HMAC
     ↓
常量时间比较
     ↓
进入业务幂等检查

注意最后还有业务幂等。

密码认证不能代替订单状态机。

一个最小 Java 示例

java
Mac mac = Mac.getInstance("HmacSHA256");
SecretKeySpec key = new SecretKeySpec(
    secret,
    "HmacSHA256"
);
mac.init(key);

byte[] result = mac.doFinal(
    canonical.getBytes(StandardCharsets.UTF_8)
);

然后双方约定将结果编码成:

text
HEX

或:

text
Base64

编码方式也必须进入协议。

不要用普通字符串比较敏感认证值

验证 MAC 时,不建议自己做过早退出的逐字符比较。

应该使用密码库提供的适合比较固定长度认证值的方法,避免比较耗时随第一个不同位置发生明显变化。

在 Java 里可以使用:

java
MessageDigest.isEqual(expected, actual)

共享密钥模型适合什么场景

HMAC 很适合:

text
两个服务已经安全共享 secret

例如某些支付接口、内部服务或 webhook。

但如果要让很多不同组织验证同一个发送方,而又不希望把同一份秘密分发给所有人,公私钥数字签名往往更合适。

因为 HMAC 验证方也拥有同一把 secret,理论上验证方同样具备生成合法 HMAC 的能力。

本课小结

HMAC 用共享秘密为消息提供完整性和来源认证。真正的工程难点不只是 HmacSHA256 API,而是规范化待签名数据、密钥管理、时间戳、Nonce、防重放以及稳定编码。

普通 SHA-256 不能替代 HMAC,自行设计 hash(secret + message) 也不是正确替代方案。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

使用 HMAC 保护接口完整性

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通