Python 库手册：hmac 消息摘要认证模块|hmac|key|sha1|token|密钥|算法|认证模块

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 对象中追加消息。

参数：