hmac —- 基于密钥的消息验证

Source code:Lib/hmac.py

This module implements the HMAC algorithm as described by RFC 2104.

• hmac.new(key, msg=None, digestmod='')
• Return a new hmac object. key is a bytes or bytearray object giving thesecret key. If msg is present, the method call update(msg) is made.digestmod is the digest name, digest constructor or module for the HMACobject to use. It may be any name suitable to hashlib.new().Despite its argument position, it is required.

在 3.4 版更改: Parameter key can be a bytes or bytearray object.Parameter msg can be of any type supported by hashlib.Parameter digestmod can be the name of a hash algorithm.

Deprecated since version 3.4, will be removed in version 3.8: MD5 as implicit default digest for digestmod is deprecated.The digestmod parameter is now required. Pass it as a keywordargument to avoid awkwardness when you do not have an initial msg.

• hmac.digest(key, msg, digest)
• Return digest of msg for given secret key and digest. Thefunction is equivalent to HMAC(key, msg, digest).digest(), butuses an optimized C or inline implementation, which is faster for messagesthat fit into memory. The parameters key, msg, and digest havethe same meaning as in new().

CPython implementation detail, the optimized C implementation is only usedwhen digest is a string and name of a digest algorithm, which issupported by OpenSSL.

3.7 新版功能.

An HMAC object has the following methods:

• HMAC.update(msg)
• Update the hmac object with msg. Repeated calls are equivalent to asingle call with the concatenation of all the arguments:m.update(a); m.update(b) is equivalent to m.update(a + b).

在 3.4 版更改: Parameter msg can be of any type supported by hashlib.

• HMAC.digest()
• Return the digest of the bytes passed to the update() method so far.This bytes object will be the same length as the digest_size of the digestgiven to the constructor. It may contain non-ASCII bytes, including NULbytes.

警告

When comparing the output of digest() to an externally-supplieddigest during a verification routine, it is recommended to use thecompare_digest() function instead of the == operatorto reduce the vulnerability to timing attacks.

• HMAC.hexdigest()
• Like digest() except the digest is returned as a string twice thelength containing only hexadecimal digits. This may be used to exchange thevalue safely in email or other non-binary environments.

警告

When comparing the output of hexdigest() to an externally-supplieddigest during a verification routine, it is recommended to use thecompare_digest() function instead of the == operatorto reduce the vulnerability to timing attacks.

• HMAC.copy()
• Return a copy ("clone") of the hmac object. This can be used to efficientlycompute the digests of strings that share a common initial substring.

A hash object has the following attributes:

• HMAC.digest_size

• The size of the resulting HMAC digest in bytes.

• HMAC.block_size

• The internal block size of the hash algorithm in bytes.

3.4 新版功能.

• HMAC.name
• The canonical name of this HMAC, always lowercase, e.g. hmac-md5.

3.4 新版功能.

This module also provides the following helper function:

• hmac.comparedigest(_a, b)
• Return a == b. This function uses an approach designed to preventtiming analysis by avoiding content-based short circuiting behaviour,making it appropriate for cryptography. a and b must both be of thesame type: either str (ASCII only, as e.g. returned byHMAC.hexdigest()), or a bytes-like object.

注解

If a and b are of different lengths, or if an error occurs,a timing attack could theoretically reveal information about thetypes and lengths of a and b—but not their values.

3.3 新版功能.

参见

• Module hashlib
• The Python module providing secure hash functions.