用Java做HMAC签名验证解决API接口安全问题是我这两年做得最多的一件事。前阵子对接某开放平台的接口时对方文档里就一句话“所有请求需要携带X-Sign签名”我原以为很简单结果来来回回对了一下午最后才发现是待签名字符串拼接顺序不一致。这篇把HMAC实战里最关键的东西一次性说清楚从原理、完整代码到排查方法都有适合后端开发和对接口安全有需求的同学直接参考。尤其现在前后端分离、第三方接口对接已经成为标配能写出稳的签名验证代码等于给所有接口上了一道低成本保险。1. 为什么API签名验证要选HMAC1.1 从一次接口被刷的教训说起我之前维护过一个查询服务为了给内部前端快速上线接口直接暴露了前端通过账号密码登录后拿着token请求逻辑上看着没问题。结果有一天发现某个IP在半夜以每秒几十次的频率循环调用把数据库连接池都打满了。排查下来这个接口既没有做来源限制也没有做参数防篡改拿到URL就能无限请求。这类问题在真实项目里太常见了特别是团队多人协作、接口文档不完整的时候。接口一旦不设防轻则被第三方拿来当免费数据源重则被刷爆流量再严重一点攻击者构造恶意参数直接走业务流程可能造成真金白银的损失。签名验证并不是多高深的安全手段但它能解决两个非常基本的问题请求方的身份可信以及请求内容在传输过程中没有被篡改。那次事故之后我只要写接口就默认加一层签名验证哪怕只是内部服务之间的调用。因为很多安全设计都是等出事了才觉得该早点做签名验证属于“早做早省心”的东西实现成本很低但防线的价值很高。1.2 HMAC和普通MD5加盐有什么区别先说一个常见误用很多同学会直接MD5(secret timestamp body)把密钥和参数拼在一起算一个哈希。这种方案最大的问题是强度不够而且拼接顺序一旦被人猜出来攻击者就可以轻易构造伪签名。如果请求还是明文传输抓包之后把参数整理一下验证规则基本就暴露了。HMAC全称是Hash-based Message Authentication Code中文叫基于哈希的消息认证码。它不是简单地把密钥拼上去再哈希而是通过内部两轮异或和填充运算把密钥和消息组织成更规整的输入。这样做既能防止长度扩展攻击也能让相同消息在不同密钥下产生完全不同的摘要。用生活化的类比来说普通MD5加盐像是给行李箱贴了一张写了密码的字条HMAC则像是行李箱本身内置了一把需要密钥才能打开的锁。实际开发中HMAC比直接拼接加盐更值得用因为它是被广泛规范化的算法Java标准库直接支持HmacSHA256、HmacSHA1、HmacMD5等选择。我一般默认选HmacSHA256SHA1已经不建议使用MD5更不用说虽然性能快一点但安全性已经落后。对于绝大多数API签名场景HmacSHA256在性能和安全性之间是最平衡的选择。方案安全性实现复杂度推荐度明文参数无最低不推荐MD5拼接密钥存在长度扩展风险低谨慎使用HMAC-SHA256高低首选注意签名验证解决的是“请求是否来自持有密钥的人、请求内容是否被篡改”不是“传输数据是否加密”。如果接口涉及敏感数据签名验证和HTTPS应该同时使用不要用签名替代加密。2. 动手前的签名方案设计需要想清楚的三件事2.1 直接拿JDK原生实现还是用Spring封装很多人会问Spring Security里有没有现成的HMAC过滤器其实Spring Security的核心是认证授权HMAC签名验证这种轻量级场景我更推荐用JDK自带的javax.crypto.Mac类再基于Spring MVC的HandlerInterceptor或者Servlet的Filter做一层拦截。这样可控性更强也避免引入一堆不需要的安全框架依赖。Mac类是Java标准库提供的一个通用消息认证码实现初始化时传入算法名和密钥然后调用doFinal就能拿到签名摘要。整个过程不依赖第三方库不管项目是Spring Boot还是普通的Servlet应用甚至纯Java控制台程序都能用同一套代码。这也是我觉得HMAC作为API签名方案特别有生命力的原因几乎所有主流语言都有对应实现换语言对接时协议完全不会变。大团队如果已经有统一的安全网关那可以直接使用网关能力不必重复造轮子。但中小型项目里自己封装一个不到一百行的工具类性价比非常高。我习惯把签名工具类单独拎出来不让它耦合Spring的类这样单元测试好写以后移植到其他模块也方便。2.2 签名里要包含哪些参数身份、时间、内容签名不是越复杂越好但至少要覆盖请求的“身份、时间、内容”三个维度。身份用AppId标识时间用timestamp内容就是请求方法、路径、请求体。我还会再加一个nonce随机字符串用来配合防重放。AppId相当于账号告诉服务端这是谁在请求服务端根据AppId找到对应的Secret。timestamp签名时间服务端用它判断请求是否在有效窗口内。nonce一次性随机字符串服务端在窗口期内记录已使用过的nonce避免同一签名被重复提交。方法、路径、请求体把这些关键内容拼进待签名字符串确保URL或参数被篡改后签名对不上。把这些信息放在HTTP Header里有一个好处Header不会被网关、代理日志识别为业务参数一定程度上减少信息泄露。而且Header的取值是字符串拼接待签名字符串时不容易和请求参数混在一起。我在项目中使用的Header约定是X-App-Id、X-Timestamp、X-Nonce、X-Sign这个命名风格在主流开放平台中很常见双方对起来也方便。2.3 密钥从哪来AppId与Secret的配对关系服务端需要保存一份密钥表每一对AppId对应一个Secret。Secret不能随着请求传输只保存在服务端和请求方的配置中心或环境变量里。为什么要特意强调这一点因为签名验证的核心假设就是“Secret只有双方知道”一旦Secret通过明文请求体传出去攻击者抓包就能拿到签名形同虚设。生成Secret时我习惯用SecureRandom生成32字节随机值再转成64位十六进制字符串。这样生成的Secret长度均匀而且不依赖人肉记忆。即使某个AppId的Secret泄露也只会影响该调用方不会波及其他接口。线上环境还要定期更换具体方案我在后面讲密钥轮换时会展开。3. 完整代码实现从签名工具类到服务端校验3.1 封装HMAC签名工具类先给出最核心的工具类这个类不依赖Spring直接拷贝到任意Java项目都能用。代码里我选择了HmacSHA256同时做了Hex编码保证签名在HTTP传输中始终是可见的ASCII字符。import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec; import java.nio.charset.StandardCharsets; import java.security.MessageDigest; public class HmacUtil { private static final String HMAC_ALGORITHM HmacSHA256; private static final char[] HEX_CHARS 0123456789abcdef.toCharArray(); private HmacUtil() { } public static String sign(String data, String secret) { try { Mac mac Mac.getInstance(HMAC_ALGORITHM); SecretKeySpec keySpec new SecretKeySpec( secret.getBytes(StandardCharsets.UTF_8), HMAC_ALGORITHM); mac.init(keySpec); byte[] raw mac.doFinal(data.getBytes(StandardCharsets.UTF_8)); return toHex(raw); } catch (Exception e) { throw new IllegalStateException(HMAC-SHA256签名失败, e); } } public static boolean verify(String data, String secret, String sign) { if (sign null || sign.isEmpty()) { return false; } String expected sign(data, secret); // 使用MessageDigest.isEqual做常量时间比较避免简单equals带来的时序差异 return MessageDigest.isEqual( expected.getBytes(StandardCharsets.UTF_8), sign.getBytes(StandardCharsets.UTF_8)); } private static String toHex(byte[] bytes) { char[] chars new char[bytes.length * 2]; for (int i 0; i bytes.length; i) { int v bytes[i] 0xFF; chars[i * 2] HEX_CHARS[v 4]; chars[i * 2 1] HEX_CHARS[v 0x0F]; } return new String(chars); } }有几个细节值得单独说。第一MessageDigest.isEqual做的是字节比较长度不一致时也尽量保持耗时一致比直接用String.equals更安全。虽然API签名场景下攻击者很难利用时序差异但养成好习惯总没错。第二异常处理采用包装成IllegalStateException的方式因为初始化失败属于环境级错误没必要让上层业务继续执行。第三签名工具类只负责“用密钥算摘要”不负责“业务参数拼装”待签名字符串的拼装规则应该单独放在另一个类里这样双方按同一份协议文档对齐时会容易很多。3.2 请求端如何构造签名并发送请求假设现在我们是调用方要向某个开放接口发送创建订单的请求。需要提前把AppId、Secret配置好然后在构造请求时按约定生成签名。下面是一个基于java.net.http.HttpClient的完整示例。import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.nio.charset.StandardCharsets; import java.time.Duration; import java.util.UUID; public class ApiClient { private static final String APP_ID your-app-id; private static final String SECRET your-secret; private static final String BASE_URL http://localhost:8080; public static void main(String[] args) throws Exception { String path /api/v1/order; String method POST; String body {\productId\:\1001\,\quantity\:2}; long timestamp System.currentTimeMillis(); String nonce UUID.randomUUID().toString().replace(-, ); String raw method \n path \n timestamp \n nonce \n body; String sign HmacUtil.sign(raw, SECRET); HttpClient client HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(5)) .build(); HttpRequest request HttpRequest.newBuilder() .uri(URI.create(BASE_URL path)) .header(Content-Type, application/json) .header(X-App-Id, APP_ID) .header(X-Timestamp, String.valueOf(timestamp)) .header(X-Nonce, nonce) .header(X-Sign, sign) .POST(HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8)) .build(); HttpResponseString response client.send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body()); } }这段代码里有几个容易踩坑的地方。一个是待签名字符串里的换行符\n我建议统一用\n不要用系统默认的line.separator否则Windows和Linux上计算结果不一样。另一个是请求体的编码签名计算用的字符串必须和实际发送出去的字节完全一致所以我显式指定了StandardCharsets.UTF_8。还有一个容易忽略的点path字段要不要带Query参数如果带拼接前最好对URL参数做排序保证双方看到的是一串相同的字符。我在示例里去掉了Query参数是为了让核心逻辑更清晰真实项目里可以按需求扩展。3.3 服务端如何用拦截器完成签名校验服务端这边我选择Spring Boot的HandlerInterceptor来做签名校验它能在Controller方法执行前拦截请求并返回统一的业务错误码。下面这段代码展示了核心校验流程实际使用时需要把密钥存储、nonce存储替换成真实的配置和缓存实现。import org.springframework.web.servlet.HandlerInterceptor; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import java.nio.charset.StandardCharsets; public class SignatureInterceptor implements HandlerInterceptor { private static final long MAX_AGE_MILLIS 5 * 60 * 1000L; private final SecretService secretService; private final NonceService nonceService; public SignatureInterceptor(SecretService secretService, NonceService nonceService) { this.secretService secretService; this.nonceService nonceService; } Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { String appId request.getHeader(X-App-Id); String timestamp request.getHeader(X-Timestamp); String nonce request.getHeader(X-Nonce); String sign request.getHeader(X-Sign); if (appId null || timestamp null || nonce null || sign null) { throw new BizException(missing signature headers); } // 校验时间戳窗口 long ts Long.parseLong(timestamp); long now System.currentTimeMillis(); if (Math.abs(now - ts) MAX_AGE_MILLIS) { throw new BizException(timestamp expired); } // 校验nonce是否已使用 if (!nonceService.tryUseNonce(appId, nonce, MAX_AGE_MILLIS)) { throw new BizException(nonce reused); } // 查询AppId对应的Secret String secret secretService.getSecretByAppId(appId); if (secret null) { throw new BizException(invalid appId); } // 读取请求体 String body readBody(request); // 构造待签名字符串顺序必须与请求端完全一致 StringBuilder rawBuilder new StringBuilder(); rawBuilder.append(request.getMethod()).append(\n); rawBuilder.append(request.getRequestURI()).append(\n); rawBuilder.append(timestamp).append(\n); rawBuilder.append(nonce).append(\n); rawBuilder.append(body); boolean valid HmacUtil.verify(rawBuilder.toString(), secret, sign); if (!valid) { throw new BizException(signature mismatch); } return true; } private String readBody(HttpServletRequest request) throws Exception { // 这里需要注意request.getInputStream()只能读一次 // 推荐用ContentCachingRequestWrapper一次性包装读取 return new String(request.getInputStream().readAllBytes(), StandardCharsets.UTF_8); } }服务端校验的核心逻辑和请求端完全对称同样的header取出同样的拼接顺序同样的算法。只要任何一边多了一个空格、少了一个换行结果都会对不上。这也是我在代码里把待签名字符串的构造单独提取出来的原因因为它太容易被两端改着改着就不一致了。时间戳窗口我采用的是正负5分钟也就是说请求方的时钟和服务器时钟偏差比较大时签名会直接报过期。窗口不宜设得过大过大意味着被重放的攻击窗口也变大但也不能设得过小过小会导致正常用户的时钟偏差被误杀。5分钟是一个相对通用的行业默认值。nonce的过期时间应该和窗口保持一致演示中的tryUseNonce可以用Redis的SETNX结合过期时间实现保证同一nonce在窗口内只能成功一次。3.4 注册拦截器并测试完整链路有了拦截器还需要注册到Spring MVC中。可以写一个配置类实现WebMvcConfigurer把需要签名校验的URL路径匹配进去。我在实际项目中通常把签名校验范围限定在以/api/开头的地址内网管理接口则单独处理。import org.springframework.context.annotation.Configuration; import org.springframework.web.servlet.config.annotation.InterceptorRegistry; import org.springframework.web.servlet.config.annotation.WebMvcConfigurer; Configuration public class WebConfig implements WebMvcConfigurer { private final SecretService secretService; private final NonceService nonceService; public WebConfig(SecretService secretService, NonceService nonceService) { this.secretService secretService; this.nonceService nonceService; } Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(new SignatureInterceptor(secretService, nonceService)) .addPathPatterns(/api/**) .excludePathPatterns(/api/public/**); } }到这里请求端用HMAC生成签名、服务端校验签名、拦截器注册这三步已经形成了一条完整链路。你可以在本地启动一个Spring Boot服务再运行上面的ApiClient模拟调用几分钟就能跑通。第一次跑通时可以故意把timestamp或nonce改错一个字符再观察服务端返回的错误码这样会对签名校验的每个环节有更直观的理解。4. 常见问题与排查技巧实录4.1 签名对不上的五大原因签名验证最烦人的问题就是“我这边明明算出来的签名是对的服务端就是不认”。根据我处理过的对接反馈九成以上都能归结到下面几类。待签名字符串的顺序不一致。请求端和服务端拼接参数时的顺序不同只要有一项错位签名必然不同。这个问题在文档不全时特别常见建议在开发前先用一个简单文本把拼接规则写死不要靠口头约定。时间戳单位不一致。有的端用毫秒有的端用秒。如果服务端按毫秒解析而请求端传的是秒时间戳校验就直接失败。我习惯统一为毫秒并且在接口文档里明确写清楚。编码不一致。中文字符串或特殊字符在UTF-8和GBK下的字节序列不同算出的签名也不同。代码里务必统一使用StandardCharsets.UTF_8。大小写问题。Hex编码后的签名有大小写之分服务端和客户端如果一边小写一边大写也会校验失败。我统一使用小写因为小写更容易和日志里常见的十六进制串保持一致。请求体读取问题。服务端request.getInputStream()只能读一次如果在拦截器里读完之后Controller再读就会拿不到body。如果服务端把body拿来拼了签名后续业务还要继续读body就要使用包装Request的方式先行缓存。为了快速定位这类问题建议在服务端写一条临时日志打印收到的sign、计算出的expected_sign以及完整的待签名字符串。两边比对一下一眼就能看出差在哪里。这个方法比反复看代码高效很多。4.2 时间戳过期校验的正确姿势有的团队会把时间戳校验写成只允许往后偏移5分钟也就是只判断now - ts 300000结果忽略了请求方时钟比服务器快的情况。客户端本地时间不准时几乎无法调用成功。正确做法是使用绝对值判断Math.abs(now - ts) 300000。这样客户端时钟不管是快还是慢只要偏差在窗口内都能接受。还有一点容易被忽略校验完时间戳窗口之后别忘了把时间戳也纳入待签名字符串。如果签名时根本没带timestamp攻击者把请求头里的X-Timestamp改成一个大窗口内的新时间服务端校验时用的是新时间签名依然有效时间戳防重放就失去了意义。这里再补充一个容易被误伤的细节如果服务器是多实例部署实例间的系统时间可能存在秒级偏差。对签名校验来说5分钟窗口通常能覆盖这种偏差但如果某些实例上了云平台后开启了NTP但同步周期较长还是可能出现偶发过期。遇到这种问题第一反应不是改业务代码而是先检查所有实例的系统时间漂移情况。4.3 密钥定期轮换方案密钥长期不变泄露风险会随时间累积。比较简单的方案是给密钥表增加一个version字段请求端在Header里同时带上X-Version服务端根据version取出对应密钥进行校验。这样轮换时可以做灰度切换先让新版本密钥上线保留旧版本一段时间等所有调用方都切换到新密钥后再下线旧版本。轮换的关键是不能一刀切否则线上正在跑的请求会突然全部校验失败。我经历过一次比较紧张的场景某天夜里需要紧急更换一个调用方的密钥团队直接在服务端把旧密钥删了结果对方还缓存着旧值页面报错持续了十几分钟才被监测到。后来我调整成双密钥机制才彻底避免这类问题。密钥存储方面项目初期可以放在配置文件里但线上环境建议使用配置中心或密钥管理服务。原因很简单配置文件一旦被拉到开发环境密钥就可能随代码仓库泄露。而密钥管理服务可以做到按环境隔离、定时轮换、访问审计即使开发人员往往也只能看到脱敏后的值。5. 从能跑到好用进阶实践与避坑建议5.1 防重放攻击的nonce机制前面提到了nonce一次性校验严格来说没有nonce的HMAC签名只能防篡改不能防重放。什么意思攻击者把已经抓到的合法请求原样再发一次签名依然有效服务器依然会处理。如果这个请求是创建订单、扣减库存之类的写操作后果就会比较严重。加上nonce之后服务端记录一段时间内使用过的nonce同一个签名只能成功提交一次。我建议用Redis的SET key value EX seconds NX命令来实现先尝试写入如果返回成功说明nonce从未被使用过如果返回失败说明重复提交直接拒绝。Redis的原子性保证了并发场景下也不会出现同一个nonce被同时成功两次的情况。这个key的过期时间就设为时间戳窗口的时长比如5分钟窗口过了自动清理避免Redis内存被无限制占满。这里有一个细节nonce不需要加密它本身不承载密码学作用长度也不需要太长32位十六进制字符串已经足够。它只是配合timestamp一起完成“短期防重放”的手段。5.2 日志脱敏与排查便捷性怎么平衡线上排查签名问题时我们需要打印待签名字符串和签名结果但这些信息如果原样打到日志里等于把敏感数据和密钥间接暴露给了有日志权限的人。尤其是请求体里如果包含手机号、身份证号之类的敏感字段更要注意脱敏。我的做法是在默认日志级别下只打印appId、timestamp、nonce以及签名的前8位和后4位中间用星号代替。这样可以判断请求是否到达了服务端、时间戳是否正常又不会直接把完整敏感信息铺在日志中。真正的完整待签名字符串通过DEBUG级别日志输出并且生产环境默认关闭。如果某次需要彻底排查再临时把某个AppId的日志级别调整为DEBUG。日志也是双方对接时的重要依据。我建议服务端在返回签名错误时错误信息采用统一格式比如“signature mismatch: appIdxxx, expected-len64, actual-len63”这种风格让调用方一眼就能看出是长度不对还是内容不对减少来回沟通成本。5.3 多服务间共享密钥的安全隐患如果项目做了微服务拆分内部服务之间也需要互相调用很多人会图省事让所有服务共享一对AppId和Secret。这个方案最大的问题是一旦某个服务被攻破所有依赖关系的信任都会崩溃。更合理的做法是每个服务一个AppId在网关层维护一套服务间的密钥映射服务间调用时同样要走签名。内部服务的签名校验不必完全复用外部API那套逻辑。外部接口通常要校验时间戳和nonce内部服务之间因为网络环境相对可控时间戳窗口可以适当放宽甚至可以只做签名校验不做nonce。但至少要把“来源服务身份”验证做起来不然一旦某个服务能直接请求另一个服务的内网接口整个链路就失去了隔离性。如果技术栈允许服务间通信还可以考虑更底层的双向认证让每个服务持有独立证书。这是一个比HMAC更强的手段但配置成本和运维复杂度也更高。我一般的判断标准是如果服务间只是低风险接口HMAC签名足够如果涉及资金、批量导出等高危接口建议叠加双向认证。5.4 我踩过的坑和现在默认遵守的三条约定第一所有参与签名的字段都用\n分隔不用空格、逗号或者其他容易混淆的符号。第二Hex编码统一小写不管对方代码里怎么写的我这边负责兼容但前提是文档里写明。第三任何Signature相关的常量类都不允许用枚举去表达算法名因为很多人会把枚举的name()和算法串搞混导致实际使用到错误的算法标识生成签名。这三年里我照着这套方案对接过不少外部开放平台也帮同事排过很多签名错误最后发现真正出问题的场景并不在算法本身而在于编码、顺序、字段遗漏这些细节。HMAC的好处正是它的实现标准且简单一旦约定对齐调试成本就会非常低。如果你也在做API签名验证希望这篇内容能帮你少走一点弯路。