TrustedFirmware Git Browser
Code Review Sign In
review.trustedfirmware.org / mirror / mbed-crypto / 132d88c4436af3a8ad535238788b3c8beb21e29d / . / docs / html / api / ops / macs.html
blob: 38e608c0e981e6081821021b2bf75a22b792f9cd [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.3. Message authentication codes (MAC) &#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.4. Unauthenticated ciphers" href="ciphers.html" />
28 <link rel="prev" title="10.2. Message digests" href="hashes.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-authentication-codes-mac">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]44<span id="macs"></span><h1>10.3. Message authentication codes (MAC)</h1>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]45<div class="section" id="mac-algorithms">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]46<span id="id1"></span><h2>10.3.1. MAC algorithms</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]47<div class="section" id="PSA_ALG_HMAC">
48<span id="c.PSA_ALG_HMAC"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_HMAC</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]49<p>Macro to build an HMAC message-authentication-code algorithm from an underlying hash algorithm.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]50<pre class="literal-block">
51#define <a class="reference internal" href="#c.PSA_ALG_HMAC" title="PSA_ALG_HMAC">PSA_ALG_HMAC</a>(hash_alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
52</pre>
53<p class="rubric">Parameters</p>
54<dl class="docutils">
55<dt> <code class="docutils literal"><span class="pre">hash_alg</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]56<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">hash_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]57</dl>
58<p class="rubric">Returns</p>
59<p>The corresponding HMAC algorithm.</p>
60<p>Unspecified if <code class="docutils literal"><span class="pre">hash_alg</span></code> is not a supported hash algorithm.</p>
61<p class="rubric">Description</p>
62<p>For example, <a class="reference internal" href="#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><a class="reference internal" href="hashes.html#c.PSA_ALG_SHA_256" title="PSA_ALG_SHA_256"><code class="docutils literal"><span class="pre">PSA_ALG_SHA_256</span></code></a><code class="docutils literal"><span class="pre">)</span></code> is HMAC-SHA-256.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]63<p>The HMAC construction is defined in <span><em>HMAC: Keyed-Hashing for Message Authentication</em> <a class="reference internal" href="../../about.html#citation-rfc2104"><span class="cite">[RFC2104]</span></a></span>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]64</div>
65<div class="section" id="PSA_ALG_TRUNCATED_MAC">
66<span id="c.PSA_ALG_TRUNCATED_MAC"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_TRUNCATED_MAC</span></code> (macro)</h3>
67<p>Macro to build a truncated MAC algorithm.</p>
68<pre class="literal-block">
69#define <a class="reference internal" href="#c.PSA_ALG_TRUNCATED_MAC" title="PSA_ALG_TRUNCATED_MAC">PSA_ALG_TRUNCATED_MAC</a>(mac_alg, mac_length) \
70 <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
71</pre>
72<p class="rubric">Parameters</p>
73<dl class="docutils">
74<dt> <code class="docutils literal"><span class="pre">mac_alg</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]75<dd>A MAC algorithm identifier (value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a> such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_MAC" title="PSA_ALG_IS_MAC"><code class="docutils literal"><span class="pre">PSA_ALG_IS_MAC</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). This can be a truncated or untruncated MAC algorithm.</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]76<dt> <code class="docutils literal"><span class="pre">mac_length</span></code></dt>
77<dd>Desired length of the truncated MAC in bytes. This must be at most the full length of the MAC and must be at least an implementation-specified minimum. The implementation-specified minimum must not be zero.</dd>
78</dl>
79<p class="rubric">Returns</p>
80<p>The corresponding MAC algorithm with the specified length.</p>
81<p>Unspecified if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported MAC algorithm or if <code class="docutils literal"><span class="pre">mac_length</span></code> is too small or too large for the specified MAC algorithm.</p>
82<p class="rubric">Description</p>
83<p>A truncated MAC algorithm is identical to the corresponding MAC algorithm except that the MAC value for the truncated algorithm consists of only the first <code class="docutils literal"><span class="pre">mac_length</span></code> bytes of the MAC value for the untruncated algorithm.</p>
84<div class="admonition note">
85<p class="first admonition-title">Note</p>
86<p class="last">This macro might allow constructing algorithm identifiers that are not valid, either because the specified length is larger than the untruncated MAC or because the specified length is smaller than permitted by the implementation.</p>
87</div>
88<div class="admonition note">
89<p class="first admonition-title">Note</p>
90<p class="last">It is implementation-defined whether a truncated MAC that is truncated to the same length as the MAC of the untruncated algorithm is considered identical to the untruncated algorithm for policy comparison purposes.</p>
91</div>
92<p>The full-length MAC algorithm can be recovered using <a class="reference internal" href="#c.PSA_ALG_FULL_LENGTH_MAC" title="PSA_ALG_FULL_LENGTH_MAC"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_FULL_LENGTH_MAC()</span></code></a>.</p>
93</div>
94<div class="section" id="PSA_ALG_CBC_MAC">
95<span id="c.PSA_ALG_CBC_MAC"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_CBC_MAC</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]96<p>The CBC-MAC message-authentication-code algorithm, constructed over a block cipher.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]97<pre class="literal-block">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]98#define <a class="reference internal" href="#c.PSA_ALG_CBC_MAC" title="PSA_ALG_CBC_MAC">PSA_ALG_CBC_MAC</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x03c00100)
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]99</pre>
100<div class="admonition warning">
101<p class="first admonition-title">Warning</p>
102<p class="last">CBC-MAC is insecure in many cases. A more secure mode, such as <a class="reference internal" href="#c.PSA_ALG_CMAC" title="PSA_ALG_CMAC"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_CMAC</span></code></a>, is recommended.</p>
103</div>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]104<p>The CBC-MAC algorithm must be used with a key for a block cipher. For example, one of <a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_AES" title="PSA_KEY_TYPE_AES"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_AES</span></code></a>.</p>
105<p>CBC-MAC is defined as <em>MAC Algorithm 1</em> in <span><em>ISO/IEC 9797-1:2011 Information technology — Security techniques — Message Authentication Codes (MACs) — Part 1: Mechanisms using a block cipher</em> <a class="reference internal" href="../../about.html#citation-iso9797"><span class="cite">[ISO9797]</span></a></span>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]106</div>
107<div class="section" id="PSA_ALG_CMAC">
108<span id="c.PSA_ALG_CMAC"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_CMAC</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]109<p>The CMAC message-authentication-code algorithm, constructed over a block cipher.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]110<pre class="literal-block">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]111#define <a class="reference internal" href="#c.PSA_ALG_CMAC" title="PSA_ALG_CMAC">PSA_ALG_CMAC</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x03c00200)
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]112</pre>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]113<p>The CMAC algorithm must be used with a key for a block cipher. For example, when used with a key with type <a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_AES" title="PSA_KEY_TYPE_AES"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_AES</span></code></a>, the resulting operation is AES-CMAC.</p>
114<p>CMAC is defined in <span><em>NIST Special Publication 800-38B: Recommendation for Block Cipher Modes of Operation: the CMAC Mode for Authentication</em> <a class="reference internal" href="../../about.html#citation-sp800-38b"><span class="cite">[SP800-38B]</span></a></span>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]115</div>
116</div>
117<div class="section" id="single-part-mac-functions">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]118<h2>10.3.2. Single-part MAC functions</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]119<div class="section" id="psa_mac_compute">
120<span id="c.psa_mac_compute"></span><h3><code class="docutils literal"><span class="pre">psa_mac_compute</span></code> (function)</h3>
121<p>Calculate the message authentication code (MAC) of a message.</p>
122<pre class="literal-block">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]123<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_mac_compute" title="psa_mac_compute">psa_mac_compute</a>(<a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
124 <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]125 const uint8_t * input,
126 size_t input_length,
127 uint8_t * mac,
128 size_t mac_size,
129 size_t * mac_length);
130</pre>
131<p class="rubric">Parameters</p>
132<dl class="docutils">
133<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
134<dd>Identifier of the key to use for the operation.
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]135It must allow the usage <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_SIGN_MESSAGE" title="PSA_KEY_USAGE_SIGN_MESSAGE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_SIGN_MESSAGE</span></code></a>.</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]136<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]137<dd>The MAC 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_MAC" title="PSA_ALG_IS_MAC"><code class="docutils literal"><span class="pre">PSA_ALG_IS_MAC</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]138<dt> <code class="docutils literal"><span class="pre">input</span></code></dt>
139<dd>Buffer containing the input message.</dd>
140<dt> <code class="docutils literal"><span class="pre">input_length</span></code></dt>
141<dd>Size of the <code class="docutils literal"><span class="pre">input</span></code> buffer in bytes.</dd>
142<dt> <code class="docutils literal"><span class="pre">mac</span></code></dt>
143<dd>Buffer where the MAC value is to be written.</dd>
144<dt> <code class="docutils literal"><span class="pre">mac_size</span></code></dt>
145<dd><p class="first">Size of the <code class="docutils literal"><span class="pre">mac</span></code> buffer in bytes.
146This must be appropriate for the selected algorithm and key:</p>
147<ul class="last simple">
148<li>The exact MAC size is <a class="reference internal" href="#c.PSA_MAC_LENGTH" title="PSA_MAC_LENGTH"><code class="docutils literal"><span class="pre">PSA_MAC_LENGTH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">key_type</span></code><code class="docutils literal"><span class="pre">,</span> </code><code class="docutils literal"><span class="pre">key_bits</span></code><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">key_type</span></code> and <code class="docutils literal"><span class="pre">key_bits</span></code> are attributes of the key used to compute the MAC.</li>
149<li><a class="reference internal" href="#c.PSA_MAC_MAX_SIZE" title="PSA_MAC_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_MAC_MAX_SIZE</span></code></a> evaluates to the maximum MAC size of any supported MAC algorithm.</li>
150</ul>
151</dd>
152<dt> <code class="docutils literal"><span class="pre">mac_length</span></code></dt>
153<dd>On success, the number of bytes that make up the MAC value.</dd>
154</dl>
155<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>
156<dl class="docutils">
157<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>
158<dd>Success.</dd>
159<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
160<dd></dd>
161<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]162<dd>The key does not have the <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_SIGN_MESSAGE" title="PSA_KEY_USAGE_SIGN_MESSAGE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_SIGN_MESSAGE</span></code></a> flag, or it does not permit the requested algorithm.</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]163<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>
164<dd><code class="docutils literal"><span class="pre">key</span></code> is not compatible with <code class="docutils literal"><span class="pre">alg</span></code>.</dd>
165<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>
166<dd><code class="docutils literal"><span class="pre">alg</span></code> is not supported or is not a MAC algorithm.</dd>
167<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>
168<dd>The size of the <code class="docutils literal"><span class="pre">mac</span></code> buffer is too small.
169<a class="reference internal" href="#c.PSA_MAC_LENGTH" title="PSA_MAC_LENGTH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_MAC_LENGTH()</span></code></a> or <a class="reference internal" href="#c.PSA_MAC_MAX_SIZE" title="PSA_MAC_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_MAC_MAX_SIZE</span></code></a> can be used to determine the required buffer size.</dd>
170<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>
171<dd></dd>
172<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>
173<dd></dd>
174<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>
175<dd></dd>
176<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>
177<dd></dd>
178<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt>
179<dd>The key could not be retrieved from storage.</dd>
180<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt>
181<dd>The key could not be retrieved from storage.</dd>
182<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt>
183<dd>The key could not be retrieved from storage.</dd>
184<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>
185<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>
186</dl>
187<p class="rubric">Description</p>
188<div class="admonition note">
189<p class="first admonition-title">Note</p>
190<p class="last">To verify the MAC of a message against an expected value, use <a class="reference internal" href="#c.psa_mac_verify" title="psa_mac_verify"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_verify()</span></code></a> instead. Beware that comparing integrity or authenticity data such as MAC 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 MAC value which could allow an attacker to guess a valid MAC and thereby bypass security controls.</p>
191</div>
192</div>
193<div class="section" id="psa_mac_verify">
194<span id="c.psa_mac_verify"></span><h3><code class="docutils literal"><span class="pre">psa_mac_verify</span></code> (function)</h3>
195<p>Calculate the MAC of a message and compare it with a reference value.</p>
196<pre class="literal-block">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]197<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_mac_verify" title="psa_mac_verify">psa_mac_verify</a>(<a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
198 <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 const uint8_t * mac,
202 size_t mac_length);
203</pre>
204<p class="rubric">Parameters</p>
205<dl class="docutils">
206<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
207<dd>Identifier of the key to use for the operation.
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]208It must allow the usage <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_VERIFY_MESSAGE" title="PSA_KEY_USAGE_VERIFY_MESSAGE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_VERIFY_MESSAGE</span></code></a>.</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]209<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]210<dd>The MAC 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_MAC" title="PSA_ALG_IS_MAC"><code class="docutils literal"><span class="pre">PSA_ALG_IS_MAC</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]211<dt> <code class="docutils literal"><span class="pre">input</span></code></dt>
212<dd>Buffer containing the input message.</dd>
213<dt> <code class="docutils literal"><span class="pre">input_length</span></code></dt>
214<dd>Size of the <code class="docutils literal"><span class="pre">input</span></code> buffer in bytes.</dd>
215<dt> <code class="docutils literal"><span class="pre">mac</span></code></dt>
216<dd>Buffer containing the expected MAC value.</dd>
217<dt> <code class="docutils literal"><span class="pre">mac_length</span></code></dt>
218<dd>Size of the <code class="docutils literal"><span class="pre">mac</span></code> buffer in bytes.</dd>
219</dl>
220<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>
221<dl class="docutils">
222<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>
223<dd>The expected MAC is identical to the actual MAC of the input.</dd>
224<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>
225<dd>The MAC of the message was calculated successfully, but it differs from the expected value.</dd>
226<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
227<dd></dd>
228<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]229<dd>The key does not have the <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_VERIFY_MESSAGE" title="PSA_KEY_USAGE_VERIFY_MESSAGE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_VERIFY_MESSAGE</span></code></a> flag, or it does not permit the requested algorithm.</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]230<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>
231<dd><code class="docutils literal"><span class="pre">key</span></code> is not compatible with <code class="docutils literal"><span class="pre">alg</span></code>.</dd>
232<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>
233<dd><code class="docutils literal"><span class="pre">alg</span></code> is not supported or is not a MAC algorithm.</dd>
234<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>
235<dd></dd>
236<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
237<dd></dd>
238<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>
239<dd></dd>
240<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>
241<dd></dd>
242<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt>
243<dd>The key could not be retrieved from storage.</dd>
244<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt>
245<dd>The key could not be retrieved from storage.</dd>
246<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt>
247<dd>The key could not be retrieved from storage.</dd>
248<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>
249<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>
250</dl>
251</div>
252</div>
253<div class="section" id="multi-part-mac-operations">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]254<h2>10.3.3. Multi-part MAC operations</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]255<div class="section" id="psa_mac_operation_t">
256<span id="c.psa_mac_operation_t"></span><h3><code class="docutils literal"><span class="pre">psa_mac_operation_t</span></code> (type)</h3>
257<p>The type of the state object for multi-part MAC operations.</p>
258<pre class="literal-block">
259typedef <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_mac_operation_t" title="psa_mac_operation_t">psa_mac_operation_t</a>;
260</pre>
261<p>Before calling any function on a MAC operation object, the application must initialize it by any of the following means:</p>
262<ul>
263<li><p class="first">Set the object to all-bits-zero, for example:</p>
264<pre class="literal-block">
265<a class="reference internal" href="#c.psa_mac_operation_t" title="psa_mac_operation_t">psa_mac_operation_t</a> operation;
266memset(&amp;operation, 0, sizeof(operation));
267</pre>
268</li>
269<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>
270<pre class="literal-block">
271static <a class="reference internal" href="#c.psa_mac_operation_t" title="psa_mac_operation_t">psa_mac_operation_t</a> operation;
272</pre>
273</li>
274<li><p class="first">Initialize the object to the initializer <a class="reference internal" href="#c.PSA_MAC_OPERATION_INIT" title="PSA_MAC_OPERATION_INIT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_MAC_OPERATION_INIT</span></code></a>, for example:</p>
275<pre class="literal-block">
276<a class="reference internal" href="#c.psa_mac_operation_t" title="psa_mac_operation_t">psa_mac_operation_t</a> operation = <a class="reference internal" href="#c.PSA_MAC_OPERATION_INIT" title="PSA_MAC_OPERATION_INIT">PSA_MAC_OPERATION_INIT</a>;
277</pre>
278</li>
279<li><p class="first">Assign the result of the function <a class="reference internal" href="#c.psa_mac_operation_init" title="psa_mac_operation_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_operation_init()</span></code></a> to the object, for example:</p>
280<pre class="literal-block">
281<a class="reference internal" href="#c.psa_mac_operation_t" title="psa_mac_operation_t">psa_mac_operation_t</a> operation;
282operation = <a class="reference internal" href="#c.psa_mac_operation_init" title="psa_mac_operation_init">psa_mac_operation_init</a>();
283</pre>
284</li>
285</ul>
286<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>
287</div>
288<div class="section" id="PSA_MAC_OPERATION_INIT">
289<span id="c.PSA_MAC_OPERATION_INIT"></span><h3><code class="docutils literal"><span class="pre">PSA_MAC_OPERATION_INIT</span></code> (macro)</h3>
290<p>This macro returns a suitable initializer for a MAC operation object of type <a class="reference internal" href="#c.psa_mac_operation_t" title="psa_mac_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_mac_operation_t</span></code></a>.</p>
291<pre class="literal-block">
292#define <a class="reference internal" href="#c.PSA_MAC_OPERATION_INIT" title="PSA_MAC_OPERATION_INIT">PSA_MAC_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>
293</pre>
294</div>
295<div class="section" id="psa_mac_operation_init">
296<span id="c.psa_mac_operation_init"></span><h3><code class="docutils literal"><span class="pre">psa_mac_operation_init</span></code> (function)</h3>
297<p>Return an initial value for a MAC operation object.</p>
298<pre class="literal-block">
299<a class="reference internal" href="#c.psa_mac_operation_t" title="psa_mac_operation_t">psa_mac_operation_t</a> <a class="reference internal" href="#c.psa_mac_operation_init" title="psa_mac_operation_init">psa_mac_operation_init</a>(void);
300</pre>
301<p class="rubric">Returns: <a class="reference internal" href="#c.psa_mac_operation_t" title="psa_mac_operation_t"><code class="docutils literal"><span class="pre">psa_mac_operation_t</span></code></a></p>
302</div>
303<div class="section" id="psa_mac_sign_setup">
304<span id="c.psa_mac_sign_setup"></span><h3><code class="docutils literal"><span class="pre">psa_mac_sign_setup</span></code> (function)</h3>
305<p>Set up a multi-part MAC calculation operation.</p>
306<pre class="literal-block">
307<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_mac_sign_setup" title="psa_mac_sign_setup">psa_mac_sign_setup</a>(<a class="reference internal" href="#c.psa_mac_operation_t" title="psa_mac_operation_t">psa_mac_operation_t</a> * operation,
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]308 <a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
309 <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]310</pre>
311<p class="rubric">Parameters</p>
312<dl class="docutils">
313<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
314<dd>The operation object to set up. It must have been initialized as per the documentation for <a class="reference internal" href="#c.psa_mac_operation_t" title="psa_mac_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_mac_operation_t</span></code></a> and not yet in use.</dd>
315<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
316<dd>Identifier of the key to use for the operation. It must remain valid until the operation terminates.
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]317It must allow the usage <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_SIGN_MESSAGE" title="PSA_KEY_USAGE_SIGN_MESSAGE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_SIGN_MESSAGE</span></code></a>.</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]318<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]319<dd>The MAC 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_MAC" title="PSA_ALG_IS_MAC"><code class="docutils literal"><span class="pre">PSA_ALG_IS_MAC</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]320</dl>
321<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>
322<dl class="docutils">
323<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>
324<dd>Success.</dd>
325<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
326<dd></dd>
327<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]328<dd>The key does not have the <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_SIGN_MESSAGE" title="PSA_KEY_USAGE_SIGN_MESSAGE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_SIGN_MESSAGE</span></code></a> flag, or it does not permit the requested algorithm.</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]329<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>
330<dd><code class="docutils literal"><span class="pre">key</span></code> is not compatible with <code class="docutils literal"><span class="pre">alg</span></code>.</dd>
331<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>
332<dd><code class="docutils literal"><span class="pre">alg</span></code> is not supported or is not a MAC algorithm.</dd>
333<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>
334<dd></dd>
335<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>
336<dd></dd>
337<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>
338<dd></dd>
339<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
340<dd></dd>
341<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt>
342<dd>The key could not be retrieved from storage.</dd>
343<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt>
344<dd>The key could not be retrieved from storage.</dd>
345<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt>
346<dd>The key could not be retrieved from storage.</dd>
347<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>
348<dd>The operation state is not valid: it must be inactive.</dd>
349<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>
350<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>
351</dl>
352<p class="rubric">Description</p>
353<p>This function sets up the calculation of the message authentication code (MAC) of a byte string. To verify the MAC of a message against an expected value, use <a class="reference internal" href="#c.psa_mac_verify_setup" title="psa_mac_verify_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_verify_setup()</span></code></a> instead.</p>
354<p>The sequence of operations to calculate a MAC is as follows:</p>
355<ol class="arabic simple">
356<li>Allocate an operation object which will be passed to all the functions listed here.</li>
357<li>Initialize the operation object with one of the methods described in the documentation for <a class="reference internal" href="#c.psa_mac_operation_t" title="psa_mac_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_mac_operation_t</span></code></a>, e.g. <a class="reference internal" href="#c.PSA_MAC_OPERATION_INIT" title="PSA_MAC_OPERATION_INIT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_MAC_OPERATION_INIT</span></code></a>.</li>
358<li>Call <a class="reference internal" href="#c.psa_mac_sign_setup" title="psa_mac_sign_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_sign_setup()</span></code></a> to specify the algorithm and key.</li>
359<li>Call <a class="reference internal" href="#c.psa_mac_update" title="psa_mac_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_update()</span></code></a> zero, one or more times, passing a fragment of the message each time. The MAC that is calculated is the MAC of the concatenation of these messages in order.</li>
360<li>At the end of the message, call <a class="reference internal" href="#c.psa_mac_sign_finish" title="psa_mac_sign_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_sign_finish()</span></code></a> to finish calculating the MAC value and retrieve it.</li>
361</ol>
362<p>If an error occurs at any step after a call to <a class="reference internal" href="#c.psa_mac_sign_setup" title="psa_mac_sign_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_sign_setup()</span></code></a>, the operation will need to be reset by a call to <a class="reference internal" href="#c.psa_mac_abort" title="psa_mac_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_abort()</span></code></a>. The application can call <a class="reference internal" href="#c.psa_mac_abort" title="psa_mac_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_abort()</span></code></a> at any time after the operation has been initialized.</p>
363<p>After a successful call to <a class="reference internal" href="#c.psa_mac_sign_setup" title="psa_mac_sign_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_sign_setup()</span></code></a>, the application must eventually terminate the operation through one of the following methods:</p>
364<ul class="simple">
365<li>A successful call to <a class="reference internal" href="#c.psa_mac_sign_finish" title="psa_mac_sign_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_sign_finish()</span></code></a>.</li>
366<li>A call to <a class="reference internal" href="#c.psa_mac_abort" title="psa_mac_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_abort()</span></code></a>.</li>
367</ul>
368</div>
369<div class="section" id="psa_mac_verify_setup">
370<span id="c.psa_mac_verify_setup"></span><h3><code class="docutils literal"><span class="pre">psa_mac_verify_setup</span></code> (function)</h3>
371<p>Set up a multi-part MAC verification operation.</p>
372<pre class="literal-block">
373<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_mac_verify_setup" title="psa_mac_verify_setup">psa_mac_verify_setup</a>(<a class="reference internal" href="#c.psa_mac_operation_t" title="psa_mac_operation_t">psa_mac_operation_t</a> * operation,
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]374 <a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
375 <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]376</pre>
377<p class="rubric">Parameters</p>
378<dl class="docutils">
379<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
380<dd>The operation object to set up. It must have been initialized as per the documentation for <a class="reference internal" href="#c.psa_mac_operation_t" title="psa_mac_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_mac_operation_t</span></code></a> and not yet in use.</dd>
381<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
382<dd>Identifier of the key to use for the operation. It must remain valid until the operation terminates.
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]383It must allow the usage <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_VERIFY_MESSAGE" title="PSA_KEY_USAGE_VERIFY_MESSAGE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_VERIFY_MESSAGE</span></code></a>.</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]384<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]385<dd>The MAC 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_MAC" title="PSA_ALG_IS_MAC"><code class="docutils literal"><span class="pre">PSA_ALG_IS_MAC</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]386</dl>
387<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>
388<dl class="docutils">
389<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>
390<dd>Success.</dd>
391<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
392<dd></dd>
393<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]394<dd>The key does not have the <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_VERIFY_MESSAGE" title="PSA_KEY_USAGE_VERIFY_MESSAGE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_VERIFY_MESSAGE</span></code></a> flag, or it does not permit the requested algorithm.</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]395<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>
396<dd><code class="docutils literal"><span class="pre">key</span></code> is not compatible with <code class="docutils literal"><span class="pre">alg</span></code>.</dd>
397<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>
398<dd><code class="docutils literal"><span class="pre">alg</span></code> is not supported or is not a MAC algorithm.</dd>
399<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>
400<dd></dd>
401<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>
402<dd></dd>
403<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>
404<dd></dd>
405<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>
406<dd></dd>
407<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt>
408<dd>The key could not be retrieved from storage</dd>
409<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt>
410<dd>The key could not be retrieved from storage.</dd>
411<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt>
412<dd>The key could not be retrieved from storage.</dd>
413<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>
414<dd>The operation state is not valid: it must be inactive.</dd>
415<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>
416<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>
417</dl>
418<p class="rubric">Description</p>
419<p>This function sets up the verification of the message authentication code (MAC) of a byte string against an expected value.</p>
420<p>The sequence of operations to verify a MAC is as follows:</p>
421<ol class="arabic simple">
422<li>Allocate an operation object which will be passed to all the functions listed here.</li>
423<li>Initialize the operation object with one of the methods described in the documentation for <a class="reference internal" href="#c.psa_mac_operation_t" title="psa_mac_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_mac_operation_t</span></code></a>, e.g. <a class="reference internal" href="#c.PSA_MAC_OPERATION_INIT" title="PSA_MAC_OPERATION_INIT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_MAC_OPERATION_INIT</span></code></a>.</li>
424<li>Call <a class="reference internal" href="#c.psa_mac_verify_setup" title="psa_mac_verify_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_verify_setup()</span></code></a> to specify the algorithm and key.</li>
425<li>Call <a class="reference internal" href="#c.psa_mac_update" title="psa_mac_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_update()</span></code></a> zero, one or more times, passing a fragment of the message each time. The MAC that is calculated is the MAC of the concatenation of these messages in order.</li>
426<li>At the end of the message, call <a class="reference internal" href="#c.psa_mac_verify_finish" title="psa_mac_verify_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_verify_finish()</span></code></a> to finish calculating the actual MAC of the message and verify it against the expected value.</li>
427</ol>
428<p>If an error occurs at any step after a call to <a class="reference internal" href="#c.psa_mac_verify_setup" title="psa_mac_verify_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_verify_setup()</span></code></a>, the operation will need to be reset by a call to <a class="reference internal" href="#c.psa_mac_abort" title="psa_mac_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_abort()</span></code></a>. The application can call <a class="reference internal" href="#c.psa_mac_abort" title="psa_mac_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_abort()</span></code></a> at any time after the operation has been initialized.</p>
429<p>After a successful call to <a class="reference internal" href="#c.psa_mac_verify_setup" title="psa_mac_verify_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_verify_setup()</span></code></a>, the application must eventually terminate the operation through one of the following methods:</p>
430<ul class="simple">
431<li>A successful call to <a class="reference internal" href="#c.psa_mac_verify_finish" title="psa_mac_verify_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_verify_finish()</span></code></a>.</li>
432<li>A call to <a class="reference internal" href="#c.psa_mac_abort" title="psa_mac_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_abort()</span></code></a>.</li>
433</ul>
434</div>
435<div class="section" id="psa_mac_update">
436<span id="c.psa_mac_update"></span><h3><code class="docutils literal"><span class="pre">psa_mac_update</span></code> (function)</h3>
437<p>Add a message fragment to a multi-part MAC operation.</p>
438<pre class="literal-block">
439<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_mac_update" title="psa_mac_update">psa_mac_update</a>(<a class="reference internal" href="#c.psa_mac_operation_t" title="psa_mac_operation_t">psa_mac_operation_t</a> * operation,
440 const uint8_t * input,
441 size_t input_length);
442</pre>
443<p class="rubric">Parameters</p>
444<dl class="docutils">
445<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
446<dd>Active MAC operation.</dd>
447<dt> <code class="docutils literal"><span class="pre">input</span></code></dt>
448<dd>Buffer containing the message fragment to add to the MAC calculation.</dd>
449<dt> <code class="docutils literal"><span class="pre">input_length</span></code></dt>
450<dd>Size of the <code class="docutils literal"><span class="pre">input</span></code> buffer in bytes.</dd>
451</dl>
452<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>
453<dl class="docutils">
454<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>
455<dd>Success.</dd>
456<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>
457<dd>The operation state is not valid: it must be active.</dd>
458<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>
459<dd></dd>
460<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>
461<dd></dd>
462<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>
463<dd></dd>
464<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>
465<dd></dd>
466<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt>
467<dd></dd>
468<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt>
469<dd></dd>
470<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt>
471<dd></dd>
472<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>
473<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>
474</dl>
475<p class="rubric">Description</p>
476<p>The application must call <a class="reference internal" href="#c.psa_mac_sign_setup" title="psa_mac_sign_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_sign_setup()</span></code></a> or <a class="reference internal" href="#c.psa_mac_verify_setup" title="psa_mac_verify_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_verify_setup()</span></code></a> before calling this function.</p>
477<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_mac_abort" title="psa_mac_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_abort()</span></code></a>.</p>
478</div>
479<div class="section" id="psa_mac_sign_finish">
480<span id="c.psa_mac_sign_finish"></span><h3><code class="docutils literal"><span class="pre">psa_mac_sign_finish</span></code> (function)</h3>
481<p>Finish the calculation of the MAC of a message.</p>
482<pre class="literal-block">
483<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_mac_sign_finish" title="psa_mac_sign_finish">psa_mac_sign_finish</a>(<a class="reference internal" href="#c.psa_mac_operation_t" title="psa_mac_operation_t">psa_mac_operation_t</a> * operation,
484 uint8_t * mac,
485 size_t mac_size,
486 size_t * mac_length);
487</pre>
488<p class="rubric">Parameters</p>
489<dl class="docutils">
490<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
491<dd>Active MAC operation.</dd>
492<dt> <code class="docutils literal"><span class="pre">mac</span></code></dt>
493<dd>Buffer where the MAC value is to be written.</dd>
494<dt> <code class="docutils literal"><span class="pre">mac_size</span></code></dt>
495<dd><p class="first">Size of the <code class="docutils literal"><span class="pre">mac</span></code> buffer in bytes.
496This must be appropriate for the selected algorithm and key:</p>
497<ul class="last simple">
498<li>The exact MAC size is <a class="reference internal" href="#c.PSA_MAC_LENGTH" title="PSA_MAC_LENGTH"><code class="docutils literal"><span class="pre">PSA_MAC_LENGTH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">key_type</span></code><code class="docutils literal"><span class="pre">,</span> </code><code class="docutils literal"><span class="pre">key_bits</span></code><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">key_type</span></code> and <code class="docutils literal"><span class="pre">key_bits</span></code> are attributes of the key, and <code class="docutils literal"><span class="pre">alg</span></code> is the algorithm used to compute the MAC.</li>
499<li><a class="reference internal" href="#c.PSA_MAC_MAX_SIZE" title="PSA_MAC_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_MAC_MAX_SIZE</span></code></a> evaluates to the maximum MAC size of any supported MAC algorithm.</li>
500</ul>
501</dd>
502<dt> <code class="docutils literal"><span class="pre">mac_length</span></code></dt>
503<dd>On success, the number of bytes that make up the MAC value. This is always <code class="docutils literal"><span class="pre">PSA_MAC_FINAL_SIZE</span></code><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">key_type</span></code><code class="docutils literal"><span class="pre">,</span> </code><code class="docutils literal"><span class="pre">key_bits</span></code><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">key_type</span></code> and <code class="docutils literal"><span class="pre">key_bits</span></code> are the type and bit-size respectively of the key and <code class="docutils literal"><span class="pre">alg</span></code> is the MAC algorithm that is calculated.</dd>
504</dl>
505<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>
506<dl class="docutils">
507<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>
508<dd>Success.</dd>
509<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>
510<dd>The operation state is not valid: it must be an active mac sign operation.</dd>
511<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>
512<dd>The size of the <code class="docutils literal"><span class="pre">mac</span></code> buffer is too small.
513<a class="reference internal" href="#c.PSA_MAC_LENGTH" title="PSA_MAC_LENGTH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_MAC_LENGTH()</span></code></a> or <a class="reference internal" href="#c.PSA_MAC_MAX_SIZE" title="PSA_MAC_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_MAC_MAX_SIZE</span></code></a> can be used to determine the required buffer size.</dd>
514<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>
515<dd></dd>
516<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>
517<dd></dd>
518<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>
519<dd></dd>
520<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>
521<dd></dd>
522<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt>
523<dd></dd>
524<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt>
525<dd></dd>
526<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt>
527<dd></dd>
528<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>
529<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>
530</dl>
531<p class="rubric">Description</p>
532<p>The application must call <a class="reference internal" href="#c.psa_mac_sign_setup" title="psa_mac_sign_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_sign_setup()</span></code></a> before calling this function. This function calculates the MAC of the message formed by concatenating the inputs passed to preceding calls to <a class="reference internal" href="#c.psa_mac_update" title="psa_mac_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_update()</span></code></a>.</p>
533<p>When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling <a class="reference internal" href="#c.psa_mac_abort" title="psa_mac_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_abort()</span></code></a>.</p>
534<div class="admonition warning">
535<p class="first admonition-title">Warning</p>
536<p>It is not recommended to use this function when a specific value is expected for the MAC. Call <a class="reference internal" href="#c.psa_mac_verify_finish" title="psa_mac_verify_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_verify_finish()</span></code></a> instead with the expected MAC value.</p>
537<p class="last">Comparing integrity or authenticity data such as MAC 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 MAC and thereby bypass security controls.</p>
538</div>
539</div>
540<div class="section" id="psa_mac_verify_finish">
541<span id="c.psa_mac_verify_finish"></span><h3><code class="docutils literal"><span class="pre">psa_mac_verify_finish</span></code> (function)</h3>
542<p>Finish the calculation of the MAC of a message and compare it with an expected value.</p>
543<pre class="literal-block">
544<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_mac_verify_finish" title="psa_mac_verify_finish">psa_mac_verify_finish</a>(<a class="reference internal" href="#c.psa_mac_operation_t" title="psa_mac_operation_t">psa_mac_operation_t</a> * operation,
545 const uint8_t * mac,
546 size_t mac_length);
547</pre>
548<p class="rubric">Parameters</p>
549<dl class="docutils">
550<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
551<dd>Active MAC operation.</dd>
552<dt> <code class="docutils literal"><span class="pre">mac</span></code></dt>
553<dd>Buffer containing the expected MAC value.</dd>
554<dt> <code class="docutils literal"><span class="pre">mac_length</span></code></dt>
555<dd>Size of the <code class="docutils literal"><span class="pre">mac</span></code> buffer in bytes.</dd>
556</dl>
557<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
558<dl class="docutils">
559<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
560<dd>The expected MAC is identical to the actual MAC of the message.</dd>
561<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>
562<dd>The MAC of the message was calculated successfully, but it differs from the expected MAC.</dd>
563<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>
564<dd>The operation state is not valid: it must be an active mac verify operation.</dd>
565<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>
566<dd></dd>
567<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>
568<dd></dd>
569<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>
570<dd></dd>
571<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>
572<dd></dd>
573<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt>
574<dd></dd>
575<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt>
576<dd></dd>
577<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt>
578<dd></dd>
579<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>
580<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>
581</dl>
582<p class="rubric">Description</p>
583<p>The application must call <a class="reference internal" href="#c.psa_mac_verify_setup" title="psa_mac_verify_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_verify_setup()</span></code></a> before calling this function. This function calculates the MAC of the message formed by concatenating the inputs passed to preceding calls to <a class="reference internal" href="#c.psa_mac_update" title="psa_mac_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_update()</span></code></a>. It then compares the calculated MAC with the expected MAC passed as a parameter to this function.</p>
584<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_mac_abort" title="psa_mac_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_abort()</span></code></a>.</p>
585<div class="admonition note">
586<p class="first admonition-title">Note</p>
587<p class="last">Implementations must make the best effort to ensure that the comparison between the actual MAC and the expected MAC is performed in constant time.</p>
588</div>
589</div>
590<div class="section" id="psa_mac_abort">
591<span id="c.psa_mac_abort"></span><h3><code class="docutils literal"><span class="pre">psa_mac_abort</span></code> (function)</h3>
592<p>Abort a MAC operation.</p>
593<pre class="literal-block">
594<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_mac_abort" title="psa_mac_abort">psa_mac_abort</a>(<a class="reference internal" href="#c.psa_mac_operation_t" title="psa_mac_operation_t">psa_mac_operation_t</a> * operation);
595</pre>
596<p class="rubric">Parameters</p>
597<dl class="docutils">
598<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
599<dd>Initialized MAC operation.</dd>
600</dl>
601<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>
602<dl class="docutils">
603<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>
604<dd></dd>
605<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>
606<dd></dd>
607<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>
608<dd></dd>
609<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>
610<dd></dd>
611<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>
612<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>
613</dl>
614<p class="rubric">Description</p>
615<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_mac_sign_setup" title="psa_mac_sign_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_sign_setup()</span></code></a> or <a class="reference internal" href="#c.psa_mac_verify_setup" title="psa_mac_verify_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_verify_setup()</span></code></a> again.</p>
616<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_mac_operation_t" title="psa_mac_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_mac_operation_t</span></code></a>.</p>
617<p>In particular, calling <a class="reference internal" href="#c.psa_mac_abort" title="psa_mac_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_abort()</span></code></a> after the operation has been terminated by a call to <a class="reference internal" href="#c.psa_mac_abort" title="psa_mac_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_abort()</span></code></a>, <a class="reference internal" href="#c.psa_mac_sign_finish" title="psa_mac_sign_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_sign_finish()</span></code></a> or <a class="reference internal" href="#c.psa_mac_verify_finish" title="psa_mac_verify_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_verify_finish()</span></code></a> is safe and has no effect.</p>
618</div>
619</div>
620<div class="section" id="support-macros">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]621<h2>10.3.4. Support macros</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]622<div class="section" id="PSA_ALG_IS_HMAC">
623<span id="c.PSA_ALG_IS_HMAC"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_HMAC</span></code> (macro)</h3>
624<p>Whether the specified algorithm is an HMAC algorithm.</p>
625<pre class="literal-block">
626#define <a class="reference internal" href="#c.PSA_ALG_IS_HMAC" title="PSA_ALG_IS_HMAC">PSA_ALG_IS_HMAC</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>
627</pre>
628<p class="rubric">Parameters</p>
629<dl class="docutils">
630<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]631<dd>An algorithm identifier (value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>).</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]632</dl>
633<p class="rubric">Returns</p>
634<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is an HMAC algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise. This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported algorithm identifier.</p>
635<p class="rubric">Description</p>
636<p>HMAC is a family of MAC algorithms that are based on a hash function.</p>
637</div>
638<div class="section" id="PSA_ALG_IS_BLOCK_CIPHER_MAC">
639<span id="c.PSA_ALG_IS_BLOCK_CIPHER_MAC"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_BLOCK_CIPHER_MAC</span></code> (macro)</h3>
640<p>Whether the specified algorithm is a MAC algorithm based on a block cipher.</p>
641<pre class="literal-block">
642#define <a class="reference internal" href="#c.PSA_ALG_IS_BLOCK_CIPHER_MAC" title="PSA_ALG_IS_BLOCK_CIPHER_MAC">PSA_ALG_IS_BLOCK_CIPHER_MAC</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>
643</pre>
644<p class="rubric">Parameters</p>
645<dl class="docutils">
646<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]647<dd>An algorithm identifier (value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>).</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]648</dl>
649<p class="rubric">Returns</p>
650<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a MAC algorithm based on a block cipher, <code class="docutils literal"><span class="pre">0</span></code> otherwise. This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported algorithm identifier.</p>
651</div>
652<div class="section" id="PSA_ALG_FULL_LENGTH_MAC">
653<span id="c.PSA_ALG_FULL_LENGTH_MAC"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_FULL_LENGTH_MAC</span></code> (macro)</h3>
654<p>Macro to construct the MAC algorithm with a full length MAC, from a truncated MAC algorithm.</p>
655<pre class="literal-block">
656#define <a class="reference internal" href="#c.PSA_ALG_FULL_LENGTH_MAC" title="PSA_ALG_FULL_LENGTH_MAC">PSA_ALG_FULL_LENGTH_MAC</a>(mac_alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
657</pre>
658<p class="rubric">Parameters</p>
659<dl class="docutils">
660<dt> <code class="docutils literal"><span class="pre">mac_alg</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]661<dd>A MAC algorithm identifier (value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a> such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_MAC" title="PSA_ALG_IS_MAC"><code class="docutils literal"><span class="pre">PSA_ALG_IS_MAC</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). This can be a truncated or untruncated MAC algorithm.</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]662</dl>
663<p class="rubric">Returns</p>
664<p>The corresponding MAC algorithm with a full length MAC.</p>
665<p>Unspecified if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported MAC algorithm.</p>
666</div>
667<div class="section" id="PSA_MAC_LENGTH">
668<span id="c.PSA_MAC_LENGTH"></span><h3><code class="docutils literal"><span class="pre">PSA_MAC_LENGTH</span></code> (macro)</h3>
669<p>The size of the output of <a class="reference internal" href="#c.psa_mac_compute" title="psa_mac_compute"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_compute()</span></code></a> and <a class="reference internal" href="#c.psa_mac_sign_finish" title="psa_mac_sign_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_sign_finish()</span></code></a>, in bytes.</p>
670<pre class="literal-block">
671#define <a class="reference internal" href="#c.PSA_MAC_LENGTH" title="PSA_MAC_LENGTH">PSA_MAC_LENGTH</a>(key_type, key_bits, alg) \
672 <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em>
673</pre>
674<p class="rubric">Parameters</p>
675<dl class="docutils">
676<dt> <code class="docutils literal"><span class="pre">key_type</span></code></dt>
677<dd>The type of the MAC key.</dd>
678<dt> <code class="docutils literal"><span class="pre">key_bits</span></code></dt>
679<dd>The size of the MAC key in bits.</dd>
680<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]681<dd>A MAC 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_MAC" title="PSA_ALG_IS_MAC"><code class="docutils literal"><span class="pre">PSA_ALG_IS_MAC</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]682</dl>
683<p class="rubric">Returns</p>
684<p>The MAC length for the specified algorithm with the specified key parameters.</p>
685<p><code class="docutils literal"><span class="pre">0</span></code> if the MAC algorithm is not recognized.</p>
686<p>Either <code class="docutils literal"><span class="pre">0</span></code> or the correct length for a MAC algorithm that the implementation recognizes, but does not support.</p>
687<p>Unspecified if the key parameters are not consistent with the algorithm.</p>
688<p class="rubric">Description</p>
689<p>This is also the MAC length that <a class="reference internal" href="#c.psa_mac_verify" title="psa_mac_verify"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_verify()</span></code></a> and <a class="reference internal" href="#c.psa_mac_verify_finish" title="psa_mac_verify_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_verify_finish()</span></code></a> expects.</p>
690<p>See also <a class="reference internal" href="#c.PSA_MAC_MAX_SIZE" title="PSA_MAC_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_MAC_MAX_SIZE</span></code></a>.</p>
691</div>
692<div class="section" id="PSA_MAC_MAX_SIZE">
693<span id="c.PSA_MAC_MAX_SIZE"></span><h3><code class="docutils literal"><span class="pre">PSA_MAC_MAX_SIZE</span></code> (macro)</h3>
694<p>Maximum size of a MAC.</p>
695<pre class="literal-block">
696#define <a class="reference internal" href="#c.PSA_MAC_MAX_SIZE" title="PSA_MAC_MAX_SIZE">PSA_MAC_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>
697</pre>
698<p>This macro must expand to a compile-time constant integer.
699It is recommended that this value is the maximum size of a MAC supported by the implementation, in bytes. The value must not be smaller than this maximum.</p>
700<p>See also <a class="reference internal" href="#c.PSA_MAC_LENGTH" title="PSA_MAC_LENGTH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_MAC_LENGTH()</span></code></a>.</p>
701</div>
702</div>
703</div>
704
705
706 </div>
707 </div>
708 </div>
709 <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]710 <div class="sphinxsidebarwrapper"><h3><a href="../../index.html"><b>PSA Crypto API</b></a></h3>
711IHI 0086<br/>
712Non-confidential<br/>
713Version 1.0.1
714<span style="color: red; font-weight: bold;"></span>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]715<ul>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]716<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]717</ul>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]718<ul class="current">
719<li class="toctree-l1"><a class="reference internal" href="../../overview/intro.html">1. Introduction</a></li>
720<li class="toctree-l1"><a class="reference internal" href="../../overview/goals.html">2. Design goals</a></li>
721<li class="toctree-l1"><a class="reference internal" href="../../overview/functionality.html">3. Functionality overview</a></li>
722<li class="toctree-l1"><a class="reference internal" href="../../overview/sample-arch.html">4. Sample architectures</a></li>
723<li class="toctree-l1"><a class="reference internal" href="../../overview/conventions.html">5. Library conventions</a></li>
724<li class="toctree-l1"><a class="reference internal" href="../../overview/implementation.html">6. Implementation considerations</a></li>
725<li class="toctree-l1"><a class="reference internal" href="../../overview/usage.html">7. Usage considerations</a></li>
726<li class="toctree-l1"><a class="reference internal" href="../library/index.html">8. Library management reference</a></li>
727<li class="toctree-l1"><a class="reference internal" href="../keys/index.html">9. Key management reference</a></li>
728<li class="toctree-l1 current"><a class="reference internal" href="index.html">10. Cryptographic operation reference</a><ul class="current">
729<li class="toctree-l2"><a class="reference internal" href="algorithms.html">10.1. Algorithms</a></li>
730<li class="toctree-l2"><a class="reference internal" href="hashes.html">10.2. Message digests</a></li>
731<li class="toctree-l2 current"><a class="current reference internal" href="#">10.3. Message authentication codes (MAC)</a><ul>
732<li class="toctree-l3"><a class="reference internal" href="#mac-algorithms">10.3.1. MAC algorithms</a></li>
733<li class="toctree-l3"><a class="reference internal" href="#single-part-mac-functions">10.3.2. Single-part MAC functions</a></li>
734<li class="toctree-l3"><a class="reference internal" href="#multi-part-mac-operations">10.3.3. Multi-part MAC operations</a></li>
735<li class="toctree-l3"><a class="reference internal" href="#support-macros">10.3.4. Support macros</a></li>
736</ul>
737</li>
738<li class="toctree-l2"><a class="reference internal" href="ciphers.html">10.4. Unauthenticated ciphers</a></li>
739<li class="toctree-l2"><a class="reference internal" href="aead.html">10.5. Authenticated encryption with associated data (AEAD)</a></li>
740<li class="toctree-l2"><a class="reference internal" href="kdf.html">10.6. Key derivation</a></li>
741<li class="toctree-l2"><a class="reference internal" href="sign.html">10.7. Asymmetric signature</a></li>
742<li class="toctree-l2"><a class="reference internal" href="pke.html">10.8. Asymmetric encryption</a></li>
743<li class="toctree-l2"><a class="reference internal" href="ka.html">10.9. Key agreement</a></li>
744<li class="toctree-l2"><a class="reference internal" href="rng.html">10.10. Other cryptographic services</a></li>
745</ul>
746</li>
747</ul>
748<ul>
749<li class="toctree-l1"><a class="reference internal" href="../../appendix/example_header.html">Example header file</a></li>
750<li class="toctree-l1"><a class="reference internal" href="../../appendix/specdef_values.html">Example macro implementations</a></li>
751<li class="toctree-l1"><a class="reference internal" href="../../appendix/history.html">Changes to the API</a></li>
752</ul>
753<ul>
754<li class="toctree-l1"><a class="reference internal" href="../../psa_c-identifiers.html">Index of API elements</a></li>
755</ul>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]756<div id="searchbox" style="display: none" role="search">
757 <h3>Quick search</h3>
758 <form class="search" action="../../search.html" method="get">
759 <div><input type="text" name="q" /></div>
760 <div><input type="submit" value="Go" /></div>
761 <input type="hidden" name="check_keywords" value="yes" />
762 <input type="hidden" name="area" value="default" />
763 </form>
764</div>
765<script type="text/javascript">$('#searchbox').show(0);</script>
766 </div>
767 </div>
768 <div class="clearer"></div>
769 </div>
770 <div class="footer">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]771 &copy; 2018-2020, Arm Limited or its affiliates. All rights reserved.
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]772
773 |
774 Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
775 &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
776
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]777 </div>
778
779
780
781
782 </body>
783</html>