TrustedFirmware Git Browser
Code Review Sign In
review.trustedfirmware.org / mirror / mbed-crypto / b0dbbb12c1b13fc6b262fa0ad65089a997bcd0d1 / . / docs / 1.0.1 / html / api / ops / hashes.html
blob: 7a13d682df807c0e58584b1d380618fbc008c295 [file] [log] [blame]
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]1
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]2<!DOCTYPE html>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]3
4<html xmlns="http://www.w3.org/1999/xhtml">
5 <head>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]6 <meta charset="utf-8" />
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]7 <title>10.2. Message digests &#8212; PSA Crypto API 1.0.1 documentation</title>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]8 <link rel="stylesheet" href="../../_static/alabaster.css" type="text/css" />
9 <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]10 <script type="text/javascript" id="documentation_options" data-url_root="../../" src="../../_static/documentation_options.js"></script>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]11 <script type="text/javascript" src="../../_static/jquery.js"></script>
12 <script type="text/javascript" src="../../_static/underscore.js"></script>
13 <script type="text/javascript" src="../../_static/doctools.js"></script>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]14 <script type="text/javascript" src="../../_static/language_data.js"></script>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]15 <link rel="author" title="About these documents" href="../../about.html" />
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]16 <link rel="index" title="Index" href="../../genindex.html" />
17 <link rel="search" title="Search" href="../../search.html" />
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]18 <link rel="next" title="10.3. Message authentication codes (MAC)" href="macs.html" />
19 <link rel="prev" title="10.1. Algorithms" href="algorithms.html" />
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]20
21 <link rel="stylesheet" href="../../_static/custom.css" type="text/css" />
22
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]23
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]24 <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
25
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]26 </head><body>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]27
28
29 <div class="document">
30 <div class="documentwrapper">
31 <div class="bodywrapper">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]32
33
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]34 <div class="body" role="main">
35
36 <div class="section" id="message-digests">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]37<span id="hashes"></span><h1>10.2. Message digests</h1>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]38<div class="section" id="hash-algorithms">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]39<span id="id1"></span><h2>10.2.1. Hash algorithms</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]40<div class="section" id="PSA_ALG_MD2">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]41<span id="c.PSA_ALG_MD2"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_ALG_MD2</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]42<p>The MD2 message-digest algorithm.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]43<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_ALG_MD2" title="PSA_ALG_MD2">PSA_ALG_MD2</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x02000001)</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]44<div class="admonition warning">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]45<p class="admonition-title">Warning</p>
46<p>The MD2 hash is weak and deprecated and is only recommended for use in legacy protocols.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]47</div>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]48<p>MD2 is defined in <span><em>The MD2 Message-Digest Algorithm</em> <a class="reference internal" href="../../about.html#citation-rfc1319"><span class="cite">[RFC1319]</span></a></span>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]49</div>
50<div class="section" id="PSA_ALG_MD4">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]51<span id="c.PSA_ALG_MD4"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_ALG_MD4</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]52<p>The MD4 message-digest algorithm.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]53<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_ALG_MD4" title="PSA_ALG_MD4">PSA_ALG_MD4</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x02000002)</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]54<div class="admonition warning">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]55<p class="admonition-title">Warning</p>
56<p>The MD4 hash is weak and deprecated and is only recommended for use in legacy protocols.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]57</div>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]58<p>MD4 is defined in <span><em>The MD4 Message-Digest Algorithm</em> <a class="reference internal" href="../../about.html#citation-rfc1320"><span class="cite">[RFC1320]</span></a></span>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]59</div>
60<div class="section" id="PSA_ALG_MD5">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]61<span id="c.PSA_ALG_MD5"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_ALG_MD5</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]62<p>The MD5 message-digest algorithm.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]63<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_ALG_MD5" title="PSA_ALG_MD5">PSA_ALG_MD5</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x02000003)</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]64<div class="admonition warning">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]65<p class="admonition-title">Warning</p>
66<p>The MD5 hash is weak and deprecated and is only recommended for use in legacy protocols.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]67</div>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]68<p>MD5 is defined in <span><em>The MD5 Message-Digest Algorithm</em> <a class="reference internal" href="../../about.html#citation-rfc1321"><span class="cite">[RFC1321]</span></a></span>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]69</div>
70<div class="section" id="PSA_ALG_RIPEMD160">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]71<span id="c.PSA_ALG_RIPEMD160"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_ALG_RIPEMD160</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]72<p>The RIPEMD-160 message-digest algorithm.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]73<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_ALG_RIPEMD160" title="PSA_ALG_RIPEMD160">PSA_ALG_RIPEMD160</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x02000004)</pre>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]74<p>RIPEMD-160 is defined in <span><em>RIPEMD-160: A Strengthened Version of RIPEMD</em> <a class="reference internal" href="../../about.html#citation-ripemd"><span class="cite">[RIPEMD]</span></a></span>, and also in <span><em>ISO/IEC 10118-3:2018 IT Security techniques — Hash-functions — Part 3: Dedicated hash-functions</em> <a class="reference internal" href="../../about.html#citation-iso10118"><span class="cite">[ISO10118]</span></a></span>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]75</div>
76<div class="section" id="PSA_ALG_SHA_1">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]77<span id="c.PSA_ALG_SHA_1"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_ALG_SHA_1</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]78<p>The SHA-1 message-digest algorithm.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]79<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_ALG_SHA_1" title="PSA_ALG_SHA_1">PSA_ALG_SHA_1</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x02000005)</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]80<div class="admonition warning">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]81<p class="admonition-title">Warning</p>
82<p>The SHA-1 hash is weak and deprecated and is only recommended for use in legacy protocols.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]83</div>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]84<p>SHA-1 is defined in <span><em>FIPS Publication 180-4: Secure Hash Standard (SHS)</em> <a class="reference internal" href="../../about.html#citation-fips180-4"><span class="cite">[FIPS180-4]</span></a></span>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]85</div>
86<div class="section" id="PSA_ALG_SHA_224">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]87<span id="c.PSA_ALG_SHA_224"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_ALG_SHA_224</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]88<p>The SHA-224 message-digest algorithm.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]89<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_ALG_SHA_224" title="PSA_ALG_SHA_224">PSA_ALG_SHA_224</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x02000008)</pre>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]90<p>SHA-224 is defined in <a class="reference internal" href="../../about.html#citation-fips180-4"><span class="cite">[FIPS180-4]</span></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]91</div>
92<div class="section" id="PSA_ALG_SHA_256">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]93<span id="c.PSA_ALG_SHA_256"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_ALG_SHA_256</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]94<p>The SHA-256 message-digest algorithm.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]95<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_ALG_SHA_256" title="PSA_ALG_SHA_256">PSA_ALG_SHA_256</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x02000009)</pre>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]96<p>SHA-256 is defined in <a class="reference internal" href="../../about.html#citation-fips180-4"><span class="cite">[FIPS180-4]</span></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]97</div>
98<div class="section" id="PSA_ALG_SHA_384">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]99<span id="c.PSA_ALG_SHA_384"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_ALG_SHA_384</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]100<p>The SHA-384 message-digest algorithm.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]101<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_ALG_SHA_384" title="PSA_ALG_SHA_384">PSA_ALG_SHA_384</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x0200000a)</pre>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]102<p>SHA-384 is defined in <a class="reference internal" href="../../about.html#citation-fips180-4"><span class="cite">[FIPS180-4]</span></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]103</div>
104<div class="section" id="PSA_ALG_SHA_512">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]105<span id="c.PSA_ALG_SHA_512"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_ALG_SHA_512</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]106<p>The SHA-512 message-digest algorithm.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]107<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_ALG_SHA_512" title="PSA_ALG_SHA_512">PSA_ALG_SHA_512</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x0200000b)</pre>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]108<p>SHA-512 is defined in <a class="reference internal" href="../../about.html#citation-fips180-4"><span class="cite">[FIPS180-4]</span></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]109</div>
110<div class="section" id="PSA_ALG_SHA_512_224">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]111<span id="c.PSA_ALG_SHA_512_224"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_ALG_SHA_512_224</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]112<p>The SHA-512/224 message-digest algorithm.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]113<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_ALG_SHA_512_224" title="PSA_ALG_SHA_512_224">PSA_ALG_SHA_512_224</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x0200000c)</pre>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]114<p>SHA-512/224 is defined in <a class="reference internal" href="../../about.html#citation-fips180-4"><span class="cite">[FIPS180-4]</span></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]115</div>
116<div class="section" id="PSA_ALG_SHA_512_256">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]117<span id="c.PSA_ALG_SHA_512_256"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_ALG_SHA_512_256</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]118<p>The SHA-512/256 message-digest algorithm.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]119<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_ALG_SHA_512_256" title="PSA_ALG_SHA_512_256">PSA_ALG_SHA_512_256</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x0200000d)</pre>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]120<p>SHA-512/256 is defined in <a class="reference internal" href="../../about.html#citation-fips180-4"><span class="cite">[FIPS180-4]</span></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]121</div>
122<div class="section" id="PSA_ALG_SHA3_224">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]123<span id="c.PSA_ALG_SHA3_224"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_ALG_SHA3_224</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]124<p>The SHA3-224 message-digest algorithm.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]125<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_ALG_SHA3_224" title="PSA_ALG_SHA3_224">PSA_ALG_SHA3_224</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x02000010)</pre>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]126<p>SHA3-224 is defined in <span><em>FIPS Publication 202: SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions</em> <a class="reference internal" href="../../about.html#citation-fips202"><span class="cite">[FIPS202]</span></a></span>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]127</div>
128<div class="section" id="PSA_ALG_SHA3_256">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]129<span id="c.PSA_ALG_SHA3_256"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_ALG_SHA3_256</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]130<p>The SHA3-256 message-digest algorithm.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]131<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_ALG_SHA3_256" title="PSA_ALG_SHA3_256">PSA_ALG_SHA3_256</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x02000011)</pre>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]132<p>SHA3-256 is defined in <a class="reference internal" href="../../about.html#citation-fips202"><span class="cite">[FIPS202]</span></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]133</div>
134<div class="section" id="PSA_ALG_SHA3_384">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]135<span id="c.PSA_ALG_SHA3_384"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_ALG_SHA3_384</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]136<p>The SHA3-384 message-digest algorithm.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]137<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_ALG_SHA3_384" title="PSA_ALG_SHA3_384">PSA_ALG_SHA3_384</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x02000012)</pre>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]138<p>SHA3-384 is defined in <a class="reference internal" href="../../about.html#citation-fips202"><span class="cite">[FIPS202]</span></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]139</div>
140<div class="section" id="PSA_ALG_SHA3_512">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]141<span id="c.PSA_ALG_SHA3_512"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_ALG_SHA3_512</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]142<p>The SHA3-512 message-digest algorithm.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]143<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_ALG_SHA3_512" title="PSA_ALG_SHA3_512">PSA_ALG_SHA3_512</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x02000013)</pre>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]144<p>SHA3-512 is defined in <a class="reference internal" href="../../about.html#citation-fips202"><span class="cite">[FIPS202]</span></a>.</p>
145</div>
146<div class="section" id="PSA_ALG_SM3">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]147<span id="c.PSA_ALG_SM3"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_ALG_SM3</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]148<p>The SM3 message-digest algorithm.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]149<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_ALG_SM3" title="PSA_ALG_SM3">PSA_ALG_SM3</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x02000014)</pre>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]150<p>SM3 is defined in <span><em>GB/T 32905-2016: Information security techniques — SM3 cryptographic hash algorithm</em> <a class="reference internal" href="../../about.html#citation-prc-sm3"><span class="cite">[PRC-SM3]</span></a></span> and <span><em>The SM3 Cryptographic Hash Function</em> <a class="reference internal" href="../../about.html#citation-ietf-sm3"><span class="cite">[IETF-SM3]</span></a></span>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]151</div>
152</div>
153<div class="section" id="single-part-hashing-functions">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]154<h2>10.2.2. Single-part hashing functions</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]155<div class="section" id="psa_hash_compute">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]156<span id="c.psa_hash_compute"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_hash_compute</span></code> (function)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]157<p>Calculate the hash (digest) of a message.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]158<pre class="literal-block"><a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_hash_compute" title="psa_hash_compute">psa_hash_compute</a>(<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]159 const uint8_t * input,
160 size_t input_length,
161 uint8_t * hash,
162 size_t hash_size,
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]163 size_t * hash_length);</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]164<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]165<dl class="simple">
166<dt> <code class="docutils literal notranslate"><span class="pre">alg</span></code></dt><dd><p>The hash algorithm to compute (<code class="docutils literal notranslate"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal notranslate"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> is true).</p>
167</dd>
168<dt> <code class="docutils literal notranslate"><span class="pre">input</span></code></dt><dd><p>Buffer containing the message to hash.</p>
169</dd>
170<dt> <code class="docutils literal notranslate"><span class="pre">input_length</span></code></dt><dd><p>Size of the <code class="docutils literal notranslate"><span class="pre">input</span></code> buffer in bytes.</p>
171</dd>
172<dt> <code class="docutils literal notranslate"><span class="pre">hash</span></code></dt><dd><p>Buffer where the hash is to be written.</p>
173</dd>
174<dt> <code class="docutils literal notranslate"><span class="pre">hash_size</span></code></dt><dd><p>Size of the <code class="docutils literal notranslate"><span class="pre">hash</span></code> buffer in bytes.
175This must be at least <a class="reference internal" href="#c.PSA_HASH_LENGTH" title="PSA_HASH_LENGTH"><code class="docutils literal notranslate"><span class="pre">PSA_HASH_LENGTH</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code>.</p>
176</dd>
177<dt> <code class="docutils literal notranslate"><span class="pre">hash_length</span></code></dt><dd><p>On success, the number of bytes that make up the hash value. This is always <a class="reference internal" href="#c.PSA_HASH_LENGTH" title="PSA_HASH_LENGTH"><code class="docutils literal notranslate"><span class="pre">PSA_HASH_LENGTH</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code>.</p>
178</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]179</dl>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]180<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code></a></p>
181<dl class="simple">
182<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code></a></dt><dd><p>Success.</p>
183</dd>
184<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt><dd><p><code class="docutils literal notranslate"><span class="pre">alg</span></code> is not supported or is not a hash algorithm.</p>
185</dd>
186<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt><dd></dd>
187<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BUFFER_TOO_SMALL" title="PSA_ERROR_BUFFER_TOO_SMALL"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a></dt><dd><p><code class="docutils literal notranslate"><span class="pre">hash_size</span></code> is too small.
188<a class="reference internal" href="#c.PSA_HASH_LENGTH" title="PSA_HASH_LENGTH"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_HASH_LENGTH()</span></code></a> can be used to determine the required buffer size.</p>
189</dd>
190<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt><dd></dd>
191<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt><dd></dd>
192<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt><dd></dd>
193<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt><dd></dd>
194<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt><dd></dd>
195<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</p>
196</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]197</dl>
198<p class="rubric">Description</p>
199<div class="admonition note">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]200<p class="admonition-title">Note</p>
201<p>To verify the hash of a message against an expected value, use <a class="reference internal" href="#c.psa_hash_compare" title="psa_hash_compare"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_compare()</span></code></a> instead.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]202</div>
203</div>
204<div class="section" id="psa_hash_compare">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]205<span id="c.psa_hash_compare"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_hash_compare</span></code> (function)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]206<p>Calculate the hash (digest) of a message and compare it with a reference value.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]207<pre class="literal-block"><a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_hash_compare" title="psa_hash_compare">psa_hash_compare</a>(<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]208 const uint8_t * input,
209 size_t input_length,
210 const uint8_t * hash,
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]211 size_t hash_length);</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]212<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]213<dl class="simple">
214<dt> <code class="docutils literal notranslate"><span class="pre">alg</span></code></dt><dd><p>The hash algorithm to compute (<code class="docutils literal notranslate"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal notranslate"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> is true).</p>
215</dd>
216<dt> <code class="docutils literal notranslate"><span class="pre">input</span></code></dt><dd><p>Buffer containing the message to hash.</p>
217</dd>
218<dt> <code class="docutils literal notranslate"><span class="pre">input_length</span></code></dt><dd><p>Size of the <code class="docutils literal notranslate"><span class="pre">input</span></code> buffer in bytes.</p>
219</dd>
220<dt> <code class="docutils literal notranslate"><span class="pre">hash</span></code></dt><dd><p>Buffer containing the expected hash value.</p>
221</dd>
222<dt> <code class="docutils literal notranslate"><span class="pre">hash_length</span></code></dt><dd><p>Size of the <code class="docutils literal notranslate"><span class="pre">hash</span></code> buffer in bytes.</p>
223</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]224</dl>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]225<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code></a></p>
226<dl class="simple">
227<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code></a></dt><dd><p>The expected hash is identical to the actual hash of the input.</p>
228</dd>
229<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_SIGNATURE" title="PSA_ERROR_INVALID_SIGNATURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_SIGNATURE</span></code></a></dt><dd><p>The hash of the message was calculated successfully, but it differs from the expected hash.</p>
230</dd>
231<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt><dd><p><code class="docutils literal notranslate"><span class="pre">alg</span></code> is not supported or is not a hash algorithm.</p>
232</dd>
233<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt><dd><p><code class="docutils literal notranslate"><span class="pre">input_length</span></code> or <code class="docutils literal notranslate"><span class="pre">hash_length</span></code> do not match the hash size for <code class="docutils literal notranslate"><span class="pre">alg</span></code></p>
234</dd>
235<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt><dd></dd>
236<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt><dd></dd>
237<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt><dd></dd>
238<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt><dd></dd>
239<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt><dd></dd>
240<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</p>
241</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]242</dl>
243</div>
244</div>
245<div class="section" id="multi-part-hashing-operations">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]246<span id="hash-mp"></span><h2>10.2.3. Multi-part hashing operations</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]247<div class="section" id="psa_hash_operation_t">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]248<span id="c.psa_hash_operation_t"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_hash_operation_t</span></code> (type)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]249<p>The type of the state object for multi-part hash operations.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]250<pre class="literal-block">typedef <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-type"><span class="std std-ref">/* implementation-defined type */</span></a></em> <a class="reference internal" href="#c.psa_hash_operation_t" title="psa_hash_operation_t">psa_hash_operation_t</a>;</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]251<p>Before calling any function on a hash operation object, the application must initialize it by any of the following means:</p>
252<ul>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]253<li><p>Set the object to all-bits-zero, for example:</p>
254<pre class="literal-block"><a class="reference internal" href="#c.psa_hash_operation_t" title="psa_hash_operation_t">psa_hash_operation_t</a> operation;
255memset(&amp;operation, 0, sizeof(operation));</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]256</li>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]257<li><p>Initialize the object to logical zero values by declaring the object as static or global without an explicit initializer, for example:</p>
258<pre class="literal-block">static <a class="reference internal" href="#c.psa_hash_operation_t" title="psa_hash_operation_t">psa_hash_operation_t</a> operation;</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]259</li>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]260<li><p>Initialize the object to the initializer <a class="reference internal" href="#c.PSA_HASH_OPERATION_INIT" title="PSA_HASH_OPERATION_INIT"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_HASH_OPERATION_INIT</span></code></a>, for example:</p>
261<pre class="literal-block"><a class="reference internal" href="#c.psa_hash_operation_t" title="psa_hash_operation_t">psa_hash_operation_t</a> operation = <a class="reference internal" href="#c.PSA_HASH_OPERATION_INIT" title="PSA_HASH_OPERATION_INIT">PSA_HASH_OPERATION_INIT</a>;</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]262</li>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]263<li><p>Assign the result of the function <a class="reference internal" href="#c.psa_hash_operation_init" title="psa_hash_operation_init"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_operation_init()</span></code></a> to the object, for example:</p>
264<pre class="literal-block"><a class="reference internal" href="#c.psa_hash_operation_t" title="psa_hash_operation_t">psa_hash_operation_t</a> operation;
265operation = <a class="reference internal" href="#c.psa_hash_operation_init" title="psa_hash_operation_init">psa_hash_operation_init</a>();</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]266</li>
267</ul>
268<p>This is an implementation-defined type. Applications that make assumptions about the content of this object will result in in implementation-specific behavior, and are non-portable.</p>
269</div>
270<div class="section" id="PSA_HASH_OPERATION_INIT">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]271<span id="c.PSA_HASH_OPERATION_INIT"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_HASH_OPERATION_INIT</span></code> (macro)</h3>
272<p>This macro returns a suitable initializer for a hash operation object of type <a class="reference internal" href="#c.psa_hash_operation_t" title="psa_hash_operation_t"><code class="xref any c c-type docutils literal notranslate"><span class="pre">psa_hash_operation_t</span></code></a>.</p>
273<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_HASH_OPERATION_INIT" title="PSA_HASH_OPERATION_INIT">PSA_HASH_OPERATION_INIT</a> <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em></pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]274</div>
275<div class="section" id="psa_hash_operation_init">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]276<span id="c.psa_hash_operation_init"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_hash_operation_init</span></code> (function)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]277<p>Return an initial value for a hash operation object.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]278<pre class="literal-block"><a class="reference internal" href="#c.psa_hash_operation_t" title="psa_hash_operation_t">psa_hash_operation_t</a> <a class="reference internal" href="#c.psa_hash_operation_init" title="psa_hash_operation_init">psa_hash_operation_init</a>(void);</pre>
279<p class="rubric">Returns: <a class="reference internal" href="#c.psa_hash_operation_t" title="psa_hash_operation_t"><code class="docutils literal notranslate"><span class="pre">psa_hash_operation_t</span></code></a></p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]280</div>
281<div class="section" id="psa_hash_setup">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]282<span id="c.psa_hash_setup"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_hash_setup</span></code> (function)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]283<p>Set up a multi-part hash operation.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]284<pre class="literal-block"><a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_hash_setup" title="psa_hash_setup">psa_hash_setup</a>(<a class="reference internal" href="#c.psa_hash_operation_t" title="psa_hash_operation_t">psa_hash_operation_t</a> * operation,
285 <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg);</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]286<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]287<dl class="simple">
288<dt> <code class="docutils literal notranslate"><span class="pre">operation</span></code></dt><dd><p>The operation object to set up. It must have been initialized as per the documentation for <a class="reference internal" href="#c.psa_hash_operation_t" title="psa_hash_operation_t"><code class="xref any c c-type docutils literal notranslate"><span class="pre">psa_hash_operation_t</span></code></a> and not yet in use.</p>
289</dd>
290<dt> <code class="docutils literal notranslate"><span class="pre">alg</span></code></dt><dd><p>The hash algorithm to compute (<code class="docutils literal notranslate"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal notranslate"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> is true).</p>
291</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]292</dl>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]293<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code></a></p>
294<dl class="simple">
295<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code></a></dt><dd><p>Success.</p>
296</dd>
297<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt><dd><p><code class="docutils literal notranslate"><span class="pre">alg</span></code> is not a supported hash algorithm.</p>
298</dd>
299<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt><dd><p><code class="docutils literal notranslate"><span class="pre">alg</span></code> is not a hash algorithm.</p>
300</dd>
301<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The operation state is not valid: it must be inactive.</p>
302</dd>
303<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt><dd></dd>
304<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt><dd></dd>
305<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt><dd></dd>
306<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt><dd></dd>
307<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</p>
308</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]309</dl>
310<p class="rubric">Description</p>
311<p>The sequence of operations to calculate a hash (message digest) is as follows:</p>
312<ol class="arabic simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]313<li><p>Allocate an operation object which will be passed to all the functions listed here.</p></li>
314<li><p>Initialize the operation object with one of the methods described in the documentation for <a class="reference internal" href="#c.psa_hash_operation_t" title="psa_hash_operation_t"><code class="xref any c c-type docutils literal notranslate"><span class="pre">psa_hash_operation_t</span></code></a>, e.g. <a class="reference internal" href="#c.PSA_HASH_OPERATION_INIT" title="PSA_HASH_OPERATION_INIT"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_HASH_OPERATION_INIT</span></code></a>.</p></li>
315<li><p>Call <a class="reference internal" href="#c.psa_hash_setup" title="psa_hash_setup"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_setup()</span></code></a> to specify the algorithm.</p></li>
316<li><p>Call <a class="reference internal" href="#c.psa_hash_update" title="psa_hash_update"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_update()</span></code></a> zero, one or more times, passing a fragment of the message each time. The hash that is calculated is the hash of the concatenation of these messages in order.</p></li>
317<li><p>To calculate the hash, call <a class="reference internal" href="#c.psa_hash_finish" title="psa_hash_finish"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_finish()</span></code></a>. To compare the hash with an expected value, call <a class="reference internal" href="#c.psa_hash_verify" title="psa_hash_verify"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_verify()</span></code></a>. To suspend the hash operation and extract the current state, call <a class="reference internal" href="#c.psa_hash_suspend" title="psa_hash_suspend"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_suspend()</span></code></a>.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]318</ol>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]319<p>If an error occurs at any step after a call to <a class="reference internal" href="#c.psa_hash_setup" title="psa_hash_setup"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_setup()</span></code></a>, the operation will need to be reset by a call to <a class="reference internal" href="#c.psa_hash_abort" title="psa_hash_abort"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_abort()</span></code></a>. The application can call <a class="reference internal" href="#c.psa_hash_abort" title="psa_hash_abort"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_abort()</span></code></a> at any time after the operation has been initialized.</p>
320<p>After a successful call to <a class="reference internal" href="#c.psa_hash_setup" title="psa_hash_setup"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_setup()</span></code></a>, the application must eventually terminate the operation. The following events terminate an operation:</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]321<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]322<li><p>A successful call to <a class="reference internal" href="#c.psa_hash_finish" title="psa_hash_finish"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_finish()</span></code></a> or <a class="reference internal" href="#c.psa_hash_verify" title="psa_hash_verify"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_verify()</span></code></a> or <a class="reference internal" href="#c.psa_hash_suspend" title="psa_hash_suspend"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_suspend()</span></code></a>.</p></li>
323<li><p>A call to <a class="reference internal" href="#c.psa_hash_abort" title="psa_hash_abort"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_abort()</span></code></a>.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]324</ul>
325</div>
326<div class="section" id="psa_hash_update">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]327<span id="c.psa_hash_update"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_hash_update</span></code> (function)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]328<p>Add a message fragment to a multi-part hash operation.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]329<pre class="literal-block"><a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_hash_update" title="psa_hash_update">psa_hash_update</a>(<a class="reference internal" href="#c.psa_hash_operation_t" title="psa_hash_operation_t">psa_hash_operation_t</a> * operation,
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]330 const uint8_t * input,
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]331 size_t input_length);</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]332<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]333<dl class="simple">
334<dt> <code class="docutils literal notranslate"><span class="pre">operation</span></code></dt><dd><p>Active hash operation.</p>
335</dd>
336<dt> <code class="docutils literal notranslate"><span class="pre">input</span></code></dt><dd><p>Buffer containing the message fragment to hash.</p>
337</dd>
338<dt> <code class="docutils literal notranslate"><span class="pre">input_length</span></code></dt><dd><p>Size of the <code class="docutils literal notranslate"><span class="pre">input</span></code> buffer in bytes.</p>
339</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]340</dl>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]341<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code></a></p>
342<dl class="simple">
343<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code></a></dt><dd><p>Success.</p>
344</dd>
345<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The operation state is not valid: it must be active.</p>
346</dd>
347<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt><dd></dd>
348<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt><dd></dd>
349<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt><dd></dd>
350<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt><dd></dd>
351<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</p>
352</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]353</dl>
354<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]355<p>The application must call <a class="reference internal" href="#c.psa_hash_setup" title="psa_hash_setup"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_setup()</span></code></a> or <a class="reference internal" href="#c.psa_hash_resume" title="psa_hash_resume"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_resume()</span></code></a> before calling this function.</p>
356<p>If this function returns an error status, the operation enters an error state and must be aborted by calling <a class="reference internal" href="#c.psa_hash_abort" title="psa_hash_abort"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_abort()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]357</div>
358<div class="section" id="psa_hash_finish">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]359<span id="c.psa_hash_finish"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_hash_finish</span></code> (function)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]360<p>Finish the calculation of the hash of a message.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]361<pre class="literal-block"><a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_hash_finish" title="psa_hash_finish">psa_hash_finish</a>(<a class="reference internal" href="#c.psa_hash_operation_t" title="psa_hash_operation_t">psa_hash_operation_t</a> * operation,
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]362 uint8_t * hash,
363 size_t hash_size,
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]364 size_t * hash_length);</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]365<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]366<dl class="simple">
367<dt> <code class="docutils literal notranslate"><span class="pre">operation</span></code></dt><dd><p>Active hash operation.</p>
368</dd>
369<dt> <code class="docutils literal notranslate"><span class="pre">hash</span></code></dt><dd><p>Buffer where the hash is to be written.</p>
370</dd>
371<dt> <code class="docutils literal notranslate"><span class="pre">hash_size</span></code></dt><dd><p>Size of the <code class="docutils literal notranslate"><span class="pre">hash</span></code> buffer in bytes. This must be at least <a class="reference internal" href="#c.PSA_HASH_LENGTH" title="PSA_HASH_LENGTH"><code class="docutils literal notranslate"><span class="pre">PSA_HASH_LENGTH</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> where <code class="docutils literal notranslate"><span class="pre">alg</span></code> is the algorithm that the operation performs.</p>
372</dd>
373<dt> <code class="docutils literal notranslate"><span class="pre">hash_length</span></code></dt><dd><p>On success, the number of bytes that make up the hash value. This is always <a class="reference internal" href="#c.PSA_HASH_LENGTH" title="PSA_HASH_LENGTH"><code class="docutils literal notranslate"><span class="pre">PSA_HASH_LENGTH</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> where <code class="docutils literal notranslate"><span class="pre">alg</span></code> is the hash algorithm that the operation performs.</p>
374</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]375</dl>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]376<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code></a></p>
377<dl class="simple">
378<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code></a></dt><dd><p>Success.</p>
379</dd>
380<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The operation state is not valid: it must be active.</p>
381</dd>
382<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BUFFER_TOO_SMALL" title="PSA_ERROR_BUFFER_TOO_SMALL"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a></dt><dd><p>The size of the <code class="docutils literal notranslate"><span class="pre">hash</span></code> buffer is too small.
383<a class="reference internal" href="#c.PSA_HASH_LENGTH" title="PSA_HASH_LENGTH"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_HASH_LENGTH()</span></code></a> can be used to determine the required buffer size.</p>
384</dd>
385<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt><dd></dd>
386<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt><dd></dd>
387<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt><dd></dd>
388<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt><dd></dd>
389<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</p>
390</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]391</dl>
392<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]393<p>The application must call <a class="reference internal" href="#c.psa_hash_setup" title="psa_hash_setup"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_setup()</span></code></a> or <a class="reference internal" href="#c.psa_hash_resume" title="psa_hash_resume"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_resume()</span></code></a> before calling this function. This function calculates the hash of the message formed by concatenating the inputs passed to preceding calls to <a class="reference internal" href="#c.psa_hash_update" title="psa_hash_update"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_update()</span></code></a>.</p>
394<p>When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling <a class="reference internal" href="#c.psa_hash_abort" title="psa_hash_abort"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_abort()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]395<div class="admonition warning">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]396<p class="admonition-title">Warning</p>
397<p>It is not recommended to use this function when a specific value is expected for the hash. Call <a class="reference internal" href="#c.psa_hash_verify" title="psa_hash_verify"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_verify()</span></code></a> instead with the expected hash value.</p>
398<p>Comparing integrity or authenticity data such as hash values with a function such as <code class="docutils literal notranslate"><span class="pre">memcmp()</span></code> is risky because the time taken by the comparison might leak information about the hashed data which could allow an attacker to guess a valid hash and thereby bypass security controls.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]399</div>
400</div>
401<div class="section" id="psa_hash_verify">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]402<span id="c.psa_hash_verify"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_hash_verify</span></code> (function)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]403<p>Finish the calculation of the hash of a message and compare it with an expected value.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]404<pre class="literal-block"><a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_hash_verify" title="psa_hash_verify">psa_hash_verify</a>(<a class="reference internal" href="#c.psa_hash_operation_t" title="psa_hash_operation_t">psa_hash_operation_t</a> * operation,
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]405 const uint8_t * hash,
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]406 size_t hash_length);</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]407<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]408<dl class="simple">
409<dt> <code class="docutils literal notranslate"><span class="pre">operation</span></code></dt><dd><p>Active hash operation.</p>
410</dd>
411<dt> <code class="docutils literal notranslate"><span class="pre">hash</span></code></dt><dd><p>Buffer containing the expected hash value.</p>
412</dd>
413<dt> <code class="docutils literal notranslate"><span class="pre">hash_length</span></code></dt><dd><p>Size of the <code class="docutils literal notranslate"><span class="pre">hash</span></code> buffer in bytes.</p>
414</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]415</dl>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]416<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code></a></p>
417<dl class="simple">
418<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code></a></dt><dd><p>The expected hash is identical to the actual hash of the message.</p>
419</dd>
420<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_SIGNATURE" title="PSA_ERROR_INVALID_SIGNATURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_SIGNATURE</span></code></a></dt><dd><p>The hash of the message was calculated successfully, but it differs from the expected hash.</p>
421</dd>
422<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The operation state is not valid: it must be active.</p>
423</dd>
424<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt><dd></dd>
425<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt><dd></dd>
426<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt><dd></dd>
427<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt><dd></dd>
428<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</p>
429</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]430</dl>
431<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]432<p>The application must call <a class="reference internal" href="#c.psa_hash_setup" title="psa_hash_setup"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_setup()</span></code></a> before calling this function. This function calculates the hash of the message formed by concatenating the inputs passed to preceding calls to <a class="reference internal" href="#c.psa_hash_update" title="psa_hash_update"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_update()</span></code></a>. It then compares the calculated hash with the expected hash passed as a parameter to this function.</p>
433<p>When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling <a class="reference internal" href="#c.psa_hash_abort" title="psa_hash_abort"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_abort()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]434<div class="admonition note">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]435<p class="admonition-title">Note</p>
436<p>Implementations must make the best effort to ensure that the comparison between the actual hash and the expected hash is performed in constant time.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]437</div>
438</div>
439<div class="section" id="psa_hash_abort">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]440<span id="c.psa_hash_abort"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_hash_abort</span></code> (function)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]441<p>Abort a hash operation.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]442<pre class="literal-block"><a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_hash_abort" title="psa_hash_abort">psa_hash_abort</a>(<a class="reference internal" href="#c.psa_hash_operation_t" title="psa_hash_operation_t">psa_hash_operation_t</a> * operation);</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]443<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]444<dl class="simple">
445<dt> <code class="docutils literal notranslate"><span class="pre">operation</span></code></dt><dd><p>Initialized hash operation.</p>
446</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]447</dl>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]448<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code></a></p>
449<dl class="simple">
450<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code></a></dt><dd></dd>
451<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt><dd></dd>
452<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt><dd></dd>
453<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt><dd></dd>
454<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</p>
455</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]456</dl>
457<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]458<p>Aborting an operation frees all associated resources except for the <code class="docutils literal notranslate"><span class="pre">operation</span></code> object itself. Once aborted, the operation object can be reused for another operation by calling <a class="reference internal" href="#c.psa_hash_setup" title="psa_hash_setup"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_setup()</span></code></a> again.</p>
459<p>This function can be called any time after the operation object has been initialized by one of the methods described in <a class="reference internal" href="#c.psa_hash_operation_t" title="psa_hash_operation_t"><code class="xref any c c-type docutils literal notranslate"><span class="pre">psa_hash_operation_t</span></code></a>.</p>
460<p>In particular, calling <a class="reference internal" href="#c.psa_hash_abort" title="psa_hash_abort"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_abort()</span></code></a> after the operation has been terminated by a call to <a class="reference internal" href="#c.psa_hash_abort" title="psa_hash_abort"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_abort()</span></code></a>, <a class="reference internal" href="#c.psa_hash_finish" title="psa_hash_finish"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_finish()</span></code></a> or <a class="reference internal" href="#c.psa_hash_verify" title="psa_hash_verify"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_verify()</span></code></a> is safe and has no effect.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]461</div>
462<div class="section" id="psa_hash_suspend">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]463<span id="c.psa_hash_suspend"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_hash_suspend</span></code> (function)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]464<p>Halt the hash operation and extract the intermediate state of the hash computation.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]465<pre class="literal-block"><a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_hash_suspend" title="psa_hash_suspend">psa_hash_suspend</a>(<a class="reference internal" href="#c.psa_hash_operation_t" title="psa_hash_operation_t">psa_hash_operation_t</a> * operation,
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]466 uint8_t * hash_state,
467 size_t hash_state_size,
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]468 size_t * hash_state_length);</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]469<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]470<dl class="simple">
471<dt> <code class="docutils literal notranslate"><span class="pre">operation</span></code></dt><dd><p>Active hash operation.</p>
472</dd>
473<dt> <code class="docutils literal notranslate"><span class="pre">hash_state</span></code></dt><dd><p>Buffer where the hash suspend state is to be written.</p>
474</dd>
475<dt> <code class="docutils literal notranslate"><span class="pre">hash_state_size</span></code></dt><dd><p>Size of the <code class="docutils literal notranslate"><span class="pre">hash_state</span></code> buffer in bytes.
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]476This must be appropriate for the selected algorithm:</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]477<ul class="simple">
478<li><p>A sufficient output size is <a class="reference internal" href="#c.PSA_HASH_SUSPEND_OUTPUT_SIZE" title="PSA_HASH_SUSPEND_OUTPUT_SIZE"><code class="docutils literal notranslate"><span class="pre">PSA_HASH_SUSPEND_OUTPUT_SIZE</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> where <code class="docutils literal notranslate"><span class="pre">alg</span></code> is the algorithm that was used to set up the operation.</p></li>
479<li><p><a class="reference internal" href="#c.PSA_HASH_SUSPEND_OUTPUT_MAX_SIZE" title="PSA_HASH_SUSPEND_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_HASH_SUSPEND_OUTPUT_MAX_SIZE</span></code></a> evaluates to the maximum output size of any supported hash algorithm.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]480</ul>
481</dd>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]482<dt> <code class="docutils literal notranslate"><span class="pre">hash_state_length</span></code></dt><dd><p>On success, the number of bytes that make up the hash suspend state.</p>
483</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]484</dl>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]485<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code></a></p>
486<dl class="simple">
487<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code></a></dt><dd><p>Success.</p>
488</dd>
489<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The operation state is not valid: it must be active.</p>
490</dd>
491<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BUFFER_TOO_SMALL" title="PSA_ERROR_BUFFER_TOO_SMALL"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a></dt><dd><p>The size of the <code class="docutils literal notranslate"><span class="pre">hash_state</span></code> buffer is too small.
492<a class="reference internal" href="#c.PSA_HASH_SUSPEND_OUTPUT_SIZE" title="PSA_HASH_SUSPEND_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_HASH_SUSPEND_OUTPUT_SIZE()</span></code></a> or <a class="reference internal" href="#c.PSA_HASH_SUSPEND_OUTPUT_MAX_SIZE" title="PSA_HASH_SUSPEND_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_HASH_SUSPEND_OUTPUT_MAX_SIZE</span></code></a> can be used to determine the required buffer size.</p>
493</dd>
494<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt><dd><p>The hash algorithm being computed does not support suspend and resume.</p>
495</dd>
496<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt><dd></dd>
497<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt><dd></dd>
498<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt><dd></dd>
499<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt><dd></dd>
500<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</p>
501</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]502</dl>
503<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]504<p>The application must call <a class="reference internal" href="#c.psa_hash_setup" title="psa_hash_setup"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_setup()</span></code></a> or <a class="reference internal" href="#c.psa_hash_resume" title="psa_hash_resume"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_resume()</span></code></a> before calling this function. This function extracts an intermediate state of the hash computation of the message formed by concatenating the inputs passed to preceding calls to <a class="reference internal" href="#c.psa_hash_update" title="psa_hash_update"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_update()</span></code></a>.</p>
505<p>This function can be used to halt a hash operation, and then resume the hash operation at a later time, or in another application, by transferring the extracted hash suspend state to a call to <a class="reference internal" href="#c.psa_hash_resume" title="psa_hash_resume"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_resume()</span></code></a>.</p>
506<p>When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling <a class="reference internal" href="#c.psa_hash_abort" title="psa_hash_abort"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_abort()</span></code></a>.</p>
507<p>Hash suspend and resume is not defined for the SHA3 family of hash algorithms. <a class="reference internal" href="#hash-suspend-state"><span class="secref">Hash suspend state</span></a> defines the format of the output from <a class="reference internal" href="#c.psa_hash_suspend" title="psa_hash_suspend"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_suspend()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]508<div class="admonition warning">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]509<p class="admonition-title">Warning</p>
510<p>Applications must not use any of the hash suspend state as if it was a hash output. Instead, the suspend state must only be used to resume a hash operation, and <a class="reference internal" href="#c.psa_hash_finish" title="psa_hash_finish"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_finish()</span></code></a> or <a class="reference internal" href="#c.psa_hash_verify" title="psa_hash_verify"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_verify()</span></code></a> can then calculate or verify the final hash value.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]511</div>
512<p class="rubric">Usage</p>
513<p>The sequence of operations to suspend and resume a hash operation is as follows:</p>
514<ol class="arabic">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]515<li><p>Compute the first part of the hash.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]516<blockquote>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]517<div><ol class="loweralpha simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]518<li><p>Allocate an operation object and initialize it as described in the documentation for <a class="reference internal" href="#c.psa_hash_operation_t" title="psa_hash_operation_t"><code class="xref any c c-type docutils literal notranslate"><span class="pre">psa_hash_operation_t</span></code></a>.</p></li>
519<li><p>Call <a class="reference internal" href="#c.psa_hash_setup" title="psa_hash_setup"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_setup()</span></code></a> to specify the algorithm.</p></li>
520<li><p>Call <a class="reference internal" href="#c.psa_hash_update" title="psa_hash_update"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_update()</span></code></a> zero, one or more times, passing a fragment of the message each time.</p></li>
521<li><p>Call <a class="reference internal" href="#c.psa_hash_suspend" title="psa_hash_suspend"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_suspend()</span></code></a> to extract the hash suspend state into a buffer.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]522</ol>
523</div></blockquote>
524</li>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]525<li><p>Pass the hash state buffer to the application which will resume the operation.</p></li>
526<li><p>Compute the rest of the hash.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]527<blockquote>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]528<div><ol class="loweralpha simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]529<li><p>Allocate an operation object and initialize it as described in the documentation for <a class="reference internal" href="#c.psa_hash_operation_t" title="psa_hash_operation_t"><code class="xref any c c-type docutils literal notranslate"><span class="pre">psa_hash_operation_t</span></code></a>.</p></li>
530<li><p>Call <a class="reference internal" href="#c.psa_hash_resume" title="psa_hash_resume"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_resume()</span></code></a> with the extracted hash state.</p></li>
531<li><p>Call <a class="reference internal" href="#c.psa_hash_update" title="psa_hash_update"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_update()</span></code></a> zero, one or more times, passing a fragment of the message each time.</p></li>
532<li><p>To calculate the hash, call <a class="reference internal" href="#c.psa_hash_finish" title="psa_hash_finish"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_finish()</span></code></a>. To compare the hash with an expected value, call <a class="reference internal" href="#c.psa_hash_verify" title="psa_hash_verify"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_verify()</span></code></a>.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]533</ol>
534</div></blockquote>
535</li>
536</ol>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]537<p>If an error occurs at any step after a call to <a class="reference internal" href="#c.psa_hash_setup" title="psa_hash_setup"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_setup()</span></code></a> or <a class="reference internal" href="#c.psa_hash_resume" title="psa_hash_resume"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_resume()</span></code></a>, the operation will need to be reset by a call to <a class="reference internal" href="#c.psa_hash_abort" title="psa_hash_abort"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_abort()</span></code></a>. The application can call <a class="reference internal" href="#c.psa_hash_abort" title="psa_hash_abort"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_abort()</span></code></a> at any time after the operation has been initialized.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]538</div>
539<div class="section" id="psa_hash_resume">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]540<span id="c.psa_hash_resume"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_hash_resume</span></code> (function)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]541<p>Set up a multi-part hash operation using the hash suspend state from a previously suspended hash operation.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]542<pre class="literal-block"><a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_hash_resume" title="psa_hash_resume">psa_hash_resume</a>(<a class="reference internal" href="#c.psa_hash_operation_t" title="psa_hash_operation_t">psa_hash_operation_t</a> * operation,
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]543 const uint8_t * hash_state,
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]544 size_t hash_state_length);</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]545<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]546<dl class="simple">
547<dt> <code class="docutils literal notranslate"><span class="pre">operation</span></code></dt><dd><p>The operation object to set up. It must have been initialized as per the documentation for <a class="reference internal" href="#c.psa_hash_operation_t" title="psa_hash_operation_t"><code class="xref any c c-type docutils literal notranslate"><span class="pre">psa_hash_operation_t</span></code></a> and not yet in use.</p>
548</dd>
549<dt> <code class="docutils literal notranslate"><span class="pre">hash_state</span></code></dt><dd><p>A buffer containing the suspended hash state which is to be resumed. This must be in the format output by <a class="reference internal" href="#c.psa_hash_suspend" title="psa_hash_suspend"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_suspend()</span></code></a>, which is described in <a class="reference internal" href="#hash-suspend-state-format"><span class="secref">Hash suspend state format</span></a>.</p>
550</dd>
551<dt> <code class="docutils literal notranslate"><span class="pre">hash_state_length</span></code></dt><dd><p>Length of <code class="docutils literal notranslate"><span class="pre">hash_state</span></code> in bytes.</p>
552</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]553</dl>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]554<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code></a></p>
555<dl class="simple">
556<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code></a></dt><dd><p>Success.</p>
557</dd>
558<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt><dd><p>The provided hash suspend state is for an algorithm that is not supported.</p>
559</dd>
560<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt><dd><p><code class="docutils literal notranslate"><span class="pre">hash_state</span></code> does not correspond to a valid hash suspend state. See <a class="reference internal" href="#hash-suspend-state-format"><span class="secref">Hash suspend state format</span></a> for the definition.</p>
561</dd>
562<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The operation state is not valid: it must be inactive.</p>
563</dd>
564<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt><dd></dd>
565<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt><dd></dd>
566<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt><dd></dd>
567<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt><dd></dd>
568<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</p>
569</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]570</dl>
571<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]572<p>See <a class="reference internal" href="#c.psa_hash_suspend" title="psa_hash_suspend"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_suspend()</span></code></a> for an example of how to use this function to suspend and resume a hash operation.</p>
573<p>After a successful call to <a class="reference internal" href="#c.psa_hash_resume" title="psa_hash_resume"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_resume()</span></code></a>, the application must eventually terminate the operation. The following events terminate an operation:</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]574<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]575<li><p>A successful call to <a class="reference internal" href="#c.psa_hash_finish" title="psa_hash_finish"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_finish()</span></code></a>, <a class="reference internal" href="#c.psa_hash_verify" title="psa_hash_verify"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_verify()</span></code></a> or <a class="reference internal" href="#c.psa_hash_suspend" title="psa_hash_suspend"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_suspend()</span></code></a>.</p></li>
576<li><p>A call to <a class="reference internal" href="#c.psa_hash_abort" title="psa_hash_abort"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_abort()</span></code></a>.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]577</ul>
578</div>
579<div class="section" id="psa_hash_clone">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]580<span id="c.psa_hash_clone"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_hash_clone</span></code> (function)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]581<p>Clone a hash operation.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]582<pre class="literal-block"><a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_hash_clone" title="psa_hash_clone">psa_hash_clone</a>(const <a class="reference internal" href="#c.psa_hash_operation_t" title="psa_hash_operation_t">psa_hash_operation_t</a> * source_operation,
583 <a class="reference internal" href="#c.psa_hash_operation_t" title="psa_hash_operation_t">psa_hash_operation_t</a> * target_operation);</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]584<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]585<dl class="simple">
586<dt> <code class="docutils literal notranslate"><span class="pre">source_operation</span></code></dt><dd><p>The active hash operation to clone.</p>
587</dd>
588<dt> <code class="docutils literal notranslate"><span class="pre">target_operation</span></code></dt><dd><p>The operation object to set up. It must be initialized but not active.</p>
589</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]590</dl>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]591<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code></a></p>
592<dl class="simple">
593<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code></a></dt><dd></dd>
594<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The <code class="docutils literal notranslate"><span class="pre">source_operation</span></code> state is not valid: it must be active.</p>
595</dd>
596<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The <code class="docutils literal notranslate"><span class="pre">target_operation</span></code> state is not valid: it must be inactive.</p>
597</dd>
598<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt><dd></dd>
599<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt><dd></dd>
600<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt><dd></dd>
601<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt><dd></dd>
602<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</p>
603</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]604</dl>
605<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]606<p>This function copies the state of an ongoing hash operation to a new operation object. In other words, this function is equivalent to calling <a class="reference internal" href="#c.psa_hash_setup" title="psa_hash_setup"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_setup()</span></code></a> on <code class="docutils literal notranslate"><span class="pre">target_operation</span></code> with the same algorithm that <code class="docutils literal notranslate"><span class="pre">source_operation</span></code> was set up for, then <a class="reference internal" href="#c.psa_hash_update" title="psa_hash_update"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_update()</span></code></a> on <code class="docutils literal notranslate"><span class="pre">target_operation</span></code> with the same input that that was passed to <code class="docutils literal notranslate"><span class="pre">source_operation</span></code>. After this function returns, the two objects are independent, i.e. subsequent calls involving one of the objects do not affect the other object.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]607</div>
608</div>
609<div class="section" id="support-macros">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]610<h2>10.2.4. Support macros</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]611<div class="section" id="PSA_HASH_LENGTH">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]612<span id="c.PSA_HASH_LENGTH"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_HASH_LENGTH</span></code> (macro)</h3>
613<p>The size of the output of <a class="reference internal" href="#c.psa_hash_compute" title="psa_hash_compute"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_compute()</span></code></a> and <a class="reference internal" href="#c.psa_hash_finish" title="psa_hash_finish"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_finish()</span></code></a>, in bytes.</p>
614<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_HASH_LENGTH" title="PSA_HASH_LENGTH">PSA_HASH_LENGTH</a>(alg) <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em></pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]615<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]616<dl class="simple">
617<dt> <code class="docutils literal notranslate"><span class="pre">alg</span></code></dt><dd><p>A hash algorithm (<code class="docutils literal notranslate"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal notranslate"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> is true), or an HMAC algorithm (<a class="reference internal" href="macs.html#c.PSA_ALG_HMAC" title="PSA_ALG_HMAC"><code class="docutils literal notranslate"><span class="pre">PSA_ALG_HMAC</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">hash_alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> where <code class="docutils literal notranslate"><span class="pre">hash_alg</span></code> is a hash algorithm).</p>
618</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]619</dl>
620<p class="rubric">Returns</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]621<p>The hash length for the specified hash algorithm. If the hash algorithm is not recognized, return <code class="docutils literal notranslate"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal notranslate"><span class="pre">0</span></code> or the correct size for a hash algorithm that it recognizes, but does not support.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]622<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]623<p>This is also the hash length that <a class="reference internal" href="#c.psa_hash_compare" title="psa_hash_compare"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_compare()</span></code></a> and <a class="reference internal" href="#c.psa_hash_verify" title="psa_hash_verify"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_verify()</span></code></a> expect.</p>
624<p>See also <a class="reference internal" href="#c.PSA_HASH_MAX_SIZE" title="PSA_HASH_MAX_SIZE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_HASH_MAX_SIZE</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]625</div>
626<div class="section" id="PSA_HASH_MAX_SIZE">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]627<span id="c.PSA_HASH_MAX_SIZE"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_HASH_MAX_SIZE</span></code> (macro)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]628<p>Maximum size of a hash.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]629<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_HASH_MAX_SIZE" title="PSA_HASH_MAX_SIZE">PSA_HASH_MAX_SIZE</a> <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em></pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]630<p>This macro must expand to a compile-time constant integer.
631It is recommended that this value is the maximum size of a hash supported by the implementation, in bytes. The value must not be smaller than this maximum.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]632<p>See also <a class="reference internal" href="#c.PSA_HASH_LENGTH" title="PSA_HASH_LENGTH"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_HASH_LENGTH()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]633</div>
634<div class="section" id="PSA_HASH_SUSPEND_OUTPUT_SIZE">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]635<span id="c.PSA_HASH_SUSPEND_OUTPUT_SIZE"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_HASH_SUSPEND_OUTPUT_SIZE</span></code> (macro)</h3>
636<p>A sufficient hash suspend state buffer size for <a class="reference internal" href="#c.psa_hash_suspend" title="psa_hash_suspend"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_suspend()</span></code></a>.</p>
637<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_HASH_SUSPEND_OUTPUT_SIZE" title="PSA_HASH_SUSPEND_OUTPUT_SIZE">PSA_HASH_SUSPEND_OUTPUT_SIZE</a>(alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em></pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]638<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]639<dl class="simple">
640<dt> <code class="docutils literal notranslate"><span class="pre">alg</span></code></dt><dd><p>A hash algorithm (<code class="docutils literal notranslate"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal notranslate"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> is true).</p>
641</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]642</dl>
643<p class="rubric">Returns</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]644<p>A sufficient output size for the algorithm. If the hash algorithm is not recognized, or is not supported by <a class="reference internal" href="#c.psa_hash_suspend" title="psa_hash_suspend"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_suspend()</span></code></a>, return <code class="docutils literal notranslate"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal notranslate"><span class="pre">0</span></code> or a correct size for a hash algorithm that it recognizes, but does not support.</p>
645<p>For a supported hash algorithm <code class="docutils literal notranslate"><span class="pre">alg</span></code>, the following expression is true:</p>
646<pre class="literal-block"><a class="reference internal" href="#c.PSA_HASH_SUSPEND_OUTPUT_SIZE" title="PSA_HASH_SUSPEND_OUTPUT_SIZE">PSA_HASH_SUSPEND_OUTPUT_SIZE</a>(alg) == <a class="reference internal" href="#c.PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH" title="PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH">PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH</a> +
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]647 <a class="reference internal" href="#c.PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH" title="PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH">PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH</a>(alg) +
648 <a class="reference internal" href="#c.PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH" title="PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH">PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH</a>(alg) +
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]649 <a class="reference internal" href="#c.PSA_HASH_BLOCK_LENGTH" title="PSA_HASH_BLOCK_LENGTH">PSA_HASH_BLOCK_LENGTH</a>(alg) - 1</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]650<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]651<p>If the size of the hash state buffer is at least this large, it is guaranteed that <a class="reference internal" href="#c.psa_hash_suspend" title="psa_hash_suspend"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_suspend()</span></code></a> will not fail due to an insufficient buffer size. The actual size of the output might be smaller in any given call.</p>
652<p>See also <a class="reference internal" href="#c.PSA_HASH_SUSPEND_OUTPUT_MAX_SIZE" title="PSA_HASH_SUSPEND_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_HASH_SUSPEND_OUTPUT_MAX_SIZE</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]653</div>
654<div class="section" id="PSA_HASH_SUSPEND_OUTPUT_MAX_SIZE">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]655<span id="c.PSA_HASH_SUSPEND_OUTPUT_MAX_SIZE"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_HASH_SUSPEND_OUTPUT_MAX_SIZE</span></code> (macro)</h3>
656<p>A sufficient hash suspend state buffer size for <a class="reference internal" href="#c.psa_hash_suspend" title="psa_hash_suspend"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_suspend()</span></code></a>, for any supported hash algorithms.</p>
657<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_HASH_SUSPEND_OUTPUT_MAX_SIZE" title="PSA_HASH_SUSPEND_OUTPUT_MAX_SIZE">PSA_HASH_SUSPEND_OUTPUT_MAX_SIZE</a> <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em></pre>
658<p>See also <a class="reference internal" href="#c.PSA_HASH_SUSPEND_OUTPUT_SIZE" title="PSA_HASH_SUSPEND_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_HASH_SUSPEND_OUTPUT_SIZE()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]659</div>
660<div class="section" id="PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]661<span id="c.PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH</span></code> (macro)</h3>
662<p>The size of the <em>algorithm</em> field that is part of the output of <a class="reference internal" href="#c.psa_hash_suspend" title="psa_hash_suspend"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_suspend()</span></code></a>, in bytes.</p>
663<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH" title="PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH">PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH</a> ((size_t)4)</pre>
664<p>Applications can use this value to unpack the hash suspend state that is output by <a class="reference internal" href="#c.psa_hash_suspend" title="psa_hash_suspend"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_suspend()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]665</div>
666<div class="section" id="PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]667<span id="c.PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH</span></code> (macro)</h3>
668<p>The size of the <em>input-length</em> field that is part of the output of <a class="reference internal" href="#c.psa_hash_suspend" title="psa_hash_suspend"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_suspend()</span></code></a>, in bytes.</p>
669<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH" title="PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH">PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH</a>(alg) \
670 <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em></pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]671<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]672<dl class="simple">
673<dt> <code class="docutils literal notranslate"><span class="pre">alg</span></code></dt><dd><p>A hash algorithm (<code class="docutils literal notranslate"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal notranslate"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> is true).</p>
674</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]675</dl>
676<p class="rubric">Returns</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]677<p>The size, in bytes, of the <em>input-length</em> field of the hash suspend state for the specified hash algorithm. If the hash algorithm is not recognized, return <code class="docutils literal notranslate"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal notranslate"><span class="pre">0</span></code> or the correct size for a hash algorithm that it recognizes, but does not support.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]678<p>The algorithm-specific values are defined in <a class="reference internal" href="#hash-suspend-state-constants"><span class="secref">Hash suspend state field sizes</span></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]679<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]680<p>Applications can use this value to unpack the hash suspend state that is output by <a class="reference internal" href="#c.psa_hash_suspend" title="psa_hash_suspend"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_suspend()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]681</div>
682<div class="section" id="PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]683<span id="c.PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH</span></code> (macro)</h3>
684<p>The size of the <em>hash-state</em> field that is part of the output of <a class="reference internal" href="#c.psa_hash_suspend" title="psa_hash_suspend"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_suspend()</span></code></a>, in bytes.</p>
685<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH" title="PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH">PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH</a>(alg) \
686 <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em></pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]687<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]688<dl class="simple">
689<dt> <code class="docutils literal notranslate"><span class="pre">alg</span></code></dt><dd><p>A hash algorithm (<code class="docutils literal notranslate"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal notranslate"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> is true).</p>
690</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]691</dl>
692<p class="rubric">Returns</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]693<p>The size, in bytes, of the <em>hash-state</em> field of the hash suspend state for the specified hash algorithm. If the hash algorithm is not recognized, return <code class="docutils literal notranslate"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal notranslate"><span class="pre">0</span></code> or the correct size for a hash algorithm that it recognizes, but does not support.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]694<p>The algorithm-specific values are defined in <a class="reference internal" href="#hash-suspend-state-constants"><span class="secref">Hash suspend state field sizes</span></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]695<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]696<p>Applications can use this value to unpack the hash suspend state that is output by <a class="reference internal" href="#c.psa_hash_suspend" title="psa_hash_suspend"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_suspend()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]697</div>
698<div class="section" id="PSA_HASH_BLOCK_LENGTH">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]699<span id="c.PSA_HASH_BLOCK_LENGTH"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_HASH_BLOCK_LENGTH</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]700<p>The input block size of a hash algorithm, in bytes.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]701<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_HASH_BLOCK_LENGTH" title="PSA_HASH_BLOCK_LENGTH">PSA_HASH_BLOCK_LENGTH</a>(alg) <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em></pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]702<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]703<dl class="simple">
704<dt> <code class="docutils literal notranslate"><span class="pre">alg</span></code></dt><dd><p>A hash algorithm (<code class="docutils literal notranslate"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal notranslate"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> is true).</p>
705</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]706</dl>
707<p class="rubric">Returns</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]708<p>The block size in bytes for the specified hash algorithm. If the hash algorithm is not recognized, return <code class="docutils literal notranslate"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal notranslate"><span class="pre">0</span></code> or the correct size for a hash algorithm that it recognizes, but does not support.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]709<p class="rubric">Description</p>
710<p>Hash algorithms process their input data in blocks. Hash operations will retain any partial blocks until they have enough input to fill the block or until the operation is finished.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]711<p>This affects the output from <a class="reference internal" href="#c.psa_hash_suspend" title="psa_hash_suspend"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_suspend()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]712</div>
713</div>
714<div class="section" id="hash-suspend-state">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]715<span id="id2"></span><h2>10.2.5. Hash suspend state</h2>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]716<p>The hash suspend state is output by <a class="reference internal" href="#c.psa_hash_suspend" title="psa_hash_suspend"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_suspend()</span></code></a> and input to <a class="reference internal" href="#c.psa_hash_resume" title="psa_hash_resume"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_resume()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]717<div class="admonition note">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]718<p class="admonition-title">Note</p>
719<p>Hash suspend and resume is not defined for the SHA3 family of hash algorithms.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]720</div>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]721<div class="section" id="hash-suspend-state-format">
722<span id="id3"></span><h3>Hash suspend state format</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]723<p>The hash suspend state has the following format:</p>
724<p><em>hash-suspend-state</em> = <em>algorithm</em> || <em>input-length</em> || <em>hash-state</em> || <em>unprocessed-input</em></p>
725<p>The fields in the hash suspend state are defined as follows:</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]726<dl>
727<dt><em>algorithm</em></dt><dd><p>A big-endian 32-bit unsigned integer.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]728<p>The PSA Crypto API algorithm identifier value.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]729<p>The byte length of the <em>algorithm</em> field can be evaluated using <a class="reference internal" href="#c.PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH" title="PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH</span></code></a>.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]730</dd>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]731<dt><em>input-length</em></dt><dd><p>A big-endian unsigned integer</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]732<p>The content of this field is algorithm-specific:</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]733<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]734<li><p>For MD2, this is the number of bytes in the <em>unprocessed-input</em>.</p></li>
735<li><p>For all other hash algorithms, this is the total number of bytes of input to the hash computation. This includes the <em>unprocessed-input</em> bytes.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]736</ul>
737<p>The size of this field is algorithm-specific:</p>
738<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]739<li><p>For MD2: <em>input-length</em> is an 8-bit unsigned integer.</p></li>
740<li><p>For MD4, MD5, RIPEMD-160, SHA-1, SHA-224 and SHA-256: <em>input-length</em> is a 64-bit unsigned integer.</p></li>
741<li><p>For SHA-512, SHA-384 and SHA-512/256: <em>input-length</em> is a 128-bit unsigned integer.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]742</ul>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]743<p>The length, in bytes, of the <em>input-length</em> field can be calculated using <a class="reference internal" href="#c.PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH" title="PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH"><code class="docutils literal notranslate"><span class="pre">PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> where <code class="docutils literal notranslate"><span class="pre">alg</span></code> is a hash algorithm.
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]744See <a class="reference internal" href="#hash-suspend-state-constants"><span class="secref">Hash suspend state field sizes</span></a>.</p>
745</dd>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]746<dt><em>hash-state</em></dt><dd><p>An array of bytes</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]747<p>Algorithm-specific intermediate hash state:</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]748<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]749<li><p>For MD2: 16 bytes of internal checksum, then 48 bytes of intermediate digest.</p></li>
750<li><p>For MD4 and MD5: 4x 32-bit integers, in little-endian encoding.</p></li>
751<li><p>For RIPEMD-160: 5x 32-bit integers, in little-endian encoding.</p></li>
752<li><p>For SHA-1: 5x 32-bit integers, in big-endian encoding.</p></li>
753<li><p>For SHA-224 and SHA-256: 8x 32-bit integers, in big-endian encoding.</p></li>
754<li><p>For SHA-512, SHA-384 and SHA-512/256: 8x 64-bit integers, in big-endian encoding.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]755</ul>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]756<p>The length of this field is specific to the algorithm.
757The length, in bytes, of the <em>hash-state</em> field can be calculated using <a class="reference internal" href="#c.PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH" title="PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH"><code class="docutils literal notranslate"><span class="pre">PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> where <code class="docutils literal notranslate"><span class="pre">alg</span></code> is a hash algorithm.
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]758See <a class="reference internal" href="#hash-suspend-state-constants"><span class="secref">Hash suspend state field sizes</span></a>.</p>
759</dd>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]760<dt><em>unprocessed-input</em></dt><dd><p>0 to (<em>hash-block-size</em>-1) bytes</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]761<p>A partial block of unprocessed input data. This is between zero and <em>hash-block-size</em>-1 bytes of data, the length can be calculated by:</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]762<p><code class="docutils literal notranslate"><span class="pre">length(</span></code><em>unprocessed-input</em><code class="docutils literal notranslate"><span class="pre">)</span></code> <code class="docutils literal notranslate"><span class="pre">=</span></code> <em>input-length</em> <code class="docutils literal notranslate"><span class="pre">%</span></code> <em>hash-block-size</em>.</p>
763<p>The <em>hash-block-size</em> is specific to the algorithm.
764The size of a hash block can be calculated using <a class="reference internal" href="#c.PSA_HASH_BLOCK_LENGTH" title="PSA_HASH_BLOCK_LENGTH"><code class="docutils literal notranslate"><span class="pre">PSA_HASH_BLOCK_LENGTH</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> where <code class="docutils literal notranslate"><span class="pre">alg</span></code> is a hash algorithm.
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]765See <a class="reference internal" href="#hash-suspend-state-constants"><span class="secref">Hash suspend state field sizes</span></a>.</p>
766</dd>
767</dl>
768</div>
769<div class="section" id="hash-suspend-state-field-sizes">
770<span id="hash-suspend-state-constants"></span><h3>Hash suspend state field sizes</h3>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]771<p>The following table defines the algorithm-specific field lengths for the hash suspend state returned by <a class="reference internal" href="#c.psa_hash_suspend" title="psa_hash_suspend"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_suspend()</span></code></a>. All of the field lengths are in bytes. To compute the field lengths for algorithm <code class="docutils literal notranslate"><span class="pre">alg</span></code>, use the following expressions:</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]772<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]773<li><p><a class="reference internal" href="#c.PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH" title="PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH"><code class="docutils literal notranslate"><span class="pre">PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH</span></code></a> returns the length of the <em>algorithm</em> field.</p></li>
774<li><p><a class="reference internal" href="#c.PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH" title="PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH"><code class="docutils literal notranslate"><span class="pre">PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> returns the length of the <em>input-length</em> field.</p></li>
775<li><p><a class="reference internal" href="#c.PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH" title="PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH"><code class="docutils literal notranslate"><span class="pre">PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> returns the length of the <em>hash-state</em> field.</p></li>
776<li><p><a class="reference internal" href="#c.PSA_HASH_BLOCK_LENGTH" title="PSA_HASH_BLOCK_LENGTH"><code class="docutils literal notranslate"><span class="pre">PSA_HASH_BLOCK_LENGTH</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)-1</span></code> is the maximum length of the <em>unprocessed-bytes</em> field.</p></li>
777<li><p><a class="reference internal" href="#c.PSA_HASH_SUSPEND_OUTPUT_SIZE" title="PSA_HASH_SUSPEND_OUTPUT_SIZE"><code class="docutils literal notranslate"><span class="pre">PSA_HASH_SUSPEND_OUTPUT_SIZE</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">slg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> returns the maximum size of the hash suspend state.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]778</ul>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]779<table class="colwidths-auto docutils align-left">
780<thead>
781<tr class="row-odd"><th class="head"><p>Hash algorithm</p></th>
782<th class="head"><p><em>input-length</em> size (bytes)</p></th>
783<th class="head"><p><em>hash-state</em> length (bytes)</p></th>
784<th class="head"><p><em>unprocessed-bytes</em> length (bytes)</p></th>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]785</tr>
786</thead>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]787<tbody>
788<tr class="row-even"><td><p><a class="reference internal" href="#c.PSA_ALG_MD2" title="PSA_ALG_MD2"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_ALG_MD2</span></code></a></p></td>
789<td><p>1</p></td>
790<td><p>64</p></td>
791<td><p>0 - 15</p></td>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]792</tr>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]793<tr class="row-odd"><td><p><a class="reference internal" href="#c.PSA_ALG_MD4" title="PSA_ALG_MD4"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_ALG_MD4</span></code></a></p></td>
794<td><p>8</p></td>
795<td><p>16</p></td>
796<td><p>0 - 63</p></td>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]797</tr>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]798<tr class="row-even"><td><p><a class="reference internal" href="#c.PSA_ALG_MD5" title="PSA_ALG_MD5"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_ALG_MD5</span></code></a></p></td>
799<td><p>8</p></td>
800<td><p>16</p></td>
801<td><p>0 - 63</p></td>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]802</tr>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]803<tr class="row-odd"><td><p><a class="reference internal" href="#c.PSA_ALG_RIPEMD160" title="PSA_ALG_RIPEMD160"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_ALG_RIPEMD160</span></code></a></p></td>
804<td><p>8</p></td>
805<td><p>20</p></td>
806<td><p>0 - 63</p></td>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]807</tr>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]808<tr class="row-even"><td><p><a class="reference internal" href="#c.PSA_ALG_SHA_1" title="PSA_ALG_SHA_1"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_ALG_SHA_1</span></code></a></p></td>
809<td><p>8</p></td>
810<td><p>20</p></td>
811<td><p>0 - 63</p></td>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]812</tr>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]813<tr class="row-odd"><td><p><a class="reference internal" href="#c.PSA_ALG_SHA_224" title="PSA_ALG_SHA_224"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_ALG_SHA_224</span></code></a></p></td>
814<td><p>8</p></td>
815<td><p>32</p></td>
816<td><p>0 - 63</p></td>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]817</tr>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]818<tr class="row-even"><td><p><a class="reference internal" href="#c.PSA_ALG_SHA_256" title="PSA_ALG_SHA_256"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_ALG_SHA_256</span></code></a></p></td>
819<td><p>8</p></td>
820<td><p>32</p></td>
821<td><p>0 - 63</p></td>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]822</tr>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]823<tr class="row-odd"><td><p><a class="reference internal" href="#c.PSA_ALG_SHA_512_256" title="PSA_ALG_SHA_512_256"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_ALG_SHA_512_256</span></code></a></p></td>
824<td><p>16</p></td>
825<td><p>64</p></td>
826<td><p>0 - 127</p></td>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]827</tr>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]828<tr class="row-even"><td><p><a class="reference internal" href="#c.PSA_ALG_SHA_384" title="PSA_ALG_SHA_384"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_ALG_SHA_384</span></code></a></p></td>
829<td><p>16</p></td>
830<td><p>64</p></td>
831<td><p>0 - 127</p></td>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]832</tr>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]833<tr class="row-odd"><td><p><a class="reference internal" href="#c.PSA_ALG_SHA_512" title="PSA_ALG_SHA_512"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_ALG_SHA_512</span></code></a></p></td>
834<td><p>16</p></td>
835<td><p>64</p></td>
836<td><p>0 - 127</p></td>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]837</tr>
838</tbody>
839</table>
840</div>
841</div>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]842</div>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]843
844
845 </div>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]846
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]847 </div>
848 </div>
849 <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]850 <div class="sphinxsidebarwrapper"><h3><a href="../../index.html"><b>PSA Crypto API</b></a></h3>
851IHI 0086<br/>
852Non-confidential<br/>
853Version 1.0.1
854<span style="color: red; font-weight: bold;"></span>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]855<ul>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]856<li class="toctree-l1"><a class="reference internal" href="../../about.html">About this document</a></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]857</ul>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]858<ul class="current">
859<li class="toctree-l1"><a class="reference internal" href="../../overview/intro.html">1. Introduction</a></li>
860<li class="toctree-l1"><a class="reference internal" href="../../overview/goals.html">2. Design goals</a></li>
861<li class="toctree-l1"><a class="reference internal" href="../../overview/functionality.html">3. Functionality overview</a></li>
862<li class="toctree-l1"><a class="reference internal" href="../../overview/sample-arch.html">4. Sample architectures</a></li>
863<li class="toctree-l1"><a class="reference internal" href="../../overview/conventions.html">5. Library conventions</a></li>
864<li class="toctree-l1"><a class="reference internal" href="../../overview/implementation.html">6. Implementation considerations</a></li>
865<li class="toctree-l1"><a class="reference internal" href="../../overview/usage.html">7. Usage considerations</a></li>
866<li class="toctree-l1"><a class="reference internal" href="../library/index.html">8. Library management reference</a></li>
867<li class="toctree-l1"><a class="reference internal" href="../keys/index.html">9. Key management reference</a></li>
868<li class="toctree-l1 current"><a class="reference internal" href="index.html">10. Cryptographic operation reference</a><ul class="current">
869<li class="toctree-l2"><a class="reference internal" href="algorithms.html">10.1. Algorithms</a></li>
870<li class="toctree-l2 current"><a class="current reference internal" href="#">10.2. Message digests</a><ul>
871<li class="toctree-l3"><a class="reference internal" href="#hash-algorithms">10.2.1. Hash algorithms</a></li>
872<li class="toctree-l3"><a class="reference internal" href="#single-part-hashing-functions">10.2.2. Single-part hashing functions</a></li>
873<li class="toctree-l3"><a class="reference internal" href="#multi-part-hashing-operations">10.2.3. Multi-part hashing operations</a></li>
874<li class="toctree-l3"><a class="reference internal" href="#support-macros">10.2.4. Support macros</a></li>
875<li class="toctree-l3"><a class="reference internal" href="#hash-suspend-state">10.2.5. Hash suspend state</a></li>
876</ul>
877</li>
878<li class="toctree-l2"><a class="reference internal" href="macs.html">10.3. Message authentication codes (MAC)</a></li>
879<li class="toctree-l2"><a class="reference internal" href="ciphers.html">10.4. Unauthenticated ciphers</a></li>
880<li class="toctree-l2"><a class="reference internal" href="aead.html">10.5. Authenticated encryption with associated data (AEAD)</a></li>
881<li class="toctree-l2"><a class="reference internal" href="kdf.html">10.6. Key derivation</a></li>
882<li class="toctree-l2"><a class="reference internal" href="sign.html">10.7. Asymmetric signature</a></li>
883<li class="toctree-l2"><a class="reference internal" href="pke.html">10.8. Asymmetric encryption</a></li>
884<li class="toctree-l2"><a class="reference internal" href="ka.html">10.9. Key agreement</a></li>
885<li class="toctree-l2"><a class="reference internal" href="rng.html">10.10. Other cryptographic services</a></li>
886</ul>
887</li>
888</ul>
889<ul>
890<li class="toctree-l1"><a class="reference internal" href="../../appendix/example_header.html">Example header file</a></li>
891<li class="toctree-l1"><a class="reference internal" href="../../appendix/specdef_values.html">Example macro implementations</a></li>
892<li class="toctree-l1"><a class="reference internal" href="../../appendix/history.html">Changes to the API</a></li>
893</ul>
894<ul>
895<li class="toctree-l1"><a class="reference internal" href="../../psa_c-identifiers.html">Index of API elements</a></li>
896</ul>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]897<div id="searchbox" style="display: none" role="search">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]898 <h3 id="searchlabel">Quick search</h3>
899 <div class="searchformwrapper">
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]900 <form class="search" action="../../search.html" method="get">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]901 <input type="text" name="q" aria-labelledby="searchlabel" />
902 <input type="submit" value="Go" />
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]903 </form>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]904 </div>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]905</div>
906<script type="text/javascript">$('#searchbox').show(0);</script>
907 </div>
908 </div>
909 <div class="clearer"></div>
910 </div>
911 <div class="footer">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]912 &copy; 2018-2020, Arm Limited or its affiliates. All rights reserved.
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]913
914 |
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]915 Powered by <a href="http://sphinx-doc.org/">Sphinx 2.1.2</a>
916 &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]917
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]918 </div>
919
920
921
922
923 </body>
924</html>