架构与系统设计 / 系统课时
请求签名设计
请求签名设计
本课完成一套可落地的开放接口签名方案:把请求方法、路径、排序后的参数、请求体摘要和防重放字段规范化,再使用 HMAC-SHA256 生成签名,服务端按同样规则验证请求是否被篡改。
学习目标
- 能定义稳定、无歧义的待签名字符串
- 能实现参数排序、请求体摘要和 HMAC-SHA256 签名
- 能按正确顺序完成服务端验签并处理边界情况
签名边界与字段
签名必须覆盖会影响业务结果的请求内容。推荐将 HTTP 方法、请求路径、查询参数、请求体摘要、时间戳、随机串和请求编号全部纳入签名,并通过请求头传递 X-Timestamp、X-Nonce、X-Request-Id 与 X-Signature。
密钥不应直接参与字符串拼接。客户端与平台保存同一份商户密钥,使用 HMAC 计算消息认证码。这样既能发现参数被修改,也避免把密钥暴露在请求中。
规范化待签名字符串
不同语言对 Map 顺序、空格、字符编码和 JSON 序列化的处理可能不同,因此必须先定义规范化规则。以下方案使用 UTF-8,查询参数按名称升序排列,名称和值采用 RFC 3986 百分号编码,请求体先计算 SHA-256 十六进制摘要。
待签名字符串固定为七行,字段缺失时也要按协议填入空字符串,不能擅自删除行:
HTTP_METHOD
REQUEST_PATH
CANONICAL_QUERY
BODY_SHA256
TIMESTAMP
NONCE
REQUEST_ID
Java 主示例
下面的程序可直接使用 JDK 17 编译运行。示例使用固定输入,便于客户端与服务端对照测试;生产环境中的时间戳、随机串、请求编号和密钥必须动态生成或从安全配置读取。
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.Base64;
import java.util.Map;
import java.util.TreeMap;
import java.util.stream.Collectors;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
public class RequestSignatureDemo {
private static final String HMAC_ALGORITHM = "HmacSHA256";
public static void main(String[] args) throws Exception {
String method = "POST";
String path = "/open-api/v1/payments";
Map<String, String> query = Map.of(
"merchantNo", "M10001",
"amount", "100.00",
"currency", "HKD"
);
String body = "{\"merchantOrderNo\":\"ORD202608030001\"}";
String timestamp = "1785754800";
String nonce = "n-7f3c9a";
String requestId = "req-20260803-0001";
String secret = "demo-secret-key";
// 查询参数排序和编码必须与服务端协议完全一致
String canonicalQuery = canonicalQuery(query);
// 请求体按原始 UTF-8 内容摘要,避免重新序列化
String bodySha256 = sha256Hex(body);
String canonicalString = String.join("\n",
method, path, canonicalQuery, bodySha256,
timestamp, nonce, requestId);
String signature = sign(canonicalString, secret);
boolean verified = verify(canonicalString, secret, signature);
System.out.println("canonicalQuery=" + canonicalQuery);
System.out.println("bodySha256=" + bodySha256);
System.out.println("signature=" + signature);
System.out.println("verified=" + verified);
}
private static String canonicalQuery(Map<String, String> query) {
return new TreeMap<>(query).entrySet().stream()
.map(e -> encode(e.getKey()) + "=" + encode(e.getValue()))
.collect(Collectors.joining("&"));
}
private static String encode(String value) {
return URLEncoder.encode(value, StandardCharsets.UTF_8)
.replace("+", "%20")
.replace("%7E", "~");
}
private static String sha256Hex(String value) throws Exception {
byte[] digest = MessageDigest.getInstance("SHA-256")
.digest(value.getBytes(StandardCharsets.UTF_8));
return java.util.HexFormat.of().formatHex(digest);
}
private static String sign(String content, String secret) throws Exception {
Mac mac = Mac.getInstance(HMAC_ALGORITHM);
mac.init(new SecretKeySpec(
secret.getBytes(StandardCharsets.UTF_8), HMAC_ALGORITHM));
byte[] result = mac.doFinal(content.getBytes(StandardCharsets.UTF_8));
return Base64.getUrlEncoder().withoutPadding().encodeToString(result);
}
private static boolean verify(
String content, String secret, String receivedSignature) {
try {
byte[] expected = Base64.getUrlDecoder().decode(sign(content, secret));
byte[] received = Base64.getUrlDecoder().decode(receivedSignature);
// 恒定时间比较,避免逐字符比较泄露匹配位置
return MessageDigest.isEqual(expected, received);
} catch (Exception e) {
return false;
}
}
}预期输出
canonicalQuery=amount=100.00¤cy=HKD&merchantNo=M10001
bodySha256=5c1c99fa9727df89d19ead434ae2c5aa697cfce875605c55a7a3e97bf53c5006
signature=eWDMZUQFTalniP-DaZjVm4nRxtPPrltAecJrWX-HMZM
verified=true服务端验证流程
服务端先根据商户号加载有效密钥,再校验时间戳格式、请求编号和随机串是否合法,然后使用收到的原始请求体计算摘要并重建待签名字符串。最后使用恒定时间比较本地签名与请求签名,成功后才进入业务处理。
验签失败应统一返回认证错误,不要区分“密钥错误”“摘要错误”或“签名差一位”等细节。内部日志可以记录商户号、请求编号、算法版本和失败阶段,但不得记录完整密钥或完整签名原文。
关键边界
客户端与服务端必须对空值、重复查询参数、数组参数、路径末尾斜杠和 JSON 字段顺序达成一致。更稳妥的做法是签署收到的原始请求体字节,而不是服务端反序列化后重新生成 JSON。
签名算法要带版本号,例如请求头 X-Signature-Version: v1。密钥轮换时可让新旧密钥短暂并存,服务端优先验证当前密钥,再在受控期限内兼容上一版本。