uTools-Manuals/docs/python/hmac.html

<div class="body" role="main"><div class="section" id="module-hmac"><h1><span class="yiyi-st" id="yiyi-10">15.2. <a class="reference internal" href="#module-hmac" title="hmac: Keyed-Hashing for Message Authentication (HMAC) implementation"><code class="xref py py-mod docutils literal"><span class="pre">hmac</span></code></a> — 用于消息验证的加密哈希</span></h1><p><span class="yiyi-st" id="yiyi-11"><strong>源代码：</strong> <a class="reference external" href="https://hg.python.org/cpython/file/3.5/Lib/hmac.py">Lib/hmac.py</a></span></p><p><span class="yiyi-st" id="yiyi-12">该模块实现<span class="target" id="index-0"></span> <a class="rfc reference external" href="https://tools.ietf.org/html/rfc2104.html"><strong>RFC 2104</strong></a>描述的HMAC算法。</span></p><dl class="function"><dt id="hmac.new"><span class="yiyi-st" id="yiyi-13"><code class="descclassname">hmac.</code><code class="descname">new</code><span class="sig-paren">(</span><em>key</em>, <em>msg=None</em>, <em>digestmod=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-14">返回一个新的hmac对象。</span><span class="yiyi-st" id="yiyi-15"><em>key</em>是一个字节对象或字节数组对象，由它给出密钥。</span><span class="yiyi-st" id="yiyi-16">如果存在<em>msg</em>，则调用<code class="docutils literal"><span class="pre">update(msg)</span></code>方法。</span><span class="yiyi-st" id="yiyi-17"><em>digestmod</em>是HMAC对象要使用的摘要名称、摘要构造函数或模块。</span><span class="yiyi-st" id="yiyi-18">它支持适配<a class="reference internal" href="hashlib.html#hashlib.new" title="hashlib.new"><code class="xref py py-func docutils literal"><span class="pre">hashlib.new()</span></code></a>的任何名称，默认为<code class="xref py py-data docutils literal"><span class="pre">hashlib.md5</span></code>构造函数。</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-19"><span class="versionmodified">在版本3.4中的更改：</span>参数<em>key</em>可以是字节或字节数组对象。</span><span class="yiyi-st" id="yiyi-20">参数<em>msg</em>可以是<a class="reference internal" href="hashlib.html#module-hashlib" title="hashlib: Secure hash and message digest algorithms."><code class="xref py py-mod docutils literal"><span class="pre">hashlib</span></code></a>支持的任何类型。</span><span class="yiyi-st" id="yiyi-21">参数<em>digestmod</em>可以是哈希算法的名称。</span></p></div><div class="deprecated"><p><span class="yiyi-st" id="yiyi-22"><span class="versionmodified">自版本3.4起已弃用：</span>弃用MD5作为<em>digestmod</em>隐含的默认摘要。</span></p></div></dd></dl><p><span class="yiyi-st" id="yiyi-23">HMAC 对象具有以下方法：</span></p><dl class="method"><dt id="hmac.HMAC.update"><span class="yiyi-st" id="yiyi-24"><code class="descclassname">HMAC.</code><code class="descname">update</code><span class="sig-paren">(</span><em>msg</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-25">使用<em>msg</em>更新hmac对象。</span><span class="yiyi-st" id="yiyi-26">重复调用等效于具有所有参数串联的单个调用：<code class="docutils literal"><span class="pre">m.update(a);</span> <span class="pre">m.update(b)</span></code>等效于<code class="docutils literal"><span class="pre">m.update(a</span> <span class="pre">+</span> <span class="pre">b)</span></code>。</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-27"><span class="versionmodified">在版本3.4中更改：</span>参数<em>msg</em>可以是<a class="reference internal" href="hashlib.html#module-hashlib" title="hashlib: Secure hash and message digest algorithms."><code class="xref py py-mod docutils literal"><span class="pre">hashlib</span></code></a>支持的任何类型。</span></p></div></dd></dl><dl class="method"><dt id="hmac.HMAC.digest"><span class="yiyi-st" id="yiyi-28"><code class="descclassname">HMAC.</code><code class="descname">digest</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-29">返回到目前为止传递给<a class="reference internal" href="#hmac.HMAC.update" title="hmac.HMAC.update"><code class="xref py py-meth docutils literal"><span class="pre">update()</span></code></a>方法的字节的摘要。</span><span class="yiyi-st" id="yiyi-30">此字节对象的长度与向构造函数提供的摘要的<em>digest_size</em>长度相同。</span><span class="yiyi-st" id="yiyi-31">它可能包含非ASCII字节，包括NUL字节。</span></p><div class="admonition warning"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-32">警告</span></p><p class="last"><span class="yiyi-st" id="yiyi-33">在验证例程期间将<a class="reference internal" href="#hmac.HMAC.digest" title="hmac.HMAC.digest"><code class="xref py py-meth docutils literal"><span class="pre">digest()</span></code></a>的输出与外部提供的摘要进行比较时，建议使用<a class="reference internal" href="#hmac.compare_digest" title="hmac.compare_digest"><code class="xref py py-func docutils literal"><span class="pre">compare_digest()</span></code></a>函数代替<code class="docutils literal"><span class="pre">==</span></code>运算符，以减少定时攻击的脆弱性。</span></p></div></dd></dl><dl class="method"><dt id="hmac.HMAC.hexdigest"><span class="yiyi-st" id="yiyi-34"><code class="descclassname">HMAC.</code><code class="descname">hexdigest</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-35">像<a class="reference internal" href="#hmac.HMAC.digest" title="hmac.HMAC.digest"><code class="xref py py-meth docutils literal"><span class="pre">digest()</span></code></a>，除了摘要作为字符串返回两次只包含十六进制数字的字符串。</span><span class="yiyi-st" id="yiyi-36">这可用于在电子邮件或其它非二进制环境中安全交换数据。</span></p><div class="admonition warning"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-37">警告</span></p><p class="last"><span class="yiyi-st" id="yiyi-38">在验证例程期间将<a class="reference internal" href="#hmac.HMAC.hexdigest" title="hmac.HMAC.hexdigest"><code class="xref py py-meth docutils literal"><span class="pre">hexdigest()</span></code></a>的输出与外部提供的摘要进行比较时，建议使用<a class="reference internal" href="#hmac.compare_digest" title="hmac.compare_digest"><code class="xref py py-func docutils literal"><span class="pre">compare_digest()</span></code></a>函数代替<code class="docutils literal"><span class="pre">==</span></code>运算符，以减少定时攻击的脆弱性。</span></p></div></dd></dl><dl class="method"><dt id="hmac.HMAC.copy"><span class="yiyi-st" id="yiyi-39"><code class="descclassname">HMAC.</code><code class="descname">copy</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-40">返回 hmac 对象的副本（"克隆"）。</span><span class="yiyi-st" id="yiyi-41">这可以用于更有效地计算分享一个共同的初始子字符串的字符串的摘要。</span></p></dd></dl><p><span class="yiyi-st" id="yiyi-42">哈希对象具有以下属性：</span></p><dl class="attribute"><dt id="hmac.HMAC.digest_size"><span class="yiyi-st" id="yiyi-43"><code class="descclassname">HMAC.</code><code class="descname">digest_size</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-44">所得HMAC摘要的大小（以字节为单位）。</span></p></dd></dl><dl class="attribute"><dt id="hmac.HMAC.block_size"><span class="yiyi-st" id="yiyi-45"><code class="descclassname">HMAC.</code><code class="descname">block_size</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-46">哈希算法的内部块大小（以字节为单位）。</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-47"><span class="versionmodified">新版本3.4。</span></span></p></div></dd></dl><dl class="attribute"><dt id="hmac.HMAC.name"><span class="yiyi-st" id="yiyi-48"><code class="descclassname">HMAC.</code><code class="descname">name</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-49">此HMAC的规范名称，始终为小写，例如。</span><span class="yiyi-st" id="yiyi-50"><code class="docutils literal"><span class="pre">hmac-md5</span></code>。</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-51"><span class="versionmodified">新版本3.4。</span></span></p></div></dd></dl><p><span class="yiyi-st" id="yiyi-52">本模块还提供了以下辅助函数：</span></p><dl class="function"><dt id="hmac.compare_digest"><span class="yiyi-st" id="yiyi-53"><code class="descclassname">hmac.</code><code class="descname">compare_digest</code><span class="sig-paren">(</span><em>a</em>, <em>b</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-54">返回<code class="docutils literal"><span class="pre">a</span> <span class="pre">==</span> <span class="pre">b</span></code>。</span><span class="yiyi-st" id="yiyi-55">这个函数使用一种防止时序分析的方法，通过避免基于内容的短路行为，使其适合加密。</span><span class="yiyi-st" id="yiyi-56"><em>a</em>和<em>b</em>必须都是相同类型：<a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal"><span class="pre">str</span></code></a>（仅限ASCII，</span><span class="yiyi-st" id="yiyi-57">由<a class="reference internal" href="#hmac.HMAC.hexdigest" title="hmac.HMAC.hexdigest"><code class="xref py py-meth docutils literal"><span class="pre">HMAC.hexdigest()</span></code></a>）或<a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a>返回。</span></p><div class="admonition note"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-58">注</span></p><p class="last"><span class="yiyi-st" id="yiyi-59">如果<em>a</em>和<em>b</em>长度不同，或者如果发生错误，从理论上讲时序攻击可以揭示<em>a</em>和<em>b</em>的类型和长度等有关的信息 —— 但不能得到它们的值。</span></p></div><div class="versionadded"><p><span class="yiyi-st" id="yiyi-60"><span class="versionmodified">版本3.3中的新功能。</span></span></p></div></dd></dl><div class="admonition seealso"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-61">请参见</span></p><dl class="last docutils"><dt><span class="yiyi-st" id="yiyi-62">模块<a class="reference internal" href="hashlib.html#module-hashlib" title="hashlib: Secure hash and message digest algorithms."><code class="xref py py-mod docutils literal"><span class="pre">hashlib</span></code></a></span></dt><dd><span class="yiyi-st" id="yiyi-63">提供安全哈希函数的Python 模块</span></dd></dl></div></div></div>