TrustedFirmware Git Browser
Code Review Sign In
review.trustedfirmware.org / mirror / mbed-crypto / a586c5a66cd83f8b58216382e7d54bd6e8093bfa / . / docs / 1.1.0 / html / api / ops / hashes.html
blob: 40d8bb784aa1bc3fdb75ff4dc4fca4e4e01335df [file] [log] [blame]
Gilles Peskine882f7c72022-04-07 13:44:55 +0200[diff] [blame]1
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
3 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
4
5<html xmlns="http://www.w3.org/1999/xhtml">
6 <head>
7 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
8 <title>10.2. Message digests (Hashes) &#8212; PSA Crypto API 1.1.0 documentation</title>
9 <link rel="stylesheet" href="../../_static/alabaster.css" type="text/css" />
10 <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
11 <script type="text/javascript">
12 var DOCUMENTATION_OPTIONS = {
13 URL_ROOT: '../../',
14 VERSION: '1.1.0',
15 COLLAPSE_INDEX: false,
16 FILE_SUFFIX: '.html',
17 HAS_SOURCE: false,
18 SOURCELINK_SUFFIX: '.txt'
19 };
20 </script>
21 <script type="text/javascript" src="../../_static/jquery.js"></script>
22 <script type="text/javascript" src="../../_static/underscore.js"></script>
23 <script type="text/javascript" src="../../_static/doctools.js"></script>
24 <link rel="author" title="About these documents" href="../../about.html" />
25 <link rel="index" title="Index" href="../../genindex.html" />
26 <link rel="search" title="Search" href="../../search.html" />
27 <link rel="next" title="10.3. Message authentication codes (MAC)" href="macs.html" />
28 <link rel="prev" title="10.1. Algorithms" href="algorithms.html" />
29
30 <link rel="stylesheet" href="../../_static/custom.css" type="text/css" />
31
32 <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
33
34 </head>
35 <body>
36
37
38 <div class="document">
39 <div class="documentwrapper">
40 <div class="bodywrapper">
41 <div class="body" role="main">
42
43 <div class="section" id="message-digests-hashes">
44<span id="hashes"></span><h1>10.2. Message digests (Hashes)</h1>
45<p>The single-part hash functions are:</p>
46<ul class="simple">
47<li><a class="reference internal" href="#c.psa_hash_compute" title="psa_hash_compute"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_compute()</span></code></a> to calculate the hash of a message.</li>
48<li><a class="reference internal" href="#c.psa_hash_compare" title="psa_hash_compare"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_compare()</span></code></a> to compare the hash of a message with a reference value.</li>
49</ul>
50<p>The <a class="reference internal" href="#c.psa_hash_operation_t" title="psa_hash_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_hash_operation_t</span></code></a> <a class="reference internal" href="../../overview/functionality.html#multi-part-operations"><span class="std std-ref">multi-part operation</span></a> allows messages to be processed in fragments. A multi-part hash operation is used as follows:</p>
51<ol class="arabic simple">
52<li>Initialize the <a class="reference internal" href="#c.psa_hash_operation_t" title="psa_hash_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_hash_operation_t</span></code></a> object to zero, or by assigning the value of the associated macro <a class="reference internal" href="#c.PSA_HASH_OPERATION_INIT" title="PSA_HASH_OPERATION_INIT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_HASH_OPERATION_INIT</span></code></a>.</li>
53<li>Call <a class="reference internal" href="#c.psa_hash_setup" title="psa_hash_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_setup()</span></code></a> to specify the required hash algorithm, call <a class="reference internal" href="#c.psa_hash_clone" title="psa_hash_clone"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_clone()</span></code></a> to duplicate the state of <em>active</em> <a class="reference internal" href="#c.psa_hash_operation_t" title="psa_hash_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_hash_operation_t</span></code></a> object, or call <a class="reference internal" href="#c.psa_hash_resume" title="psa_hash_resume"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_resume()</span></code></a> to restart a hash operation with the output from a previously suspended hash operation.</li>
54<li>Call the <a class="reference internal" href="#c.psa_hash_update" title="psa_hash_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_update()</span></code></a> function on successive chunks of the message.</li>
55<li>At the end of the message, call the required finishing function:<ul>
56<li>To suspend the hash operation and extract a hash suspend state, call <a class="reference internal" href="#c.psa_hash_suspend" title="psa_hash_suspend"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_suspend()</span></code></a>. The output state can subsequently be used to resume the hash operation.</li>
57<li>To calculate the digest of a message, call <a class="reference internal" href="#c.psa_hash_finish" title="psa_hash_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_finish()</span></code></a>.</li>
58<li>To verify the digest of a message against a reference value, call <a class="reference internal" href="#c.psa_hash_verify" title="psa_hash_verify"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_verify()</span></code></a>.</li>
59</ul>
60</li>
61</ol>
62<p>To abort the operation or recover from an error, call <a class="reference internal" href="#c.psa_hash_abort" title="psa_hash_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_abort()</span></code></a>.</p>
63<div class="section" id="hash-algorithms">
64<span id="id1"></span><h2>10.2.1. Hash algorithms</h2>
65<div class="section" id="PSA_ALG_MD2">
66<span id="c.PSA_ALG_MD2"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_MD2</span></code> (macro)</h3>
67<p>The MD2 message-digest algorithm.</p>
68<pre class="literal-block">
69#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)
70</pre>
71<div class="admonition warning">
72<p class="first admonition-title">Warning</p>
73<p class="last">The MD2 hash is weak and deprecated and is only recommended for use in legacy protocols.</p>
74</div>
75<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>
76</div>
77<div class="section" id="PSA_ALG_MD4">
78<span id="c.PSA_ALG_MD4"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_MD4</span></code> (macro)</h3>
79<p>The MD4 message-digest algorithm.</p>
80<pre class="literal-block">
81#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)
82</pre>
83<div class="admonition warning">
84<p class="first admonition-title">Warning</p>
85<p class="last">The MD4 hash is weak and deprecated and is only recommended for use in legacy protocols.</p>
86</div>
87<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>
88</div>
89<div class="section" id="PSA_ALG_MD5">
90<span id="c.PSA_ALG_MD5"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_MD5</span></code> (macro)</h3>
91<p>The MD5 message-digest algorithm.</p>
92<pre class="literal-block">
93#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)
94</pre>
95<div class="admonition warning">
96<p class="first admonition-title">Warning</p>
97<p class="last">The MD5 hash is weak and deprecated and is only recommended for use in legacy protocols.</p>
98</div>
99<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>
100</div>
101<div class="section" id="PSA_ALG_RIPEMD160">
102<span id="c.PSA_ALG_RIPEMD160"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_RIPEMD160</span></code> (macro)</h3>
103<p>The RIPEMD-160 message-digest algorithm.</p>
104<pre class="literal-block">
105#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)
106</pre>
107<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>
108</div>
109<div class="section" id="PSA_ALG_SHA_1">
110<span id="c.PSA_ALG_SHA_1"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_SHA_1</span></code> (macro)</h3>
111<p>The SHA-1 message-digest algorithm.</p>
112<pre class="literal-block">
113#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)
114</pre>
115<div class="admonition warning">
116<p class="first admonition-title">Warning</p>
117<p class="last">The SHA-1 hash is weak and deprecated and is only recommended for use in legacy protocols.</p>
118</div>
119<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>
120</div>
121<div class="section" id="PSA_ALG_SHA_224">
122<span id="c.PSA_ALG_SHA_224"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_SHA_224</span></code> (macro)</h3>
123<p>The SHA-224 message-digest algorithm.</p>
124<pre class="literal-block">
125#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)
126</pre>
127<p>SHA-224 is defined in <a class="reference internal" href="../../about.html#citation-fips180-4"><span class="cite">[FIPS180-4]</span></a>.</p>
128</div>
129<div class="section" id="PSA_ALG_SHA_256">
130<span id="c.PSA_ALG_SHA_256"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_SHA_256</span></code> (macro)</h3>
131<p>The SHA-256 message-digest algorithm.</p>
132<pre class="literal-block">
133#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)
134</pre>
135<p>SHA-256 is defined in <a class="reference internal" href="../../about.html#citation-fips180-4"><span class="cite">[FIPS180-4]</span></a>.</p>
136</div>
137<div class="section" id="PSA_ALG_SHA_384">
138<span id="c.PSA_ALG_SHA_384"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_SHA_384</span></code> (macro)</h3>
139<p>The SHA-384 message-digest algorithm.</p>
140<pre class="literal-block">
141#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)
142</pre>
143<p>SHA-384 is defined in <a class="reference internal" href="../../about.html#citation-fips180-4"><span class="cite">[FIPS180-4]</span></a>.</p>
144</div>
145<div class="section" id="PSA_ALG_SHA_512">
146<span id="c.PSA_ALG_SHA_512"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_SHA_512</span></code> (macro)</h3>
147<p>The SHA-512 message-digest algorithm.</p>
148<pre class="literal-block">
149#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)
150</pre>
151<p>SHA-512 is defined in <a class="reference internal" href="../../about.html#citation-fips180-4"><span class="cite">[FIPS180-4]</span></a>.</p>
152</div>
153<div class="section" id="PSA_ALG_SHA_512_224">
154<span id="c.PSA_ALG_SHA_512_224"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_SHA_512_224</span></code> (macro)</h3>
155<p>The SHA-512/224 message-digest algorithm.</p>
156<pre class="literal-block">
157#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)
158</pre>
159<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>
160</div>
161<div class="section" id="PSA_ALG_SHA_512_256">
162<span id="c.PSA_ALG_SHA_512_256"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_SHA_512_256</span></code> (macro)</h3>
163<p>The SHA-512/256 message-digest algorithm.</p>
164<pre class="literal-block">
165#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)
166</pre>
167<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>
168</div>
169<div class="section" id="PSA_ALG_SHA3_224">
170<span id="c.PSA_ALG_SHA3_224"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_SHA3_224</span></code> (macro)</h3>
171<p>The SHA3-224 message-digest algorithm.</p>
172<pre class="literal-block">
173#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)
174</pre>
175<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>
176</div>
177<div class="section" id="PSA_ALG_SHA3_256">
178<span id="c.PSA_ALG_SHA3_256"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_SHA3_256</span></code> (macro)</h3>
179<p>The SHA3-256 message-digest algorithm.</p>
180<pre class="literal-block">
181#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)
182</pre>
183<p>SHA3-256 is defined in <a class="reference internal" href="../../about.html#citation-fips202"><span class="cite">[FIPS202]</span></a>.</p>
184</div>
185<div class="section" id="PSA_ALG_SHA3_384">
186<span id="c.PSA_ALG_SHA3_384"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_SHA3_384</span></code> (macro)</h3>
187<p>The SHA3-384 message-digest algorithm.</p>
188<pre class="literal-block">
189#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)
190</pre>
191<p>SHA3-384 is defined in <a class="reference internal" href="../../about.html#citation-fips202"><span class="cite">[FIPS202]</span></a>.</p>
192</div>
193<div class="section" id="PSA_ALG_SHA3_512">
194<span id="c.PSA_ALG_SHA3_512"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_SHA3_512</span></code> (macro)</h3>
195<p>The SHA3-512 message-digest algorithm.</p>
196<pre class="literal-block">
197#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)
198</pre>
199<p>SHA3-512 is defined in <a class="reference internal" href="../../about.html#citation-fips202"><span class="cite">[FIPS202]</span></a>.</p>
200</div>
201<div class="section" id="PSA_ALG_SHAKE256_512">
202<span id="c.PSA_ALG_SHAKE256_512"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_SHAKE256_512</span></code> (macro)</h3>
203<p>The first 512 bits (64 bytes) of the SHAKE256 output.</p>
204<pre class="literal-block">
205#define <a class="reference internal" href="#c.PSA_ALG_SHAKE256_512" title="PSA_ALG_SHAKE256_512">PSA_ALG_SHAKE256_512</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x02000015)
206</pre>
207<p>This is the prehashing for Ed448ph (see <a class="reference internal" href="sign.html#c.PSA_ALG_ED448PH" title="PSA_ALG_ED448PH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ED448PH</span></code></a>).</p>
208<p>SHAKE256 is defined in <a class="reference internal" href="../../about.html#citation-fips202"><span class="cite">[FIPS202]</span></a>.</p>
209<div class="admonition note">
210<p class="first admonition-title">Note</p>
211<p class="last">For other scenarios where a hash function based on SHA3 or SHAKE is required, SHA3-512 is recommended. SHA3-512 has the same output size, and a theoretically higher security strength.</p>
212</div>
213</div>
214<div class="section" id="PSA_ALG_SM3">
215<span id="c.PSA_ALG_SM3"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_SM3</span></code> (macro)</h3>
216<p>The SM3 message-digest algorithm.</p>
217<pre class="literal-block">
218#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)
219</pre>
220<p>SM3 is defined 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>, and also in <span><em>GM/T 0004-2012: SM3 cryptographic hash algorithm</em> <a class="reference internal" href="../../about.html#citation-cstc0004"><span class="cite">[CSTC0004]</span></a></span> (English version <a class="reference internal" href="../../about.html#citation-cstc0004-e"><span class="cite">[CSTC0004/E]</span></a>).</p>
221</div>
222</div>
223<div class="section" id="single-part-hashing-functions">
224<h2>10.2.2. Single-part hashing functions</h2>
225<div class="section" id="psa_hash_compute">
226<span id="c.psa_hash_compute"></span><h3><code class="docutils literal"><span class="pre">psa_hash_compute</span></code> (function)</h3>
227<p>Calculate the hash (digest) of a message.</p>
228<pre class="literal-block">
229<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,
230 const uint8_t * input,
231 size_t input_length,
232 uint8_t * hash,
233 size_t hash_size,
234 size_t * hash_length);
235</pre>
236<p class="rubric">Parameters</p>
237<dl class="docutils">
238<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
239<dd>The hash algorithm to compute: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a> such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true.</dd>
240<dt> <code class="docutils literal"><span class="pre">input</span></code></dt>
241<dd>Buffer containing the message to hash.</dd>
242<dt> <code class="docutils literal"><span class="pre">input_length</span></code></dt>
243<dd>Size of the <code class="docutils literal"><span class="pre">input</span></code> buffer in bytes.</dd>
244<dt> <code class="docutils literal"><span class="pre">hash</span></code></dt>
245<dd>Buffer where the hash is to be written.</dd>
246<dt> <code class="docutils literal"><span class="pre">hash_size</span></code></dt>
247<dd>Size of the <code class="docutils literal"><span class="pre">hash</span></code> buffer in bytes.
248This must be at least <a class="reference internal" href="#c.PSA_HASH_LENGTH" title="PSA_HASH_LENGTH"><code class="docutils literal"><span class="pre">PSA_HASH_LENGTH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code>.</dd>
249<dt> <code class="docutils literal"><span class="pre">hash_length</span></code></dt>
250<dd>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"><span class="pre">PSA_HASH_LENGTH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code>.</dd>
251</dl>
252<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
253<dl class="docutils">
254<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
255<dd>Success.
256The first <code class="docutils literal"><span class="pre">(*hash_length)</span></code> bytes of <code class="docutils literal"><span class="pre">hash</span></code> contain the hash value.</dd>
257<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
258<dd>The library requires initializing by a call to <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"><span class="pre">psa_crypto_init()</span></code></a>.</dd>
259<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"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a></dt>
260<dd>The size of the <code class="docutils literal"><span class="pre">hash</span></code> buffer is too small.
261<a class="reference internal" href="#c.PSA_HASH_LENGTH" title="PSA_HASH_LENGTH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_HASH_LENGTH()</span></code></a> can be used to determine a sufficient buffer size.</dd>
262<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
263<dd><p class="first">The following conditions can result in this error:</p>
264<ul class="last simple">
265<li><code class="docutils literal"><span class="pre">alg</span></code> is not a hash algorithm.</li>
266<li><code class="docutils literal"><span class="pre">input_length</span></code> is too large for <code class="docutils literal"><span class="pre">alg</span></code>.</li>
267</ul>
268</dd>
269<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
270<dd><p class="first">The following conditions can result in this error:</p>
271<ul class="last simple">
272<li><code class="docutils literal"><span class="pre">alg</span></code> is not supported or is not a hash algorithm.</li>
273<li><code class="docutils literal"><span class="pre">input_length</span></code> is too large for the implementation.</li>
274</ul>
275</dd>
276<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt>
277<dd></dd>
278<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
279<dd></dd>
280<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
281<dd></dd>
282</dl>
283<p class="rubric">Description</p>
284<div class="admonition note">
285<p class="first admonition-title">Note</p>
286<p class="last">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"><span class="pre">psa_hash_compare()</span></code></a> instead.</p>
287</div>
288</div>
289<div class="section" id="psa_hash_compare">
290<span id="c.psa_hash_compare"></span><h3><code class="docutils literal"><span class="pre">psa_hash_compare</span></code> (function)</h3>
291<p>Calculate the hash (digest) of a message and compare it with a reference value.</p>
292<pre class="literal-block">
293<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,
294 const uint8_t * input,
295 size_t input_length,
296 const uint8_t * hash,
297 size_t hash_length);
298</pre>
299<p class="rubric">Parameters</p>
300<dl class="docutils">
301<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
302<dd>The hash algorithm to compute: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a> such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true.</dd>
303<dt> <code class="docutils literal"><span class="pre">input</span></code></dt>
304<dd>Buffer containing the message to hash.</dd>
305<dt> <code class="docutils literal"><span class="pre">input_length</span></code></dt>
306<dd>Size of the <code class="docutils literal"><span class="pre">input</span></code> buffer in bytes.</dd>
307<dt> <code class="docutils literal"><span class="pre">hash</span></code></dt>
308<dd>Buffer containing the expected hash value.</dd>
309<dt> <code class="docutils literal"><span class="pre">hash_length</span></code></dt>
310<dd>Size of the <code class="docutils literal"><span class="pre">hash</span></code> buffer in bytes.</dd>
311</dl>
312<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
313<dl class="docutils">
314<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
315<dd>Success.
316The expected hash is identical to the actual hash of the input.</dd>
317<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
318<dd>The library requires initializing by a call to <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"><span class="pre">psa_crypto_init()</span></code></a>.</dd>
319<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_SIGNATURE" title="PSA_ERROR_INVALID_SIGNATURE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_SIGNATURE</span></code></a></dt>
320<dd>The calculated hash of the message does not match the value in <code class="docutils literal"><span class="pre">hash</span></code>.</dd>
321<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
322<dd><p class="first">The following conditions can result in this error:</p>
323<ul class="last simple">
324<li><code class="docutils literal"><span class="pre">alg</span></code> is not a hash algorithm.</li>
325<li><code class="docutils literal"><span class="pre">input_length</span></code> is too large for <code class="docutils literal"><span class="pre">alg</span></code>.</li>
326</ul>
327</dd>
328<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
329<dd><p class="first">The following conditions can result in this error:</p>
330<ul class="last simple">
331<li><code class="docutils literal"><span class="pre">alg</span></code> is not supported or is not a hash algorithm.</li>
332<li><code class="docutils literal"><span class="pre">input_length</span></code> is too large for the implementation.</li>
333</ul>
334</dd>
335<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt>
336<dd></dd>
337<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
338<dd></dd>
339<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
340<dd></dd>
341</dl>
342</div>
343</div>
344<div class="section" id="multi-part-hashing-operations">
345<span id="hash-mp"></span><h2>10.2.3. Multi-part hashing operations</h2>
346<div class="section" id="psa_hash_operation_t">
347<span id="c.psa_hash_operation_t"></span><h3><code class="docutils literal"><span class="pre">psa_hash_operation_t</span></code> (type)</h3>
348<p>The type of the state object for multi-part hash operations.</p>
349<pre class="literal-block">
350typedef <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>;
351</pre>
352<p>Before calling any function on a hash operation object, the application must initialize it by any of the following means:</p>
353<ul>
354<li><p class="first">Set the object to all-bits-zero, for example:</p>
355<pre class="literal-block">
356<a class="reference internal" href="#c.psa_hash_operation_t" title="psa_hash_operation_t">psa_hash_operation_t</a> operation;
357memset(&amp;operation, 0, sizeof(operation));
358</pre>
359</li>
360<li><p class="first">Initialize the object to logical zero values by declaring the object as static or global without an explicit initializer, for example:</p>
361<pre class="literal-block">
362static <a class="reference internal" href="#c.psa_hash_operation_t" title="psa_hash_operation_t">psa_hash_operation_t</a> operation;
363</pre>
364</li>
365<li><p class="first">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"><span class="pre">PSA_HASH_OPERATION_INIT</span></code></a>, for example:</p>
366<pre class="literal-block">
367<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>;
368</pre>
369</li>
370<li><p class="first">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"><span class="pre">psa_hash_operation_init()</span></code></a> to the object, for example:</p>
371<pre class="literal-block">
372<a class="reference internal" href="#c.psa_hash_operation_t" title="psa_hash_operation_t">psa_hash_operation_t</a> operation;
373operation = <a class="reference internal" href="#c.psa_hash_operation_init" title="psa_hash_operation_init">psa_hash_operation_init</a>();
374</pre>
375</li>
376</ul>
377<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>
378</div>
379<div class="section" id="PSA_HASH_OPERATION_INIT">
380<span id="c.PSA_HASH_OPERATION_INIT"></span><h3><code class="docutils literal"><span class="pre">PSA_HASH_OPERATION_INIT</span></code> (macro)</h3>
381<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"><span class="pre">psa_hash_operation_t</span></code></a>.</p>
382<pre class="literal-block">
383#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>
384</pre>
385</div>
386<div class="section" id="psa_hash_operation_init">
387<span id="c.psa_hash_operation_init"></span><h3><code class="docutils literal"><span class="pre">psa_hash_operation_init</span></code> (function)</h3>
388<p>Return an initial value for a hash operation object.</p>
389<pre class="literal-block">
390<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);
391</pre>
392<p class="rubric">Returns: <a class="reference internal" href="#c.psa_hash_operation_t" title="psa_hash_operation_t"><code class="docutils literal"><span class="pre">psa_hash_operation_t</span></code></a></p>
393</div>
394<div class="section" id="psa_hash_setup">
395<span id="c.psa_hash_setup"></span><h3><code class="docutils literal"><span class="pre">psa_hash_setup</span></code> (function)</h3>
396<p>Set up a multi-part hash operation.</p>
397<pre class="literal-block">
398<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,
399 <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg);
400</pre>
401<p class="rubric">Parameters</p>
402<dl class="docutils">
403<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
404<dd>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"><span class="pre">psa_hash_operation_t</span></code></a> and not yet in use.</dd>
405<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
406<dd>The hash algorithm to compute: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a> such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true.</dd>
407</dl>
408<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
409<dl class="docutils">
410<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
411<dd>Success.</dd>
412<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
413<dd><p class="first">The following conditions can result in this error:</p>
414<ul class="last simple">
415<li>The operation state is not valid: it must be inactive.</li>
416<li>The library requires initializing by a call to <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"><span class="pre">psa_crypto_init()</span></code></a>.</li>
417</ul>
418</dd>
419<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
420<dd><code class="docutils literal"><span class="pre">alg</span></code> is not a hash algorithm.</dd>
421<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
422<dd><code class="docutils literal"><span class="pre">alg</span></code> is not supported or is not a hash algorithm.</dd>
423<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt>
424<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"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
426<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"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
428<dd></dd>
429</dl>
430<p class="rubric">Description</p>
431<p>The sequence of operations to calculate a hash (message digest) is as follows:</p>
432<ol class="arabic simple">
433<li>Allocate an operation object which will be passed to all the functions listed here.</li>
434<li>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"><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"><span class="pre">PSA_HASH_OPERATION_INIT</span></code></a>.</li>
435<li>Call <a class="reference internal" href="#c.psa_hash_setup" title="psa_hash_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_setup()</span></code></a> to specify the algorithm.</li>
436<li>Call <a class="reference internal" href="#c.psa_hash_update" title="psa_hash_update"><code class="xref any c c-func docutils literal"><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.</li>
437<li>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"><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"><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"><span class="pre">psa_hash_suspend()</span></code></a>.</li>
438</ol>
439<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"><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"><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"><span class="pre">psa_hash_abort()</span></code></a> at any time after the operation has been initialized.</p>
440<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"><span class="pre">psa_hash_setup()</span></code></a>, the application must eventually terminate the operation. The following events terminate an operation:</p>
441<ul class="simple">
442<li>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"><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"><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"><span class="pre">psa_hash_suspend()</span></code></a>.</li>
443<li>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"><span class="pre">psa_hash_abort()</span></code></a>.</li>
444</ul>
445</div>
446<div class="section" id="psa_hash_update">
447<span id="c.psa_hash_update"></span><h3><code class="docutils literal"><span class="pre">psa_hash_update</span></code> (function)</h3>
448<p>Add a message fragment to a multi-part hash operation.</p>
449<pre class="literal-block">
450<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,
451 const uint8_t * input,
452 size_t input_length);
453</pre>
454<p class="rubric">Parameters</p>
455<dl class="docutils">
456<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
457<dd>Active hash operation.</dd>
458<dt> <code class="docutils literal"><span class="pre">input</span></code></dt>
459<dd>Buffer containing the message fragment to hash.</dd>
460<dt> <code class="docutils literal"><span class="pre">input_length</span></code></dt>
461<dd>Size of the <code class="docutils literal"><span class="pre">input</span></code> buffer in bytes.</dd>
462</dl>
463<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
464<dl class="docutils">
465<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
466<dd>Success.</dd>
467<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
468<dd><p class="first">The following conditions can result in this error:</p>
469<ul class="last simple">
470<li>The operation state is not valid: it must be active.</li>
471<li>The library requires initializing by a call to <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"><span class="pre">psa_crypto_init()</span></code></a>.</li>
472</ul>
473</dd>
474<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
475<dd>The total input for the operation is too large for the hash algorithm.</dd>
476<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
477<dd>The total input for the operation is too large for the implementation.</dd>
478<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt>
479<dd></dd>
480<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
481<dd></dd>
482<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
483<dd></dd>
484</dl>
485<p class="rubric">Description</p>
486<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"><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"><span class="pre">psa_hash_resume()</span></code></a> before calling this function.</p>
487<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"><span class="pre">psa_hash_abort()</span></code></a>.</p>
488</div>
489<div class="section" id="psa_hash_finish">
490<span id="c.psa_hash_finish"></span><h3><code class="docutils literal"><span class="pre">psa_hash_finish</span></code> (function)</h3>
491<p>Finish the calculation of the hash of a message.</p>
492<pre class="literal-block">
493<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,
494 uint8_t * hash,
495 size_t hash_size,
496 size_t * hash_length);
497</pre>
498<p class="rubric">Parameters</p>
499<dl class="docutils">
500<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
501<dd>Active hash operation.</dd>
502<dt> <code class="docutils literal"><span class="pre">hash</span></code></dt>
503<dd>Buffer where the hash is to be written.</dd>
504<dt> <code class="docutils literal"><span class="pre">hash_size</span></code></dt>
505<dd>Size of the <code class="docutils literal"><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"><span class="pre">PSA_HASH_LENGTH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">alg</span></code> is the algorithm that the operation performs.</dd>
506<dt> <code class="docutils literal"><span class="pre">hash_length</span></code></dt>
507<dd>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"><span class="pre">PSA_HASH_LENGTH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">alg</span></code> is the hash algorithm that the operation performs.</dd>
508</dl>
509<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
510<dl class="docutils">
511<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
512<dd>Success.
513The first <code class="docutils literal"><span class="pre">(*hash_length)</span></code> bytes of <code class="docutils literal"><span class="pre">hash</span></code> contain the hash value.</dd>
514<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
515<dd><p class="first">The following conditions can result in this error:</p>
516<ul class="last simple">
517<li>The operation state is not valid: it must be active.</li>
518<li>The library requires initializing by a call to <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"><span class="pre">psa_crypto_init()</span></code></a>.</li>
519</ul>
520</dd>
521<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"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a></dt>
522<dd>The size of the <code class="docutils literal"><span class="pre">hash</span></code> buffer is too small.
523<a class="reference internal" href="#c.PSA_HASH_LENGTH" title="PSA_HASH_LENGTH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_HASH_LENGTH()</span></code></a> can be used to determine a sufficient buffer size.</dd>
524<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt>
525<dd></dd>
526<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
527<dd></dd>
528<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
529<dd></dd>
530</dl>
531<p class="rubric">Description</p>
532<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"><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"><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"><span class="pre">psa_hash_update()</span></code></a>.</p>
533<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"><span class="pre">psa_hash_abort()</span></code></a>.</p>
534<div class="admonition warning">
535<p class="first admonition-title">Warning</p>
536<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"><span class="pre">psa_hash_verify()</span></code></a> instead with the expected hash value.</p>
537<p class="last">Comparing integrity or authenticity data such as hash values with a function such as <code class="docutils literal"><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>
538</div>
539</div>
540<div class="section" id="psa_hash_verify">
541<span id="c.psa_hash_verify"></span><h3><code class="docutils literal"><span class="pre">psa_hash_verify</span></code> (function)</h3>
542<p>Finish the calculation of the hash of a message and compare it with an expected value.</p>
543<pre class="literal-block">
544<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,
545 const uint8_t * hash,
546 size_t hash_length);
547</pre>
548<p class="rubric">Parameters</p>
549<dl class="docutils">
550<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
551<dd>Active hash operation.</dd>
552<dt> <code class="docutils literal"><span class="pre">hash</span></code></dt>
553<dd>Buffer containing the expected hash value.</dd>
554<dt> <code class="docutils literal"><span class="pre">hash_length</span></code></dt>
555<dd>Size of the <code class="docutils literal"><span class="pre">hash</span></code> buffer in bytes.</dd>
556</dl>
557<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
558<dl class="docutils">
559<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
560<dd>Success.
561The expected hash is identical to the actual hash of the message.</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"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
563<dd><p class="first">The following conditions can result in this error:</p>
564<ul class="last simple">
565<li>The operation state is not valid: it must be active.</li>
566<li>The library requires initializing by a call to <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"><span class="pre">psa_crypto_init()</span></code></a>.</li>
567</ul>
568</dd>
569<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_SIGNATURE" title="PSA_ERROR_INVALID_SIGNATURE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_SIGNATURE</span></code></a></dt>
570<dd>The calculated hash of the message does not match the value in <code class="docutils literal"><span class="pre">hash</span></code>.</dd>
571<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt>
572<dd></dd>
573<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
574<dd></dd>
575<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
576<dd></dd>
577</dl>
578<p class="rubric">Description</p>
579<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"><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"><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>
580<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"><span class="pre">psa_hash_abort()</span></code></a>.</p>
581<div class="admonition note">
582<p class="first admonition-title">Note</p>
583<p class="last">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>
584</div>
585</div>
586<div class="section" id="psa_hash_abort">
587<span id="c.psa_hash_abort"></span><h3><code class="docutils literal"><span class="pre">psa_hash_abort</span></code> (function)</h3>
588<p>Abort a hash operation.</p>
589<pre class="literal-block">
590<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);
591</pre>
592<p class="rubric">Parameters</p>
593<dl class="docutils">
594<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
595<dd>Initialized hash operation.</dd>
596</dl>
597<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
598<dl class="docutils">
599<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
600<dd>Success.
601The operation object can now be discarded or reused.</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"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
603<dd>The library requires initializing by a call to <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"><span class="pre">psa_crypto_init()</span></code></a>.</dd>
604<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
605<dd></dd>
606<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
607<dd></dd>
608</dl>
609<p class="rubric">Description</p>
610<p>Aborting an operation frees all associated resources except for the <code class="docutils literal"><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"><span class="pre">psa_hash_setup()</span></code></a> again.</p>
611<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"><span class="pre">psa_hash_operation_t</span></code></a>.</p>
612<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"><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"><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"><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"><span class="pre">psa_hash_verify()</span></code></a> is safe and has no effect.</p>
613</div>
614<div class="section" id="psa_hash_suspend">
615<span id="c.psa_hash_suspend"></span><h3><code class="docutils literal"><span class="pre">psa_hash_suspend</span></code> (function)</h3>
616<p>Halt the hash operation and extract the intermediate state of the hash computation.</p>
617<pre class="literal-block">
618<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,
619 uint8_t * hash_state,
620 size_t hash_state_size,
621 size_t * hash_state_length);
622</pre>
623<p class="rubric">Parameters</p>
624<dl class="docutils">
625<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
626<dd>Active hash operation.</dd>
627<dt> <code class="docutils literal"><span class="pre">hash_state</span></code></dt>
628<dd>Buffer where the hash suspend state is to be written.</dd>
629<dt> <code class="docutils literal"><span class="pre">hash_state_size</span></code></dt>
630<dd><p class="first">Size of the <code class="docutils literal"><span class="pre">hash_state</span></code> buffer in bytes.
631This must be appropriate for the selected algorithm:</p>
632<ul class="last simple">
633<li>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"><span class="pre">PSA_HASH_SUSPEND_OUTPUT_SIZE</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">alg</span></code> is the algorithm that was used to set up the operation.</li>
634<li><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"><span class="pre">PSA_HASH_SUSPEND_OUTPUT_MAX_SIZE</span></code></a> evaluates to the maximum output size of any supported hash algorithm.</li>
635</ul>
636</dd>
637<dt> <code class="docutils literal"><span class="pre">hash_state_length</span></code></dt>
638<dd>On success, the number of bytes that make up the hash suspend state.</dd>
639</dl>
640<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
641<dl class="docutils">
642<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
643<dd>Success.
644The first <code class="docutils literal"><span class="pre">(*hash_state_length)</span></code> bytes of <code class="docutils literal"><span class="pre">hash_state</span></code> contain the intermediate hash state.</dd>
645<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
646<dd><p class="first">The following conditions can result in this error:</p>
647<ul class="last simple">
648<li>The operation state is not valid: it must be active.</li>
649<li>The library requires initializing by a call to <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"><span class="pre">psa_crypto_init()</span></code></a>.</li>
650</ul>
651</dd>
652<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"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a></dt>
653<dd>The size of the <code class="docutils literal"><span class="pre">hash_state</span></code> buffer is too small.
654<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"><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"><span class="pre">PSA_HASH_SUSPEND_OUTPUT_MAX_SIZE</span></code></a> can be used to determine a sufficient buffer size.</dd>
655<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
656<dd>The hash algorithm being computed does not support suspend and resume.</dd>
657<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt>
658<dd></dd>
659<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
660<dd></dd>
661<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
662<dd></dd>
663</dl>
664<p class="rubric">Description</p>
665<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"><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"><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"><span class="pre">psa_hash_update()</span></code></a>.</p>
666<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"><span class="pre">psa_hash_resume()</span></code></a>.</p>
667<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"><span class="pre">psa_hash_abort()</span></code></a>.</p>
668<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"><span class="pre">psa_hash_suspend()</span></code></a>.</p>
669<div class="admonition warning">
670<p class="first admonition-title">Warning</p>
671<p class="last">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"><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"><span class="pre">psa_hash_verify()</span></code></a> can then calculate or verify the final hash value.</p>
672</div>
673<p class="rubric">Usage</p>
674<p>The sequence of operations to suspend and resume a hash operation is as follows:</p>
675<ol class="arabic simple">
676<li>Compute the first part of the hash.<ol class="loweralpha">
677<li>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"><span class="pre">psa_hash_operation_t</span></code></a>.</li>
678<li>Call <a class="reference internal" href="#c.psa_hash_setup" title="psa_hash_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_setup()</span></code></a> to specify the algorithm.</li>
679<li>Call <a class="reference internal" href="#c.psa_hash_update" title="psa_hash_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_update()</span></code></a> zero, one or more times, passing a fragment of the message each time.</li>
680<li>Call <a class="reference internal" href="#c.psa_hash_suspend" title="psa_hash_suspend"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_suspend()</span></code></a> to extract the hash suspend state into a buffer.</li>
681</ol>
682</li>
683<li>Pass the hash state buffer to the application which will resume the operation.</li>
684<li>Compute the rest of the hash.<ol class="loweralpha">
685<li>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"><span class="pre">psa_hash_operation_t</span></code></a>.</li>
686<li>Call <a class="reference internal" href="#c.psa_hash_resume" title="psa_hash_resume"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_resume()</span></code></a> with the extracted hash state.</li>
687<li>Call <a class="reference internal" href="#c.psa_hash_update" title="psa_hash_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_update()</span></code></a> zero, one or more times, passing a fragment of the message each time.</li>
688<li>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"><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"><span class="pre">psa_hash_verify()</span></code></a>.</li>
689</ol>
690</li>
691</ol>
692<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"><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"><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"><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"><span class="pre">psa_hash_abort()</span></code></a> at any time after the operation has been initialized.</p>
693</div>
694<div class="section" id="psa_hash_resume">
695<span id="c.psa_hash_resume"></span><h3><code class="docutils literal"><span class="pre">psa_hash_resume</span></code> (function)</h3>
696<p>Set up a multi-part hash operation using the hash suspend state from a previously suspended hash operation.</p>
697<pre class="literal-block">
698<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,
699 const uint8_t * hash_state,
700 size_t hash_state_length);
701</pre>
702<p class="rubric">Parameters</p>
703<dl class="docutils">
704<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
705<dd>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"><span class="pre">psa_hash_operation_t</span></code></a> and not yet in use.</dd>
706<dt> <code class="docutils literal"><span class="pre">hash_state</span></code></dt>
707<dd>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"><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>.</dd>
708<dt> <code class="docutils literal"><span class="pre">hash_state_length</span></code></dt>
709<dd>Length of <code class="docutils literal"><span class="pre">hash_state</span></code> in bytes.</dd>
710</dl>
711<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
712<dl class="docutils">
713<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
714<dd>Success.</dd>
715<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
716<dd><p class="first">The following conditions can result in this error:</p>
717<ul class="last simple">
718<li>The operation state is not valid: it must be inactive.</li>
719<li>The library requires initializing by a call to <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"><span class="pre">psa_crypto_init()</span></code></a>.</li>
720</ul>
721</dd>
722<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
723<dd><code class="docutils literal"><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.</dd>
724<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
725<dd>The provided hash suspend state is for an algorithm that is not supported.</dd>
726<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt>
727<dd></dd>
728<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
729<dd></dd>
730<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
731<dd></dd>
732</dl>
733<p class="rubric">Description</p>
734<p>See <a class="reference internal" href="#c.psa_hash_suspend" title="psa_hash_suspend"><code class="xref any c c-func docutils literal"><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>
735<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"><span class="pre">psa_hash_resume()</span></code></a>, the application must eventually terminate the operation. The following events terminate an operation:</p>
736<ul class="simple">
737<li>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"><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"><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"><span class="pre">psa_hash_suspend()</span></code></a>.</li>
738<li>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"><span class="pre">psa_hash_abort()</span></code></a>.</li>
739</ul>
740</div>
741<div class="section" id="psa_hash_clone">
742<span id="c.psa_hash_clone"></span><h3><code class="docutils literal"><span class="pre">psa_hash_clone</span></code> (function)</h3>
743<p>Clone a hash operation.</p>
744<pre class="literal-block">
745<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,
746 <a class="reference internal" href="#c.psa_hash_operation_t" title="psa_hash_operation_t">psa_hash_operation_t</a> * target_operation);
747</pre>
748<p class="rubric">Parameters</p>
749<dl class="docutils">
750<dt> <code class="docutils literal"><span class="pre">source_operation</span></code></dt>
751<dd>The active hash operation to clone.</dd>
752<dt> <code class="docutils literal"><span class="pre">target_operation</span></code></dt>
753<dd>The operation object to set up. It must be initialized but not active.</dd>
754</dl>
755<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
756<dl class="docutils">
757<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
758<dd>Success.
759<code class="docutils literal"><span class="pre">target_operation</span></code> is ready to continue the same hash operation as <code class="docutils literal"><span class="pre">source_operation</span></code>.</dd>
760<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
761<dd><p class="first">The following conditions can result in this error:</p>
762<ul class="last simple">
763<li>The <code class="docutils literal"><span class="pre">source_operation</span></code> state is not valid: it must be active.</li>
764<li>The <code class="docutils literal"><span class="pre">target_operation</span></code> state is not valid: it must be inactive.</li>
765<li>The library requires initializing by a call to <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"><span class="pre">psa_crypto_init()</span></code></a>.</li>
766</ul>
767</dd>
768<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt>
769<dd></dd>
770<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
771<dd></dd>
772<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
773<dd></dd>
774</dl>
775<p class="rubric">Description</p>
776<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"><span class="pre">psa_hash_setup()</span></code></a> on <code class="docutils literal"><span class="pre">target_operation</span></code> with the same algorithm that <code class="docutils literal"><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"><span class="pre">psa_hash_update()</span></code></a> on <code class="docutils literal"><span class="pre">target_operation</span></code> with the same input that that was passed to <code class="docutils literal"><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>
777</div>
778</div>
779<div class="section" id="support-macros">
780<h2>10.2.4. Support macros</h2>
781<div class="section" id="PSA_HASH_LENGTH">
782<span id="c.PSA_HASH_LENGTH"></span><h3><code class="docutils literal"><span class="pre">PSA_HASH_LENGTH</span></code> (macro)</h3>
783<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"><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"><span class="pre">psa_hash_finish()</span></code></a>, in bytes.</p>
784<pre class="literal-block">
785#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>
786</pre>
787<p class="rubric">Parameters</p>
788<dl class="docutils">
789<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
790<dd>A hash algorithm or an HMAC algorithm: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a> such that <code class="docutils literal"><span class="pre">(</span></code><a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span> <span class="pre">||</span> </code><a class="reference internal" href="macs.html#c.PSA_ALG_IS_HMAC" title="PSA_ALG_IS_HMAC"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HMAC</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">))</span></code> is true.</dd>
791</dl>
792<p class="rubric">Returns</p>
793<p>The hash length for the specified hash algorithm. If the hash algorithm is not recognized, return <code class="docutils literal"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal"><span class="pre">0</span></code> or the correct size for a hash algorithm that it recognizes, but does not support.</p>
794<p class="rubric">Description</p>
795<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"><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"><span class="pre">psa_hash_verify()</span></code></a> expect.</p>
796<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"><span class="pre">PSA_HASH_MAX_SIZE</span></code></a>.</p>
797</div>
798<div class="section" id="PSA_HASH_MAX_SIZE">
799<span id="c.PSA_HASH_MAX_SIZE"></span><h3><code class="docutils literal"><span class="pre">PSA_HASH_MAX_SIZE</span></code> (macro)</h3>
800<p>Maximum size of a hash.</p>
801<pre class="literal-block">
802#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>
803</pre>
804<p>It 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>
805<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"><span class="pre">PSA_HASH_LENGTH()</span></code></a>.</p>
806</div>
807<div class="section" id="PSA_HASH_SUSPEND_OUTPUT_SIZE">
808<span id="c.PSA_HASH_SUSPEND_OUTPUT_SIZE"></span><h3><code class="docutils literal"><span class="pre">PSA_HASH_SUSPEND_OUTPUT_SIZE</span></code> (macro)</h3>
809<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"><span class="pre">psa_hash_suspend()</span></code></a>, in bytes.</p>
810<pre class="literal-block">
811#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>
812</pre>
813<p class="rubric">Parameters</p>
814<dl class="docutils">
815<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
816<dd>A hash algorithm: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a> such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true.</dd>
817</dl>
818<p class="rubric">Returns</p>
819<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"><span class="pre">psa_hash_suspend()</span></code></a>, return <code class="docutils literal"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal"><span class="pre">0</span></code> or a correct size for a hash algorithm that it recognizes, but does not support.</p>
820<p>For a supported hash algorithm <code class="docutils literal"><span class="pre">alg</span></code>, the following expression is true:</p>
821<pre class="literal-block">
822<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> +
823 <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) +
824 <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) +
825 <a class="reference internal" href="#c.PSA_HASH_BLOCK_LENGTH" title="PSA_HASH_BLOCK_LENGTH">PSA_HASH_BLOCK_LENGTH</a>(alg) - 1
826</pre>
827<p class="rubric">Description</p>
828<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"><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>
829<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"><span class="pre">PSA_HASH_SUSPEND_OUTPUT_MAX_SIZE</span></code></a>.</p>
830</div>
831<div class="section" id="PSA_HASH_SUSPEND_OUTPUT_MAX_SIZE">
832<span id="c.PSA_HASH_SUSPEND_OUTPUT_MAX_SIZE"></span><h3><code class="docutils literal"><span class="pre">PSA_HASH_SUSPEND_OUTPUT_MAX_SIZE</span></code> (macro)</h3>
833<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"><span class="pre">psa_hash_suspend()</span></code></a>, for any supported hash algorithms.</p>
834<pre class="literal-block">
835#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>
836</pre>
837<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"><span class="pre">psa_hash_suspend()</span></code></a> will not fail due to an insufficient buffer size.</p>
838<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"><span class="pre">PSA_HASH_SUSPEND_OUTPUT_SIZE()</span></code></a>.</p>
839</div>
840<div class="section" id="PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH">
841<span id="c.PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH"></span><h3><code class="docutils literal"><span class="pre">PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH</span></code> (macro)</h3>
842<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"><span class="pre">psa_hash_suspend()</span></code></a>, in bytes.</p>
843<pre class="literal-block">
844#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)
845</pre>
846<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"><span class="pre">psa_hash_suspend()</span></code></a>.</p>
847</div>
848<div class="section" id="PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH">
849<span id="c.PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH"></span><h3><code class="docutils literal"><span class="pre">PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH</span></code> (macro)</h3>
850<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"><span class="pre">psa_hash_suspend()</span></code></a>, in bytes.</p>
851<pre class="literal-block">
852#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) \
853 <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
854</pre>
855<p class="rubric">Parameters</p>
856<dl class="docutils">
857<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
858<dd>A hash algorithm: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a> such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true.</dd>
859</dl>
860<p class="rubric">Returns</p>
861<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"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal"><span class="pre">0</span></code> or the correct size for a hash algorithm that it recognizes, but does not support.</p>
862<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>
863<p class="rubric">Description</p>
864<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"><span class="pre">psa_hash_suspend()</span></code></a>.</p>
865</div>
866<div class="section" id="PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH">
867<span id="c.PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH"></span><h3><code class="docutils literal"><span class="pre">PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH</span></code> (macro)</h3>
868<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"><span class="pre">psa_hash_suspend()</span></code></a>, in bytes.</p>
869<pre class="literal-block">
870#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) \
871 <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
872</pre>
873<p class="rubric">Parameters</p>
874<dl class="docutils">
875<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
876<dd>A hash algorithm: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a> such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true.</dd>
877</dl>
878<p class="rubric">Returns</p>
879<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"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal"><span class="pre">0</span></code> or the correct size for a hash algorithm that it recognizes, but does not support.</p>
880<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>
881<p class="rubric">Description</p>
882<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"><span class="pre">psa_hash_suspend()</span></code></a>.</p>
883</div>
884<div class="section" id="PSA_HASH_BLOCK_LENGTH">
885<span id="c.PSA_HASH_BLOCK_LENGTH"></span><h3><code class="docutils literal"><span class="pre">PSA_HASH_BLOCK_LENGTH</span></code> (macro)</h3>
886<p>The input block size of a hash algorithm, in bytes.</p>
887<pre class="literal-block">
888#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>
889</pre>
890<p class="rubric">Parameters</p>
891<dl class="docutils">
892<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
893<dd>A hash algorithm: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a> such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true.</dd>
894</dl>
895<p class="rubric">Returns</p>
896<p>The block size in bytes for the specified hash algorithm. If the hash algorithm is not recognized, return <code class="docutils literal"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal"><span class="pre">0</span></code> or the correct size for a hash algorithm that it recognizes, but does not support.</p>
897<p class="rubric">Description</p>
898<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>
899<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"><span class="pre">psa_hash_suspend()</span></code></a>.</p>
900</div>
901</div>
902<div class="section" id="hash-suspend-state">
903<span id="id2"></span><h2>10.2.5. Hash suspend state</h2>
904<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"><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"><span class="pre">psa_hash_resume()</span></code></a>.</p>
905<div class="admonition note">
906<p class="first admonition-title">Note</p>
907<p class="last">Hash suspend and resume is not defined for the SM3 algorithm and the SHA3 family of hash algorithms.</p>
908</div>
909<div class="section" id="hash-suspend-state-format">
910<span id="id3"></span><h3>Hash suspend state format</h3>
911<p>The hash suspend state has the following format:</p>
912<p><em>hash-suspend-state</em> = <em>algorithm</em> || <em>input-length</em> || <em>hash-state</em> || <em>unprocessed-input</em></p>
913<p>The fields in the hash suspend state are defined as follows:</p>
914<dl class="docutils">
915<dt><em>algorithm</em></dt>
916<dd><p class="first">A big-endian 32-bit unsigned integer.</p>
917<p>The PSA Crypto API algorithm identifier value.</p>
918<p class="last">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"><span class="pre">PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH</span></code></a>.</p>
919</dd>
920<dt><em>input-length</em></dt>
921<dd><p class="first">A big-endian unsigned integer</p>
922<p>The content of this field is algorithm-specific:</p>
923<ul class="simple">
924<li>For MD2, this is the number of bytes in the <em>unprocessed-input</em>.</li>
925<li>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.</li>
926</ul>
927<p>The size of this field is algorithm-specific:</p>
928<ul class="simple">
929<li>For MD2: <em>input-length</em> is an 8-bit unsigned integer.</li>
930<li>For MD4, MD5, RIPEMD-160, SHA-1, SHA-224, and SHA-256: <em>input-length</em> is a 64-bit unsigned integer.</li>
931<li>For SHA-512/224, SHA-512/256, SHA-384, and SHA-512: <em>input-length</em> is a 128-bit unsigned integer.</li>
932</ul>
933<p class="last">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"><span class="pre">PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">alg</span></code> is a hash algorithm.
934See <a class="reference internal" href="#hash-suspend-state-constants"><span class="secref">Hash suspend state field sizes</span></a>.</p>
935</dd>
936<dt><em>hash-state</em></dt>
937<dd><p class="first">An array of bytes</p>
938<p>Algorithm-specific intermediate hash state:</p>
939<ul class="simple">
940<li>For MD2: 16 bytes of internal checksum, then 48 bytes of intermediate digest.</li>
941<li>For MD4 and MD5: 4x 32-bit integers, in little-endian encoding.</li>
942<li>For RIPEMD-160: 5x 32-bit integers, in little-endian encoding.</li>
943<li>For SHA-1: 5x 32-bit integers, in big-endian encoding.</li>
944<li>For SHA-224 and SHA-256: 8x 32-bit integers, in big-endian encoding.</li>
945<li>For SHA-512/224, SHA-512/256, SHA-384, and SHA-512: 8x 64-bit integers, in big-endian encoding.</li>
946</ul>
947<p class="last">The length of this field is specific to the algorithm.
948The 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"><span class="pre">PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">alg</span></code> is a hash algorithm.
949See <a class="reference internal" href="#hash-suspend-state-constants"><span class="secref">Hash suspend state field sizes</span></a>.</p>
950</dd>
951<dt><em>unprocessed-input</em></dt>
952<dd><p class="first">0 to (<em>hash-block-size</em>-1) bytes</p>
953<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>
954<p><code class="docutils literal"><span class="pre">length(</span></code><em>unprocessed-input</em><code class="docutils literal"><span class="pre">)</span></code> <code class="docutils literal"><span class="pre">=</span></code> <em>input-length</em> <code class="docutils literal"><span class="pre">%</span></code> <em>hash-block-size</em>.</p>
955<p class="last">The <em>hash-block-size</em> is specific to the algorithm.
956The 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"><span class="pre">PSA_HASH_BLOCK_LENGTH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">alg</span></code> is a hash algorithm.
957See <a class="reference internal" href="#hash-suspend-state-constants"><span class="secref">Hash suspend state field sizes</span></a>.</p>
958</dd>
959</dl>
960</div>
961<div class="section" id="hash-suspend-state-field-sizes">
962<span id="hash-suspend-state-constants"></span><h3>Hash suspend state field sizes</h3>
963<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"><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"><span class="pre">alg</span></code>, use the following expressions:</p>
964<ul class="simple">
965<li><a class="reference internal" href="#c.PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH" title="PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH"><code class="docutils literal"><span class="pre">PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH</span></code></a> returns the length of the <em>algorithm</em> field.</li>
966<li><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"><span class="pre">PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> returns the length of the <em>input-length</em> field.</li>
967<li><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"><span class="pre">PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> returns the length of the <em>hash-state</em> field.</li>
968<li><a class="reference internal" href="#c.PSA_HASH_BLOCK_LENGTH" title="PSA_HASH_BLOCK_LENGTH"><code class="docutils literal"><span class="pre">PSA_HASH_BLOCK_LENGTH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)-1</span></code> is the maximum length of the <em>unprocessed-bytes</em> field.</li>
969<li><a class="reference internal" href="#c.PSA_HASH_SUSPEND_OUTPUT_SIZE" title="PSA_HASH_SUSPEND_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_HASH_SUSPEND_OUTPUT_SIZE</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> returns the maximum size of the hash suspend state.</li>
970</ul>
971<table border="1" class="colwidths-auto docutils align-left">
972<thead valign="bottom">
973<tr class="row-odd"><th class="head">Hash algorithm</th>
974<th class="head"><em>input-length</em> size (bytes)</th>
975<th class="head"><em>hash-state</em> length (bytes)</th>
976<th class="head"><em>unprocessed-bytes</em> length (bytes)</th>
977</tr>
978</thead>
979<tbody valign="top">
980<tr class="row-even"><td><a class="reference internal" href="#c.PSA_ALG_MD2" title="PSA_ALG_MD2"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_MD2</span></code></a></td>
981<td>1</td>
982<td>64</td>
983<td>0 – 15</td>
984</tr>
985<tr class="row-odd"><td><a class="reference internal" href="#c.PSA_ALG_MD4" title="PSA_ALG_MD4"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_MD4</span></code></a></td>
986<td>8</td>
987<td>16</td>
988<td>0 – 63</td>
989</tr>
990<tr class="row-even"><td><a class="reference internal" href="#c.PSA_ALG_MD5" title="PSA_ALG_MD5"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_MD5</span></code></a></td>
991<td>8</td>
992<td>16</td>
993<td>0 – 63</td>
994</tr>
995<tr class="row-odd"><td><a class="reference internal" href="#c.PSA_ALG_RIPEMD160" title="PSA_ALG_RIPEMD160"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_RIPEMD160</span></code></a></td>
996<td>8</td>
997<td>20</td>
998<td>0 – 63</td>
999</tr>
1000<tr class="row-even"><td><a class="reference internal" href="#c.PSA_ALG_SHA_1" title="PSA_ALG_SHA_1"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_SHA_1</span></code></a></td>
1001<td>8</td>
1002<td>20</td>
1003<td>0 – 63</td>
1004</tr>
1005<tr class="row-odd"><td><a class="reference internal" href="#c.PSA_ALG_SHA_224" title="PSA_ALG_SHA_224"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_SHA_224</span></code></a></td>
1006<td>8</td>
1007<td>32</td>
1008<td>0 – 63</td>
1009</tr>
1010<tr class="row-even"><td><a class="reference internal" href="#c.PSA_ALG_SHA_256" title="PSA_ALG_SHA_256"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_SHA_256</span></code></a></td>
1011<td>8</td>
1012<td>32</td>
1013<td>0 – 63</td>
1014</tr>
1015<tr class="row-odd"><td><a class="reference internal" href="#c.PSA_ALG_SHA_512_224" title="PSA_ALG_SHA_512_224"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_SHA_512_224</span></code></a></td>
1016<td>16</td>
1017<td>64</td>
1018<td>0 – 127</td>
1019</tr>
1020<tr class="row-even"><td><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"><span class="pre">PSA_ALG_SHA_512_256</span></code></a></td>
1021<td>16</td>
1022<td>64</td>
1023<td>0 – 127</td>
1024</tr>
1025<tr class="row-odd"><td><a class="reference internal" href="#c.PSA_ALG_SHA_384" title="PSA_ALG_SHA_384"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_SHA_384</span></code></a></td>
1026<td>16</td>
1027<td>64</td>
1028<td>0 – 127</td>
1029</tr>
1030<tr class="row-even"><td><a class="reference internal" href="#c.PSA_ALG_SHA_512" title="PSA_ALG_SHA_512"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_SHA_512</span></code></a></td>
1031<td>16</td>
1032<td>64</td>
1033<td>0 – 127</td>
1034</tr>
1035</tbody>
1036</table>
1037</div>
1038</div>
1039</div>
1040
1041
1042 </div>
1043 </div>
1044 </div>
1045 <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
1046 <div class="sphinxsidebarwrapper"><h3><a href="../../index.html"><b>PSA Crypto API</b></a></h3>
1047IHI 0086<br/>
1048Non-confidential<br/>
1049Version 1.1.0
1050<span style="color: red; font-weight: bold;"></span>
1051<ul>
1052<li class="toctree-l1"><a class="reference internal" href="../../about.html">About this document</a></li>
1053</ul>
1054<ul class="current">
1055<li class="toctree-l1"><a class="reference internal" href="../../overview/intro.html">1. Introduction</a></li>
1056<li class="toctree-l1"><a class="reference internal" href="../../overview/goals.html">2. Design goals</a></li>
1057<li class="toctree-l1"><a class="reference internal" href="../../overview/functionality.html">3. Functionality overview</a></li>
1058<li class="toctree-l1"><a class="reference internal" href="../../overview/sample-arch.html">4. Sample architectures</a></li>
1059<li class="toctree-l1"><a class="reference internal" href="../../overview/conventions.html">5. Library conventions</a></li>
1060<li class="toctree-l1"><a class="reference internal" href="../../overview/implementation.html">6. Implementation considerations</a></li>
1061<li class="toctree-l1"><a class="reference internal" href="../../overview/usage.html">7. Usage considerations</a></li>
1062<li class="toctree-l1"><a class="reference internal" href="../library/index.html">8. Library management reference</a></li>
1063<li class="toctree-l1"><a class="reference internal" href="../keys/index.html">9. Key management reference</a></li>
1064<li class="toctree-l1 current"><a class="reference internal" href="index.html">10. Cryptographic operation reference</a><ul class="current">
1065<li class="toctree-l2"><a class="reference internal" href="algorithms.html">10.1. Algorithms</a></li>
1066<li class="toctree-l2 current"><a class="current reference internal" href="#">10.2. Message digests (Hashes)</a><ul>
1067<li class="toctree-l3"><a class="reference internal" href="#hash-algorithms">10.2.1. Hash algorithms</a></li>
1068<li class="toctree-l3"><a class="reference internal" href="#single-part-hashing-functions">10.2.2. Single-part hashing functions</a></li>
1069<li class="toctree-l3"><a class="reference internal" href="#multi-part-hashing-operations">10.2.3. Multi-part hashing operations</a></li>
1070<li class="toctree-l3"><a class="reference internal" href="#support-macros">10.2.4. Support macros</a></li>
1071<li class="toctree-l3"><a class="reference internal" href="#hash-suspend-state">10.2.5. Hash suspend state</a></li>
1072</ul>
1073</li>
1074<li class="toctree-l2"><a class="reference internal" href="macs.html">10.3. Message authentication codes (MAC)</a></li>
1075<li class="toctree-l2"><a class="reference internal" href="ciphers.html">10.4. Unauthenticated ciphers</a></li>
1076<li class="toctree-l2"><a class="reference internal" href="aead.html">10.5. Authenticated encryption with associated data (AEAD)</a></li>
1077<li class="toctree-l2"><a class="reference internal" href="kdf.html">10.6. Key derivation</a></li>
1078<li class="toctree-l2"><a class="reference internal" href="sign.html">10.7. Asymmetric signature</a></li>
1079<li class="toctree-l2"><a class="reference internal" href="pke.html">10.8. Asymmetric encryption</a></li>
1080<li class="toctree-l2"><a class="reference internal" href="ka.html">10.9. Key agreement</a></li>
1081<li class="toctree-l2"><a class="reference internal" href="rng.html">10.10. Other cryptographic services</a></li>
1082</ul>
1083</li>
1084</ul>
1085<ul>
1086<li class="toctree-l1"><a class="reference internal" href="../../appendix/example_header.html">Example header file</a></li>
1087<li class="toctree-l1"><a class="reference internal" href="../../appendix/encodings.html">Algorithm and key type encoding</a></li>
1088<li class="toctree-l1"><a class="reference internal" href="../../appendix/specdef_values.html">Example macro implementations</a></li>
1089<li class="toctree-l1"><a class="reference internal" href="../../appendix/sra.html">Security Risk Assessment</a></li>
1090<li class="toctree-l1"><a class="reference internal" href="../../appendix/history.html">Changes to the API</a></li>
1091</ul>
1092<ul>
1093<li class="toctree-l1"><a class="reference internal" href="../../psa_c-identifiers.html">Index of API elements</a></li>
1094</ul>
1095<div id="searchbox" style="display: none" role="search">
1096 <h3>Quick search</h3>
1097 <form class="search" action="../../search.html" method="get">
1098 <div><input type="text" name="q" /></div>
1099 <div><input type="submit" value="Go" /></div>
1100 <input type="hidden" name="check_keywords" value="yes" />
1101 <input type="hidden" name="area" value="default" />
1102 </form>
1103</div>
1104<script type="text/javascript">$('#searchbox').show(0);</script>
1105 </div>
1106 </div>
1107 <div class="clearer"></div>
1108 </div>
1109 <div class="footer">
1110 &copy; 2018-2022, Arm Limited or its affiliates. All rights reserved.
1111
1112 |
1113 Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
1114 &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
1115
1116 </div>
1117
1118
1119
1120
1121 </body>
1122</html>