| |
| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" |
| "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| |
| <html xmlns="http://www.w3.org/1999/xhtml"> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> |
| <title>10.3. Message authentication codes (MAC) — PSA Crypto API 1.1.0 documentation</title> |
| <link rel="stylesheet" href="../../_static/alabaster.css" type="text/css" /> |
| <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" /> |
| <script type="text/javascript"> |
| var DOCUMENTATION_OPTIONS = { |
| URL_ROOT: '../../', |
| VERSION: '1.1.0', |
| COLLAPSE_INDEX: false, |
| FILE_SUFFIX: '.html', |
| HAS_SOURCE: false, |
| SOURCELINK_SUFFIX: '.txt' |
| }; |
| </script> |
| <script type="text/javascript" src="../../_static/jquery.js"></script> |
| <script type="text/javascript" src="../../_static/underscore.js"></script> |
| <script type="text/javascript" src="../../_static/doctools.js"></script> |
| <link rel="author" title="About these documents" href="../../about.html" /> |
| <link rel="index" title="Index" href="../../genindex.html" /> |
| <link rel="search" title="Search" href="../../search.html" /> |
| <link rel="next" title="10.4. Unauthenticated ciphers" href="ciphers.html" /> |
| <link rel="prev" title="10.2. Message digests (Hashes)" href="hashes.html" /> |
| |
| <link rel="stylesheet" href="../../_static/custom.css" type="text/css" /> |
| |
| <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" /> |
| |
| </head> |
| <body> |
| |
| |
| <div class="document"> |
| <div class="documentwrapper"> |
| <div class="bodywrapper"> |
| <div class="body" role="main"> |
| |
| <div class="section" id="message-authentication-codes-mac"> |
| <span id="macs"></span><h1>10.3. Message authentication codes (MAC)</h1> |
| <p>The single-part MAC functions are:</p> |
| <ul class="simple"> |
| <li><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> to calculate the MAC of a message.</li> |
| <li><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> to compare the MAC of a message with a reference value.</li> |
| </ul> |
| <p>The <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> <a class="reference internal" href="../../overview/functionality.html#multi-part-operations"><span class="std std-ref">multi-part operation</span></a> allows messages to be processed in fragments. A multi-part MAC operation is used as follows:</p> |
| <ol class="arabic simple"> |
| <li>Initialize the <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> object to zero, or by assigning the value of the associated macro <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> |
| <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> 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> to specify the algorithm and key.</li> |
| <li>Call the <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> function on successive chunks of the message.</li> |
| <li>At the end of the message, call the required finishing function:<ul> |
| <li>To calculate the MAC 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>.</li> |
| <li>To verify the MAC of the message against a reference value, 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>.</li> |
| </ul> |
| </li> |
| </ol> |
| <p>To abort the operation or recover from an error, 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>.</p> |
| <div class="section" id="mac-algorithms"> |
| <span id="id1"></span><h2>10.3.1. MAC algorithms</h2> |
| <div class="section" id="PSA_ALG_HMAC"> |
| <span id="c.PSA_ALG_HMAC"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_HMAC</span></code> (macro)</h3> |
| <p>Macro to build an HMAC message-authentication-code algorithm from an underlying hash algorithm.</p> |
| <pre class="literal-block"> |
| #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> |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">hash_alg</span></code></dt> |
| <dd>A hash algorithm: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a> such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">hash_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true.</dd> |
| </dl> |
| <p class="rubric">Returns</p> |
| <p>The corresponding HMAC algorithm.</p> |
| <p>Unspecified if <code class="docutils literal"><span class="pre">hash_alg</span></code> is not a supported hash algorithm.</p> |
| <p class="rubric">Description</p> |
| <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> |
| <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> |
| <p class="rubric">Compatible key types</p> |
| <div class="line-block"> |
| <div class="line"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_HMAC" title="PSA_KEY_TYPE_HMAC"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_HMAC</span></code></a></div> |
| </div> |
| </div> |
| <div class="section" id="PSA_ALG_CBC_MAC"> |
| <span id="c.PSA_ALG_CBC_MAC"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_CBC_MAC</span></code> (macro)</h3> |
| <p>The CBC-MAC message-authentication-code algorithm, constructed over a block cipher.</p> |
| <pre class="literal-block"> |
| #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) |
| </pre> |
| <div class="admonition warning"> |
| <p class="first admonition-title">Warning</p> |
| <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> |
| </div> |
| <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> |
| <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> |
| <p class="rubric">Compatible key types</p> |
| <div class="line-block"> |
| <div class="line"><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></div> |
| <div class="line"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_ARIA" title="PSA_KEY_TYPE_ARIA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_ARIA</span></code></a></div> |
| <div class="line"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_DES" title="PSA_KEY_TYPE_DES"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_DES</span></code></a></div> |
| <div class="line"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_CAMELLIA" title="PSA_KEY_TYPE_CAMELLIA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_CAMELLIA</span></code></a></div> |
| <div class="line"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_SM4" title="PSA_KEY_TYPE_SM4"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_SM4</span></code></a></div> |
| </div> |
| </div> |
| <div class="section" id="PSA_ALG_CMAC"> |
| <span id="c.PSA_ALG_CMAC"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_CMAC</span></code> (macro)</h3> |
| <p>The CMAC message-authentication-code algorithm, constructed over a block cipher.</p> |
| <pre class="literal-block"> |
| #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) |
| </pre> |
| <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> |
| <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> |
| <p class="rubric">Compatible key types</p> |
| <div class="line-block"> |
| <div class="line"><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></div> |
| <div class="line"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_ARIA" title="PSA_KEY_TYPE_ARIA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_ARIA</span></code></a></div> |
| <div class="line"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_DES" title="PSA_KEY_TYPE_DES"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_DES</span></code></a></div> |
| <div class="line"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_CAMELLIA" title="PSA_KEY_TYPE_CAMELLIA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_CAMELLIA</span></code></a></div> |
| <div class="line"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_SM4" title="PSA_KEY_TYPE_SM4"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_SM4</span></code></a></div> |
| </div> |
| </div> |
| <div class="section" id="PSA_ALG_TRUNCATED_MAC"> |
| <span id="c.PSA_ALG_TRUNCATED_MAC"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_TRUNCATED_MAC</span></code> (macro)</h3> |
| <p>Macro to build a truncated MAC algorithm.</p> |
| <pre class="literal-block"> |
| #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) \ |
| <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em> |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">mac_alg</span></code></dt> |
| <dd>A MAC algorithm: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a> such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_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">mac_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true. This can be a truncated or untruncated MAC algorithm.</dd> |
| <dt> <code class="docutils literal"><span class="pre">mac_length</span></code></dt> |
| <dd>Desired length of the truncated MAC in bytes. This must be at most the untruncated length of the MAC and must be at least an implementation-specified minimum. The implementation-specified minimum must not be zero.</dd> |
| </dl> |
| <p class="rubric">Returns</p> |
| <p>The corresponding MAC algorithm with the specified length.</p> |
| <p>Unspecified if <code class="docutils literal"><span class="pre">mac_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> |
| <p class="rubric">Description</p> |
| <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> |
| <div class="admonition note"> |
| <p class="first admonition-title">Note</p> |
| <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> |
| </div> |
| <div class="admonition note"> |
| <p class="first admonition-title">Note</p> |
| <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> |
| </div> |
| <p>The untruncated 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> |
| <p class="rubric">Compatible key types</p> |
| <p>The resulting truncated MAC algorithm is compatible with the same key types as the MAC algorithm used to construct it.</p> |
| </div> |
| <div class="section" id="PSA_ALG_FULL_LENGTH_MAC"> |
| <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> |
| <p>Macro to construct the MAC algorithm with an untruncated MAC, from a truncated MAC algorithm.</p> |
| <pre class="literal-block"> |
| #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> |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">mac_alg</span></code></dt> |
| <dd>A MAC algorithm: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a> such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_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">mac_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true. This can be a truncated or untruncated MAC algorithm.</dd> |
| </dl> |
| <p class="rubric">Returns</p> |
| <p>The corresponding MAC algorithm with an untruncated MAC.</p> |
| <p>Unspecified if <code class="docutils literal"><span class="pre">mac_alg</span></code> is not a supported MAC algorithm.</p> |
| <p class="rubric">Compatible key types</p> |
| <p>The resulting untruncated MAC algorithm is compatible with the same key types as the MAC algorithm used to construct it.</p> |
| </div> |
| <div class="section" id="PSA_ALG_AT_LEAST_THIS_LENGTH_MAC"> |
| <span id="c.PSA_ALG_AT_LEAST_THIS_LENGTH_MAC"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_AT_LEAST_THIS_LENGTH_MAC</span></code> (macro)</h3> |
| <p>Macro to build a MAC minimum-MAC-length wildcard algorithm.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_ALG_AT_LEAST_THIS_LENGTH_MAC" title="PSA_ALG_AT_LEAST_THIS_LENGTH_MAC">PSA_ALG_AT_LEAST_THIS_LENGTH_MAC</a>(mac_alg, min_mac_length) \ |
| <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em> |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">mac_alg</span></code></dt> |
| <dd>A MAC algorithm: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a> such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_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> |
| <dt> <code class="docutils literal"><span class="pre">min_mac_length</span></code></dt> |
| <dd>Desired minimum length of the message authentication code in bytes. This must be at most the untruncated length of the MAC and must be at least <code class="docutils literal"><span class="pre">1</span></code>.</dd> |
| </dl> |
| <p class="rubric">Returns</p> |
| <p>The corresponding MAC wildcard algorithm with the specified minimum MAC length.</p> |
| <p>Unspecified if <code class="docutils literal"><span class="pre">mac_alg</span></code> is not a supported MAC algorithm or if <code class="docutils literal"><span class="pre">min_mac_length</span></code> is less than <code class="docutils literal"><span class="pre">1</span></code> or too large for the specified MAC algorithm.</p> |
| <p class="rubric">Description</p> |
| <p>A key with a minimum-MAC-length MAC wildcard algorithm as permitted algorithm policy can be used with all MAC algorithms sharing the same base algorithm, and where the (potentially truncated) MAC length of the specific algorithm is equal to or larger then the wildcard algorithm’s minimum MAC length.</p> |
| <div class="admonition note"> |
| <p class="first admonition-title">Note</p> |
| <p class="last">When setting the minimum required MAC length to less than the smallest MAC length allowed by the base algorithm, this effectively becomes an ‘any-MAC-length-allowed’ policy for that base algorithm.</p> |
| </div> |
| <p>The untruncated 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> |
| <p class="rubric">Compatible key types</p> |
| <p>The resulting wildcard MAC algorithm is compatible with the same key types as the MAC algorithm used to construct it.</p> |
| </div> |
| </div> |
| <div class="section" id="single-part-mac-functions"> |
| <h2>10.3.2. Single-part MAC functions</h2> |
| <div class="section" id="psa_mac_compute"> |
| <span id="c.psa_mac_compute"></span><h3><code class="docutils literal"><span class="pre">psa_mac_compute</span></code> (function)</h3> |
| <p>Calculate the message authentication code (MAC) of a message.</p> |
| <pre class="literal-block"> |
| <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_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, |
| <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg, |
| const uint8_t * input, |
| size_t input_length, |
| uint8_t * mac, |
| size_t mac_size, |
| size_t * mac_length); |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">key</span></code></dt> |
| <dd>Identifier of the key to use for the operation. |
| It 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> |
| <dt> <code class="docutils literal"><span class="pre">alg</span></code></dt> |
| <dd>The MAC algorithm to compute: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a> such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_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> |
| <dt> <code class="docutils literal"><span class="pre">input</span></code></dt> |
| <dd>Buffer containing the input message.</dd> |
| <dt> <code class="docutils literal"><span class="pre">input_length</span></code></dt> |
| <dd>Size of the <code class="docutils literal"><span class="pre">input</span></code> buffer in bytes.</dd> |
| <dt> <code class="docutils literal"><span class="pre">mac</span></code></dt> |
| <dd>Buffer where the MAC value is to be written.</dd> |
| <dt> <code class="docutils literal"><span class="pre">mac_size</span></code></dt> |
| <dd><p class="first">Size of the <code class="docutils literal"><span class="pre">mac</span></code> buffer in bytes. |
| This must be appropriate for the selected algorithm and key:</p> |
| <ul class="last simple"> |
| <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> |
| <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> |
| </ul> |
| </dd> |
| <dt> <code class="docutils literal"><span class="pre">mac_length</span></code></dt> |
| <dd>On success, the number of bytes that make up the MAC value.</dd> |
| </dl> |
| <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> |
| <dl class="docutils"> |
| <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> |
| <dd>Success. |
| The first <code class="docutils literal"><span class="pre">(*mac_length)</span></code> bytes of <code class="docutils literal"><span class="pre">mac</span></code> contain the MAC value.</dd> |
| <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> |
| <dd>The library requires initializing by a call to <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_crypto_init()</span></code></a>.</dd> |
| <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> |
| <dd><code class="docutils literal"><span class="pre">key</span></code> is not a valid key identifier.</dd> |
| <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> |
| <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> |
| <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> |
| <dd>The size of the <code class="docutils literal"><span class="pre">mac</span></code> buffer is too small. |
| <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 a sufficient buffer size.</dd> |
| <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> |
| <dd><p class="first">The following conditions can result in this error:</p> |
| <ul class="last simple"> |
| <li><code class="docutils literal"><span class="pre">alg</span></code> is not a MAC algorithm.</li> |
| <li><code class="docutils literal"><span class="pre">key</span></code> is not compatible with <code class="docutils literal"><span class="pre">alg</span></code>.</li> |
| <li><code class="docutils literal"><span class="pre">input_length</span></code> is too large for <code class="docutils literal"><span class="pre">alg</span></code>.</li> |
| </ul> |
| </dd> |
| <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> |
| <dd><p class="first">The following conditions can result in this error:</p> |
| <ul class="last simple"> |
| <li><code class="docutils literal"><span class="pre">alg</span></code> is not supported or is not a MAC algorithm.</li> |
| <li><code class="docutils literal"><span class="pre">key</span></code> is not supported for use with <code class="docutils literal"><span class="pre">alg</span></code>.</li> |
| <li><code class="docutils literal"><span class="pre">input_length</span></code> is too large for the implementation.</li> |
| </ul> |
| </dd> |
| <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> |
| <dd></dd> |
| <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> |
| <dd></dd> |
| <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> |
| <dd></dd> |
| <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> |
| <dd></dd> |
| <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> |
| <dd></dd> |
| <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> |
| <dd></dd> |
| </dl> |
| <p class="rubric">Description</p> |
| <div class="admonition note"> |
| <p class="first admonition-title">Note</p> |
| <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> |
| </div> |
| </div> |
| <div class="section" id="psa_mac_verify"> |
| <span id="c.psa_mac_verify"></span><h3><code class="docutils literal"><span class="pre">psa_mac_verify</span></code> (function)</h3> |
| <p>Calculate the MAC of a message and compare it with a reference value.</p> |
| <pre class="literal-block"> |
| <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_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, |
| <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg, |
| const uint8_t * input, |
| size_t input_length, |
| const uint8_t * mac, |
| size_t mac_length); |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">key</span></code></dt> |
| <dd>Identifier of the key to use for the operation. |
| It 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> |
| <dt> <code class="docutils literal"><span class="pre">alg</span></code></dt> |
| <dd>The MAC algorithm to compute: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a> such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_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> |
| <dt> <code class="docutils literal"><span class="pre">input</span></code></dt> |
| <dd>Buffer containing the input message.</dd> |
| <dt> <code class="docutils literal"><span class="pre">input_length</span></code></dt> |
| <dd>Size of the <code class="docutils literal"><span class="pre">input</span></code> buffer in bytes.</dd> |
| <dt> <code class="docutils literal"><span class="pre">mac</span></code></dt> |
| <dd>Buffer containing the expected MAC value.</dd> |
| <dt> <code class="docutils literal"><span class="pre">mac_length</span></code></dt> |
| <dd>Size of the <code class="docutils literal"><span class="pre">mac</span></code> buffer in bytes.</dd> |
| </dl> |
| <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> |
| <dl class="docutils"> |
| <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> |
| <dd>Success. |
| The expected MAC is identical to the actual MAC of the input.</dd> |
| <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> |
| <dd>The library requires initializing by a call to <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_crypto_init()</span></code></a>.</dd> |
| <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> |
| <dd><code class="docutils literal"><span class="pre">key</span></code> is not a valid key identifier.</dd> |
| <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> |
| <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> |
| <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> |
| <dd>The calculated MAC of the message does not match the value in <code class="docutils literal"><span class="pre">mac</span></code>.</dd> |
| <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> |
| <dd><p class="first">The following conditions can result in this error:</p> |
| <ul class="last simple"> |
| <li><code class="docutils literal"><span class="pre">alg</span></code> is not a MAC algorithm.</li> |
| <li><code class="docutils literal"><span class="pre">key</span></code> is not compatible with <code class="docutils literal"><span class="pre">alg</span></code>.</li> |
| <li><code class="docutils literal"><span class="pre">input_length</span></code> is too large for <code class="docutils literal"><span class="pre">alg</span></code>.</li> |
| </ul> |
| </dd> |
| <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> |
| <dd><p class="first">The following conditions can result in this error:</p> |
| <ul class="last simple"> |
| <li><code class="docutils literal"><span class="pre">alg</span></code> is not supported or is not a MAC algorithm.</li> |
| <li><code class="docutils literal"><span class="pre">key</span></code> is not supported for use with <code class="docutils literal"><span class="pre">alg</span></code>.</li> |
| <li><code class="docutils literal"><span class="pre">input_length</span></code> is too large for the implementation.</li> |
| </ul> |
| </dd> |
| <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> |
| <dd></dd> |
| <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> |
| <dd></dd> |
| <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> |
| <dd></dd> |
| <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> |
| <dd></dd> |
| <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> |
| <dd></dd> |
| <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> |
| <dd></dd> |
| </dl> |
| </div> |
| </div> |
| <div class="section" id="multi-part-mac-operations"> |
| <h2>10.3.3. Multi-part MAC operations</h2> |
| <div class="section" id="psa_mac_operation_t"> |
| <span id="c.psa_mac_operation_t"></span><h3><code class="docutils literal"><span class="pre">psa_mac_operation_t</span></code> (type)</h3> |
| <p>The type of the state object for multi-part MAC operations.</p> |
| <pre class="literal-block"> |
| typedef <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-type"><span class="std std-ref">/* implementation-defined type */</span></a></em> <a class="reference internal" href="#c.psa_mac_operation_t" title="psa_mac_operation_t">psa_mac_operation_t</a>; |
| </pre> |
| <p>Before calling any function on a MAC operation object, the application must initialize it by any of the following means:</p> |
| <ul> |
| <li><p class="first">Set the object to all-bits-zero, for example:</p> |
| <pre class="literal-block"> |
| <a class="reference internal" href="#c.psa_mac_operation_t" title="psa_mac_operation_t">psa_mac_operation_t</a> operation; |
| memset(&operation, 0, sizeof(operation)); |
| </pre> |
| </li> |
| <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> |
| <pre class="literal-block"> |
| static <a class="reference internal" href="#c.psa_mac_operation_t" title="psa_mac_operation_t">psa_mac_operation_t</a> operation; |
| </pre> |
| </li> |
| <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> |
| <pre class="literal-block"> |
| <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>; |
| </pre> |
| </li> |
| <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> |
| <pre class="literal-block"> |
| <a class="reference internal" href="#c.psa_mac_operation_t" title="psa_mac_operation_t">psa_mac_operation_t</a> operation; |
| operation = <a class="reference internal" href="#c.psa_mac_operation_init" title="psa_mac_operation_init">psa_mac_operation_init</a>(); |
| </pre> |
| </li> |
| </ul> |
| <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> |
| </div> |
| <div class="section" id="PSA_MAC_OPERATION_INIT"> |
| <span id="c.PSA_MAC_OPERATION_INIT"></span><h3><code class="docutils literal"><span class="pre">PSA_MAC_OPERATION_INIT</span></code> (macro)</h3> |
| <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> |
| <pre class="literal-block"> |
| #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> |
| </pre> |
| </div> |
| <div class="section" id="psa_mac_operation_init"> |
| <span id="c.psa_mac_operation_init"></span><h3><code class="docutils literal"><span class="pre">psa_mac_operation_init</span></code> (function)</h3> |
| <p>Return an initial value for a MAC operation object.</p> |
| <pre class="literal-block"> |
| <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); |
| </pre> |
| <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> |
| </div> |
| <div class="section" id="psa_mac_sign_setup"> |
| <span id="c.psa_mac_sign_setup"></span><h3><code class="docutils literal"><span class="pre">psa_mac_sign_setup</span></code> (function)</h3> |
| <p>Set up a multi-part MAC calculation operation.</p> |
| <pre class="literal-block"> |
| <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_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, |
| <a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key, |
| <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg); |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">operation</span></code></dt> |
| <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> |
| <dt> <code class="docutils literal"><span class="pre">key</span></code></dt> |
| <dd>Identifier of the key to use for the operation. It must remain valid until the operation terminates. |
| It 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> |
| <dt> <code class="docutils literal"><span class="pre">alg</span></code></dt> |
| <dd>The MAC algorithm to compute: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a> such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_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> |
| </dl> |
| <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> |
| <dl class="docutils"> |
| <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> |
| <dd>Success.</dd> |
| <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> |
| <dd><p class="first">The following conditions can result in this error:</p> |
| <ul class="last simple"> |
| <li>The operation state is not valid: it must be inactive.</li> |
| <li>The library requires initializing by a call to <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_crypto_init()</span></code></a>.</li> |
| </ul> |
| </dd> |
| <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> |
| <dd><code class="docutils literal"><span class="pre">key</span></code> is not a valid key identifier.</dd> |
| <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> |
| <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> |
| <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> |
| <dd><p class="first">The following conditions can result in this error:</p> |
| <ul class="last simple"> |
| <li><code class="docutils literal"><span class="pre">alg</span></code> is not a MAC algorithm.</li> |
| <li><code class="docutils literal"><span class="pre">key</span></code> is not compatible with <code class="docutils literal"><span class="pre">alg</span></code>.</li> |
| </ul> |
| </dd> |
| <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> |
| <dd><p class="first">The following conditions can result in this error:</p> |
| <ul class="last simple"> |
| <li><code class="docutils literal"><span class="pre">alg</span></code> is not supported or is not a MAC algorithm.</li> |
| <li><code class="docutils literal"><span class="pre">key</span></code> is not supported for use with <code class="docutils literal"><span class="pre">alg</span></code>.</li> |
| </ul> |
| </dd> |
| <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> |
| <dd></dd> |
| <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> |
| <dd></dd> |
| <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> |
| <dd></dd> |
| <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> |
| <dd></dd> |
| <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> |
| <dd></dd> |
| <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> |
| <dd></dd> |
| </dl> |
| <p class="rubric">Description</p> |
| <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> |
| <p>The sequence of operations to calculate a MAC is as follows:</p> |
| <ol class="arabic simple"> |
| <li>Allocate an operation object which will be passed to all the functions listed here.</li> |
| <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> |
| <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> |
| <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> |
| <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> |
| </ol> |
| <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> |
| <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> |
| <ul class="simple"> |
| <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> |
| <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> |
| </ul> |
| </div> |
| <div class="section" id="psa_mac_verify_setup"> |
| <span id="c.psa_mac_verify_setup"></span><h3><code class="docutils literal"><span class="pre">psa_mac_verify_setup</span></code> (function)</h3> |
| <p>Set up a multi-part MAC verification operation.</p> |
| <pre class="literal-block"> |
| <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_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, |
| <a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key, |
| <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg); |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">operation</span></code></dt> |
| <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> |
| <dt> <code class="docutils literal"><span class="pre">key</span></code></dt> |
| <dd>Identifier of the key to use for the operation. It must remain valid until the operation terminates. |
| It 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> |
| <dt> <code class="docutils literal"><span class="pre">alg</span></code></dt> |
| <dd>The MAC algorithm to compute: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a> such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_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> |
| </dl> |
| <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> |
| <dl class="docutils"> |
| <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> |
| <dd>Success.</dd> |
| <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> |
| <dd><p class="first">The following conditions can result in this error:</p> |
| <ul class="last simple"> |
| <li>The operation state is not valid: it must be inactive.</li> |
| <li>The library requires initializing by a call to <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_crypto_init()</span></code></a>.</li> |
| </ul> |
| </dd> |
| <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> |
| <dd><code class="docutils literal"><span class="pre">key</span></code> is not a valid key identifier.</dd> |
| <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> |
| <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> |
| <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> |
| <dd><p class="first">The following conditions can result in this error:</p> |
| <ul class="last simple"> |
| <li><code class="docutils literal"><span class="pre">alg</span></code> is not a MAC algorithm.</li> |
| <li><code class="docutils literal"><span class="pre">key</span></code> is not compatible with <code class="docutils literal"><span class="pre">alg</span></code>.</li> |
| </ul> |
| </dd> |
| <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> |
| <dd><p class="first">The following conditions can result in this error:</p> |
| <ul class="last simple"> |
| <li><code class="docutils literal"><span class="pre">alg</span></code> is not supported or is not a MAC algorithm.</li> |
| <li><code class="docutils literal"><span class="pre">key</span></code> is not supported for use with <code class="docutils literal"><span class="pre">alg</span></code>.</li> |
| </ul> |
| </dd> |
| <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> |
| <dd></dd> |
| <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> |
| <dd></dd> |
| <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> |
| <dd></dd> |
| <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> |
| <dd></dd> |
| <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> |
| <dd></dd> |
| <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> |
| <dd></dd> |
| </dl> |
| <p class="rubric">Description</p> |
| <p>This function sets up the verification of the message authentication code (MAC) of a byte string against an expected value.</p> |
| <p>The sequence of operations to verify a MAC is as follows:</p> |
| <ol class="arabic simple"> |
| <li>Allocate an operation object which will be passed to all the functions listed here.</li> |
| <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> |
| <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> |
| <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> |
| <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> |
| </ol> |
| <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> |
| <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> |
| <ul class="simple"> |
| <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> |
| <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> |
| </ul> |
| </div> |
| <div class="section" id="psa_mac_update"> |
| <span id="c.psa_mac_update"></span><h3><code class="docutils literal"><span class="pre">psa_mac_update</span></code> (function)</h3> |
| <p>Add a message fragment to a multi-part MAC operation.</p> |
| <pre class="literal-block"> |
| <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_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, |
| const uint8_t * input, |
| size_t input_length); |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">operation</span></code></dt> |
| <dd>Active MAC operation.</dd> |
| <dt> <code class="docutils literal"><span class="pre">input</span></code></dt> |
| <dd>Buffer containing the message fragment to add to the MAC calculation.</dd> |
| <dt> <code class="docutils literal"><span class="pre">input_length</span></code></dt> |
| <dd>Size of the <code class="docutils literal"><span class="pre">input</span></code> buffer in bytes.</dd> |
| </dl> |
| <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> |
| <dl class="docutils"> |
| <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> |
| <dd>Success.</dd> |
| <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> |
| <dd><p class="first">The following conditions can result in this error:</p> |
| <ul class="last simple"> |
| <li>The operation state is not valid: it must be active.</li> |
| <li>The library requires initializing by a call to <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_crypto_init()</span></code></a>.</li> |
| </ul> |
| </dd> |
| <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> |
| <dd>The total input for the operation is too large for the MAC algorithm.</dd> |
| <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> |
| <dd>The total input for the operation is too large for the implementation.</dd> |
| <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> |
| <dd></dd> |
| <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> |
| <dd></dd> |
| <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> |
| <dd></dd> |
| <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> |
| <dd></dd> |
| <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> |
| <dd></dd> |
| <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> |
| <dd></dd> |
| </dl> |
| <p class="rubric">Description</p> |
| <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> |
| <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> |
| </div> |
| <div class="section" id="psa_mac_sign_finish"> |
| <span id="c.psa_mac_sign_finish"></span><h3><code class="docutils literal"><span class="pre">psa_mac_sign_finish</span></code> (function)</h3> |
| <p>Finish the calculation of the MAC of a message.</p> |
| <pre class="literal-block"> |
| <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_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, |
| uint8_t * mac, |
| size_t mac_size, |
| size_t * mac_length); |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">operation</span></code></dt> |
| <dd>Active MAC operation.</dd> |
| <dt> <code class="docutils literal"><span class="pre">mac</span></code></dt> |
| <dd>Buffer where the MAC value is to be written.</dd> |
| <dt> <code class="docutils literal"><span class="pre">mac_size</span></code></dt> |
| <dd><p class="first">Size of the <code class="docutils literal"><span class="pre">mac</span></code> buffer in bytes. |
| This must be appropriate for the selected algorithm and key:</p> |
| <ul class="last simple"> |
| <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> |
| <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> |
| </ul> |
| </dd> |
| <dt> <code class="docutils literal"><span class="pre">mac_length</span></code></dt> |
| <dd>On success, the number of bytes that make up the MAC value. |
| This is always <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.</dd> |
| </dl> |
| <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> |
| <dl class="docutils"> |
| <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> |
| <dd>Success. |
| The first <code class="docutils literal"><span class="pre">(*mac_length)</span></code> bytes of <code class="docutils literal"><span class="pre">mac</span></code> contain the MAC value.</dd> |
| <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> |
| <dd><p class="first">The following conditions can result in this error:</p> |
| <ul class="last simple"> |
| <li>The operation state is not valid: it must be an active mac sign operation.</li> |
| <li>The library requires initializing by a call to <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_crypto_init()</span></code></a>.</li> |
| </ul> |
| </dd> |
| <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> |
| <dd>The size of the <code class="docutils literal"><span class="pre">mac</span></code> buffer is too small. |
| <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 a sufficient buffer size.</dd> |
| <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> |
| <dd></dd> |
| <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> |
| <dd></dd> |
| <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> |
| <dd></dd> |
| <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> |
| <dd></dd> |
| <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> |
| <dd></dd> |
| <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> |
| <dd></dd> |
| </dl> |
| <p class="rubric">Description</p> |
| <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> |
| <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> |
| <div class="admonition warning"> |
| <p class="first admonition-title">Warning</p> |
| <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> |
| <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> |
| </div> |
| </div> |
| <div class="section" id="psa_mac_verify_finish"> |
| <span id="c.psa_mac_verify_finish"></span><h3><code class="docutils literal"><span class="pre">psa_mac_verify_finish</span></code> (function)</h3> |
| <p>Finish the calculation of the MAC of a message and compare it with an expected value.</p> |
| <pre class="literal-block"> |
| <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_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, |
| const uint8_t * mac, |
| size_t mac_length); |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">operation</span></code></dt> |
| <dd>Active MAC operation.</dd> |
| <dt> <code class="docutils literal"><span class="pre">mac</span></code></dt> |
| <dd>Buffer containing the expected MAC value.</dd> |
| <dt> <code class="docutils literal"><span class="pre">mac_length</span></code></dt> |
| <dd>Size of the <code class="docutils literal"><span class="pre">mac</span></code> buffer in bytes.</dd> |
| </dl> |
| <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> |
| <dl class="docutils"> |
| <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> |
| <dd>Success. |
| The expected MAC is identical to the actual MAC of the message.</dd> |
| <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> |
| <dd><p class="first">The following conditions can result in this error:</p> |
| <ul class="last simple"> |
| <li>The operation state is not valid: it must be an active mac verify operation.</li> |
| <li>The library requires initializing by a call to <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_crypto_init()</span></code></a>.</li> |
| </ul> |
| </dd> |
| <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> |
| <dd>The calculated MAC of the message does not match the value in <code class="docutils literal"><span class="pre">mac</span></code>.</dd> |
| <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> |
| <dd></dd> |
| <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> |
| <dd></dd> |
| <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> |
| <dd></dd> |
| <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> |
| <dd></dd> |
| <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> |
| <dd></dd> |
| <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> |
| <dd></dd> |
| </dl> |
| <p class="rubric">Description</p> |
| <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> |
| <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> |
| <div class="admonition note"> |
| <p class="first admonition-title">Note</p> |
| <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> |
| </div> |
| </div> |
| <div class="section" id="psa_mac_abort"> |
| <span id="c.psa_mac_abort"></span><h3><code class="docutils literal"><span class="pre">psa_mac_abort</span></code> (function)</h3> |
| <p>Abort a MAC operation.</p> |
| <pre class="literal-block"> |
| <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_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); |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">operation</span></code></dt> |
| <dd>Initialized MAC operation.</dd> |
| </dl> |
| <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> |
| <dl class="docutils"> |
| <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> |
| <dd>Success. |
| The operation object can now be discarded or reused.</dd> |
| <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> |
| <dd>The library requires initializing by a call to <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_crypto_init()</span></code></a>.</dd> |
| <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> |
| <dd></dd> |
| <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> |
| <dd></dd> |
| </dl> |
| <p class="rubric">Description</p> |
| <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> |
| <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> |
| <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> |
| </div> |
| </div> |
| <div class="section" id="support-macros"> |
| <h2>10.3.4. Support macros</h2> |
| <div class="section" id="PSA_ALG_IS_HMAC"> |
| <span id="c.PSA_ALG_IS_HMAC"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_HMAC</span></code> (macro)</h3> |
| <p>Whether the specified algorithm is an HMAC algorithm.</p> |
| <pre class="literal-block"> |
| #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> |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">alg</span></code></dt> |
| <dd>An algorithm identifier: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>.</dd> |
| </dl> |
| <p class="rubric">Returns</p> |
| <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> |
| <p class="rubric">Description</p> |
| <p>HMAC is a family of MAC algorithms that are based on a hash function.</p> |
| </div> |
| <div class="section" id="PSA_ALG_IS_BLOCK_CIPHER_MAC"> |
| <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> |
| <p>Whether the specified algorithm is a MAC algorithm based on a block cipher.</p> |
| <pre class="literal-block"> |
| #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> |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">alg</span></code></dt> |
| <dd>An algorithm identifier: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>.</dd> |
| </dl> |
| <p class="rubric">Returns</p> |
| <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> |
| </div> |
| <div class="section" id="PSA_MAC_LENGTH"> |
| <span id="c.PSA_MAC_LENGTH"></span><h3><code class="docutils literal"><span class="pre">PSA_MAC_LENGTH</span></code> (macro)</h3> |
| <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> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_MAC_LENGTH" title="PSA_MAC_LENGTH">PSA_MAC_LENGTH</a>(key_type, key_bits, alg) \ |
| <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em> |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">key_type</span></code></dt> |
| <dd>The type of the MAC key.</dd> |
| <dt> <code class="docutils literal"><span class="pre">key_bits</span></code></dt> |
| <dd>The size of the MAC key in bits.</dd> |
| <dt> <code class="docutils literal"><span class="pre">alg</span></code></dt> |
| <dd>A MAC algorithm: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a> such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_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> |
| </dl> |
| <p class="rubric">Returns</p> |
| <p>The MAC length for the specified algorithm with the specified key parameters.</p> |
| <p><code class="docutils literal"><span class="pre">0</span></code> if the MAC algorithm is not recognized.</p> |
| <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> |
| <p>Unspecified if the key parameters are not consistent with the algorithm.</p> |
| <p class="rubric">Description</p> |
| <p>If the size of the MAC buffer is at least this large, it is guaranteed that <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> will not fail due to an insufficient buffer size.</p> |
| <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> expect.</p> |
| <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> |
| </div> |
| <div class="section" id="PSA_MAC_MAX_SIZE"> |
| <span id="c.PSA_MAC_MAX_SIZE"></span><h3><code class="docutils literal"><span class="pre">PSA_MAC_MAX_SIZE</span></code> (macro)</h3> |
| <p>A sufficient buffer size for storing the MAC output by <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>, for any of the supported key types and MAC algorithms.</p> |
| <pre class="literal-block"> |
| #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> |
| </pre> |
| <p>If the size of the MAC buffer is at least this large, it is guaranteed 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> will not fail due to an insufficient buffer size.</p> |
| <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> |
| </div> |
| </div> |
| </div> |
| |
| |
| </div> |
| </div> |
| </div> |
| <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> |
| <div class="sphinxsidebarwrapper"><h3><a href="../../index.html"><b>PSA Crypto API</b></a></h3> |
| IHI 0086<br/> |
| Non-confidential<br/> |
| Version 1.1.0 |
| <span style="color: red; font-weight: bold;"></span> |
| <ul> |
| <li class="toctree-l1"><a class="reference internal" href="../../about.html">About this document</a></li> |
| </ul> |
| <ul class="current"> |
| <li class="toctree-l1"><a class="reference internal" href="../../overview/intro.html">1. Introduction</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../overview/goals.html">2. Design goals</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../overview/functionality.html">3. Functionality overview</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../overview/sample-arch.html">4. Sample architectures</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../overview/conventions.html">5. Library conventions</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../overview/implementation.html">6. Implementation considerations</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../overview/usage.html">7. Usage considerations</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../library/index.html">8. Library management reference</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../keys/index.html">9. Key management reference</a></li> |
| <li class="toctree-l1 current"><a class="reference internal" href="index.html">10. Cryptographic operation reference</a><ul class="current"> |
| <li class="toctree-l2"><a class="reference internal" href="algorithms.html">10.1. Algorithms</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="hashes.html">10.2. Message digests (Hashes)</a></li> |
| <li class="toctree-l2 current"><a class="current reference internal" href="#">10.3. Message authentication codes (MAC)</a><ul> |
| <li class="toctree-l3"><a class="reference internal" href="#mac-algorithms">10.3.1. MAC algorithms</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#single-part-mac-functions">10.3.2. Single-part MAC functions</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#multi-part-mac-operations">10.3.3. Multi-part MAC operations</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#support-macros">10.3.4. Support macros</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l2"><a class="reference internal" href="ciphers.html">10.4. Unauthenticated ciphers</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="aead.html">10.5. Authenticated encryption with associated data (AEAD)</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="kdf.html">10.6. Key derivation</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="sign.html">10.7. Asymmetric signature</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="pke.html">10.8. Asymmetric encryption</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="ka.html">10.9. Key agreement</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="rng.html">10.10. Other cryptographic services</a></li> |
| </ul> |
| </li> |
| </ul> |
| <ul> |
| <li class="toctree-l1"><a class="reference internal" href="../../appendix/example_header.html">Example header file</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../appendix/encodings.html">Algorithm and key type encoding</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../appendix/specdef_values.html">Example macro implementations</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../appendix/sra.html">Security Risk Assessment</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../appendix/history.html">Changes to the API</a></li> |
| </ul> |
| <ul> |
| <li class="toctree-l1"><a class="reference internal" href="../../psa_c-identifiers.html">Index of API elements</a></li> |
| </ul> |
| <div id="searchbox" style="display: none" role="search"> |
| <h3>Quick search</h3> |
| <form class="search" action="../../search.html" method="get"> |
| <div><input type="text" name="q" /></div> |
| <div><input type="submit" value="Go" /></div> |
| <input type="hidden" name="check_keywords" value="yes" /> |
| <input type="hidden" name="area" value="default" /> |
| </form> |
| </div> |
| <script type="text/javascript">$('#searchbox').show(0);</script> |
| </div> |
| </div> |
| <div class="clearer"></div> |
| </div> |
| <div class="footer"> |
| © 2018-2022, Arm Limited or its affiliates. All rights reserved. |
| |
| | |
| Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a> |
| & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a> |
| |
| </div> |
| |
| |
| |
| |
| </body> |
| </html> |