架构与系统设计 / 系统课时

请求签名设计

请求签名设计

本课完成一套可落地的开放接口签名方案:把请求方法、路径、排序后的参数、请求体摘要和防重放字段规范化,再使用 HMAC-SHA256 生成签名,服务端按同样规则验证请求是否被篡改。

学习目标

  • 能定义稳定、无歧义的待签名字符串
  • 能实现参数排序、请求体摘要和 HMAC-SHA256 签名
  • 能按正确顺序完成服务端验签并处理边界情况

签名边界与字段

签名必须覆盖会影响业务结果的请求内容。推荐将 HTTP 方法、请求路径、查询参数、请求体摘要、时间戳、随机串和请求编号全部纳入签名,并通过请求头传递 X-Timestamp、X-Nonce、X-Request-Id 与 X-Signature。

密钥不应直接参与字符串拼接。客户端与平台保存同一份商户密钥,使用 HMAC 计算消息认证码。这样既能发现参数被修改,也避免把密钥暴露在请求中。

规范化待签名字符串

不同语言对 Map 顺序、空格、字符编码和 JSON 序列化的处理可能不同,因此必须先定义规范化规则。以下方案使用 UTF-8,查询参数按名称升序排列,名称和值采用 RFC 3986 百分号编码,请求体先计算 SHA-256 十六进制摘要。

待签名字符串固定为七行,字段缺失时也要按协议填入空字符串,不能擅自删除行:

text
HTTP_METHOD
REQUEST_PATH
CANONICAL_QUERY
BODY_SHA256
TIMESTAMP
NONCE
REQUEST_ID

请求签名生成与验证时序

Java 主示例

下面的程序可直接使用 JDK 17 编译运行。示例使用固定输入,便于客户端与服务端对照测试;生产环境中的时间戳、随机串、请求编号和密钥必须动态生成或从安全配置读取。

java
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;
        }
    }
}

预期输出

text
canonicalQuery=amount=100.00&currency=HKD&merchantNo=M10001
bodySha256=5c1c99fa9727df89d19ead434ae2c5aa697cfce875605c55a7a3e97bf53c5006
signature=eWDMZUQFTalniP-DaZjVm4nRxtPPrltAecJrWX-HMZM
verified=true

服务端验证流程

服务端先根据商户号加载有效密钥,再校验时间戳格式、请求编号和随机串是否合法,然后使用收到的原始请求体计算摘要并重建待签名字符串。最后使用恒定时间比较本地签名与请求签名,成功后才进入业务处理。

验签失败应统一返回认证错误,不要区分“密钥错误”“摘要错误”或“签名差一位”等细节。内部日志可以记录商户号、请求编号、算法版本和失败阶段,但不得记录完整密钥或完整签名原文。

关键边界

客户端与服务端必须对空值、重复查询参数、数组参数、路径末尾斜杠和 JSON 字段顺序达成一致。更稳妥的做法是签署收到的原始请求体字节,而不是服务端反序列化后重新生成 JSON。

签名算法要带版本号,例如请求头 X-Signature-Version: v1。密钥轮换时可让新旧密钥短暂并存,服务端优先验证当前密钥,再在受控期限内兼容上一版本。

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

目录与阅读设置

阅读设置

17

记录一个想法

请求签名设计

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

登录哪都通