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