diff options
Diffstat (limited to 'devdocs/python~3.12/library%2Fhmac.html')
| -rw-r--r-- | devdocs/python~3.12/library%2Fhmac.html | 40 |
1 files changed, 40 insertions, 0 deletions
diff --git a/devdocs/python~3.12/library%2Fhmac.html b/devdocs/python~3.12/library%2Fhmac.html new file mode 100644 index 00000000..b0f44294 --- /dev/null +++ b/devdocs/python~3.12/library%2Fhmac.html @@ -0,0 +1,40 @@ + <span id="hmac-keyed-hashing-for-message-authentication"></span><h1>hmac — Keyed-Hashing for Message Authentication</h1> <p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Lib/hmac.py">Lib/hmac.py</a></p> <p>This module implements the HMAC algorithm as described by <span class="target" id="index-0"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2104.html"><strong>RFC 2104</strong></a>.</p> <dl class="py function"> <dt class="sig sig-object py" id="hmac.new"> +<code>hmac.new(key, msg=None, digestmod)</code> </dt> <dd> +<p>Return a new hmac object. <em>key</em> is a bytes or bytearray object giving the secret key. If <em>msg</em> is present, the method call <code>update(msg)</code> is made. <em>digestmod</em> is the digest name, digest constructor or module for the HMAC object to use. It may be any name suitable to <a class="reference internal" href="hashlib#hashlib.new" title="hashlib.new"><code>hashlib.new()</code></a>. Despite its argument position, it is required.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.4: </span>Parameter <em>key</em> can be a bytes or bytearray object. Parameter <em>msg</em> can be of any type supported by <a class="reference internal" href="hashlib#module-hashlib" title="hashlib: Secure hash and message digest algorithms."><code>hashlib</code></a>. Parameter <em>digestmod</em> can be the name of a hash algorithm.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.8: </span>The <em>digestmod</em> argument is now required. Pass it as a keyword argument to avoid awkwardness when you do not have an initial <em>msg</em>.</p> </div> </dd> +</dl> <dl class="py function"> <dt class="sig sig-object py" id="hmac.digest"> +<code>hmac.digest(key, msg, digest)</code> </dt> <dd> +<p>Return digest of <em>msg</em> for given secret <em>key</em> and <em>digest</em>. The function is equivalent to <code>HMAC(key, msg, digest).digest()</code>, but uses an optimized C or inline implementation, which is faster for messages that fit into memory. The parameters <em>key</em>, <em>msg</em>, and <em>digest</em> have the same meaning as in <a class="reference internal" href="#hmac.new" title="hmac.new"><code>new()</code></a>.</p> <p>CPython implementation detail, the optimized C implementation is only used when <em>digest</em> is a string and name of a digest algorithm, which is supported by OpenSSL.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.7.</span></p> </div> </dd> +</dl> <p>An HMAC object has the following methods:</p> <dl class="py method"> <dt class="sig sig-object py" id="hmac.HMAC.update"> +<code>HMAC.update(msg)</code> </dt> <dd> +<p>Update the hmac object with <em>msg</em>. Repeated calls are equivalent to a single call with the concatenation of all the arguments: <code>m.update(a); m.update(b)</code> is equivalent to <code>m.update(a + b)</code>.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.4: </span>Parameter <em>msg</em> can be of any type supported by <a class="reference internal" href="hashlib#module-hashlib" title="hashlib: Secure hash and message digest algorithms."><code>hashlib</code></a>.</p> </div> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="hmac.HMAC.digest"> +<code>HMAC.digest()</code> </dt> <dd> +<p>Return the digest of the bytes passed to the <a class="reference internal" href="#hmac.HMAC.update" title="hmac.HMAC.update"><code>update()</code></a> method so far. This bytes object will be the same length as the <em>digest_size</em> of the digest given to the constructor. It may contain non-ASCII bytes, including NUL bytes.</p> <div class="admonition warning"> <p class="admonition-title">Warning</p> <p>When comparing the output of <a class="reference internal" href="#hmac.digest" title="hmac.digest"><code>digest()</code></a> to an externally supplied digest during a verification routine, it is recommended to use the <a class="reference internal" href="#hmac.compare_digest" title="hmac.compare_digest"><code>compare_digest()</code></a> function instead of the <code>==</code> operator to reduce the vulnerability to timing attacks.</p> </div> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="hmac.HMAC.hexdigest"> +<code>HMAC.hexdigest()</code> </dt> <dd> +<p>Like <a class="reference internal" href="#hmac.digest" title="hmac.digest"><code>digest()</code></a> 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.</p> <div class="admonition warning"> <p class="admonition-title">Warning</p> <p>When comparing the output of <a class="reference internal" href="#hmac.HMAC.hexdigest" title="hmac.HMAC.hexdigest"><code>hexdigest()</code></a> to an externally supplied digest during a verification routine, it is recommended to use the <a class="reference internal" href="#hmac.compare_digest" title="hmac.compare_digest"><code>compare_digest()</code></a> function instead of the <code>==</code> operator to reduce the vulnerability to timing attacks.</p> </div> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="hmac.HMAC.copy"> +<code>HMAC.copy()</code> </dt> <dd> +<p>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.</p> </dd> +</dl> <p>A hash object has the following attributes:</p> <dl class="py attribute"> <dt class="sig sig-object py" id="hmac.HMAC.digest_size"> +<code>HMAC.digest_size</code> </dt> <dd> +<p>The size of the resulting HMAC digest in bytes.</p> </dd> +</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="hmac.HMAC.block_size"> +<code>HMAC.block_size</code> </dt> <dd> +<p>The internal block size of the hash algorithm in bytes.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.4.</span></p> </div> </dd> +</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="hmac.HMAC.name"> +<code>HMAC.name</code> </dt> <dd> +<p>The canonical name of this HMAC, always lowercase, e.g. <code>hmac-md5</code>.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.4.</span></p> </div> </dd> +</dl> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.10: </span>Removed the undocumented attributes <code>HMAC.digest_cons</code>, <code>HMAC.inner</code>, and <code>HMAC.outer</code>.</p> </div> <p>This module also provides the following helper function:</p> <dl class="py function"> <dt class="sig sig-object py" id="hmac.compare_digest"> +<code>hmac.compare_digest(a, b)</code> </dt> <dd> +<p>Return <code>a == b</code>. This function uses an approach designed to prevent timing analysis by avoiding content-based short circuiting behaviour, making it appropriate for cryptography. <em>a</em> and <em>b</em> must both be of the same type: either <a class="reference internal" href="stdtypes#str" title="str"><code>str</code></a> (ASCII only, as e.g. returned by <a class="reference internal" href="#hmac.HMAC.hexdigest" title="hmac.HMAC.hexdigest"><code>HMAC.hexdigest()</code></a>), or a <a class="reference internal" href="../glossary#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a>.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>If <em>a</em> and <em>b</em> are of different lengths, or if an error occurs, a timing attack could theoretically reveal information about the types and lengths of <em>a</em> and <em>b</em>—but not their values.</p> </div> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.3.</span></p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.10: </span>The function uses OpenSSL’s <code>CRYPTO_memcmp()</code> internally when available.</p> </div> </dd> +</dl> <div class="admonition seealso"> <p class="admonition-title">See also</p> <dl class="simple"> <dt> +<code>Module</code> <a class="reference internal" href="hashlib#module-hashlib" title="hashlib: Secure hash and message digest algorithms."><code>hashlib</code></a> +</dt> +<dd> +<p>The Python module providing secure hash functions.</p> </dd> </dl> </div> <div class="_attribution"> + <p class="_attribution-p"> + © 2001–2023 Python Software Foundation<br>Licensed under the PSF License.<br> + <a href="https://docs.python.org/3.12/library/hmac.html" class="_attribution-link">https://docs.python.org/3.12/library/hmac.html</a> + </p> +</div> |