hmac — 消息认证的密钥哈希

**源代码:** Lib/hmac.py


此模块实现了 RFC 2104 中描述的 HMAC 算法。

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

返回一个新的 hmac 对象。*key* 是一个给出密钥的字节串或字节数组对象。如果提供了 *msg*,则会调用 update(msg) 方法。*digestmod* 是 HMAC 对象要使用的摘要名称、摘要构造函数或模块。它可以是任何适合 hashlib.new() 的名称。尽管它是可选参数,但它是必需的。

在 3.4 版更改: 参数 *key* 可以是字节串或字节数组对象。参数 *msg* 可以是 hashlib 支持的任何类型。参数 *digestmod* 可以是哈希算法的名称。

在 3.8 版更改: 现在需要 *digestmod* 参数。将其作为关键字参数传递,以避免在没有初始 *msg* 时出现尴尬。

hmac.digest(key, msg, digest)

返回给定密钥 *key* 和 *digest* 的 *msg* 的摘要。该函数等效于 HMAC(key, msg, digest).digest(),但使用优化的 C 或内联实现,这对于适合内存的消息来说速度更快。参数 *key*、*msg* 和 *digest* 的含义与 new() 中的相同。

CPython 实现细节,优化的 C 实现仅在 *digest* 是字符串且是 OpenSSL 支持的摘要算法名称时使用。

3.7 版新增。

HMAC 对象具有以下方法

HMAC.update(msg)

使用 *msg* 更新 hmac 对象。重复调用等效于使用所有参数的串联进行一次调用:m.update(a); m.update(b) 等效于 m.update(a + b)

在 3.4 版更改: 参数 *msg* 可以是 hashlib 支持的任何类型。

HMAC.digest()

返回到目前为止传递给 update() 方法的字节串的摘要。此字节串对象的长度将与传递给构造函数的摘要的 *digest_size* 相同。它可能包含非 ASCII 字节,包括 NUL 字节。

警告

在验证例程期间将 digest() 的输出与外部提供的摘要进行比较时,建议使用 compare_digest() 函数而不是 == 运算符,以减少计时攻击的漏洞。

HMAC.hexdigest()

digest() 类似,但摘要以字符串形式返回,其长度是原来的两倍,并且只包含十六进制数字。这可以用于在电子邮件或其他非二进制环境中安全地交换值。

警告

在验证例程期间将 hexdigest() 的输出与外部提供的摘要进行比较时,建议使用 compare_digest() 函数而不是 == 运算符,以减少计时攻击的漏洞。

HMAC.copy()

返回 hmac 对象的副本(“克隆”)。这可以用于有效地计算共享公共初始子字符串的字符串的摘要。

哈希对象具有以下属性

HMAC.digest_size

生成的 HMAC 摘要的大小,以字节为单位。

HMAC.block_size

哈希算法的内部块大小,以字节为单位。

3.4 版新增。

HMAC.name

此 HMAC 的规范名称,始终为小写,例如 hmac-md5

3.4 版新增。

在 3.10 版更改: 删除了未记录的属性 HMAC.digest_consHMAC.innerHMAC.outer

此模块还提供以下辅助函数

hmac.compare_digest(a, b)

返回 a == b。此函数使用一种旨在通过避免基于内容的短路行为来防止计时分析的方法,使其适用于加密。ab 必须是相同的类型:str(仅限 ASCII,例如 HMAC.hexdigest() 返回的类型),或 类字节对象

注意

如果 ab 的长度不同,或者发生错误,则理论上计时攻击可以揭示有关 ab 的类型和长度的信息,但不能揭示它们的值。

3.3 版新增。

在 3.10 版更改: 该函数在可用时在内部使用 OpenSSL 的 CRYPTO_memcmp()

另请参阅

模块 hashlib

提供安全哈希函数的 Python 模块。