15.2. "hmac" --- 基于密钥的消息验证
***********************************

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

======================================================================

此模块实现了 HMAC 算法，算法的描述参见 **RFC 2104**。

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

   返回一个新的 hmac 对象。 *key* 是一个指定密钥的 bytes 或 bytearray
   对象。 如果提供了 *msg*，将会调用 "update(msg)" 方法。 *digestmod*
   为 HMAC 对象要使用的摘要名称、摘要构造器或模块。 它支持任何适用于
   "hashlib.new()" 的名称并默认设为 "hashlib.md5" 构造器。

   3.4 版更變: 形参 *key* 可以为 bytes 或 bytearray 对象。 形参 *msg*
   可以为 "hashlib" 所支持的任意类型。 形参 *digestmod* 可以为某种哈希
   算法的名称。

   3.4 版後已棄用: MD5 作为 *digestmod* 的隐式默认摘要已被弃用。

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 对象的副本（“克隆）。 这可被用来高效地计算共享相同初始子
   串的数据的摘要。

hash 对象具有以下属性：

HMAC.digest_size

   以字节表示的结果 HMAC 摘要的大小。

HMAC.block_size

   以字节表示的哈希算法的内部块大小。

   3.4 版新加入.

HMAC.name

   HMAC 的规范名称，总是为小写形式，例如 "hmac-md5"。

   3.4 版新加入.

这个模块还提供了下列辅助函数:

hmac.compare_digest(a, b)

   返回 "a == b"。 此函数使用一种经专门设计的方式通过避免基于内容的短
   路行为来防止定时分析，使得它适合处理密码。 *a* 和 *b* 必须为相同的
   类型：或者是 "str" (仅限 ASCII 字符，如 "HMAC.hexdigest()" 的返回值
   )，或者是 *bytes-like object*。

   備註:

     如果 *a* 和 *b* 具有不同的长度，或者如果发生了错误，定时攻击在理
     论上可以获取有关 *a* 和 *b* 的类型和长度信息 — 但不能获取它们的值
     。

   3.3 版新加入.

也參考:

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