Python 库手册：hmac 消息摘要认证模块

hmac（Hash-based Message Authentication Code）模块用于生成消息认证码（MAC），以确保数据完整性和身份验证安全性。它结合了哈希算法（如 MD5、SHA256）和密钥，防止数据在传输过程中被篡改，是构建安全通信协议的重要工具。

常见应用场景：

（1）网络请求签名验证（如 API 请求）。

（2）用户数据校验（如 cookie 签名）。

（3）消息认证与防篡改机制。

（4）实现 HMAC-based 身份认证协议（如 OAuth、JWT）。

◆ ◆ ◆

核心概念

1、HMAC 原理

将消息（message）与密钥（key）混合，再使用哈希算法生成摘要。即使内容一致，不同密钥也会产生不同结果。

2、不可逆 + 加盐

在哈希的基础上引入密钥（即“盐”），增强安全性并防止“哈希碰撞攻击”。

3、支持多种哈希算法

如 md5, sha1, sha256, sha512 等，底层基于 hashlib。

4、安全比较函数

hmac.compare_digest() 用于避免时序攻击，推荐用于密钥/摘要比对。

◆ ◆ ◆

应用举例

例 1：生成 HMAC 签名（默认使用 sha256）

import hmac
import hashlib

key = b'secret_key'
message = b'hello world'

signature = hmac.new(key, message, hashlib.sha256).hexdigest()
print("HMAC 签名（sha256）：", signature)

例 2：验证两个 HMAC 是否一致（安全比较）

import hmac
import hashlib

key = b'secret_key'
msg = b'hello world'

sig1 = hmac.new(key, msg, hashlib.sha256).digest()
sig2 = hmac.new(key, msg, hashlib.sha256).digest()

print("签名一致：" , hmac.compare_digest(sig1, sig2))

例 3：使用 sha1 生成较短签名

import hashlib

key = b'key123'
msg = b'important message'

signature = hmac.new(key, msg, hashlib.sha1).hexdigest()
print("HMAC 签名（sha1）：", signature)

例 4：HMAC 用于 Webhook 签名验证

import hmac
import hmac
import hashlib

def is_valid_signature(secret, message, signature):
    mac = hmac.new(secret.encode(), message.encode(), hashlib.sha256)
    return hmac.compare_digest(mac.hexdigest(), signature)

# 示例参数
msg = 'event=data'
secret = 'webhook_key'
sig = hmac.new(secret.encode(), msg.encode(), hashlib.sha256).hexdigest()

print("签名验证结果：", is_valid_signature(secret, msg, sig))

例 5：将 HMAC 签名用于 token 加密存储

import hmac
import hashlib
import base64

key = b'session_secret'
token = b'user_id=1001&exp=2025-12-31'

signature = hmac.new(key, token, hashlib.sha256).digest()
token_with_sig = token + b"." + base64.urlsafe_b64encode(signature)

print("带签名的 token：", token_with_sig.decode())

◆ ◆ ◆

常用函数速览

hmac.new(key, msg=None, digestmod=None)

创建一个新的 HMAC 对象。

参数：

key：密钥（bytes 类型）

msg：要加密的消息（可选，bytes 类型）

digestmod：哈希算法函数，如 hashlib.sha256

返回：HMAC 对象（支持 .update()、.digest()、.hexdigest()）

HMAC.update(msg)

向当前 HMAC 对象中追加消息。

参数：

msg：追加的消息内容（bytes 类型）

返回：无

HMAC.digest()

返回二进制格式的 HMAC 摘要。

参数：无

返回：bytes 类型

HMAC.hexdigest()

返回十六进制字符串形式的 HMAC 摘要。

参数：无

返回：str 类型

hmac.compare_digest(a, b)

安全比较两个摘要，防止时序攻击。

参数：

a, b：两个 bytes 或 str 对象

返回：bool 类型，内容相同为 True，否则 False

◆ ◆ ◆

补充说明

1、HMAC 摘要是不可逆的，仅用于验证而非还原原始消息。

2、HMAC 的安全性依赖于密钥的保密性与哈希算法的抗碰撞能力。

3、与对称加密不同，HMAC 不会加密内容，只生成认证签名。

“点赞有美意，赞赏是鼓励”