## 📋 目录

- 一、工具类功能
- 二、所需环境
- 三、方法与调用示例（按需调用）
- 四、工具类源码（可直接复制）

## 一、工具类功能

给接口签名、Webhook 验签、令牌防篡改算 HMAC 并常量时间比对，支持 HmacMD5 到 HmacSHA512 四种算法，输出十六进制、Base64 或原始字节，新接入一律选 HmacSHA256。

## 二、所需环境

JDK 17或以上

## 三、方法与调用示例（按需调用）

🔢 **方法序号**：1

🎯 **方法用途**：
- 算 HmacMD5 并给小写十六进制串，输出固定 32 位
- 只为还在用 HmacMD5 的遗留系统保留，新接入别选它

🧩 **方法定义**：`public static String hmacMd5(String data, String key)`

🗣️ **入参解释**：`public static String hmacMd5(正文, 密钥)`

📤 **返回值解释**：`String`，32 位小写十六进制的 MAC

💡 **边界口径**：
- 正文与密钥都按 UTF-8 取字节，双方必须约定同一套编码
- 空正文是合法输入，只有 null 被拒绝
- 正文为 null 抛 `IllegalArgumentException`，密钥为 null 或空白同样抛
- MD5 已经不该再用于新签名方案，能用 SHA-256 就用 SHA-256

🧪 **方法示例**：
- `hmacMd5(BODY, SECRET)` 拿到 `d6dcbdcd2d45983d049e4e7003fc3b95`
- 正文传 null 抛 `待认证数据不能为null`
- 密钥给空白串抛 `密钥不能为null或空白`

---

🔢 **方法序号**：2

🎯 **方法用途**：
- 算 HmacSHA1 并给小写十六进制串，输出 40 位
- 部分开放平台的历史签名要求是它，新接入不选

🧩 **方法定义**：`public static String hmacSha1(String data, String key)`

🗣️ **入参解释**：`public static String hmacSha1(正文, 密钥)`

📤 **返回值解释**：`String`，40 位小写十六进制的 MAC

💡 **边界口径**：
- 与 `hmacMd5` 同一条路径，只是算法换成 `HmacSHA1`
- 参数校验、UTF-8 取字节、空正文合法这些口径完全一致

🧪 **方法示例**：
- `hmacSha1(BODY, SECRET)` 拿到 `61dfc9cbe98cfafc960917405584cfa91564b3fc`，长度 40

---

🔢 **方法序号**：3

🎯 **方法用途**：
- 算 HmacSHA256 并给小写十六进制串，新接入的推荐选择
- 接口签名、Webhook 校验、令牌防篡改都从它起步

🧩 **方法定义**：`public static String hmacSha256(String data, String key)`

🗣️ **入参解释**：`public static String hmacSha256(正文, 密钥)`

📤 **返回值解释**：`String`，64 位小写十六进制的 MAC

💡 **边界口径**：
- 等价于 `hmacHex(HMAC_SHA256, data, key)`，输出长度固定 64 位
- 同一输入反复计算结果稳定，可以拿它做缓存键与重放对比
- `Mac` 实例非线程安全，本类每次调用新建，可并发使用

🧪 **方法示例**：
- `hmacSha256(BODY, SECRET)` 拿到 `d237de3947138319e4b6d18eaca7d0e26a86816f95b9dd3e0eb6fa21482ea191`
- `hmacSha256("", SECRET)` 拿到 `2dadd0e065f61424af1a9e2ab71633c0e7bc6a18b34f06fd1da80ef0ca9e7150`，空正文照样出签名
- 上一步的空串签名再交给 `verifyHex` 验，拿到 `true`

---

🔢 **方法序号**：4

🎯 **方法用途**：
- 算 HmacSHA512 并给小写十六进制串，输出 128 位
- 对方协议点名要 SHA-512，或想要更长摘要时用

🧩 **方法定义**：`public static String hmacSha512(String data, String key)`

🗣️ **入参解释**：`public static String hmacSha512(正文, 密钥)`

📤 **返回值解释**：`String`，128 位小写十六进制的 MAC

💡 **边界口径**：
- 原始字节固定 64 个，编码成十六进制才是 128 位，签名字段要留够宽度
- 口径与其余具名入口一致，只是摘要更长

🧪 **方法示例**：
- `hmacSha512(BODY, SECRET)` 拿到 `823a8add31a9b58ea2ddf4ea4cdc318925b4aa853739715ff63c873787d43a373f8950506d61b858855a9dbb6050585f05ce01b36772fbf94e3516c2805940c4`
- `hmac("HmacSHA512", "payload-with-中文", "secret-key").length` 拿到 `64`

---

🔢 **方法序号**：5

🎯 **方法用途**：
- 指定算法名算 HMAC 出十六进制，算法名不必逐字对得上 JCA
- 配置项里存的常常是 `HMAC-SHA256`、`hmac_sha256` 这类产品名，靠它归一命中

🧩 **方法定义**：`public static String hmacHex(String algorithm, String data, String key)`

🗣️ **入参解释**：`public static String hmacHex(算法名, 正文, 密钥)`

📤 **返回值解释**：`String`，小写十六进制的 MAC

💡 **边界口径**：
- 归一规则是去首尾空白、转大写、去掉 `_` 与 `-`，四个算法的别名都能命中
- 别名表之外的名字抛 `IllegalArgumentException` 并列出支持范围，不做模糊猜测
- 算法名为 null 或空白同样抛异常
- 结果是稳定值，同一输入换台机器也算得一样

🧪 **方法示例**：
- `hmacHex(HmacUtils.HMAC_SHA256, BODY, SECRET)` 拿到 `d237de3947138319e4b6d18eaca7d0e26a86816f95b9dd3e0eb6fa21482ea191`
- `hmacHex("HMAC-SHA256", BODY, SECRET)` 也拿到 `d237de3947138319e4b6d18eaca7d0e26a86816f95b9dd3e0eb6fa21482ea191`
- `hmacHex("hmac_sha256", BODY, SECRET)` 同样拿到 `d237de3947138319e4b6d18eaca7d0e26a86816f95b9dd3e0eb6fa21482ea191`
- `hmacHex("SM4", BODY, SECRET)` 抛 `不支持的HMAC算法: SM4，仅支持 HmacMD5/HmacSHA1/HmacSHA256/HmacSHA512`
- `hmacHex("   ", BODY, SECRET)` 抛 `HMAC算法不能为null或空白`

---

🔢 **方法序号**：6

🎯 **方法用途**：
- 指定算法算 HMAC 并输出标准 Base64，含 padding
- 签名要放进 header 或 JSON 字段、嫌十六进制太长时用这一版

🧩 **方法定义**：`public static String hmacBase64(String algorithm, String data, String key)`

🗣️ **入参解释**：`public static String hmacBase64(算法名, 正文, 密钥)`

📤 **返回值解释**：`String`，标准 Base64 形态的 MAC

💡 **边界口径**：
- 与 `hmacHex` 是同一份字节的两种编码，长度约为十六进制的四分之三
- 出的是标准字母表；对方给 URL 安全或无 padding 的写法，验签侧仍然认
- 参数校验口径同 `hmacHex`

🧪 **方法示例**：
- `hmacBase64(HmacUtils.HMAC_SHA256, BODY, SECRET)` 拿到 `0jfeOUcTgxnkttGOrKfQ4mqGgW+Vud0+Drb6IUguoZE=`
- `verifyBase64(HmacUtils.HMAC_SHA512, BODY, SECRET, b64)` 拿到 `true`，b64 就是 `hmacBase64(HmacUtils.HMAC_SHA512, BODY, SECRET)` 的结果

---

🔢 **方法序号**：7

🎯 **方法用途**：
- 字节形态的十六进制出口，密钥含 `0x00` 与高字节也不失真
- 数据是已序列化的报文、文件内容时走这个入口，别先转成字符串

🧩 **方法定义**：`public static String hmacHex(String algorithm, byte[] data, byte[] key)`

🗣️ **入参解释**：`public static String hmacHex(算法名, 字节正文, 字节密钥)`

📤 **返回值解释**：`String`，小写十六进制的 MAC

💡 **边界口径**：
- 字节按原样进 MAC 计算，不做任何字符集解释
- 空密钥数组被拒：空密钥的 MAC 没有意义，不该静默算出一个值
- 正文是空数组则合法

🧪 **方法示例**：
- `hmacHex("HmacSHA256", raw, rawKey)` 拿到 `b759f847ecaa80661dc79a4a11012258261078bced6a4d27148041b96dac3632`，rawKey 是含 `0x00` 的四个字节
- `hmacHex("HmacSHA256", new byte[]{1}, new byte[0])` 抛 `密钥字节不能为null或空数组`
- 字符串入口 `hmacHex("HmacSHA256", "payload-with-中文", "secret-key")` 与字节入口比对，拿到 `true`

---

🔢 **方法序号**：8

🎯 **方法用途**：
- 字节形态的 Base64 出口，二进制内容要放进文本字段时用
- 密钥本身是字节数组的配置项走这一版

🧩 **方法定义**：`public static String hmacBase64(String algorithm, byte[] data, byte[] key)`

🗣️ **入参解释**：`public static String hmacBase64(算法名, 字节正文, 字节密钥)`

📤 **返回值解释**：`String`，标准 Base64 形态的 MAC

💡 **边界口径**：
- 与字节版 `hmacHex` 同一份字节，只是换了编码
- 校验口径与字节版 `hmacHex` 一致

🧪 **方法示例**：
- `hmacBase64("HmacSHA256", raw, rawKey)` 拿到 `t1n4R+yqgGYdx5pKEQEiWCYQeLztak0nFIBBuW2sNjI=`

---

🔢 **方法序号**：9

🎯 **方法用途**：
- 取 MAC 的原始字节，编码方式与后续派生自己决定
- 要把签名再拼进密钥派生、或自己转成别的编码时用

🧩 **方法定义**：`public static byte[] hmac(String algorithm, String data, String key)`

🗣️ **入参解释**：`public static byte[] hmac(算法名, 正文, 密钥)`

📤 **返回值解释**：`byte[]`，MAC 原始字节，SHA-256 是 32 个

💡 **边界口径**：
- 返回的数组与 `hmacHex`、`hmacBase64` 是同一份字节
- 数组可写可改，不想被下游改动就自己复制一份
- 字符串入口固定按 UTF-8 取字节

🧪 **方法示例**：
- `hmac(HmacUtils.HMAC_SHA256, BODY, SECRET)` 拿到 `32 字节`
- `hmacHex(HmacUtils.HMAC_SHA256, BODY, SECRET).length() == macBytes.length * 2` 拿到 `true`，两种出口同源

---

🔢 **方法序号**：10

🎯 **方法用途**：
- 字节形态取 MAC 原始字节，用于原始报文与文件内容
- 二进制协议要比字节签名时先用它拿值

🧩 **方法定义**：`public static byte[] hmac(String algorithm, byte[] data, byte[] key)`

🗣️ **入参解释**：`public static byte[] hmac(算法名, 字节正文, 字节密钥)`

📤 **返回值解释**：`byte[]`，MAC 原始字节

💡 **边界口径**：
- 与字符串入口取的是同一套 UTF-8 字节，两侧结果一致
- 空密钥数组抛 `IllegalArgumentException`，空正文数组合法

🧪 **方法示例**：
- `Arrays.equals(macBytes, stringPath)` 拿到 `true`，两个入口算出的是同一份 MAC

---

🔢 **方法序号**：11

🎯 **方法用途**：
- 校验十六进制 MAC，常量时间比较，忽略预期值的大小写与空白
- 对方给的签名可能是大写、可能带分组空格时用它，别直接比字符串

🧩 **方法定义**：`public static boolean verifyHex(String algorithm, String data, String key, String expectedHex)`

🗣️ **入参解释**：`public static boolean verifyHex(算法名, 正文, 密钥, 预期签名)`

📤 **返回值解释**：`boolean`，比对通过返回 `true`

💡 **边界口径**：
- 比的是解码后的字节，`d237…` 与 `D237…` 判成同一个签名
- 预期值里的空白会被剥掉，分组换行不影响判定；正文本身的空白不参与忽略
- 预期值是非法十六进制或长度为奇数时判不通过，返回 `false` 而不是抛异常
- 预期值为 null 或空白属参数问题，抛 `IllegalArgumentException`

🧪 **方法示例**：
- `verifyHex(HmacUtils.HMAC_SHA512, BODY, SECRET, HmacUtils.hmacHex(HmacUtils.HMAC_SHA512, BODY, SECRET).toUpperCase())` 拿到 `true`
- `verifyHex(HmacUtils.HMAC_SHA512, BODY + " ", SECRET, HmacUtils.hmacHex(HmacUtils.HMAC_SHA512, BODY, SECRET))` 拿到 `false`，正文多一个空格就判不过
- 预期值截成奇数长度 `d237de3` 时拿到 `false`
- 预期值传 null 抛 `预期MAC不能为null或空白`

---

🔢 **方法序号**：12

🎯 **方法用途**：
- 校验 Base64 MAC，标准与 URL 安全、有无需 padding、折行写法都能识别
- 网关把签名头折过行、前端给的串没补 `=` 时用这一版

🧩 **方法定义**：`public static boolean verifyBase64(String algorithm, String data, String key, String expectedBase64)`

🗣️ **入参解释**：`public static boolean verifyBase64(算法名, 正文, 密钥, 预期签名)`

📤 **返回值解释**：`boolean`，比对通过返回 `true`

💡 **边界口径**：
- 解码依次试标准、URL 安全、补 padding 三种写法，解开再比字节
- 三种写法都解不开就判不通过返回 `false`，不把网关错误记成系统故障
- 预期值为 null 或空白属参数问题，抛 `IllegalArgumentException`

🧪 **方法示例**：
- `verifyBase64(HmacUtils.HMAC_SHA512, BODY, SECRET, b64)` 标准形态拿到 `true`
- 同一个 MAC 换成 URL 安全且无 padding 的 `urlSafeNoPadding` 仍拿到 `true`
- 中间插了回车换行的 `folded` 也拿到 `true`
- 预期值是垃圾串时拿到 `false`

---

🔢 **方法序号**：13

🎯 **方法用途**：
- 直接比对 MAC 原始字节，二进制协议与自定义编码报文用
- 手里已经是 `byte[]` 时省掉再编码成字符串的一步

🧩 **方法定义**：`public static boolean verify(String algorithm, byte[] data, byte[] key, byte[] expectedMac)`

🗣️ **入参解释**：`public static boolean verify(算法名, 字节正文, 字节密钥, 预期字节)`

📤 **返回值解释**：`boolean`，字节完全一致返回 `true`

💡 **边界口径**：
- 用 `MessageDigest.isEqual` 常量时间比较，长度不同直接判不通过
- 预期字节为 null 返回 `false` 而不抛异常，这点与两个字符串版验签入口不同
- 正文与密钥的校验口径同 `hmac` 字节入口

🧪 **方法示例**：
- `verify(HmacUtils.HMAC_SHA256, BODY.getBytes(StandardCharsets.UTF_8), SECRET.getBytes(StandardCharsets.UTF_8), macBytes)` 拿到 `true`
- 预期字节传 null 拿到 `false`，不抛异常

## 四、工具类源码（可直接复制）

📦 评论区留言



给接口签名、Webhook 验签、令牌防篡改算 HMAC 并常量时间比对，支持 HmacMD5 到 HmacSHA512 四种算法，输出十六进制、Base64 或原始字节，新接入一律选 HmacSHA256。

接口签名Webhook验签，这个Java工具类13个方法常量时间比对

人工智能

基于JDK17的HMAC签名与验签工具类，支持HmacMD5至HmacSHA512四种算法，输出十六进制、Base64或原始字节。提供字符串与字节双入口，内置常量时间比对、算法名归一化及兼容性验签，推荐新系统采用HmacSHA256，适用于接口签名、Webhook验签及令牌防篡改。

JSON

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

接口签名Webhook验签，这个Java工具类13个方法常量时间比对-腾讯云开发者社区-腾讯云

接口签名Webhook验签，这个Java工具类13个方法常量时间比对

接口签名Webhook验签，这个Java工具类13个方法常量时间比对

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐