parthtamu/rag-code-assistant
0
1<!DOCTYPE html>2 3<html lang="en" data-content_root="../">4 <head>5 <meta charset="utf-8" />6 <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />7<meta property="og:title" content="hashlib — Secure hashes and message digests" />8<meta property="og:type" content="website" />9<meta property="og:url" content="https://docs.python.org/3/library/hashlib.html" />10<meta property="og:site_name" content="Python documentation" />11<meta property="og:description" content="Source code: Lib/hashlib.py This module implements a common interface to many different hash algorithms. Included are the FIPS secure hash algorithms SHA224, SHA256, SHA384, SHA512, (defined in the..." />12<meta property="og:image:width" content="1146" />13<meta property="og:image:height" content="600" />14<meta property="og:image" content="https://docs.python.org/3.15/_images/social_previews/summary_library_hashlib_9fcb3b95.png" />15<meta property="og:image:alt" content="Source code: Lib/hashlib.py This module implements a common interface to many different hash algorithms. Included are the FIPS secure hash algorithms SHA224, SHA256, SHA384, SHA512, (defined in the..." />16<meta name="description" content="Source code: Lib/hashlib.py This module implements a common interface to many different hash algorithms. Included are the FIPS secure hash algorithms SHA224, SHA256, SHA384, SHA512, (defined in the..." />17<meta name="twitter:card" content="summary_large_image" />18<meta name="theme-color" content="#3776ab">19 20 <title>hashlib — Secure hashes and message digests — Python 3.15.0a6 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">21 22 <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />23 <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />24 <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=89a2f22a" />25 <link rel="stylesheet" type="text/css" href="../_static/profiling-sampling-visualization.css?v=0c2600ae" />26 <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />27 28 <script src="../_static/documentation_options.js?v=6b7c9ff5"></script>29 <script src="../_static/doctools.js?v=9bcbadda"></script>30 <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>31 <script src="../_static/profiling-sampling-visualization.js?v=9811ed04"></script>32 33 <script src="../_static/sidebar.js"></script>34 35 <link rel="search" type="application/opensearchdescription+xml"36 title="Search within Python 3.15.0a6 documentation"37 href="../_static/opensearch.xml"/>38 <link rel="author" title="About these documents" href="../about.html" />39 <link rel="index" title="Index" href="../genindex.html" />40 <link rel="search" title="Search" href="../search.html" />41 <link rel="copyright" title="Copyright" href="../copyright.html" />42 <link rel="next" title="hmac — Keyed-Hashing for Message Authentication" href="hmac.html" />43 <link rel="prev" title="Cryptographic Services" href="crypto.html" />44 45 46 <script defer file-types="bz2,epub,zip" data-domain="docs.python.org" src="https://analytics.python.org/js/script.file-downloads.outbound-links.js"></script>47 48 <link rel="canonical" href="https://docs.python.org/3/library/hashlib.html">49 50 51 52 53 <style>54 @media only screen {55 table.full-width-table {56 width: 100%;57 }58 }59 </style>60<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">61 <link rel="shortcut icon" type="image/png" href="../_static/py.svg">62 <script type="text/javascript" src="../_static/copybutton.js"></script>63 <script type="text/javascript" src="../_static/menu.js"></script>64 <script type="text/javascript" src="../_static/search-focus.js"></script>65 <script type="text/javascript" src="../_static/themetoggle.js"></script> 66 <script type="text/javascript" src="../_static/rtd_switcher.js"></script>67 <meta name="readthedocs-addons-api-version" content="1">68 69 </head>70<body>71<div class="mobile-nav">72 <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"73 aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">74 <nav class="nav-content" role="navigation">75 <label for="menuToggler" class="toggler__label">76 <span></span>77 </label>78 <span class="nav-items-wrapper">79 <a href="https://www.python.org/" class="nav-logo">80 <img src="../_static/py.svg" alt="Python logo">81 </a>82 <span class="version_switcher_placeholder"></span>83 <form role="search" class="search" action="../search.html" method="get">84 <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">85 <path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>86 </svg>87 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q">88 <input type="submit" value="Go">89 </form>90 </span>91 </nav>92 <div class="menu-wrapper">93 <nav class="menu" role="navigation" aria-label="main navigation">94 <div class="language_switcher_placeholder"></div>95 96<label class="theme-selector-label">97 Theme98 <select class="theme-selector" oninput="activateTheme(this.value)">99 <option value="auto" selected>Auto</option>100 <option value="light">Light</option>101 <option value="dark">Dark</option>102 </select>103</label>104 <div>105 <h3><a href="../contents.html">Table of Contents</a></h3>106 <ul>107<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">hashlib</span></code> — Secure hashes and message digests</a><ul>108<li><a class="reference internal" href="#hash-algorithms">Hash algorithms</a></li>109<li><a class="reference internal" href="#usage">Usage</a></li>110<li><a class="reference internal" href="#constructors">Constructors</a></li>111<li><a class="reference internal" href="#attributes">Attributes</a></li>112<li><a class="reference internal" href="#hash-objects">Hash Objects</a></li>113<li><a class="reference internal" href="#shake-variable-length-digests">SHAKE variable length digests</a></li>114<li><a class="reference internal" href="#file-hashing">File hashing</a></li>115<li><a class="reference internal" href="#key-derivation">Key derivation</a></li>116<li><a class="reference internal" href="#blake2">BLAKE2</a><ul>117<li><a class="reference internal" href="#creating-hash-objects">Creating hash objects</a></li>118<li><a class="reference internal" href="#constants">Constants</a></li>119<li><a class="reference internal" href="#examples">Examples</a><ul>120<li><a class="reference internal" href="#simple-hashing">Simple hashing</a></li>121<li><a class="reference internal" href="#using-different-digest-sizes">Using different digest sizes</a></li>122<li><a class="reference internal" href="#keyed-hashing">Keyed hashing</a></li>123<li><a class="reference internal" href="#randomized-hashing">Randomized hashing</a></li>124<li><a class="reference internal" href="#personalization">Personalization</a></li>125<li><a class="reference internal" href="#tree-mode">Tree mode</a></li>126</ul>127</li>128<li><a class="reference internal" href="#credits">Credits</a></li>129</ul>130</li>131</ul>132</li>133</ul>134 135 </div>136 <div>137 <h4>Previous topic</h4>138 <p class="topless"><a href="crypto.html"139 title="previous chapter">Cryptographic Services</a></p>140 </div>141 <div>142 <h4>Next topic</h4>143 <p class="topless"><a href="hmac.html"144 title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">hmac</span></code> — Keyed-Hashing for Message Authentication</a></p>145 </div>146 <script>147 document.addEventListener('DOMContentLoaded', () => {148 const title = document.querySelector('meta[property="og:title"]').content;149 const elements = document.querySelectorAll('.improvepage');150 const pageurl = window.location.href.split('?')[0];151 elements.forEach(element => {152 const url = new URL(element.href.split('?')[0].replace("-nojs", ""));153 url.searchParams.set('pagetitle', title);154 url.searchParams.set('pageurl', pageurl);155 url.searchParams.set('pagesource', "library/hashlib.rst");156 element.href = url.toString();157 });158 });159 </script>160 <div role="note" aria-label="source link">161 <h3>This page</h3>162 <ul class="this-page-menu">163 <li><a href="../bugs.html">Report a bug</a></li>164 <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>165 <li>166 <a href="https://github.com/python/cpython/blob/main/Doc/library/hashlib.rst?plain=1"167 rel="nofollow">Show source168 </a>169 </li>170 171 </ul>172 </div>173 </nav>174 </div>175</div>176 177 178 <div class="related" role="navigation" aria-label="Related">179 <h3>Navigation</h3>180 <ul>181 <li class="right" style="margin-right: 10px">182 <a href="../genindex.html" title="General Index"183 accesskey="I">index</a></li>184 <li class="right" >185 <a href="../py-modindex.html" title="Python Module Index"186 >modules</a> |</li>187 <li class="right" >188 <a href="hmac.html" title="hmac — Keyed-Hashing for Message Authentication"189 accesskey="N">next</a> |</li>190 <li class="right" >191 <a href="crypto.html" title="Cryptographic Services"192 accesskey="P">previous</a> |</li>193 194 <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>195 <li><a href="https://www.python.org/">Python</a> »</li>196 <li class="switchers">197 <div class="language_switcher_placeholder"></div>198 <div class="version_switcher_placeholder"></div>199 </li>200 <li>201 202 </li>203 <li id="cpython-language-and-version">204 <a href="../index.html">3.15.0a6 Documentation</a> »205 </li>206 207 <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>208 <li class="nav-item nav-item-2"><a href="crypto.html" accesskey="U">Cryptographic Services</a> »</li>209 <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">hashlib</span></code> — Secure hashes and message digests</a></li>210 <li class="right">211 212 213 <div class="inline-search" role="search">214 <form class="inline-search" action="../search.html" method="get">215 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">216 <input type="submit" value="Go">217 </form>218 </div>219 |220 </li>221 <li class="right">222<label class="theme-selector-label">223 Theme224 <select class="theme-selector" oninput="activateTheme(this.value)">225 <option value="auto" selected>Auto</option>226 <option value="light">Light</option>227 <option value="dark">Dark</option>228 </select>229</label> |</li>230 231 </ul>232 </div> 233 234 <div class="document">235 <div class="documentwrapper">236 <div class="bodywrapper">237 <div class="body" role="main">238 239 <section id="module-hashlib">240<span id="hashlib-secure-hashes-and-message-digests"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">hashlib</span></code> — Secure hashes and message digests<a class="headerlink" href="#module-hashlib" title="Link to this heading">¶</a></h1>241<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/main/Lib/hashlib.py">Lib/hashlib.py</a></p>242<span class="target" id="index-0"></span><hr class="docutils" />243<p>This module implements a common interface to many different hash algorithms.244Included are the FIPS secure hash algorithms SHA224, SHA256, SHA384, SHA512,245(defined in <a class="reference external" href="https://csrc.nist.gov/pubs/fips/180-4/upd1/final">the FIPS 180-4 standard</a>), the SHA-3 series (defined in <a class="reference external" href="https://csrc.nist.gov/pubs/fips/202/final">the FIPS246202 standard</a>) as well as the legacy algorithms SHA1 (<a class="reference external" href="https://csrc.nist.gov/news/2023/decision-to-revise-fips-180-4">formerly part of FIPS</a>)247and the MD5 algorithm (defined in internet <span class="target" id="index-1"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc1321.html"><strong>RFC 1321</strong></a>).</p>248<div class="admonition note">249<p class="admonition-title">Note</p>250<p>If you want the adler32 or crc32 hash functions, they are available in251the <a class="reference internal" href="zlib.html#module-zlib" title="zlib: Low-level interface to compression and decompression routines compatible with gzip."><code class="xref py py-mod docutils literal notranslate"><span class="pre">zlib</span></code></a> module.</p>252</div>253<section id="hash-algorithms">254<span id="id1"></span><h2>Hash algorithms<a class="headerlink" href="#hash-algorithms" title="Link to this heading">¶</a></h2>255<p>There is one constructor method named for each type of <em class="dfn">hash</em>. All return256a hash object with the same simple interface. For example: use <a class="reference internal" href="#hashlib.sha256" title="hashlib.sha256"><code class="xref py py-func docutils literal notranslate"><span class="pre">sha256()</span></code></a>257to create a SHA-256 hash object. You can now feed this object with258<a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like objects</span></a> (normally <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a>) using259the <a class="reference internal" href="#hashlib.hash.update" title="hashlib.hash.update"><code class="xref py py-meth docutils literal notranslate"><span class="pre">update</span></code></a> method. At any point you can ask it for the260<em class="dfn">digest</em> of the concatenation of the data fed to it so far using the261<a class="reference internal" href="#hashlib.hash.digest" title="hashlib.hash.digest"><code class="xref py py-meth docutils literal notranslate"><span class="pre">digest()</span></code></a> or <a class="reference internal" href="#hashlib.hash.hexdigest" title="hashlib.hash.hexdigest"><code class="xref py py-meth docutils literal notranslate"><span class="pre">hexdigest()</span></code></a> methods.</p>262<p>To allow multithreading, the Python <a class="reference internal" href="../glossary.html#term-GIL"><span class="xref std std-term">GIL</span></a> is released while computing a263hash supplied more than 2047 bytes of data at once in its constructor or264<a class="reference internal" href="#hashlib.hash.update" title="hashlib.hash.update"><code class="xref py py-meth docutils literal notranslate"><span class="pre">.update</span></code></a> method.</p>265<p id="index-2">Constructors for hash algorithms that are always present in this module are266<a class="reference internal" href="#hashlib.sha1" title="hashlib.sha1"><code class="xref py py-func docutils literal notranslate"><span class="pre">sha1()</span></code></a>, <a class="reference internal" href="#hashlib.sha224" title="hashlib.sha224"><code class="xref py py-func docutils literal notranslate"><span class="pre">sha224()</span></code></a>, <a class="reference internal" href="#hashlib.sha256" title="hashlib.sha256"><code class="xref py py-func docutils literal notranslate"><span class="pre">sha256()</span></code></a>, <a class="reference internal" href="#hashlib.sha384" title="hashlib.sha384"><code class="xref py py-func docutils literal notranslate"><span class="pre">sha384()</span></code></a>, <a class="reference internal" href="#hashlib.sha512" title="hashlib.sha512"><code class="xref py py-func docutils literal notranslate"><span class="pre">sha512()</span></code></a>,267<a class="reference internal" href="#hashlib.sha3_224" title="hashlib.sha3_224"><code class="xref py py-func docutils literal notranslate"><span class="pre">sha3_224()</span></code></a>, <a class="reference internal" href="#hashlib.sha3_256" title="hashlib.sha3_256"><code class="xref py py-func docutils literal notranslate"><span class="pre">sha3_256()</span></code></a>, <a class="reference internal" href="#hashlib.sha3_384" title="hashlib.sha3_384"><code class="xref py py-func docutils literal notranslate"><span class="pre">sha3_384()</span></code></a>, <a class="reference internal" href="#hashlib.sha3_512" title="hashlib.sha3_512"><code class="xref py py-func docutils literal notranslate"><span class="pre">sha3_512()</span></code></a>,268<a class="reference internal" href="#hashlib.shake_128" title="hashlib.shake_128"><code class="xref py py-func docutils literal notranslate"><span class="pre">shake_128()</span></code></a>, <a class="reference internal" href="#hashlib.shake_256" title="hashlib.shake_256"><code class="xref py py-func docutils literal notranslate"><span class="pre">shake_256()</span></code></a>, <a class="reference internal" href="#hashlib.blake2b" title="hashlib.blake2b"><code class="xref py py-func docutils literal notranslate"><span class="pre">blake2b()</span></code></a>, and <a class="reference internal" href="#hashlib.blake2s" title="hashlib.blake2s"><code class="xref py py-func docutils literal notranslate"><span class="pre">blake2s()</span></code></a>.269<a class="reference internal" href="#hashlib.md5" title="hashlib.md5"><code class="xref py py-func docutils literal notranslate"><span class="pre">md5()</span></code></a> is normally available as well, though it may be missing or blocked270if you are using a rare “FIPS compliant” build of Python.271These correspond to <a class="reference internal" href="#hashlib.algorithms_guaranteed" title="hashlib.algorithms_guaranteed"><code class="xref py py-data docutils literal notranslate"><span class="pre">algorithms_guaranteed</span></code></a>.</p>272<p>Additional algorithms may also be available if your Python distribution’s273<code class="xref py py-mod docutils literal notranslate"><span class="pre">hashlib</span></code> was linked against a build of OpenSSL that provides others.274Others <em>are not guaranteed available</em> on all installations and will only be275accessible by name via <a class="reference internal" href="#hashlib.new" title="hashlib.new"><code class="xref py py-func docutils literal notranslate"><span class="pre">new()</span></code></a>. See <a class="reference internal" href="#hashlib.algorithms_available" title="hashlib.algorithms_available"><code class="xref py py-data docutils literal notranslate"><span class="pre">algorithms_available</span></code></a>.</p>276<div class="admonition warning">277<p class="admonition-title">Warning</p>278<p>Some algorithms have known hash collision weaknesses (including MD5 and279SHA1). Refer to <a class="reference external" href="https://en.wikipedia.org/wiki/Cryptographic_hash_function#Attacks_on_cryptographic_hash_algorithms">Attacks on cryptographic hash algorithms</a> and the280<a class="reference internal" href="#hashlib-seealso">hashlib-seealso</a> section at the end of this document.</p>281</div>282<div class="versionadded">283<p><span class="versionmodified added">Added in version 3.6: </span>SHA3 (Keccak) and SHAKE constructors <a class="reference internal" href="#hashlib.sha3_224" title="hashlib.sha3_224"><code class="xref py py-func docutils literal notranslate"><span class="pre">sha3_224()</span></code></a>, <a class="reference internal" href="#hashlib.sha3_256" title="hashlib.sha3_256"><code class="xref py py-func docutils literal notranslate"><span class="pre">sha3_256()</span></code></a>,284<a class="reference internal" href="#hashlib.sha3_384" title="hashlib.sha3_384"><code class="xref py py-func docutils literal notranslate"><span class="pre">sha3_384()</span></code></a>, <a class="reference internal" href="#hashlib.sha3_512" title="hashlib.sha3_512"><code class="xref py py-func docutils literal notranslate"><span class="pre">sha3_512()</span></code></a>, <a class="reference internal" href="#hashlib.shake_128" title="hashlib.shake_128"><code class="xref py py-func docutils literal notranslate"><span class="pre">shake_128()</span></code></a>, <a class="reference internal" href="#hashlib.shake_256" title="hashlib.shake_256"><code class="xref py py-func docutils literal notranslate"><span class="pre">shake_256()</span></code></a>285were added.286<a class="reference internal" href="#hashlib.blake2b" title="hashlib.blake2b"><code class="xref py py-func docutils literal notranslate"><span class="pre">blake2b()</span></code></a> and <a class="reference internal" href="#hashlib.blake2s" title="hashlib.blake2s"><code class="xref py py-func docutils literal notranslate"><span class="pre">blake2s()</span></code></a> were added.</p>287</div>288<div class="versionchanged" id="hashlib-usedforsecurity">289<p><span class="versionmodified changed">Changed in version 3.9: </span>All hashlib constructors take a keyword-only argument <em>usedforsecurity</em>290with default value <code class="docutils literal notranslate"><span class="pre">True</span></code>. A false value allows the use of insecure and291blocked hashing algorithms in restricted environments. <code class="docutils literal notranslate"><span class="pre">False</span></code> indicates292that the hashing algorithm is not used in a security context, e.g. as a293non-cryptographic one-way compression function.</p>294</div>295<div class="versionchanged">296<p><span class="versionmodified changed">Changed in version 3.9: </span>Hashlib now uses SHA3 and SHAKE from OpenSSL if it provides it.</p>297</div>298<div class="versionchanged">299<p><span class="versionmodified changed">Changed in version 3.12: </span>For any of the MD5, SHA1, SHA2, or SHA3 algorithms that the linked300OpenSSL does not provide we fall back to a verified implementation from301the <a class="reference external" href="https://github.com/hacl-star/hacl-star">HACL* project</a>.</p>302</div>303<div class="deprecated-removed">304<p><span class="versionmodified deprecated">Deprecated since version 3.15, will be removed in version 3.19: </span>The undocumented <code class="docutils literal notranslate"><span class="pre">string</span></code> keyword parameter in <code class="xref py py-func docutils literal notranslate"><span class="pre">_hashlib.new()</span></code>305and hash-named constructors such as <code class="xref py py-func docutils literal notranslate"><span class="pre">_md5.md5()</span></code> is deprecated.306Prefer passing the initial data as a positional argument for maximum307backwards compatibility.</p>308</div>309</section>310<section id="usage">311<h2>Usage<a class="headerlink" href="#usage" title="Link to this heading">¶</a></h2>312<p>To obtain the digest of the byte string <code class="docutils literal notranslate"><span class="pre">b"Nobody</span> <span class="pre">inspects</span> <span class="pre">the</span> <span class="pre">spammish</span>313<span class="pre">repetition"</span></code>:</p>314<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span><span class="w"> </span><span class="nn">hashlib</span>315<span class="gp">>>> </span><span class="n">m</span> <span class="o">=</span> <span class="n">hashlib</span><span class="o">.</span><span class="n">sha256</span><span class="p">()</span>316<span class="gp">>>> </span><span class="n">m</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="sa">b</span><span class="s2">"Nobody inspects"</span><span class="p">)</span>317<span class="gp">>>> </span><span class="n">m</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="sa">b</span><span class="s2">" the spammish repetition"</span><span class="p">)</span>318<span class="gp">>>> </span><span class="n">m</span><span class="o">.</span><span class="n">digest</span><span class="p">()</span>319<span class="go">b'\x03\x1e\xdd}Ae\x15\x93\xc5\xfe\\\x00o\xa5u+7\xfd\xdf\xf7\xbcN\x84:\xa6\xaf\x0c\x95\x0fK\x94\x06'</span>320<span class="gp">>>> </span><span class="n">m</span><span class="o">.</span><span class="n">hexdigest</span><span class="p">()</span>321<span class="go">'031edd7d41651593c5fe5c006fa5752b37fddff7bc4e843aa6af0c950f4b9406'</span>322</pre></div>323</div>324<p>More condensed:</p>325<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">hashlib</span><span class="o">.</span><span class="n">sha256</span><span class="p">(</span><span class="sa">b</span><span class="s2">"Nobody inspects the spammish repetition"</span><span class="p">)</span><span class="o">.</span><span class="n">hexdigest</span><span class="p">()</span>326<span class="go">'031edd7d41651593c5fe5c006fa5752b37fddff7bc4e843aa6af0c950f4b9406'</span>327</pre></div>328</div>329</section>330<section id="constructors">331<h2>Constructors<a class="headerlink" href="#constructors" title="Link to this heading">¶</a></h2>332<dl class="py function">333<dt class="sig sig-object py" id="hashlib.new">334<span class="sig-prename descclassname"><span class="pre">hashlib.</span></span><span class="sig-name descname"><span class="pre">new</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em>, <span class="optional">[</span><em class="sig-param"><span class="n"><span class="pre">data</span></span></em>, <span class="optional">]</span><em class="sig-param"><span class="n"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">usedforsecurity=True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#hashlib.new" title="Link to this definition">¶</a></dt>335<dd><p>Is a generic constructor that takes the string <em>name</em> of the desired336algorithm as its first parameter. It also exists to allow access to the337above listed hashes as well as any other algorithms that your OpenSSL338library may offer.</p>339</dd></dl>340 341<p>Using <a class="reference internal" href="#hashlib.new" title="hashlib.new"><code class="xref py py-func docutils literal notranslate"><span class="pre">new()</span></code></a> with an algorithm name:</p>342<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">h</span> <span class="o">=</span> <span class="n">hashlib</span><span class="o">.</span><span class="n">new</span><span class="p">(</span><span class="s1">'sha256'</span><span class="p">)</span>343<span class="gp">>>> </span><span class="n">h</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="sa">b</span><span class="s2">"Nobody inspects the spammish repetition"</span><span class="p">)</span>344<span class="gp">>>> </span><span class="n">h</span><span class="o">.</span><span class="n">hexdigest</span><span class="p">()</span>345<span class="go">'031edd7d41651593c5fe5c006fa5752b37fddff7bc4e843aa6af0c950f4b9406'</span>346</pre></div>347</div>348<dl class="py function">349<dt class="sig sig-object py" id="hashlib.md5">350<span class="sig-prename descclassname"><span class="pre">hashlib.</span></span><span class="sig-name descname"><span class="pre">md5</span></span><span class="sig-paren">(</span><span class="optional">[</span><em class="sig-param"><span class="n"><span class="pre">data</span></span></em>, <span class="optional">]</span><em class="sig-param"><span class="n"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">usedforsecurity=True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#hashlib.md5" title="Link to this definition">¶</a></dt>351<dd></dd></dl>352 353<dl class="py function">354<dt class="sig sig-object py" id="hashlib.sha1">355<span class="sig-prename descclassname"><span class="pre">hashlib.</span></span><span class="sig-name descname"><span class="pre">sha1</span></span><span class="sig-paren">(</span><span class="optional">[</span><em class="sig-param"><span class="n"><span class="pre">data</span></span></em>, <span class="optional">]</span><em class="sig-param"><span class="n"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">usedforsecurity=True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#hashlib.sha1" title="Link to this definition">¶</a></dt>356<dd></dd></dl>357 358<dl class="py function">359<dt class="sig sig-object py" id="hashlib.sha224">360<span class="sig-prename descclassname"><span class="pre">hashlib.</span></span><span class="sig-name descname"><span class="pre">sha224</span></span><span class="sig-paren">(</span><span class="optional">[</span><em class="sig-param"><span class="n"><span class="pre">data</span></span></em>, <span class="optional">]</span><em class="sig-param"><span class="n"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">usedforsecurity=True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#hashlib.sha224" title="Link to this definition">¶</a></dt>361<dd></dd></dl>362 363<dl class="py function">364<dt class="sig sig-object py" id="hashlib.sha256">365<span class="sig-prename descclassname"><span class="pre">hashlib.</span></span><span class="sig-name descname"><span class="pre">sha256</span></span><span class="sig-paren">(</span><span class="optional">[</span><em class="sig-param"><span class="n"><span class="pre">data</span></span></em>, <span class="optional">]</span><em class="sig-param"><span class="n"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">usedforsecurity=True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#hashlib.sha256" title="Link to this definition">¶</a></dt>366<dd></dd></dl>367 368<dl class="py function">369<dt class="sig sig-object py" id="hashlib.sha384">370<span class="sig-prename descclassname"><span class="pre">hashlib.</span></span><span class="sig-name descname"><span class="pre">sha384</span></span><span class="sig-paren">(</span><span class="optional">[</span><em class="sig-param"><span class="n"><span class="pre">data</span></span></em>, <span class="optional">]</span><em class="sig-param"><span class="n"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">usedforsecurity=True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#hashlib.sha384" title="Link to this definition">¶</a></dt>371<dd></dd></dl>372 373<dl class="py function">374<dt class="sig sig-object py" id="hashlib.sha512">375<span class="sig-prename descclassname"><span class="pre">hashlib.</span></span><span class="sig-name descname"><span class="pre">sha512</span></span><span class="sig-paren">(</span><span class="optional">[</span><em class="sig-param"><span class="n"><span class="pre">data</span></span></em>, <span class="optional">]</span><em class="sig-param"><span class="n"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">usedforsecurity=True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#hashlib.sha512" title="Link to this definition">¶</a></dt>376<dd></dd></dl>377 378<dl class="py function">379<dt class="sig sig-object py" id="hashlib.sha3_224">380<span class="sig-prename descclassname"><span class="pre">hashlib.</span></span><span class="sig-name descname"><span class="pre">sha3_224</span></span><span class="sig-paren">(</span><span class="optional">[</span><em class="sig-param"><span class="n"><span class="pre">data</span></span></em>, <span class="optional">]</span><em class="sig-param"><span class="n"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">usedforsecurity=True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#hashlib.sha3_224" title="Link to this definition">¶</a></dt>381<dd></dd></dl>382 383<dl class="py function">384<dt class="sig sig-object py" id="hashlib.sha3_256">385<span class="sig-prename descclassname"><span class="pre">hashlib.</span></span><span class="sig-name descname"><span class="pre">sha3_256</span></span><span class="sig-paren">(</span><span class="optional">[</span><em class="sig-param"><span class="n"><span class="pre">data</span></span></em>, <span class="optional">]</span><em class="sig-param"><span class="n"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">usedforsecurity=True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#hashlib.sha3_256" title="Link to this definition">¶</a></dt>386<dd></dd></dl>387 388<dl class="py function">389<dt class="sig sig-object py" id="hashlib.sha3_384">390<span class="sig-prename descclassname"><span class="pre">hashlib.</span></span><span class="sig-name descname"><span class="pre">sha3_384</span></span><span class="sig-paren">(</span><span class="optional">[</span><em class="sig-param"><span class="n"><span class="pre">data</span></span></em>, <span class="optional">]</span><em class="sig-param"><span class="n"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">usedforsecurity=True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#hashlib.sha3_384" title="Link to this definition">¶</a></dt>391<dd></dd></dl>392 393<dl class="py function">394<dt class="sig sig-object py" id="hashlib.sha3_512">395<span class="sig-prename descclassname"><span class="pre">hashlib.</span></span><span class="sig-name descname"><span class="pre">sha3_512</span></span><span class="sig-paren">(</span><span class="optional">[</span><em class="sig-param"><span class="n"><span class="pre">data</span></span></em>, <span class="optional">]</span><em class="sig-param"><span class="n"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">usedforsecurity=True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#hashlib.sha3_512" title="Link to this definition">¶</a></dt>396<dd></dd></dl>397 398<p>Named constructors such as these are faster than passing an algorithm name to399<a class="reference internal" href="#hashlib.new" title="hashlib.new"><code class="xref py py-func docutils literal notranslate"><span class="pre">new()</span></code></a>.</p>400</section>401<section id="attributes">402<h2>Attributes<a class="headerlink" href="#attributes" title="Link to this heading">¶</a></h2>403<p>Hashlib provides the following constant module attributes:</p>404<dl class="py data">405<dt class="sig sig-object py" id="hashlib.algorithms_guaranteed">406<span class="sig-prename descclassname"><span class="pre">hashlib.</span></span><span class="sig-name descname"><span class="pre">algorithms_guaranteed</span></span><a class="headerlink" href="#hashlib.algorithms_guaranteed" title="Link to this definition">¶</a></dt>407<dd><p>A set containing the names of the hash algorithms guaranteed to be supported408by this module on all platforms. Note that ‘md5’ is in this list despite409some upstream vendors offering an odd “FIPS compliant” Python build that410excludes it.</p>411<div class="versionadded">412<p><span class="versionmodified added">Added in version 3.2.</span></p>413</div>414</dd></dl>415 416<dl class="py data">417<dt class="sig sig-object py" id="hashlib.algorithms_available">418<span class="sig-prename descclassname"><span class="pre">hashlib.</span></span><span class="sig-name descname"><span class="pre">algorithms_available</span></span><a class="headerlink" href="#hashlib.algorithms_available" title="Link to this definition">¶</a></dt>419<dd><p>A set containing the names of the hash algorithms that are available in the420running Python interpreter. These names will be recognized when passed to421<a class="reference internal" href="#hashlib.new" title="hashlib.new"><code class="xref py py-func docutils literal notranslate"><span class="pre">new()</span></code></a>. <a class="reference internal" href="#hashlib.algorithms_guaranteed" title="hashlib.algorithms_guaranteed"><code class="xref py py-attr docutils literal notranslate"><span class="pre">algorithms_guaranteed</span></code></a> will always be a subset. The422same algorithm may appear multiple times in this set under different names423(thanks to OpenSSL).</p>424<div class="versionadded">425<p><span class="versionmodified added">Added in version 3.2.</span></p>426</div>427</dd></dl>428 429</section>430<section id="hash-objects">431<h2>Hash Objects<a class="headerlink" href="#hash-objects" title="Link to this heading">¶</a></h2>432<p>The following values are provided as constant attributes of the hash objects433returned by the constructors:</p>434<dl class="py data">435<dt class="sig sig-object py" id="hashlib.hash.digest_size">436<span class="sig-prename descclassname"><span class="pre">hash.</span></span><span class="sig-name descname"><span class="pre">digest_size</span></span><a class="headerlink" href="#hashlib.hash.digest_size" title="Link to this definition">¶</a></dt>437<dd><p>The size of the resulting hash in bytes.</p>438</dd></dl>439 440<dl class="py data">441<dt class="sig sig-object py" id="hashlib.hash.block_size">442<span class="sig-prename descclassname"><span class="pre">hash.</span></span><span class="sig-name descname"><span class="pre">block_size</span></span><a class="headerlink" href="#hashlib.hash.block_size" title="Link to this definition">¶</a></dt>443<dd><p>The internal block size of the hash algorithm in bytes.</p>444</dd></dl>445 446<p>A hash object has the following attributes:</p>447<dl class="py attribute">448<dt class="sig sig-object py" id="hashlib.hash.name">449<span class="sig-prename descclassname"><span class="pre">hash.</span></span><span class="sig-name descname"><span class="pre">name</span></span><a class="headerlink" href="#hashlib.hash.name" title="Link to this definition">¶</a></dt>450<dd><p>The canonical name of this hash, always lowercase and always suitable as a451parameter to <a class="reference internal" href="#hashlib.new" title="hashlib.new"><code class="xref py py-func docutils literal notranslate"><span class="pre">new()</span></code></a> to create another hash of this type.</p>452<div class="versionchanged">453<p><span class="versionmodified changed">Changed in version 3.4: </span>The name attribute has been present in CPython since its inception, but454until Python 3.4 was not formally specified, so may not exist on some455platforms.</p>456</div>457</dd></dl>458 459<p>A hash object has the following methods:</p>460<dl class="py method">461<dt class="sig sig-object py" id="hashlib.hash.update">462<span class="sig-prename descclassname"><span class="pre">hash.</span></span><span class="sig-name descname"><span class="pre">update</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">data</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#hashlib.hash.update" title="Link to this definition">¶</a></dt>463<dd><p>Update the hash object with the <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a>.464Repeated calls are equivalent to a single call with the465concatenation of all the arguments: <code class="docutils literal notranslate"><span class="pre">m.update(a);</span> <span class="pre">m.update(b)</span></code> is466equivalent to <code class="docutils literal notranslate"><span class="pre">m.update(a+b)</span></code>.</p>467</dd></dl>468 469<dl class="py method">470<dt class="sig sig-object py" id="hashlib.hash.digest">471<span class="sig-prename descclassname"><span class="pre">hash.</span></span><span class="sig-name descname"><span class="pre">digest</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#hashlib.hash.digest" title="Link to this definition">¶</a></dt>472<dd><p>Return the digest of the data passed to the <a class="reference internal" href="#hashlib.hash.update" title="hashlib.hash.update"><code class="xref py py-meth docutils literal notranslate"><span class="pre">update()</span></code></a> method so far.473This is a bytes object of size <a class="reference internal" href="#hashlib.hash.digest_size" title="hashlib.hash.digest_size"><code class="xref py py-attr docutils literal notranslate"><span class="pre">digest_size</span></code></a> which may contain bytes in474the whole range from 0 to 255.</p>475</dd></dl>476 477<dl class="py method">478<dt class="sig sig-object py" id="hashlib.hash.hexdigest">479<span class="sig-prename descclassname"><span class="pre">hash.</span></span><span class="sig-name descname"><span class="pre">hexdigest</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#hashlib.hash.hexdigest" title="Link to this definition">¶</a></dt>480<dd><p>Like <a class="reference internal" href="#hashlib.hash.digest" title="hashlib.hash.digest"><code class="xref py py-meth docutils literal notranslate"><span class="pre">digest()</span></code></a> except the digest is returned as a string object of481double length, containing only hexadecimal digits. This may be used to482exchange the value safely in email or other non-binary environments.</p>483</dd></dl>484 485<dl class="py method">486<dt class="sig sig-object py" id="hashlib.hash.copy">487<span class="sig-prename descclassname"><span class="pre">hash.</span></span><span class="sig-name descname"><span class="pre">copy</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#hashlib.hash.copy" title="Link to this definition">¶</a></dt>488<dd><p>Return a copy (“clone”) of the hash object. This can be used to efficiently489compute the digests of data sharing a common initial substring.</p>490</dd></dl>491 492</section>493<section id="shake-variable-length-digests">494<h2>SHAKE variable length digests<a class="headerlink" href="#shake-variable-length-digests" title="Link to this heading">¶</a></h2>495<dl class="py function">496<dt class="sig sig-object py" id="hashlib.shake_128">497<span class="sig-prename descclassname"><span class="pre">hashlib.</span></span><span class="sig-name descname"><span class="pre">shake_128</span></span><span class="sig-paren">(</span><span class="optional">[</span><em class="sig-param"><span class="n"><span class="pre">data</span></span></em>, <span class="optional">]</span><em class="sig-param"><span class="n"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">usedforsecurity=True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#hashlib.shake_128" title="Link to this definition">¶</a></dt>498<dd></dd></dl>499 500<dl class="py function">501<dt class="sig sig-object py" id="hashlib.shake_256">502<span class="sig-prename descclassname"><span class="pre">hashlib.</span></span><span class="sig-name descname"><span class="pre">shake_256</span></span><span class="sig-paren">(</span><span class="optional">[</span><em class="sig-param"><span class="n"><span class="pre">data</span></span></em>, <span class="optional">]</span><em class="sig-param"><span class="n"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">usedforsecurity=True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#hashlib.shake_256" title="Link to this definition">¶</a></dt>503<dd></dd></dl>504 505<p>The <a class="reference internal" href="#hashlib.shake_128" title="hashlib.shake_128"><code class="xref py py-func docutils literal notranslate"><span class="pre">shake_128()</span></code></a> and <a class="reference internal" href="#hashlib.shake_256" title="hashlib.shake_256"><code class="xref py py-func docutils literal notranslate"><span class="pre">shake_256()</span></code></a> algorithms provide variable506length digests with length_in_bits//2 up to 128 or 256 bits of security.507As such, their digest methods require a length. Maximum length is not limited508by the SHAKE algorithm.</p>509<dl class="py method">510<dt class="sig sig-object py" id="hashlib.shake.digest">511<span class="sig-prename descclassname"><span class="pre">shake.</span></span><span class="sig-name descname"><span class="pre">digest</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">length</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#hashlib.shake.digest" title="Link to this definition">¶</a></dt>512<dd><p>Return the digest of the data passed to the <a class="reference internal" href="#hashlib.hash.update" title="hashlib.hash.update"><code class="xref py py-meth docutils literal notranslate"><span class="pre">update()</span></code></a> method so far.513This is a bytes object of size <em>length</em> which may contain bytes in514the whole range from 0 to 255.</p>515</dd></dl>516 517<dl class="py method">518<dt class="sig sig-object py" id="hashlib.shake.hexdigest">519<span class="sig-prename descclassname"><span class="pre">shake.</span></span><span class="sig-name descname"><span class="pre">hexdigest</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">length</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#hashlib.shake.hexdigest" title="Link to this definition">¶</a></dt>520<dd><p>Like <a class="reference internal" href="#hashlib.shake.digest" title="hashlib.shake.digest"><code class="xref py py-meth docutils literal notranslate"><span class="pre">digest()</span></code></a> except the digest is returned as a string object of521double length, containing only hexadecimal digits. This may be used to522exchange the value in email or other non-binary environments.</p>523</dd></dl>524 525<p>Example use:</p>526<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">h</span> <span class="o">=</span> <span class="n">hashlib</span><span class="o">.</span><span class="n">shake_256</span><span class="p">(</span><span class="sa">b</span><span class="s1">'Nobody inspects the spammish repetition'</span><span class="p">)</span>527<span class="gp">>>> </span><span class="n">h</span><span class="o">.</span><span class="n">hexdigest</span><span class="p">(</span><span class="mi">20</span><span class="p">)</span>528<span class="go">'44709d6fcb83d92a76dcb0b668c98e1b1d3dafe7'</span>529</pre></div>530</div>531</section>532<section id="file-hashing">533<h2>File hashing<a class="headerlink" href="#file-hashing" title="Link to this heading">¶</a></h2>534<p>The hashlib module provides a helper function for efficient hashing of535a file or file-like object.</p>536<dl class="py function">537<dt class="sig sig-object py" id="hashlib.file_digest">538<span class="sig-prename descclassname"><span class="pre">hashlib.</span></span><span class="sig-name descname"><span class="pre">file_digest</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">fileobj</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">digest</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span><a class="headerlink" href="#hashlib.file_digest" title="Link to this definition">¶</a></dt>539<dd><p>Return a digest object that has been updated with contents of file object.</p>540<p><em>fileobj</em> must be a file-like object opened for reading in binary mode.541It accepts file objects from builtin <a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a>, <a class="reference internal" href="io.html#io.BytesIO" title="io.BytesIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesIO</span></code></a>542instances, SocketIO objects from <a class="reference internal" href="socket.html#socket.socket.makefile" title="socket.socket.makefile"><code class="xref py py-meth docutils literal notranslate"><span class="pre">socket.socket.makefile()</span></code></a>, and543similar. <em>fileobj</em> must be opened in blocking mode, otherwise a544<a class="reference internal" href="exceptions.html#BlockingIOError" title="BlockingIOError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">BlockingIOError</span></code></a> may be raised.</p>545<p>The function may bypass Python’s I/O and use the file descriptor546from <a class="reference internal" href="io.html#io.IOBase.fileno" title="io.IOBase.fileno"><code class="xref py py-meth docutils literal notranslate"><span class="pre">fileno()</span></code></a> directly. <em>fileobj</em> must be assumed to be547in an unknown state after this function returns or raises. It is up to548the caller to close <em>fileobj</em>.</p>549<p><em>digest</em> must either be a hash algorithm name as a <em>str</em>, a hash550constructor, or a callable that returns a hash object.</p>551<p>Example:</p>552<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span><span class="w"> </span><span class="nn">io</span><span class="o">,</span><span class="w"> </span><span class="nn">hashlib</span><span class="o">,</span><span class="w"> </span><span class="nn">hmac</span>553<span class="gp">>>> </span><span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s2">"library/hashlib.rst"</span><span class="p">,</span> <span class="s2">"rb"</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>554<span class="gp">... </span> <span class="n">digest</span> <span class="o">=</span> <span class="n">hashlib</span><span class="o">.</span><span class="n">file_digest</span><span class="p">(</span><span class="n">f</span><span class="p">,</span> <span class="s2">"sha256"</span><span class="p">)</span>555<span class="gp">...</span>556<span class="gp">>>> </span><span class="n">digest</span><span class="o">.</span><span class="n">hexdigest</span><span class="p">()</span>557<span class="go">'...'</span>558</pre></div>559</div>560<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">buf</span> <span class="o">=</span> <span class="n">io</span><span class="o">.</span><span class="n">BytesIO</span><span class="p">(</span><span class="sa">b</span><span class="s2">"somedata"</span><span class="p">)</span>561<span class="gp">>>> </span><span class="n">mac1</span> <span class="o">=</span> <span class="n">hmac</span><span class="o">.</span><span class="n">HMAC</span><span class="p">(</span><span class="sa">b</span><span class="s2">"key"</span><span class="p">,</span> <span class="n">digestmod</span><span class="o">=</span><span class="n">hashlib</span><span class="o">.</span><span class="n">sha512</span><span class="p">)</span>562<span class="gp">>>> </span><span class="n">digest</span> <span class="o">=</span> <span class="n">hashlib</span><span class="o">.</span><span class="n">file_digest</span><span class="p">(</span><span class="n">buf</span><span class="p">,</span> <span class="k">lambda</span><span class="p">:</span> <span class="n">mac1</span><span class="p">)</span>563</pre></div>564</div>565<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">digest</span> <span class="ow">is</span> <span class="n">mac1</span>566<span class="go">True</span>567<span class="gp">>>> </span><span class="n">mac2</span> <span class="o">=</span> <span class="n">hmac</span><span class="o">.</span><span class="n">HMAC</span><span class="p">(</span><span class="sa">b</span><span class="s2">"key"</span><span class="p">,</span> <span class="sa">b</span><span class="s2">"somedata"</span><span class="p">,</span> <span class="n">digestmod</span><span class="o">=</span><span class="n">hashlib</span><span class="o">.</span><span class="n">sha512</span><span class="p">)</span>568<span class="gp">>>> </span><span class="n">mac1</span><span class="o">.</span><span class="n">digest</span><span class="p">()</span> <span class="o">==</span> <span class="n">mac2</span><span class="o">.</span><span class="n">digest</span><span class="p">()</span>569<span class="go">True</span>570</pre></div>571</div>572<div class="versionadded">573<p><span class="versionmodified added">Added in version 3.11.</span></p>574</div>575<div class="versionchanged">576<p><span class="versionmodified changed">Changed in version 3.14: </span>Now raises a <a class="reference internal" href="exceptions.html#BlockingIOError" title="BlockingIOError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">BlockingIOError</span></code></a> if the file is opened in non-blocking577mode. Previously, spurious null bytes were added to the digest.</p>578</div>579</dd></dl>580 581</section>582<section id="key-derivation">583<h2>Key derivation<a class="headerlink" href="#key-derivation" title="Link to this heading">¶</a></h2>584<p>Key derivation and key stretching algorithms are designed for secure password585hashing. Naive algorithms such as <code class="docutils literal notranslate"><span class="pre">sha1(password)</span></code> are not resistant against586brute-force attacks. A good password hashing function must be tunable, slow, and587include a <a class="reference external" href="https://en.wikipedia.org/wiki/Salt_%28cryptography%29">salt</a>.</p>588<dl class="py function">589<dt class="sig sig-object py" id="hashlib.pbkdf2_hmac">590<span class="sig-prename descclassname"><span class="pre">hashlib.</span></span><span class="sig-name descname"><span class="pre">pbkdf2_hmac</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">hash_name</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">password</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">salt</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">iterations</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">dklen</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#hashlib.pbkdf2_hmac" title="Link to this definition">¶</a></dt>591<dd><p>The function provides PKCS#5 password-based key derivation function 2. It592uses HMAC as pseudorandom function.</p>593<p>The string <em>hash_name</em> is the desired name of the hash digest algorithm for594HMAC, e.g. ‘sha1’ or ‘sha256’. <em>password</em> and <em>salt</em> are interpreted as595buffers of bytes. Applications and libraries should limit <em>password</em> to596a sensible length (e.g. 1024). <em>salt</em> should be about 16 or more bytes from597a proper source, e.g. <a class="reference internal" href="os.html#os.urandom" title="os.urandom"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.urandom()</span></code></a>.</p>598<p>The number of <em>iterations</em> should be chosen based on the hash algorithm and599computing power. As of 2022, hundreds of thousands of iterations of SHA-256600are suggested. For rationale as to why and how to choose what is best for601your application, read <em>Appendix A.2.2</em> of <a class="reference external" href="https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-132.pdf">NIST-SP-800-132</a>. The answers602on the <a class="reference external" href="https://security.stackexchange.com/questions/3959/recommended-of-iterations-when-using-pbkdf2-sha256/">stackexchange pbkdf2 iterations question</a> explain in detail.</p>603<p><em>dklen</em> is the length of the derived key in bytes. If <em>dklen</em> is <code class="docutils literal notranslate"><span class="pre">None</span></code> then the604digest size of the hash algorithm <em>hash_name</em> is used, e.g. 64 for SHA-512.</p>605<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">hashlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">pbkdf2_hmac</span>606<span class="gp">>>> </span><span class="n">our_app_iters</span> <span class="o">=</span> <span class="mi">500_000</span> <span class="c1"># Application specific, read above.</span>607<span class="gp">>>> </span><span class="n">dk</span> <span class="o">=</span> <span class="n">pbkdf2_hmac</span><span class="p">(</span><span class="s1">'sha256'</span><span class="p">,</span> <span class="sa">b</span><span class="s1">'password'</span><span class="p">,</span> <span class="sa">b</span><span class="s1">'bad salt'</span> <span class="o">*</span> <span class="mi">2</span><span class="p">,</span> <span class="n">our_app_iters</span><span class="p">)</span>608<span class="gp">>>> </span><span class="n">dk</span><span class="o">.</span><span class="n">hex</span><span class="p">()</span>609<span class="go">'15530bba69924174860db778f2c6f8104d3aaf9d26241840c8c4a641c8d000a9'</span>610</pre></div>611</div>612<p>Function only available when Python is compiled with OpenSSL.</p>613<div class="versionadded">614<p><span class="versionmodified added">Added in version 3.4.</span></p>615</div>616<div class="versionchanged">617<p><span class="versionmodified changed">Changed in version 3.12: </span>Function now only available when Python is built with OpenSSL. The slow618pure Python implementation has been removed.</p>619</div>620</dd></dl>621 622<dl class="py function">623<dt class="sig sig-object py" id="hashlib.scrypt">624<span class="sig-prename descclassname"><span class="pre">hashlib.</span></span><span class="sig-name descname"><span class="pre">scrypt</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">password</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">salt</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">n</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">r</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">p</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">maxmem</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">dklen</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">64</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#hashlib.scrypt" title="Link to this definition">¶</a></dt>625<dd><p>The function provides scrypt password-based key derivation function as626defined in <span class="target" id="index-3"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc7914.html"><strong>RFC 7914</strong></a>.</p>627<p><em>password</em> and <em>salt</em> must be <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like objects</span></a>. Applications and libraries should limit <em>password</em>628to a sensible length (e.g. 1024). <em>salt</em> should be about 16 or more629bytes from a proper source, e.g. <a class="reference internal" href="os.html#os.urandom" title="os.urandom"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.urandom()</span></code></a>.</p>630<p><em>n</em> is the CPU/Memory cost factor, <em>r</em> the block size, <em>p</em> parallelization631factor and <em>maxmem</em> limits memory (OpenSSL 1.1.0 defaults to 32 MiB).632<em>dklen</em> is the length of the derived key in bytes.</p>633<div class="versionadded">634<p><span class="versionmodified added">Added in version 3.6.</span></p>635</div>636</dd></dl>637 638</section>639<section id="blake2">640<span id="hashlib-blake2"></span><h2>BLAKE2<a class="headerlink" href="#blake2" title="Link to this heading">¶</a></h2>641<p id="index-4"><a class="reference external" href="https://www.blake2.net">BLAKE2</a> is a cryptographic hash function defined in <span class="target" id="index-5"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc7693.html"><strong>RFC 7693</strong></a> that comes in two642flavors:</p>643<ul class="simple">644<li><p><strong>BLAKE2b</strong>, optimized for 64-bit platforms and produces digests of any size645between 1 and 64 bytes,</p></li>646<li><p><strong>BLAKE2s</strong>, optimized for 8- to 32-bit platforms and produces digests of any647size between 1 and 32 bytes.</p></li>648</ul>649<p>BLAKE2 supports <strong>keyed mode</strong> (a faster and simpler replacement for <a class="reference external" href="https://en.wikipedia.org/wiki/Hash-based_message_authentication_code">HMAC</a>),650<strong>salted hashing</strong>, <strong>personalization</strong>, and <strong>tree hashing</strong>.</p>651<p>Hash objects from this module follow the API of standard library’s652<code class="xref py py-mod docutils literal notranslate"><span class="pre">hashlib</span></code> objects.</p>653<section id="creating-hash-objects">654<h3>Creating hash objects<a class="headerlink" href="#creating-hash-objects" title="Link to this heading">¶</a></h3>655<p>New hash objects are created by calling constructor functions:</p>656<dl class="py function">657<dt class="sig sig-object py" id="hashlib.blake2b">658<span class="sig-prename descclassname"><span class="pre">hashlib.</span></span><span class="sig-name descname"><span class="pre">blake2b</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">data</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">b''</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">digest_size</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">64</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">key</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">b''</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">salt</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">b''</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">person</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">b''</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">fanout</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">depth</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">leaf_size</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">node_offset</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">node_depth</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">inner_size</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">last_node</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">usedforsecurity</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#hashlib.blake2b" title="Link to this definition">¶</a></dt>659<dd></dd></dl>660 661<dl class="py function">662<dt class="sig sig-object py" id="hashlib.blake2s">663<span class="sig-prename descclassname"><span class="pre">hashlib.</span></span><span class="sig-name descname"><span class="pre">blake2s</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">data</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">b''</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">digest_size</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">32</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">key</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">b''</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">salt</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">b''</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">person</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">b''</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">fanout</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">depth</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">leaf_size</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">node_offset</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">node_depth</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">inner_size</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">last_node</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">usedforsecurity</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#hashlib.blake2s" title="Link to this definition">¶</a></dt>664<dd></dd></dl>665 666<p>These functions return the corresponding hash objects for calculating667BLAKE2b or BLAKE2s. They optionally take these general parameters:</p>668<ul class="simple">669<li><p><em>data</em>: initial chunk of data to hash, which must be670<a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a>. It can be passed only as positional argument.</p></li>671<li><p><em>digest_size</em>: size of output digest in bytes.</p></li>672<li><p><em>key</em>: key for keyed hashing (up to 64 bytes for BLAKE2b, up to 32 bytes for673BLAKE2s).</p></li>674<li><p><em>salt</em>: salt for randomized hashing (up to 16 bytes for BLAKE2b, up to 8675bytes for BLAKE2s).</p></li>676<li><p><em>person</em>: personalization string (up to 16 bytes for BLAKE2b, up to 8 bytes677for BLAKE2s).</p></li>678</ul>679<p>The following table shows limits for general parameters (in bytes):</p>680<table class="docutils align-default">681<thead>682<tr class="row-odd"><th class="head"><p>Hash</p></th>683<th class="head"><p>digest_size</p></th>684<th class="head"><p>len(key)</p></th>685<th class="head"><p>len(salt)</p></th>686<th class="head"><p>len(person)</p></th>687</tr>688</thead>689<tbody>690<tr class="row-even"><td><p>BLAKE2b</p></td>691<td><p>64</p></td>692<td><p>64</p></td>693<td><p>16</p></td>694<td><p>16</p></td>695</tr>696<tr class="row-odd"><td><p>BLAKE2s</p></td>697<td><p>32</p></td>698<td><p>32</p></td>699<td><p>8</p></td>700<td><p>8</p></td>701</tr>702</tbody>703</table>704<div class="admonition note">705<p class="admonition-title">Note</p>706<p>BLAKE2 specification defines constant lengths for salt and personalization707parameters, however, for convenience, this implementation accepts byte708strings of any size up to the specified length. If the length of the709parameter is less than specified, it is padded with zeros, thus, for710example, <code class="docutils literal notranslate"><span class="pre">b'salt'</span></code> and <code class="docutils literal notranslate"><span class="pre">b'salt\x00'</span></code> is the same value. (This is not711the case for <em>key</em>.)</p>712</div>713<p>These sizes are available as module <a class="reference internal" href="#constants">constants</a> described below.</p>714<p>Constructor functions also accept the following tree hashing parameters:</p>715<ul class="simple">716<li><p><em>fanout</em>: fanout (0 to 255, 0 if unlimited, 1 in sequential mode).</p></li>717<li><p><em>depth</em>: maximal depth of tree (1 to 255, 255 if unlimited, 1 in718sequential mode).</p></li>719<li><p><em>leaf_size</em>: maximal byte length of leaf (0 to <code class="docutils literal notranslate"><span class="pre">2**32-1</span></code>, 0 if unlimited or in720sequential mode).</p></li>721<li><p><em>node_offset</em>: node offset (0 to <code class="docutils literal notranslate"><span class="pre">2**64-1</span></code> for BLAKE2b, 0 to <code class="docutils literal notranslate"><span class="pre">2**48-1</span></code> for722BLAKE2s, 0 for the first, leftmost, leaf, or in sequential mode).</p></li>723<li><p><em>node_depth</em>: node depth (0 to 255, 0 for leaves, or in sequential mode).</p></li>724<li><p><em>inner_size</em>: inner digest size (0 to 64 for BLAKE2b, 0 to 32 for725BLAKE2s, 0 in sequential mode).</p></li>726<li><p><em>last_node</em>: boolean indicating whether the processed node is the last727one (<code class="docutils literal notranslate"><span class="pre">False</span></code> for sequential mode).</p></li>728</ul>729<figure class="align-default">730<img alt="Explanation of tree mode parameters." class="invert-in-dark-mode" src="../_images/hashlib-blake2-tree.png" />731</figure>732<p>See section 2.10 in <a class="reference external" href="https://www.blake2.net/blake2_20130129.pdf">BLAKE2 specification</a> for comprehensive review of tree733hashing.</p>734</section>735<section id="constants">736<h3>Constants<a class="headerlink" href="#constants" title="Link to this heading">¶</a></h3>737<dl class="py data">738<dt class="sig sig-object py" id="hashlib.blake2b.SALT_SIZE">739<span class="sig-prename descclassname"><span class="pre">blake2b.</span></span><span class="sig-name descname"><span class="pre">SALT_SIZE</span></span><a class="headerlink" href="#hashlib.blake2b.SALT_SIZE" title="Link to this definition">¶</a></dt>740<dd></dd></dl>741 742<dl class="py data">743<dt class="sig sig-object py" id="hashlib.blake2s.SALT_SIZE">744<span class="sig-prename descclassname"><span class="pre">blake2s.</span></span><span class="sig-name descname"><span class="pre">SALT_SIZE</span></span><a class="headerlink" href="#hashlib.blake2s.SALT_SIZE" title="Link to this definition">¶</a></dt>745<dd></dd></dl>746 747<p>Salt length (maximum length accepted by constructors).</p>748<dl class="py data">749<dt class="sig sig-object py" id="hashlib.blake2b.PERSON_SIZE">750<span class="sig-prename descclassname"><span class="pre">blake2b.</span></span><span class="sig-name descname"><span class="pre">PERSON_SIZE</span></span><a class="headerlink" href="#hashlib.blake2b.PERSON_SIZE" title="Link to this definition">¶</a></dt>751<dd></dd></dl>752 753<dl class="py data">754<dt class="sig sig-object py" id="hashlib.blake2s.PERSON_SIZE">755<span class="sig-prename descclassname"><span class="pre">blake2s.</span></span><span class="sig-name descname"><span class="pre">PERSON_SIZE</span></span><a class="headerlink" href="#hashlib.blake2s.PERSON_SIZE" title="Link to this definition">¶</a></dt>756<dd></dd></dl>757 758<p>Personalization string length (maximum length accepted by constructors).</p>759<dl class="py data">760<dt class="sig sig-object py" id="hashlib.blake2b.MAX_KEY_SIZE">761<span class="sig-prename descclassname"><span class="pre">blake2b.</span></span><span class="sig-name descname"><span class="pre">MAX_KEY_SIZE</span></span><a class="headerlink" href="#hashlib.blake2b.MAX_KEY_SIZE" title="Link to this definition">¶</a></dt>762<dd></dd></dl>763 764<dl class="py data">765<dt class="sig sig-object py" id="hashlib.blake2s.MAX_KEY_SIZE">766<span class="sig-prename descclassname"><span class="pre">blake2s.</span></span><span class="sig-name descname"><span class="pre">MAX_KEY_SIZE</span></span><a class="headerlink" href="#hashlib.blake2s.MAX_KEY_SIZE" title="Link to this definition">¶</a></dt>767<dd></dd></dl>768 769<p>Maximum key size.</p>770<dl class="py data">771<dt class="sig sig-object py" id="hashlib.blake2b.MAX_DIGEST_SIZE">772<span class="sig-prename descclassname"><span class="pre">blake2b.</span></span><span class="sig-name descname"><span class="pre">MAX_DIGEST_SIZE</span></span><a class="headerlink" href="#hashlib.blake2b.MAX_DIGEST_SIZE" title="Link to this definition">¶</a></dt>773<dd></dd></dl>774 775<dl class="py data">776<dt class="sig sig-object py" id="hashlib.blake2s.MAX_DIGEST_SIZE">777<span class="sig-prename descclassname"><span class="pre">blake2s.</span></span><span class="sig-name descname"><span class="pre">MAX_DIGEST_SIZE</span></span><a class="headerlink" href="#hashlib.blake2s.MAX_DIGEST_SIZE" title="Link to this definition">¶</a></dt>778<dd></dd></dl>779 780<p>Maximum digest size that the hash function can output.</p>781</section>782<section id="examples">783<h3>Examples<a class="headerlink" href="#examples" title="Link to this heading">¶</a></h3>784<section id="simple-hashing">785<h4>Simple hashing<a class="headerlink" href="#simple-hashing" title="Link to this heading">¶</a></h4>786<p>To calculate hash of some data, you should first construct a hash object by787calling the appropriate constructor function (<a class="reference internal" href="#hashlib.blake2b" title="hashlib.blake2b"><code class="xref py py-func docutils literal notranslate"><span class="pre">blake2b()</span></code></a> or788<a class="reference internal" href="#hashlib.blake2s" title="hashlib.blake2s"><code class="xref py py-func docutils literal notranslate"><span class="pre">blake2s()</span></code></a>), then update it with the data by calling <a class="reference internal" href="#hashlib.hash.update" title="hashlib.hash.update"><code class="xref py py-meth docutils literal notranslate"><span class="pre">update()</span></code></a> on the789object, and, finally, get the digest out of the object by calling790<a class="reference internal" href="#hashlib.hash.digest" title="hashlib.hash.digest"><code class="xref py py-meth docutils literal notranslate"><span class="pre">digest()</span></code></a> (or <a class="reference internal" href="#hashlib.hash.hexdigest" title="hashlib.hash.hexdigest"><code class="xref py py-meth docutils literal notranslate"><span class="pre">hexdigest()</span></code></a> for hex-encoded string).</p>791<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">hashlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">blake2b</span>792<span class="gp">>>> </span><span class="n">h</span> <span class="o">=</span> <span class="n">blake2b</span><span class="p">()</span>793<span class="gp">>>> </span><span class="n">h</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="sa">b</span><span class="s1">'Hello world'</span><span class="p">)</span>794<span class="gp">>>> </span><span class="n">h</span><span class="o">.</span><span class="n">hexdigest</span><span class="p">()</span>795<span class="go">'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'</span>796</pre></div>797</div>798<p>As a shortcut, you can pass the first chunk of data to update directly to the799constructor as the positional argument:</p>800<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">hashlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">blake2b</span>801<span class="gp">>>> </span><span class="n">blake2b</span><span class="p">(</span><span class="sa">b</span><span class="s1">'Hello world'</span><span class="p">)</span><span class="o">.</span><span class="n">hexdigest</span><span class="p">()</span>802<span class="go">'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'</span>803</pre></div>804</div>805<p>You can call <a class="reference internal" href="#hashlib.hash.update" title="hashlib.hash.update"><code class="xref py py-meth docutils literal notranslate"><span class="pre">hash.update()</span></code></a> as many times as you need to iteratively806update the hash:</p>807<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">hashlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">blake2b</span>808<span class="gp">>>> </span><span class="n">items</span> <span class="o">=</span> <span class="p">[</span><span class="sa">b</span><span class="s1">'Hello'</span><span class="p">,</span> <span class="sa">b</span><span class="s1">' '</span><span class="p">,</span> <span class="sa">b</span><span class="s1">'world'</span><span class="p">]</span>809<span class="gp">>>> </span><span class="n">h</span> <span class="o">=</span> <span class="n">blake2b</span><span class="p">()</span>810<span class="gp">>>> </span><span class="k">for</span> <span class="n">item</span> <span class="ow">in</span> <span class="n">items</span><span class="p">:</span>811<span class="gp">... </span> <span class="n">h</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="n">item</span><span class="p">)</span>812<span class="gp">...</span>813<span class="gp">>>> </span><span class="n">h</span><span class="o">.</span><span class="n">hexdigest</span><span class="p">()</span>814<span class="go">'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'</span>815</pre></div>816</div>817</section>818<section id="using-different-digest-sizes">819<h4>Using different digest sizes<a class="headerlink" href="#using-different-digest-sizes" title="Link to this heading">¶</a></h4>820<p>BLAKE2 has configurable size of digests up to 64 bytes for BLAKE2b and up to 32821bytes for BLAKE2s. For example, to replace SHA-1 with BLAKE2b without changing822the size of output, we can tell BLAKE2b to produce 20-byte digests:</p>823<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">hashlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">blake2b</span>824<span class="gp">>>> </span><span class="n">h</span> <span class="o">=</span> <span class="n">blake2b</span><span class="p">(</span><span class="n">digest_size</span><span class="o">=</span><span class="mi">20</span><span class="p">)</span>825<span class="gp">>>> </span><span class="n">h</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="sa">b</span><span class="s1">'Replacing SHA1 with the more secure function'</span><span class="p">)</span>826<span class="gp">>>> </span><span class="n">h</span><span class="o">.</span><span class="n">hexdigest</span><span class="p">()</span>827<span class="go">'d24f26cf8de66472d58d4e1b1774b4c9158b1f4c'</span>828<span class="gp">>>> </span><span class="n">h</span><span class="o">.</span><span class="n">digest_size</span>829<span class="go">20</span>830<span class="gp">>>> </span><span class="nb">len</span><span class="p">(</span><span class="n">h</span><span class="o">.</span><span class="n">digest</span><span class="p">())</span>831<span class="go">20</span>832</pre></div>833</div>834<p>Hash objects with different digest sizes have completely different outputs835(shorter hashes are <em>not</em> prefixes of longer hashes); BLAKE2b and BLAKE2s836produce different outputs even if the output length is the same:</p>837<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">hashlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">blake2b</span><span class="p">,</span> <span class="n">blake2s</span>838<span class="gp">>>> </span><span class="n">blake2b</span><span class="p">(</span><span class="n">digest_size</span><span class="o">=</span><span class="mi">10</span><span class="p">)</span><span class="o">.</span><span class="n">hexdigest</span><span class="p">()</span>839<span class="go">'6fa1d8fcfd719046d762'</span>840<span class="gp">>>> </span><span class="n">blake2b</span><span class="p">(</span><span class="n">digest_size</span><span class="o">=</span><span class="mi">11</span><span class="p">)</span><span class="o">.</span><span class="n">hexdigest</span><span class="p">()</span>841<span class="go">'eb6ec15daf9546254f0809'</span>842<span class="gp">>>> </span><span class="n">blake2s</span><span class="p">(</span><span class="n">digest_size</span><span class="o">=</span><span class="mi">10</span><span class="p">)</span><span class="o">.</span><span class="n">hexdigest</span><span class="p">()</span>843<span class="go">'1bf21a98c78a1c376ae9'</span>844<span class="gp">>>> </span><span class="n">blake2s</span><span class="p">(</span><span class="n">digest_size</span><span class="o">=</span><span class="mi">11</span><span class="p">)</span><span class="o">.</span><span class="n">hexdigest</span><span class="p">()</span>845<span class="go">'567004bf96e4a25773ebf4'</span>846</pre></div>847</div>848</section>849<section id="keyed-hashing">850<h4>Keyed hashing<a class="headerlink" href="#keyed-hashing" title="Link to this heading">¶</a></h4>851<p>Keyed hashing can be used for authentication as a faster and simpler852replacement for <a class="reference external" href="https://en.wikipedia.org/wiki/HMAC">Hash-based message authentication code</a> (HMAC).853BLAKE2 can be securely used in prefix-MAC mode thanks to the854indifferentiability property inherited from BLAKE.</p>855<p>This example shows how to get a (hex-encoded) 128-bit authentication code for856message <code class="docutils literal notranslate"><span class="pre">b'message</span> <span class="pre">data'</span></code> with key <code class="docutils literal notranslate"><span class="pre">b'pseudorandom</span> <span class="pre">key'</span></code>:</p>857<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">hashlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">blake2b</span>858<span class="gp">>>> </span><span class="n">h</span> <span class="o">=</span> <span class="n">blake2b</span><span class="p">(</span><span class="n">key</span><span class="o">=</span><span class="sa">b</span><span class="s1">'pseudorandom key'</span><span class="p">,</span> <span class="n">digest_size</span><span class="o">=</span><span class="mi">16</span><span class="p">)</span>859<span class="gp">>>> </span><span class="n">h</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="sa">b</span><span class="s1">'message data'</span><span class="p">)</span>860<span class="gp">>>> </span><span class="n">h</span><span class="o">.</span><span class="n">hexdigest</span><span class="p">()</span>861<span class="go">'3d363ff7401e02026f4a4687d4863ced'</span>862</pre></div>863</div>864<p>As a practical example, a web application can symmetrically sign cookies sent865to users and later verify them to make sure they weren’t tampered with:</p>866<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">hashlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">blake2b</span>867<span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">hmac</span><span class="w"> </span><span class="kn">import</span> <span class="n">compare_digest</span>868<span class="gp">>>></span>869<span class="gp">>>> </span><span class="n">SECRET_KEY</span> <span class="o">=</span> <span class="sa">b</span><span class="s1">'pseudorandomly generated server secret key'</span>870<span class="gp">>>> </span><span class="n">AUTH_SIZE</span> <span class="o">=</span> <span class="mi">16</span>871<span class="gp">>>></span>872<span class="gp">>>> </span><span class="k">def</span><span class="w"> </span><span class="nf">sign</span><span class="p">(</span><span class="n">cookie</span><span class="p">):</span>873<span class="gp">... </span> <span class="n">h</span> <span class="o">=</span> <span class="n">blake2b</span><span class="p">(</span><span class="n">digest_size</span><span class="o">=</span><span class="n">AUTH_SIZE</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="n">SECRET_KEY</span><span class="p">)</span>874<span class="gp">... </span> <span class="n">h</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="n">cookie</span><span class="p">)</span>875<span class="gp">... </span> <span class="k">return</span> <span class="n">h</span><span class="o">.</span><span class="n">hexdigest</span><span class="p">()</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s1">'utf-8'</span><span class="p">)</span>876<span class="gp">>>></span>877<span class="gp">>>> </span><span class="k">def</span><span class="w"> </span><span class="nf">verify</span><span class="p">(</span><span class="n">cookie</span><span class="p">,</span> <span class="n">sig</span><span class="p">):</span>878<span class="gp">... </span> <span class="n">good_sig</span> <span class="o">=</span> <span class="n">sign</span><span class="p">(</span><span class="n">cookie</span><span class="p">)</span>879<span class="gp">... </span> <span class="k">return</span> <span class="n">compare_digest</span><span class="p">(</span><span class="n">good_sig</span><span class="p">,</span> <span class="n">sig</span><span class="p">)</span>880<span class="gp">>>></span>881<span class="gp">>>> </span><span class="n">cookie</span> <span class="o">=</span> <span class="sa">b</span><span class="s1">'user-alice'</span>882<span class="gp">>>> </span><span class="n">sig</span> <span class="o">=</span> <span class="n">sign</span><span class="p">(</span><span class="n">cookie</span><span class="p">)</span>883<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="s2">"</span><span class="si">{0}</span><span class="s2">,</span><span class="si">{1}</span><span class="s2">"</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">cookie</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s1">'utf-8'</span><span class="p">),</span> <span class="n">sig</span><span class="p">))</span>884<span class="go">user-alice,b'43b3c982cf697e0c5ab22172d1ca7421'</span>885<span class="gp">>>> </span><span class="n">verify</span><span class="p">(</span><span class="n">cookie</span><span class="p">,</span> <span class="n">sig</span><span class="p">)</span>886<span class="go">True</span>887<span class="gp">>>> </span><span class="n">verify</span><span class="p">(</span><span class="sa">b</span><span class="s1">'user-bob'</span><span class="p">,</span> <span class="n">sig</span><span class="p">)</span>888<span class="go">False</span>889<span class="gp">>>> </span><span class="n">verify</span><span class="p">(</span><span class="n">cookie</span><span class="p">,</span> <span class="sa">b</span><span class="s1">'0102030405060708090a0b0c0d0e0f00'</span><span class="p">)</span>890<span class="go">False</span>891</pre></div>892</div>893<p>Even though there’s a native keyed hashing mode, BLAKE2 can, of course, be used894in HMAC construction with <a class="reference internal" href="hmac.html#module-hmac" title="hmac: Keyed-Hashing for Message Authentication (HMAC) implementation"><code class="xref py py-mod docutils literal notranslate"><span class="pre">hmac</span></code></a> module:</p>895<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span><span class="w"> </span><span class="nn">hmac</span><span class="o">,</span><span class="w"> </span><span class="nn">hashlib</span>896<span class="gp">>>> </span><span class="n">m</span> <span class="o">=</span> <span class="n">hmac</span><span class="o">.</span><span class="n">new</span><span class="p">(</span><span class="sa">b</span><span class="s1">'secret key'</span><span class="p">,</span> <span class="n">digestmod</span><span class="o">=</span><span class="n">hashlib</span><span class="o">.</span><span class="n">blake2s</span><span class="p">)</span>897<span class="gp">>>> </span><span class="n">m</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="sa">b</span><span class="s1">'message'</span><span class="p">)</span>898<span class="gp">>>> </span><span class="n">m</span><span class="o">.</span><span class="n">hexdigest</span><span class="p">()</span>899<span class="go">'e3c8102868d28b5ff85fc35dda07329970d1a01e273c37481326fe0c861c8142'</span>900</pre></div>901</div>902</section>903<section id="randomized-hashing">904<h4>Randomized hashing<a class="headerlink" href="#randomized-hashing" title="Link to this heading">¶</a></h4>905<p>By setting <em>salt</em> parameter users can introduce randomization to the hash906function. Randomized hashing is useful for protecting against collision attacks907on the hash function used in digital signatures.</p>908<blockquote>909<div><p>Randomized hashing is designed for situations where one party, the message910preparer, generates all or part of a message to be signed by a second911party, the message signer. If the message preparer is able to find912cryptographic hash function collisions (i.e., two messages producing the913same hash value), then they might prepare meaningful versions of the message914that would produce the same hash value and digital signature, but with915different results (e.g., transferring $1,000,000 to an account, rather than916$10). Cryptographic hash functions have been designed with collision917resistance as a major goal, but the current concentration on attacking918cryptographic hash functions may result in a given cryptographic hash919function providing less collision resistance than expected. Randomized920hashing offers the signer additional protection by reducing the likelihood921that a preparer can generate two or more messages that ultimately yield the922same hash value during the digital signature generation process — even if923it is practical to find collisions for the hash function. However, the use924of randomized hashing may reduce the amount of security provided by a925digital signature when all portions of the message are prepared926by the signer.</p>927<p>(<a class="reference external" href="https://csrc.nist.gov/pubs/sp/800/106/final">NIST SP-800-106 “Randomized Hashing for Digital Signatures”</a>)</p>928</div></blockquote>929<p>In BLAKE2 the salt is processed as a one-time input to the hash function during930initialization, rather than as an input to each compression function.</p>931<div class="admonition warning">932<p class="admonition-title">Warning</p>933<p><em>Salted hashing</em> (or just hashing) with BLAKE2 or any other general-purpose934cryptographic hash function, such as SHA-256, is not suitable for hashing935passwords. See <a class="reference external" href="https://www.blake2.net/#qa">BLAKE2 FAQ</a> for more936information.</p>937</div>938<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span><span class="w"> </span><span class="nn">os</span>939<span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">hashlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">blake2b</span>940<span class="gp">>>> </span><span class="n">msg</span> <span class="o">=</span> <span class="sa">b</span><span class="s1">'some message'</span>941<span class="gp">>>> </span><span class="c1"># Calculate the first hash with a random salt.</span>942<span class="gp">>>> </span><span class="n">salt1</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">urandom</span><span class="p">(</span><span class="n">blake2b</span><span class="o">.</span><span class="n">SALT_SIZE</span><span class="p">)</span>943<span class="gp">>>> </span><span class="n">h1</span> <span class="o">=</span> <span class="n">blake2b</span><span class="p">(</span><span class="n">salt</span><span class="o">=</span><span class="n">salt1</span><span class="p">)</span>944<span class="gp">>>> </span><span class="n">h1</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="n">msg</span><span class="p">)</span>945<span class="gp">>>> </span><span class="c1"># Calculate the second hash with a different random salt.</span>946<span class="gp">>>> </span><span class="n">salt2</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">urandom</span><span class="p">(</span><span class="n">blake2b</span><span class="o">.</span><span class="n">SALT_SIZE</span><span class="p">)</span>947<span class="gp">>>> </span><span class="n">h2</span> <span class="o">=</span> <span class="n">blake2b</span><span class="p">(</span><span class="n">salt</span><span class="o">=</span><span class="n">salt2</span><span class="p">)</span>948<span class="gp">>>> </span><span class="n">h2</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="n">msg</span><span class="p">)</span>949<span class="gp">>>> </span><span class="c1"># The digests are different.</span>950<span class="gp">>>> </span><span class="n">h1</span><span class="o">.</span><span class="n">digest</span><span class="p">()</span> <span class="o">!=</span> <span class="n">h2</span><span class="o">.</span><span class="n">digest</span><span class="p">()</span>951<span class="go">True</span>952</pre></div>953</div>954</section>955<section id="personalization">956<h4>Personalization<a class="headerlink" href="#personalization" title="Link to this heading">¶</a></h4>957<p>Sometimes it is useful to force hash function to produce different digests for958the same input for different purposes. Quoting the authors of the Skein hash959function:</p>960<blockquote>961<div><p>We recommend that all application designers seriously consider doing this;962we have seen many protocols where a hash that is computed in one part of963the protocol can be used in an entirely different part because two hash964computations were done on similar or related data, and the attacker can965force the application to make the hash inputs the same. Personalizing each966hash function used in the protocol summarily stops this type of attack.</p>967<p>(<a class="reference external" href="https://www.schneier.com/wp-content/uploads/2016/02/skein.pdf">The Skein Hash Function Family</a>,968p. 21)</p>969</div></blockquote>970<p>BLAKE2 can be personalized by passing bytes to the <em>person</em> argument:</p>971<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">hashlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">blake2b</span>972<span class="gp">>>> </span><span class="n">FILES_HASH_PERSON</span> <span class="o">=</span> <span class="sa">b</span><span class="s1">'MyApp Files Hash'</span>973<span class="gp">>>> </span><span class="n">BLOCK_HASH_PERSON</span> <span class="o">=</span> <span class="sa">b</span><span class="s1">'MyApp Block Hash'</span>974<span class="gp">>>> </span><span class="n">h</span> <span class="o">=</span> <span class="n">blake2b</span><span class="p">(</span><span class="n">digest_size</span><span class="o">=</span><span class="mi">32</span><span class="p">,</span> <span class="n">person</span><span class="o">=</span><span class="n">FILES_HASH_PERSON</span><span class="p">)</span>975<span class="gp">>>> </span><span class="n">h</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="sa">b</span><span class="s1">'the same content'</span><span class="p">)</span>976<span class="gp">>>> </span><span class="n">h</span><span class="o">.</span><span class="n">hexdigest</span><span class="p">()</span>977<span class="go">'20d9cd024d4fb086aae819a1432dd2466de12947831b75c5a30cf2676095d3b4'</span>978<span class="gp">>>> </span><span class="n">h</span> <span class="o">=</span> <span class="n">blake2b</span><span class="p">(</span><span class="n">digest_size</span><span class="o">=</span><span class="mi">32</span><span class="p">,</span> <span class="n">person</span><span class="o">=</span><span class="n">BLOCK_HASH_PERSON</span><span class="p">)</span>979<span class="gp">>>> </span><span class="n">h</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="sa">b</span><span class="s1">'the same content'</span><span class="p">)</span>980<span class="gp">>>> </span><span class="n">h</span><span class="o">.</span><span class="n">hexdigest</span><span class="p">()</span>981<span class="go">'cf68fb5761b9c44e7878bfb2c4c9aea52264a80b75005e65619778de59f383a3'</span>982</pre></div>983</div>984<p>Personalization together with the keyed mode can also be used to derive different985keys from a single one.</p>986<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">hashlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">blake2s</span>987<span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">base64</span><span class="w"> </span><span class="kn">import</span> <span class="n">b64decode</span><span class="p">,</span> <span class="n">b64encode</span>988<span class="gp">>>> </span><span class="n">orig_key</span> <span class="o">=</span> <span class="n">b64decode</span><span class="p">(</span><span class="sa">b</span><span class="s1">'Rm5EPJai72qcK3RGBpW3vPNfZy5OZothY+kHY6h21KM='</span><span class="p">)</span>989<span class="gp">>>> </span><span class="n">enc_key</span> <span class="o">=</span> <span class="n">blake2s</span><span class="p">(</span><span class="n">key</span><span class="o">=</span><span class="n">orig_key</span><span class="p">,</span> <span class="n">person</span><span class="o">=</span><span class="sa">b</span><span class="s1">'kEncrypt'</span><span class="p">)</span><span class="o">.</span><span class="n">digest</span><span class="p">()</span>990<span class="gp">>>> </span><span class="n">mac_key</span> <span class="o">=</span> <span class="n">blake2s</span><span class="p">(</span><span class="n">key</span><span class="o">=</span><span class="n">orig_key</span><span class="p">,</span> <span class="n">person</span><span class="o">=</span><span class="sa">b</span><span class="s1">'kMAC'</span><span class="p">)</span><span class="o">.</span><span class="n">digest</span><span class="p">()</span>991<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">b64encode</span><span class="p">(</span><span class="n">enc_key</span><span class="p">)</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s1">'utf-8'</span><span class="p">))</span>992<span class="go">rbPb15S/Z9t+agffno5wuhB77VbRi6F9Iv2qIxU7WHw=</span>993<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">b64encode</span><span class="p">(</span><span class="n">mac_key</span><span class="p">)</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s1">'utf-8'</span><span class="p">))</span>994<span class="go">G9GtHFE1YluXY1zWPlYk1e/nWfu0WSEb0KRcjhDeP/o=</span>995</pre></div>996</div>997</section>998<section id="tree-mode">999<h4>Tree mode<a class="headerlink" href="#tree-mode" title="Link to this heading">¶</a></h4>1000<p>Here’s an example of hashing a minimal tree with two leaf nodes:</p>1001<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span> <span class="mi">10</span>1002 <span class="o">/</span> \1003<span class="mi">00</span> <span class="mi">01</span>1004</pre></div>1005</div>1006<p>This example uses 64-byte internal digests, and returns the 32-byte final1007digest:</p>1008<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">hashlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">blake2b</span>1009<span class="gp">>>></span>1010<span class="gp">>>> </span><span class="n">FANOUT</span> <span class="o">=</span> <span class="mi">2</span>1011<span class="gp">>>> </span><span class="n">DEPTH</span> <span class="o">=</span> <span class="mi">2</span>1012<span class="gp">>>> </span><span class="n">LEAF_SIZE</span> <span class="o">=</span> <span class="mi">4096</span>1013<span class="gp">>>> </span><span class="n">INNER_SIZE</span> <span class="o">=</span> <span class="mi">64</span>1014<span class="gp">>>></span>1015<span class="gp">>>> </span><span class="n">buf</span> <span class="o">=</span> <span class="nb">bytearray</span><span class="p">(</span><span class="mi">6000</span><span class="p">)</span>1016<span class="gp">>>></span>1017<span class="gp">>>> </span><span class="c1"># Left leaf</span>1018<span class="gp">... </span><span class="n">h00</span> <span class="o">=</span> <span class="n">blake2b</span><span class="p">(</span><span class="n">buf</span><span class="p">[</span><span class="mi">0</span><span class="p">:</span><span class="n">LEAF_SIZE</span><span class="p">],</span> <span class="n">fanout</span><span class="o">=</span><span class="n">FANOUT</span><span class="p">,</span> <span class="n">depth</span><span class="o">=</span><span class="n">DEPTH</span><span class="p">,</span>1019<span class="gp">... </span> <span class="n">leaf_size</span><span class="o">=</span><span class="n">LEAF_SIZE</span><span class="p">,</span> <span class="n">inner_size</span><span class="o">=</span><span class="n">INNER_SIZE</span><span class="p">,</span>1020<span class="gp">... </span> <span class="n">node_offset</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">node_depth</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">last_node</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>1021<span class="gp">>>> </span><span class="c1"># Right leaf</span>1022<span class="gp">... </span><span class="n">h01</span> <span class="o">=</span> <span class="n">blake2b</span><span class="p">(</span><span class="n">buf</span><span class="p">[</span><span class="n">LEAF_SIZE</span><span class="p">:],</span> <span class="n">fanout</span><span class="o">=</span><span class="n">FANOUT</span><span class="p">,</span> <span class="n">depth</span><span class="o">=</span><span class="n">DEPTH</span><span class="p">,</span>1023<span class="gp">... </span> <span class="n">leaf_size</span><span class="o">=</span><span class="n">LEAF_SIZE</span><span class="p">,</span> <span class="n">inner_size</span><span class="o">=</span><span class="n">INNER_SIZE</span><span class="p">,</span>1024<span class="gp">... </span> <span class="n">node_offset</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">node_depth</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">last_node</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>1025<span class="gp">>>> </span><span class="c1"># Root node</span>1026<span class="gp">... </span><span class="n">h10</span> <span class="o">=</span> <span class="n">blake2b</span><span class="p">(</span><span class="n">digest_size</span><span class="o">=</span><span class="mi">32</span><span class="p">,</span> <span class="n">fanout</span><span class="o">=</span><span class="n">FANOUT</span><span class="p">,</span> <span class="n">depth</span><span class="o">=</span><span class="n">DEPTH</span><span class="p">,</span>1027<span class="gp">... </span> <span class="n">leaf_size</span><span class="o">=</span><span class="n">LEAF_SIZE</span><span class="p">,</span> <span class="n">inner_size</span><span class="o">=</span><span class="n">INNER_SIZE</span><span class="p">,</span>1028<span class="gp">... </span> <span class="n">node_offset</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">node_depth</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">last_node</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>1029<span class="gp">>>> </span><span class="n">h10</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="n">h00</span><span class="o">.</span><span class="n">digest</span><span class="p">())</span>1030<span class="gp">>>> </span><span class="n">h10</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="n">h01</span><span class="o">.</span><span class="n">digest</span><span class="p">())</span>1031<span class="gp">>>> </span><span class="n">h10</span><span class="o">.</span><span class="n">hexdigest</span><span class="p">()</span>1032<span class="go">'3ad2a9b37c6070e374c7a8c508fe20ca86b6ed54e286e93a0318e95e881db5aa'</span>1033</pre></div>1034</div>1035</section>1036</section>1037<section id="credits">1038<h3>Credits<a class="headerlink" href="#credits" title="Link to this heading">¶</a></h3>1039<p><a class="reference external" href="https://www.blake2.net">BLAKE2</a> was designed by <em>Jean-Philippe Aumasson</em>, <em>Samuel Neves</em>, <em>Zooko1040Wilcox-O’Hearn</em>, and <em>Christian Winnerlein</em> based on <a class="reference external" href="https://en.wikipedia.org/wiki/Secure_Hash_Algorithms">SHA-3</a> finalist <a class="reference external" href="https://web.archive.org/web/20200918190133/https://131002.net/blake/">BLAKE</a>1041created by <em>Jean-Philippe Aumasson</em>, <em>Luca Henzen</em>, <em>Willi Meier</em>, and1042<em>Raphael C.-W. Phan</em>.</p>1043<p>It uses core algorithm from <a class="reference external" href="https://cr.yp.to/chacha.html">ChaCha</a> cipher designed by <em>Daniel J. Bernstein</em>.</p>1044<p>The stdlib implementation is based on <a class="reference external" href="https://pythonhosted.org/pyblake2/">pyblake2</a> module. It was written by1045<em>Dmitry Chestnykh</em> based on C implementation written by <em>Samuel Neves</em>. The1046documentation was copied from <a class="reference external" href="https://pythonhosted.org/pyblake2/">pyblake2</a> and written by <em>Dmitry Chestnykh</em>.</p>1047<p>The C code was partly rewritten for Python by <em>Christian Heimes</em>.</p>1048<p>The following public domain dedication applies for both C hash function1049implementation, extension code, and this documentation:</p>1050<blockquote>1051<div><p>To the extent possible under law, the author(s) have dedicated all copyright1052and related and neighboring rights to this software to the public domain1053worldwide. This software is distributed without any warranty.</p>1054<p>You should have received a copy of the CC0 Public Domain Dedication along1055with this software. If not, see1056<a class="reference external" href="https://creativecommons.org/publicdomain/zero/1.0/">https://creativecommons.org/publicdomain/zero/1.0/</a>.</p>1057</div></blockquote>1058<p>The following people have helped with development or contributed their changes1059to the project and the public domain according to the Creative Commons Public1060Domain Dedication 1.0 Universal:</p>1061<ul class="simple">1062<li><p><em>Alexandr Sokolovskiy</em></p></li>1063</ul>1064<div class="admonition seealso" id="hashlib-seealso">1065<p class="admonition-title">See also</p>1066<dl class="simple">1067<dt>Module <a class="reference internal" href="hmac.html#module-hmac" title="hmac: Keyed-Hashing for Message Authentication (HMAC) implementation"><code class="xref py py-mod docutils literal notranslate"><span class="pre">hmac</span></code></a></dt><dd><p>A module to generate message authentication codes using hashes.</p>1068</dd>1069<dt>Module <a class="reference internal" href="base64.html#module-base64" title="base64: RFC 4648: Base16, Base32, Base64 Data Encodings; Base85 and Ascii85"><code class="xref py py-mod docutils literal notranslate"><span class="pre">base64</span></code></a></dt><dd><p>Another way to encode binary hashes for non-binary environments.</p>1070</dd>1071<dt><a class="reference external" href="https://nvlpubs.nist.gov/nistpubs/fips/nist.fips.180-4.pdf">https://nvlpubs.nist.gov/nistpubs/fips/nist.fips.180-4.pdf</a></dt><dd><p>The FIPS 180-4 publication on Secure Hash Algorithms.</p>1072</dd>1073<dt><a class="reference external" href="https://csrc.nist.gov/pubs/fips/202/final">https://csrc.nist.gov/pubs/fips/202/final</a></dt><dd><p>The FIPS 202 publication on the SHA-3 Standard.</p>1074</dd>1075<dt><a class="reference external" href="https://www.blake2.net/">https://www.blake2.net/</a></dt><dd><p>Official BLAKE2 website.</p>1076</dd>1077<dt><a class="reference external" href="https://en.wikipedia.org/wiki/Cryptographic_hash_function">https://en.wikipedia.org/wiki/Cryptographic_hash_function</a></dt><dd><p>Wikipedia article with information on which algorithms have known issues1078and what that means regarding their use.</p>1079</dd>1080<dt><a class="reference external" href="https://www.ietf.org/rfc/rfc8018.txt">https://www.ietf.org/rfc/rfc8018.txt</a></dt><dd><p>PKCS #5: Password-Based Cryptography Specification Version 2.1</p>1081</dd>1082<dt><a class="reference external" href="https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-132.pdf">https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-132.pdf</a></dt><dd><p>NIST Recommendation for Password-Based Key Derivation.</p>1083</dd>1084</dl>1085</div>1086</section>1087</section>1088</section>1089 1090 1091 <div class="clearer"></div>1092 </div>1093 </div>1094 </div>1095 <div class="sphinxsidebar" role="navigation" aria-label="Main">1096 <div class="sphinxsidebarwrapper">1097 <div>1098 <h3><a href="../contents.html">Table of Contents</a></h3>1099 <ul>1100<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">hashlib</span></code> — Secure hashes and message digests</a><ul>1101<li><a class="reference internal" href="#hash-algorithms">Hash algorithms</a></li>1102<li><a class="reference internal" href="#usage">Usage</a></li>1103<li><a class="reference internal" href="#constructors">Constructors</a></li>1104<li><a class="reference internal" href="#attributes">Attributes</a></li>1105<li><a class="reference internal" href="#hash-objects">Hash Objects</a></li>1106<li><a class="reference internal" href="#shake-variable-length-digests">SHAKE variable length digests</a></li>1107<li><a class="reference internal" href="#file-hashing">File hashing</a></li>1108<li><a class="reference internal" href="#key-derivation">Key derivation</a></li>1109<li><a class="reference internal" href="#blake2">BLAKE2</a><ul>1110<li><a class="reference internal" href="#creating-hash-objects">Creating hash objects</a></li>1111<li><a class="reference internal" href="#constants">Constants</a></li>1112<li><a class="reference internal" href="#examples">Examples</a><ul>1113<li><a class="reference internal" href="#simple-hashing">Simple hashing</a></li>1114<li><a class="reference internal" href="#using-different-digest-sizes">Using different digest sizes</a></li>1115<li><a class="reference internal" href="#keyed-hashing">Keyed hashing</a></li>1116<li><a class="reference internal" href="#randomized-hashing">Randomized hashing</a></li>1117<li><a class="reference internal" href="#personalization">Personalization</a></li>1118<li><a class="reference internal" href="#tree-mode">Tree mode</a></li>1119</ul>1120</li>1121<li><a class="reference internal" href="#credits">Credits</a></li>1122</ul>1123</li>1124</ul>1125</li>1126</ul>1127 1128 </div>1129 <div>1130 <h4>Previous topic</h4>1131 <p class="topless"><a href="crypto.html"1132 title="previous chapter">Cryptographic Services</a></p>1133 </div>1134 <div>1135 <h4>Next topic</h4>1136 <p class="topless"><a href="hmac.html"1137 title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">hmac</span></code> — Keyed-Hashing for Message Authentication</a></p>1138 </div>1139 <script>1140 document.addEventListener('DOMContentLoaded', () => {1141 const title = document.querySelector('meta[property="og:title"]').content;1142 const elements = document.querySelectorAll('.improvepage');1143 const pageurl = window.location.href.split('?')[0];1144 elements.forEach(element => {1145 const url = new URL(element.href.split('?')[0].replace("-nojs", ""));1146 url.searchParams.set('pagetitle', title);1147 url.searchParams.set('pageurl', pageurl);1148 url.searchParams.set('pagesource', "library/hashlib.rst");1149 element.href = url.toString();1150 });1151 });1152 </script>1153 <div role="note" aria-label="source link">1154 <h3>This page</h3>1155 <ul class="this-page-menu">1156 <li><a href="../bugs.html">Report a bug</a></li>1157 <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>1158 <li>1159 <a href="https://github.com/python/cpython/blob/main/Doc/library/hashlib.rst?plain=1"1160 rel="nofollow">Show source1161 </a>1162 </li>1163 1164 </ul>1165 </div>1166 </div>1167<div id="sidebarbutton" title="Collapse sidebar">1168<span>«</span>1169</div>1170 1171 </div>1172 <div class="clearer"></div>1173 </div> 1174 <div class="related" role="navigation" aria-label="Related">1175 <h3>Navigation</h3>1176 <ul>1177 <li class="right" style="margin-right: 10px">1178 <a href="../genindex.html" title="General Index"1179 >index</a></li>1180 <li class="right" >1181 <a href="../py-modindex.html" title="Python Module Index"1182 >modules</a> |</li>1183 <li class="right" >1184 <a href="hmac.html" title="hmac — Keyed-Hashing for Message Authentication"1185 >next</a> |</li>1186 <li class="right" >1187 <a href="crypto.html" title="Cryptographic Services"1188 >previous</a> |</li>1189 1190 <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>1191 <li><a href="https://www.python.org/">Python</a> »</li>1192 <li class="switchers">1193 <div class="language_switcher_placeholder"></div>1194 <div class="version_switcher_placeholder"></div>1195 </li>1196 <li>1197 1198 </li>1199 <li id="cpython-language-and-version">1200 <a href="../index.html">3.15.0a6 Documentation</a> »