1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
|
:mod:`!hmac` --- Keyed-Hashing for Message Authentication
=========================================================
.. module:: hmac
:synopsis: Keyed-Hashing for Message Authentication (HMAC) implementation
.. moduleauthor:: Gerhard Häring <ghaering@users.sourceforge.net>
.. sectionauthor:: Gerhard Häring <ghaering@users.sourceforge.net>
**Source code:** :source:`Lib/hmac.py`
--------------
This module implements the HMAC algorithm as described by :rfc:`2104`.
The interface allows to use any hash function with a *fixed* digest size.
In particular, extendable output functions such as SHAKE-128 or SHAKE-256
cannot be used with HMAC.
.. function:: new(key, msg=None, digestmod)
Return a new hmac object. *key* is a bytes or bytearray object giving the
secret key. If *msg* is present, the method call ``update(msg)`` is made.
*digestmod* is the digest name, digest constructor or module for the HMAC
object to use. It may be any name suitable to :func:`hashlib.new`.
Despite its argument position, it is required.
.. versionchanged:: 3.4
Parameter *key* can be a bytes or bytearray object.
Parameter *msg* can be of any type supported by :mod:`hashlib`.
Parameter *digestmod* can be the name of a hash algorithm.
.. versionchanged:: 3.8
The *digestmod* argument is now required. Pass it as a keyword
argument to avoid awkwardness when you do not have an initial *msg*.
.. function:: digest(key, msg, digest)
Return digest of *msg* for given secret *key* and *digest*. The
function is equivalent to ``HMAC(key, msg, digest).digest()``, but
uses an optimized C or inline implementation, which is faster for messages
that fit into memory. The parameters *key*, *msg*, and *digest* have
the same meaning as in :func:`~hmac.new`.
CPython implementation detail, the optimized C implementation is only used
when *digest* is a string and name of a digest algorithm, which is
supported by OpenSSL.
.. versionadded:: 3.7
An HMAC object has the following methods:
.. method:: HMAC.update(msg)
Update the hmac object with *msg*. Repeated calls are equivalent to a
single call with the concatenation of all the arguments:
``m.update(a); m.update(b)`` is equivalent to ``m.update(a + b)``.
.. versionchanged:: 3.4
Parameter *msg* can be of any type supported by :mod:`hashlib`.
.. method:: HMAC.digest()
Return the digest of the bytes passed to the :meth:`update` method so far.
This bytes object will be the same length as the *digest_size* of the digest
given to the constructor. It may contain non-ASCII bytes, including NUL
bytes.
.. warning::
When comparing the output of :meth:`digest` to an externally supplied
digest during a verification routine, it is recommended to use the
:func:`compare_digest` function instead of the ``==`` operator
to reduce the vulnerability to timing attacks.
.. method:: HMAC.hexdigest()
Like :meth:`digest` except the digest is returned as a string twice the
length containing only hexadecimal digits. This may be used to exchange the
value safely in email or other non-binary environments.
.. warning::
When comparing the output of :meth:`hexdigest` to an externally supplied
digest during a verification routine, it is recommended to use the
:func:`compare_digest` function instead of the ``==`` operator
to reduce the vulnerability to timing attacks.
.. method:: HMAC.copy()
Return a copy ("clone") of the hmac object. This can be used to efficiently
compute the digests of strings that share a common initial substring.
A hash object has the following attributes:
.. attribute:: HMAC.digest_size
The size of the resulting HMAC digest in bytes.
.. attribute:: HMAC.block_size
The internal block size of the hash algorithm in bytes.
.. versionadded:: 3.4
.. attribute:: HMAC.name
The canonical name of this HMAC, always lowercase, e.g. ``hmac-md5``.
.. versionadded:: 3.4
.. versionchanged:: 3.10
Removed the undocumented attributes ``HMAC.digest_cons``, ``HMAC.inner``,
and ``HMAC.outer``.
This module also provides the following helper function:
.. function:: compare_digest(a, b)
Return ``a == b``. This function uses an approach designed to prevent
timing analysis by avoiding content-based short circuiting behaviour,
making it appropriate for cryptography. *a* and *b* must both be of the
same type: either :class:`str` (ASCII only, as e.g. returned by
:meth:`HMAC.hexdigest`), or a :term:`bytes-like object`.
.. note::
If *a* and *b* are of different lengths, or if an error occurs,
a timing attack could theoretically reveal information about the
types and lengths of *a* and *b*—but not their values.
.. versionadded:: 3.3
.. versionchanged:: 3.10
The function uses OpenSSL's ``CRYPTO_memcmp()`` internally when
available.
.. seealso::
Module :mod:`hashlib`
The Python module providing secure hash functions.
|
