| |
| <!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.5. Authenticated encryption with associated data (AEAD) — 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.6. Key derivation" href="kdf.html" /> |
| <link rel="prev" title="10.4. Unauthenticated ciphers" href="ciphers.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="authenticated-encryption-with-associated-data-aead"> |
| <span id="aead"></span><h1>10.5. Authenticated encryption with associated data (AEAD)</h1> |
| <p>The single-part AEAD functions are:</p> |
| <ul class="simple"> |
| <li><a class="reference internal" href="#c.psa_aead_encrypt" title="psa_aead_encrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_encrypt()</span></code></a> to encrypt a message using an authenticated symmetric cipher.</li> |
| <li><a class="reference internal" href="#c.psa_aead_decrypt" title="psa_aead_decrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_decrypt()</span></code></a> to decrypt a message using an authenticated symmetric cipher.</li> |
| </ul> |
| <p>These functions follow the interface recommended by <span><em>An Interface and Algorithms for Authenticated Encryption</em> <a class="reference internal" href="../../about.html#citation-rfc5116"><span class="cite">[RFC5116]</span></a></span>.</p> |
| <p>The encryption function requires a nonce to be provided. To generate a random nonce, either call <a class="reference internal" href="rng.html#c.psa_generate_random" title="psa_generate_random"><code class="xref any c c-func docutils literal"><span class="pre">psa_generate_random()</span></code></a> or use the AEAD multi-part API.</p> |
| <p>The <a class="reference internal" href="#c.psa_aead_operation_t" title="psa_aead_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_aead_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> permits alternative initialization parameters and allows messages to be processed in fragments. A multi-part AEAD operation is used as follows:</p> |
| <ol class="arabic simple"> |
| <li>Initialize the <a class="reference internal" href="#c.psa_aead_operation_t" title="psa_aead_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_aead_operation_t</span></code></a> object to zero, or by assigning the value of the associated macro <a class="reference internal" href="#c.PSA_AEAD_OPERATION_INIT" title="PSA_AEAD_OPERATION_INIT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_OPERATION_INIT</span></code></a>.</li> |
| <li>Call <a class="reference internal" href="#c.psa_aead_encrypt_setup" title="psa_aead_encrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_encrypt_setup()</span></code></a> or <a class="reference internal" href="#c.psa_aead_decrypt_setup" title="psa_aead_decrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_decrypt_setup()</span></code></a> to specify the algorithm and key.</li> |
| <li>Provide additional parameters:<ul> |
| <li>If the algorithm requires it, call <a class="reference internal" href="#c.psa_aead_set_lengths" title="psa_aead_set_lengths"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_set_lengths()</span></code></a> to specify the length of the non-encrypted and encrypted inputs to the operation.</li> |
| <li>When encrypting, call either <a class="reference internal" href="#c.psa_aead_generate_nonce" title="psa_aead_generate_nonce"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_generate_nonce()</span></code></a> or <a class="reference internal" href="#c.psa_aead_set_nonce" title="psa_aead_set_nonce"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_set_nonce()</span></code></a> to generate or set the nonce.</li> |
| <li>When decrypting, call <a class="reference internal" href="#c.psa_aead_set_nonce" title="psa_aead_set_nonce"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_set_nonce()</span></code></a> to set the nonce.</li> |
| </ul> |
| </li> |
| <li>Call <a class="reference internal" href="#c.psa_aead_update_ad" title="psa_aead_update_ad"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_update_ad()</span></code></a> zero or more times with fragments of the non-encrypted additional data.</li> |
| <li>Call <a class="reference internal" href="#c.psa_aead_update" title="psa_aead_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_update()</span></code></a> zero or more times with fragments of the plaintext or ciphertext to encrypt or decrypt.</li> |
| <li>At the end of the message, call the required finishing function:<ul> |
| <li>To complete an encryption operation, call <a class="reference internal" href="#c.psa_aead_finish" title="psa_aead_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_finish()</span></code></a> to compute and return authentication tag.</li> |
| <li>To complete a decryption operation, call <a class="reference internal" href="#c.psa_aead_verify" title="psa_aead_verify"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_verify()</span></code></a> to compute the authentication tag and verify it against a reference value.</li> |
| </ul> |
| </li> |
| </ol> |
| <p>To abort the operation or recover from an error, call <a class="reference internal" href="#c.psa_aead_abort" title="psa_aead_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_abort()</span></code></a>.</p> |
| <div class="admonition note"> |
| <p class="first admonition-title">Note</p> |
| <p>Using a multi-part interface to authenticated encryption raises specific issues.</p> |
| <ul class="last simple"> |
| <li>Multi-part authenticated decryption produces intermediate results that are not authenticated. Revealing unauthenticated results, either directly or indirectly through the application’s behavior, can compromise the confidentiality of all inputs that are encrypted with the same key. See the <a class="reference internal" href="#aead-multi-part-warning"><span class="std std-ref">detailed warning</span></a>.</li> |
| <li>For encryption, some common algorithms cannot be processed in a streaming fashion. For SIV mode, the whole plaintext must be known before the encryption can start; the multi-part AEAD API is not meant to be usable with SIV mode. For CCM mode, the length of the plaintext must be known before the encryption can start; the application can call the function <a class="reference internal" href="#c.psa_aead_set_lengths" title="psa_aead_set_lengths"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_set_lengths()</span></code></a> to provide these lengths before providing input.</li> |
| </ul> |
| </div> |
| <div class="section" id="aead-algorithms"> |
| <span id="id1"></span><h2>10.5.1. AEAD algorithms</h2> |
| <div class="section" id="PSA_ALG_CCM"> |
| <span id="c.PSA_ALG_CCM"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_CCM</span></code> (macro)</h3> |
| <p>The <em>Counter with CBC-MAC</em> (CCM) authenticated encryption algorithm.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_ALG_CCM" title="PSA_ALG_CCM">PSA_ALG_CCM</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x05500100) |
| </pre> |
| <p>CCM is defined for block ciphers that have a 128-bit block size. The underlying block cipher is determined by the key type.</p> |
| <p>To use <a class="reference internal" href="#c.PSA_ALG_CCM" title="PSA_ALG_CCM"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_CCM</span></code></a> with a multi-part AEAD operation, the application must call <a class="reference internal" href="#c.psa_aead_set_lengths" title="psa_aead_set_lengths"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_set_lengths()</span></code></a> before providing the nonce, the additional data and plaintext to the operation.</p> |
| <p>CCM requires a nonce of between 7 and 13 bytes in length. The length of the nonce affects the maximum length of the plaintext than can be encrypted or decrypted. If the nonce has length <em>N</em>, then the plaintext length <em>pLen</em> is encoded in <em>L</em> = 15 - <em>N</em> octets, this requires that <em>pLen</em> < 2<sup>8L</sup>.</p> |
| <p>The value for <em>L</em> that is used with <a class="reference internal" href="#c.PSA_ALG_CCM" title="PSA_ALG_CCM"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_CCM</span></code></a> depends on the function used to provide the nonce:</p> |
| <ul class="simple"> |
| <li>A call to <a class="reference internal" href="#c.psa_aead_encrypt" title="psa_aead_encrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_encrypt()</span></code></a>, <a class="reference internal" href="#c.psa_aead_decrypt" title="psa_aead_decrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_decrypt()</span></code></a>, or <a class="reference internal" href="#c.psa_aead_set_nonce" title="psa_aead_set_nonce"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_set_nonce()</span></code></a> will set <em>L</em> to 15 - <code class="docutils literal"><span class="pre">nonce_length</span></code>. If the plaintext length cannot be encoded in <em>L</em> octets, then a <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a> error is returned.</li> |
| <li>A call to <a class="reference internal" href="#c.psa_aead_generate_nonce" title="psa_aead_generate_nonce"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_generate_nonce()</span></code></a> on a multi-part cipher operation will select <em>L</em> as the smallest integer >= 2 where <em>pLen</em> < 2<sup>8L</sup>, with <em>pLen</em> being the <code class="docutils literal"><span class="pre">plaintext_length</span></code> provided to <a class="reference internal" href="#c.psa_aead_set_lengths" title="psa_aead_set_lengths"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_set_lengths()</span></code></a>. The call to <a class="reference internal" href="#c.psa_aead_generate_nonce" title="psa_aead_generate_nonce"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_generate_nonce()</span></code></a> will generate and return a random nonce of length 15 - <em>L</em> bytes.</li> |
| </ul> |
| <p>CCM supports authentication tag sizes of 4, 6, 8, 10, 12, 14, and 16 bytes. The default tag length is 16. Shortened tag lengths can be requested using <a class="reference internal" href="#c.PSA_ALG_AEAD_WITH_SHORTENED_TAG" title="PSA_ALG_AEAD_WITH_SHORTENED_TAG"><code class="docutils literal"><span class="pre">PSA_ALG_AEAD_WITH_SHORTENED_TAG</span></code></a><code class="docutils literal"><span class="pre">(</span></code><a class="reference internal" href="#c.PSA_ALG_CCM" title="PSA_ALG_CCM"><code class="docutils literal"><span class="pre">PSA_ALG_CCM</span></code></a><code class="docutils literal"><span class="pre">,</span> </code><code class="docutils literal"><span class="pre">tag_length</span></code><code class="docutils literal"><span class="pre">)</span></code>, where <code class="docutils literal"><span class="pre">tag_length</span></code> is a valid CCM tag length.</p> |
| <p>The CCM block cipher mode is defined in <span><em>Counter with CBC-MAC (CCM)</em> <a class="reference internal" href="../../about.html#citation-rfc3610"><span class="cite">[RFC3610]</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_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_GCM"> |
| <span id="c.PSA_ALG_GCM"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_GCM</span></code> (macro)</h3> |
| <p>The <em>Galois/Counter Mode</em> (GCM) authenticated encryption algorithm.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_ALG_GCM" title="PSA_ALG_GCM">PSA_ALG_GCM</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x05500200) |
| </pre> |
| <p>GCM is defined for block ciphers that have a 128-bit block size. The underlying block cipher is determined by the key type.</p> |
| <p>GCM requires a nonce of at least 1 byte in length. The maximum supported nonce size is <a class="reference internal" href="../../about.html#term-implementation-defined"><span class="scterm">implementation defined</span></a>. Calling <a class="reference internal" href="#c.psa_aead_generate_nonce" title="psa_aead_generate_nonce"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_generate_nonce()</span></code></a> will generate a random 12-byte nonce.</p> |
| <p>GCM supports authentication tag sizes of 4, 8, 12, 13, 14, 15, and 16 bytes. The default tag length is 16. Shortened tag lengths can be requested using <a class="reference internal" href="#c.PSA_ALG_AEAD_WITH_SHORTENED_TAG" title="PSA_ALG_AEAD_WITH_SHORTENED_TAG"><code class="docutils literal"><span class="pre">PSA_ALG_AEAD_WITH_SHORTENED_TAG</span></code></a><code class="docutils literal"><span class="pre">(</span></code><a class="reference internal" href="#c.PSA_ALG_GCM" title="PSA_ALG_GCM"><code class="docutils literal"><span class="pre">PSA_ALG_GCM</span></code></a><code class="docutils literal"><span class="pre">,</span> </code><code class="docutils literal"><span class="pre">tag_length</span></code><code class="docutils literal"><span class="pre">)</span></code>, where <code class="docutils literal"><span class="pre">tag_length</span></code> is a valid GCM tag length.</p> |
| <p>The GCM block cipher mode is defined in <span><em>NIST Special Publication 800-38D: Recommendation for Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC</em> <a class="reference internal" href="../../about.html#citation-sp800-38d"><span class="cite">[SP800-38D]</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_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_CHACHA20_POLY1305"> |
| <span id="c.PSA_ALG_CHACHA20_POLY1305"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_CHACHA20_POLY1305</span></code> (macro)</h3> |
| <p>The ChaCha20-Poly1305 AEAD algorithm.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_ALG_CHACHA20_POLY1305" title="PSA_ALG_CHACHA20_POLY1305">PSA_ALG_CHACHA20_POLY1305</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x05100500) |
| </pre> |
| <p>There are two defined variants of ChaCha20-Poly1305:</p> |
| <ul class="simple"> |
| <li>An implementation that supports ChaCha20-Poly1305 must support the variant defined by <span><em>ChaCha20 and Poly1305 for IETF Protocols</em> <a class="reference internal" href="../../about.html#citation-rfc7539"><span class="cite">[RFC7539]</span></a></span>, which has a 96-bit nonce and 32-bit counter.</li> |
| <li>An implementation can optionally also support the original variant defined by <span><em>ChaCha, a variant of Salsa20</em> <a class="reference internal" href="../../about.html#citation-chacha20"><span class="cite">[CHACHA20]</span></a></span>, which has a 64-bit nonce and 64-bit counter.</li> |
| </ul> |
| <p>The variant used for the AEAD encryption or decryption operation, depends on the nonce provided for an AEAD operation using <a class="reference internal" href="#c.PSA_ALG_CHACHA20_POLY1305" title="PSA_ALG_CHACHA20_POLY1305"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_CHACHA20_POLY1305</span></code></a>:</p> |
| <ul class="simple"> |
| <li>A nonce provided in a call to <a class="reference internal" href="#c.psa_aead_encrypt" title="psa_aead_encrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_encrypt()</span></code></a>, <a class="reference internal" href="#c.psa_aead_decrypt" title="psa_aead_decrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_decrypt()</span></code></a> or <a class="reference internal" href="#c.psa_aead_set_nonce" title="psa_aead_set_nonce"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_set_nonce()</span></code></a> must be 8 or 12 bytes. The size of nonce will select the appropriate variant of the algorithm.</li> |
| <li>A nonce generated by a call to <a class="reference internal" href="#c.psa_aead_generate_nonce" title="psa_aead_generate_nonce"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_generate_nonce()</span></code></a> will be 12 bytes, and will use the <a class="reference internal" href="../../about.html#citation-rfc7539"><span class="cite">[RFC7539]</span></a> variant.</li> |
| </ul> |
| <p>Implementations must support 16-byte tags. It is recommended that truncated tag sizes are rejected.</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_CHACHA20" title="PSA_KEY_TYPE_CHACHA20"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_CHACHA20</span></code></a></div> |
| </div> |
| </div> |
| <div class="section" id="PSA_ALG_AEAD_WITH_SHORTENED_TAG"> |
| <span id="c.PSA_ALG_AEAD_WITH_SHORTENED_TAG"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_AEAD_WITH_SHORTENED_TAG</span></code> (macro)</h3> |
| <p>Macro to build a AEAD algorithm with a shortened tag.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_ALG_AEAD_WITH_SHORTENED_TAG" title="PSA_ALG_AEAD_WITH_SHORTENED_TAG">PSA_ALG_AEAD_WITH_SHORTENED_TAG</a>(aead_alg, tag_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">aead_alg</span></code></dt> |
| <dd>An AEAD 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_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">aead_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true.</dd> |
| <dt> <code class="docutils literal"><span class="pre">tag_length</span></code></dt> |
| <dd>Desired length of the authentication tag in bytes.</dd> |
| </dl> |
| <p class="rubric">Returns</p> |
| <p>The corresponding AEAD algorithm with the specified tag length.</p> |
| <p>Unspecified if <code class="docutils literal"><span class="pre">aead_alg</span></code> is not a supported AEAD algorithm or if <code class="docutils literal"><span class="pre">tag_length</span></code> is not valid for the specified AEAD algorithm.</p> |
| <p class="rubric">Description</p> |
| <p>An AEAD algorithm with a shortened tag is similar to the corresponding AEAD algorithm, but has an authentication tag that consists of fewer bytes. Depending on the algorithm, the tag length might affect the calculation of the ciphertext.</p> |
| <p>The AEAD algorithm with a default length tag can be recovered using <a class="reference internal" href="#c.PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG" title="PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG()</span></code></a>.</p> |
| <p class="rubric">Compatible key types</p> |
| <p>The resulting AEAD algorithm is compatible with the same key types as the AEAD algorithm used to construct it.</p> |
| </div> |
| <div class="section" id="PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG"> |
| <span id="c.PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG</span></code> (macro)</h3> |
| <p>An AEAD algorithm with the default tag length.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG" title="PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG">PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG</a>(aead_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">aead_alg</span></code></dt> |
| <dd>An AEAD 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_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">aead_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true.</dd> |
| </dl> |
| <p class="rubric">Returns</p> |
| <p>The corresponding AEAD algorithm with the default tag length for that algorithm.</p> |
| <p class="rubric">Description</p> |
| <p>This macro can be used to construct the AEAD algorithm with default tag length from an AEAD algorithm with a shortened tag. See also <a class="reference internal" href="#c.PSA_ALG_AEAD_WITH_SHORTENED_TAG" title="PSA_ALG_AEAD_WITH_SHORTENED_TAG"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_AEAD_WITH_SHORTENED_TAG()</span></code></a>.</p> |
| <p class="rubric">Compatible key types</p> |
| <p>The resulting AEAD algorithm is compatible with the same key types as the AEAD algorithm used to construct it.</p> |
| </div> |
| <div class="section" id="PSA_ALG_AEAD_WITH_AT_LEAST_THIS_LENGTH_TAG"> |
| <span id="c.PSA_ALG_AEAD_WITH_AT_LEAST_THIS_LENGTH_TAG"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_AEAD_WITH_AT_LEAST_THIS_LENGTH_TAG</span></code> (macro)</h3> |
| <p>Macro to build an AEAD minimum-tag-length wildcard algorithm.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_ALG_AEAD_WITH_AT_LEAST_THIS_LENGTH_TAG" title="PSA_ALG_AEAD_WITH_AT_LEAST_THIS_LENGTH_TAG">PSA_ALG_AEAD_WITH_AT_LEAST_THIS_LENGTH_TAG</a>(aead_alg, min_tag_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">aead_alg</span></code></dt> |
| <dd>An AEAD 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_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">aead_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true.</dd> |
| <dt> <code class="docutils literal"><span class="pre">min_tag_length</span></code></dt> |
| <dd>Desired minimum length of the authentication tag in bytes. This must be at least <code class="docutils literal"><span class="pre">1</span></code> and at most the largest allowed tag length of the algorithm.</dd> |
| </dl> |
| <p class="rubric">Returns</p> |
| <p>The corresponding AEAD wildcard algorithm with the specified minimum tag length.</p> |
| <p>Unspecified if <code class="docutils literal"><span class="pre">aead_alg</span></code> is not a supported AEAD algorithm or if <code class="docutils literal"><span class="pre">min_tag_length</span></code> is less than <code class="docutils literal"><span class="pre">1</span></code> or too large for the specified AEAD algorithm.</p> |
| <p class="rubric">Description</p> |
| <p>A key with a minimum-tag-length AEAD wildcard algorithm as permitted algorithm policy can be used with all AEAD algorithms sharing the same base algorithm, and where the tag length of the specific algorithm is equal to or larger then the minimum tag length specified by the wildcard algorithm.</p> |
| <div class="admonition note"> |
| <p class="first admonition-title">Note</p> |
| <p class="last">When setting the minimum required tag length to less than the smallest tag length allowed by the base algorithm, this effectively becomes an ‘any-tag-length-allowed’ policy for that base algorithm.</p> |
| </div> |
| <p>The AEAD algorithm with a default length tag can be recovered using <a class="reference internal" href="#c.PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG" title="PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG()</span></code></a>.</p> |
| <p class="rubric">Compatible key types</p> |
| <p>The resulting wildcard AEAD algorithm is compatible with the same key types as the AEAD algorithm used to construct it.</p> |
| </div> |
| </div> |
| <div class="section" id="single-part-aead-functions"> |
| <h2>10.5.2. Single-part AEAD functions</h2> |
| <div class="section" id="psa_aead_encrypt"> |
| <span id="c.psa_aead_encrypt"></span><h3><code class="docutils literal"><span class="pre">psa_aead_encrypt</span></code> (function)</h3> |
| <p>Process an authenticated encryption 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_aead_encrypt" title="psa_aead_encrypt">psa_aead_encrypt</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 * nonce, |
| size_t nonce_length, |
| const uint8_t * additional_data, |
| size_t additional_data_length, |
| const uint8_t * plaintext, |
| size_t plaintext_length, |
| uint8_t * ciphertext, |
| size_t ciphertext_size, |
| size_t * ciphertext_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_ENCRYPT" title="PSA_KEY_USAGE_ENCRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_ENCRYPT</span></code></a>.</dd> |
| <dt> <code class="docutils literal"><span class="pre">alg</span></code></dt> |
| <dd>The AEAD 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_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</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">nonce</span></code></dt> |
| <dd>Nonce or IV to use.</dd> |
| <dt> <code class="docutils literal"><span class="pre">nonce_length</span></code></dt> |
| <dd>Size of the <code class="docutils literal"><span class="pre">nonce</span></code> buffer in bytes. This must be appropriate for the selected algorithm. The default nonce size is <a class="reference internal" href="#c.PSA_AEAD_NONCE_LENGTH" title="PSA_AEAD_NONCE_LENGTH"><code class="docutils literal"><span class="pre">PSA_AEAD_NONCE_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">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">key_type</span></code> is the type of <code class="docutils literal"><span class="pre">key</span></code>.</dd> |
| <dt> <code class="docutils literal"><span class="pre">additional_data</span></code></dt> |
| <dd>Additional data that will be authenticated but not encrypted.</dd> |
| <dt> <code class="docutils literal"><span class="pre">additional_data_length</span></code></dt> |
| <dd>Size of <code class="docutils literal"><span class="pre">additional_data</span></code> in bytes.</dd> |
| <dt> <code class="docutils literal"><span class="pre">plaintext</span></code></dt> |
| <dd>Data that will be authenticated and encrypted.</dd> |
| <dt> <code class="docutils literal"><span class="pre">plaintext_length</span></code></dt> |
| <dd>Size of <code class="docutils literal"><span class="pre">plaintext</span></code> in bytes.</dd> |
| <dt> <code class="docutils literal"><span class="pre">ciphertext</span></code></dt> |
| <dd>Output buffer for the authenticated and encrypted data. The additional data is not part of this output. For algorithms where the encrypted data and the authentication tag are defined as separate outputs, the authentication tag is appended to the encrypted data.</dd> |
| <dt> <code class="docutils literal"><span class="pre">ciphertext_size</span></code></dt> |
| <dd><p class="first">Size of the <code class="docutils literal"><span class="pre">ciphertext</span></code> buffer in bytes. This must be appropriate for the selected algorithm and key:</p> |
| <ul class="last simple"> |
| <li>A sufficient output size is <a class="reference internal" href="#c.PSA_AEAD_ENCRYPT_OUTPUT_SIZE" title="PSA_AEAD_ENCRYPT_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_AEAD_ENCRYPT_OUTPUT_SIZE</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">alg</span></code><code class="docutils literal"><span class="pre">,</span> </code><code class="docutils literal"><span class="pre">plaintext_length</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">key_type</span></code> is the type of <code class="docutils literal"><span class="pre">key</span></code>.</li> |
| <li><a class="reference internal" href="#c.PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE" title="PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE"><code class="docutils literal"><span class="pre">PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">plaintext_length</span></code><code class="docutils literal"><span class="pre">)</span></code> evaluates to the maximum ciphertext size of any supported AEAD encryption.</li> |
| </ul> |
| </dd> |
| <dt> <code class="docutils literal"><span class="pre">ciphertext_length</span></code></dt> |
| <dd>On success, the size of the output in the <code class="docutils literal"><span class="pre">ciphertext</span></code> buffer.</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">(*ciphertext_length)</span></code> bytes of <code class="docutils literal"><span class="pre">ciphertext</span></code> contain the output.</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_ENCRYPT" title="PSA_KEY_USAGE_ENCRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_ENCRYPT</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">ciphertext</span></code> buffer is too small. <a class="reference internal" href="#c.PSA_AEAD_ENCRYPT_OUTPUT_SIZE" title="PSA_AEAD_ENCRYPT_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_ENCRYPT_OUTPUT_SIZE()</span></code></a> or <a class="reference internal" href="#c.PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE" title="PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_ENCRYPT_OUTPUT_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 an AEAD 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">nonce_length</span></code> is not valid for use with <code class="docutils literal"><span class="pre">alg</span></code> and <code class="docutils literal"><span class="pre">key</span></code>.</li> |
| <li><code class="docutils literal"><span class="pre">additional_data_length</span></code> or <code class="docutils literal"><span class="pre">plaintext_length</span></code> are 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 an AEAD 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">nonce_length</span></code> is not supported for use with <code class="docutils literal"><span class="pre">alg</span></code> and <code class="docutils literal"><span class="pre">key</span></code>.</li> |
| <li><code class="docutils literal"><span class="pre">additional_data_length</span></code> or <code class="docutils literal"><span class="pre">plaintext_length</span></code> are 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 class="section" id="psa_aead_decrypt"> |
| <span id="c.psa_aead_decrypt"></span><h3><code class="docutils literal"><span class="pre">psa_aead_decrypt</span></code> (function)</h3> |
| <p>Process an authenticated decryption 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_aead_decrypt" title="psa_aead_decrypt">psa_aead_decrypt</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 * nonce, |
| size_t nonce_length, |
| const uint8_t * additional_data, |
| size_t additional_data_length, |
| const uint8_t * ciphertext, |
| size_t ciphertext_length, |
| uint8_t * plaintext, |
| size_t plaintext_size, |
| size_t * plaintext_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_DECRYPT" title="PSA_KEY_USAGE_DECRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DECRYPT</span></code></a>.</dd> |
| <dt> <code class="docutils literal"><span class="pre">alg</span></code></dt> |
| <dd>The AEAD 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_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</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">nonce</span></code></dt> |
| <dd>Nonce or IV to use.</dd> |
| <dt> <code class="docutils literal"><span class="pre">nonce_length</span></code></dt> |
| <dd>Size of the <code class="docutils literal"><span class="pre">nonce</span></code> buffer in bytes. This must be appropriate for the selected algorithm. The default nonce size is <a class="reference internal" href="#c.PSA_AEAD_NONCE_LENGTH" title="PSA_AEAD_NONCE_LENGTH"><code class="docutils literal"><span class="pre">PSA_AEAD_NONCE_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">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">key_type</span></code> is the type of <code class="docutils literal"><span class="pre">key</span></code>.</dd> |
| <dt> <code class="docutils literal"><span class="pre">additional_data</span></code></dt> |
| <dd>Additional data that has been authenticated but not encrypted.</dd> |
| <dt> <code class="docutils literal"><span class="pre">additional_data_length</span></code></dt> |
| <dd>Size of <code class="docutils literal"><span class="pre">additional_data</span></code> in bytes.</dd> |
| <dt> <code class="docutils literal"><span class="pre">ciphertext</span></code></dt> |
| <dd>Data that has been authenticated and encrypted. For algorithms where the encrypted data and the authentication tag are defined as separate inputs, the buffer must contain the encrypted data followed by the authentication tag.</dd> |
| <dt> <code class="docutils literal"><span class="pre">ciphertext_length</span></code></dt> |
| <dd>Size of <code class="docutils literal"><span class="pre">ciphertext</span></code> in bytes.</dd> |
| <dt> <code class="docutils literal"><span class="pre">plaintext</span></code></dt> |
| <dd>Output buffer for the decrypted data.</dd> |
| <dt> <code class="docutils literal"><span class="pre">plaintext_size</span></code></dt> |
| <dd><p class="first">Size of the <code class="docutils literal"><span class="pre">plaintext</span></code> buffer in bytes. This must be appropriate for the selected algorithm and key:</p> |
| <ul class="last simple"> |
| <li>A sufficient output size is <a class="reference internal" href="#c.PSA_AEAD_DECRYPT_OUTPUT_SIZE" title="PSA_AEAD_DECRYPT_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_AEAD_DECRYPT_OUTPUT_SIZE</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">alg</span></code><code class="docutils literal"><span class="pre">,</span> </code><code class="docutils literal"><span class="pre">ciphertext_length</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">key_type</span></code> is the type of <code class="docutils literal"><span class="pre">key</span></code>.</li> |
| <li><a class="reference internal" href="#c.PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE" title="PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE"><code class="docutils literal"><span class="pre">PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">ciphertext_length</span></code><code class="docutils literal"><span class="pre">)</span></code> evaluates to the maximum plaintext size of any supported AEAD decryption.</li> |
| </ul> |
| </dd> |
| <dt> <code class="docutils literal"><span class="pre">plaintext_length</span></code></dt> |
| <dd>On success, the size of the output in the <code class="docutils literal"><span class="pre">plaintext</span></code> buffer.</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">(*plaintext_length)</span></code> bytes of <code class="docutils literal"><span class="pre">plaintext</span></code> contain the output.</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_DECRYPT" title="PSA_KEY_USAGE_DECRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DECRYPT</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 ciphertext is not authentic.</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">plaintext</span></code> buffer is too small. <a class="reference internal" href="#c.PSA_AEAD_DECRYPT_OUTPUT_SIZE" title="PSA_AEAD_DECRYPT_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_DECRYPT_OUTPUT_SIZE()</span></code></a> or <a class="reference internal" href="#c.PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE" title="PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_DECRYPT_OUTPUT_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 an AEAD 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">nonce_length</span></code> is not valid for use with <code class="docutils literal"><span class="pre">alg</span></code> and <code class="docutils literal"><span class="pre">key</span></code>.</li> |
| <li><code class="docutils literal"><span class="pre">additional_data_length</span></code> or <code class="docutils literal"><span class="pre">ciphertext_length</span></code> are 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 an AEAD 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">nonce_length</span></code> is not supported for use with <code class="docutils literal"><span class="pre">alg</span></code> and <code class="docutils literal"><span class="pre">key</span></code>.</li> |
| <li><code class="docutils literal"><span class="pre">additional_data_length</span></code> or <code class="docutils literal"><span class="pre">plaintext_length</span></code> are 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-aead-operations"> |
| <h2>10.5.3. Multi-part AEAD operations</h2> |
| <div class="admonition warning" id="aead-multi-part-warning"> |
| <p class="first admonition-title">Warning</p> |
| <p>When decrypting using a multi-part AEAD operation, there is no guarantee that the input or output is valid until <a class="reference internal" href="#c.psa_aead_verify" title="psa_aead_verify"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_verify()</span></code></a> has returned <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_SUCCESS</span></code></a>.</p> |
| <p>A call to <a class="reference internal" href="#c.psa_aead_update" title="psa_aead_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_update()</span></code></a> or <a class="reference internal" href="#c.psa_aead_update_ad" title="psa_aead_update_ad"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_update_ad()</span></code></a> returning <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_SUCCESS</span></code></a> <strong>does not</strong> indicate that the input and output is valid.</p> |
| <p>Until an application calls <a class="reference internal" href="#c.psa_aead_verify" title="psa_aead_verify"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_verify()</span></code></a> and it has returned <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_SUCCESS</span></code></a>, the following rules apply to input and output data from a multi-part AEAD operation:</p> |
| <ul class="simple"> |
| <li>Do not trust the input. If the application takes any action that depends on the input data, this action will need to be undone if the input turns out to be invalid.</li> |
| <li>Store the output in a confidential location. In particular, the application must not copy the output to a memory or storage space which is shared.</li> |
| <li>Do not trust the output. If the application takes any action that depends on the tentative decrypted data, this action will need to be undone if the input turns out to be invalid. Furthermore, if an adversary can observe that this action took place, for example, through timing, they might be able to use this fact as an oracle to decrypt any message encrypted with the same key.</li> |
| </ul> |
| <p class="last">An application that does not follow these rules might be vulnerable to maliciously constructed AEAD input data.</p> |
| </div> |
| <div class="section" id="psa_aead_operation_t"> |
| <span id="c.psa_aead_operation_t"></span><h3><code class="docutils literal"><span class="pre">psa_aead_operation_t</span></code> (type)</h3> |
| <p>The type of the state object for multi-part AEAD 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_aead_operation_t" title="psa_aead_operation_t">psa_aead_operation_t</a>; |
| </pre> |
| <p>Before calling any function on an AEAD 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_aead_operation_t" title="psa_aead_operation_t">psa_aead_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_aead_operation_t" title="psa_aead_operation_t">psa_aead_operation_t</a> operation; |
| </pre> |
| </li> |
| <li><p class="first">Initialize the object to the initializer <a class="reference internal" href="#c.PSA_AEAD_OPERATION_INIT" title="PSA_AEAD_OPERATION_INIT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_OPERATION_INIT</span></code></a>, for example:</p> |
| <pre class="literal-block"> |
| <a class="reference internal" href="#c.psa_aead_operation_t" title="psa_aead_operation_t">psa_aead_operation_t</a> operation = <a class="reference internal" href="#c.PSA_AEAD_OPERATION_INIT" title="PSA_AEAD_OPERATION_INIT">PSA_AEAD_OPERATION_INIT</a>; |
| </pre> |
| </li> |
| <li><p class="first">Assign the result of the function <a class="reference internal" href="#c.psa_aead_operation_init" title="psa_aead_operation_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_operation_init()</span></code></a> to the object, for example:</p> |
| <pre class="literal-block"> |
| <a class="reference internal" href="#c.psa_aead_operation_t" title="psa_aead_operation_t">psa_aead_operation_t</a> operation; |
| operation = <a class="reference internal" href="#c.psa_aead_operation_init" title="psa_aead_operation_init">psa_aead_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_AEAD_OPERATION_INIT"> |
| <span id="c.PSA_AEAD_OPERATION_INIT"></span><h3><code class="docutils literal"><span class="pre">PSA_AEAD_OPERATION_INIT</span></code> (macro)</h3> |
| <p>This macro returns a suitable initializer for an AEAD operation object of type <a class="reference internal" href="#c.psa_aead_operation_t" title="psa_aead_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_aead_operation_t</span></code></a>.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_AEAD_OPERATION_INIT" title="PSA_AEAD_OPERATION_INIT">PSA_AEAD_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_aead_operation_init"> |
| <span id="c.psa_aead_operation_init"></span><h3><code class="docutils literal"><span class="pre">psa_aead_operation_init</span></code> (function)</h3> |
| <p>Return an initial value for an AEAD operation object.</p> |
| <pre class="literal-block"> |
| <a class="reference internal" href="#c.psa_aead_operation_t" title="psa_aead_operation_t">psa_aead_operation_t</a> <a class="reference internal" href="#c.psa_aead_operation_init" title="psa_aead_operation_init">psa_aead_operation_init</a>(void); |
| </pre> |
| <p class="rubric">Returns: <a class="reference internal" href="#c.psa_aead_operation_t" title="psa_aead_operation_t"><code class="docutils literal"><span class="pre">psa_aead_operation_t</span></code></a></p> |
| </div> |
| <div class="section" id="psa_aead_encrypt_setup"> |
| <span id="c.psa_aead_encrypt_setup"></span><h3><code class="docutils literal"><span class="pre">psa_aead_encrypt_setup</span></code> (function)</h3> |
| <p>Set the key for a multi-part authenticated encryption 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_aead_encrypt_setup" title="psa_aead_encrypt_setup">psa_aead_encrypt_setup</a>(<a class="reference internal" href="#c.psa_aead_operation_t" title="psa_aead_operation_t">psa_aead_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_aead_operation_t" title="psa_aead_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_aead_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_ENCRYPT" title="PSA_KEY_USAGE_ENCRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_ENCRYPT</span></code></a>.</dd> |
| <dt> <code class="docutils literal"><span class="pre">alg</span></code></dt> |
| <dd>The AEAD 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_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</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_ENCRYPT" title="PSA_KEY_USAGE_ENCRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_ENCRYPT</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 an AEAD 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 an AEAD 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>The sequence of operations to encrypt a message with authentication 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_aead_operation_t" title="psa_aead_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_aead_operation_t</span></code></a>, e.g. <a class="reference internal" href="#c.PSA_AEAD_OPERATION_INIT" title="PSA_AEAD_OPERATION_INIT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_OPERATION_INIT</span></code></a>.</li> |
| <li>Call <a class="reference internal" href="#c.psa_aead_encrypt_setup" title="psa_aead_encrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_encrypt_setup()</span></code></a> to specify the algorithm and key.</li> |
| <li>If needed, call <a class="reference internal" href="#c.psa_aead_set_lengths" title="psa_aead_set_lengths"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_set_lengths()</span></code></a> to specify the length of the inputs to the subsequent calls to <a class="reference internal" href="#c.psa_aead_update_ad" title="psa_aead_update_ad"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_update_ad()</span></code></a> and <a class="reference internal" href="#c.psa_aead_update" title="psa_aead_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_update()</span></code></a>. See the documentation of <a class="reference internal" href="#c.psa_aead_set_lengths" title="psa_aead_set_lengths"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_set_lengths()</span></code></a> for details.</li> |
| <li>Call either <a class="reference internal" href="#c.psa_aead_generate_nonce" title="psa_aead_generate_nonce"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_generate_nonce()</span></code></a> or <a class="reference internal" href="#c.psa_aead_set_nonce" title="psa_aead_set_nonce"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_set_nonce()</span></code></a> to generate or set the nonce. It is recommended to use <a class="reference internal" href="#c.psa_aead_generate_nonce" title="psa_aead_generate_nonce"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_generate_nonce()</span></code></a> unless the protocol being implemented requires a specific nonce value.</li> |
| <li>Call <a class="reference internal" href="#c.psa_aead_update_ad" title="psa_aead_update_ad"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_update_ad()</span></code></a> zero, one or more times, passing a fragment of the non-encrypted additional authenticated data each time.</li> |
| <li>Call <a class="reference internal" href="#c.psa_aead_update" title="psa_aead_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_update()</span></code></a> zero, one or more times, passing a fragment of the message to encrypt each time.</li> |
| <li>Call <a class="reference internal" href="#c.psa_aead_finish" title="psa_aead_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_finish()</span></code></a>.</li> |
| </ol> |
| <p>If an error occurs at any step after a call to <a class="reference internal" href="#c.psa_aead_encrypt_setup" title="psa_aead_encrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_encrypt_setup()</span></code></a>, the operation will need to be reset by a call to <a class="reference internal" href="#c.psa_aead_abort" title="psa_aead_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_abort()</span></code></a>. The application can call <a class="reference internal" href="#c.psa_aead_abort" title="psa_aead_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_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_aead_encrypt_setup" title="psa_aead_encrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_encrypt_setup()</span></code></a>, the application must eventually terminate the operation. The following events terminate an operation:</p> |
| <ul class="simple"> |
| <li>A successful call to <a class="reference internal" href="#c.psa_aead_finish" title="psa_aead_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_finish()</span></code></a>.</li> |
| <li>A call to <a class="reference internal" href="#c.psa_aead_abort" title="psa_aead_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_abort()</span></code></a>.</li> |
| </ul> |
| </div> |
| <div class="section" id="psa_aead_decrypt_setup"> |
| <span id="c.psa_aead_decrypt_setup"></span><h3><code class="docutils literal"><span class="pre">psa_aead_decrypt_setup</span></code> (function)</h3> |
| <p>Set the key for a multi-part authenticated decryption 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_aead_decrypt_setup" title="psa_aead_decrypt_setup">psa_aead_decrypt_setup</a>(<a class="reference internal" href="#c.psa_aead_operation_t" title="psa_aead_operation_t">psa_aead_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_aead_operation_t" title="psa_aead_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_aead_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_DECRYPT" title="PSA_KEY_USAGE_DECRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DECRYPT</span></code></a>.</dd> |
| <dt> <code class="docutils literal"><span class="pre">alg</span></code></dt> |
| <dd>The AEAD 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_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</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_DECRYPT" title="PSA_KEY_USAGE_DECRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DECRYPT</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 an AEAD 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 an AEAD 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>The sequence of operations to decrypt a message with authentication 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_aead_operation_t" title="psa_aead_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_aead_operation_t</span></code></a>, e.g. <a class="reference internal" href="#c.PSA_AEAD_OPERATION_INIT" title="PSA_AEAD_OPERATION_INIT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_OPERATION_INIT</span></code></a>.</li> |
| <li>Call <a class="reference internal" href="#c.psa_aead_decrypt_setup" title="psa_aead_decrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_decrypt_setup()</span></code></a> to specify the algorithm and key.</li> |
| <li>If needed, call <a class="reference internal" href="#c.psa_aead_set_lengths" title="psa_aead_set_lengths"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_set_lengths()</span></code></a> to specify the length of the inputs to the subsequent calls to <a class="reference internal" href="#c.psa_aead_update_ad" title="psa_aead_update_ad"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_update_ad()</span></code></a> and <a class="reference internal" href="#c.psa_aead_update" title="psa_aead_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_update()</span></code></a>. See the documentation of <a class="reference internal" href="#c.psa_aead_set_lengths" title="psa_aead_set_lengths"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_set_lengths()</span></code></a> for details.</li> |
| <li>Call <a class="reference internal" href="#c.psa_aead_set_nonce" title="psa_aead_set_nonce"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_set_nonce()</span></code></a> with the nonce for the decryption.</li> |
| <li>Call <a class="reference internal" href="#c.psa_aead_update_ad" title="psa_aead_update_ad"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_update_ad()</span></code></a> zero, one or more times, passing a fragment of the non-encrypted additional authenticated data each time.</li> |
| <li>Call <a class="reference internal" href="#c.psa_aead_update" title="psa_aead_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_update()</span></code></a> zero, one or more times, passing a fragment of the ciphertext to decrypt each time.</li> |
| <li>Call <a class="reference internal" href="#c.psa_aead_verify" title="psa_aead_verify"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_verify()</span></code></a>.</li> |
| </ol> |
| <p>If an error occurs at any step after a call to <a class="reference internal" href="#c.psa_aead_decrypt_setup" title="psa_aead_decrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_decrypt_setup()</span></code></a>, the operation will need to be reset by a call to <a class="reference internal" href="#c.psa_aead_abort" title="psa_aead_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_abort()</span></code></a>. The application can call <a class="reference internal" href="#c.psa_aead_abort" title="psa_aead_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_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_aead_decrypt_setup" title="psa_aead_decrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_decrypt_setup()</span></code></a>, the application must eventually terminate the operation. The following events terminate an operation:</p> |
| <ul class="simple"> |
| <li>A successful call to <a class="reference internal" href="#c.psa_aead_verify" title="psa_aead_verify"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_verify()</span></code></a>.</li> |
| <li>A call to <a class="reference internal" href="#c.psa_aead_abort" title="psa_aead_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_abort()</span></code></a>.</li> |
| </ul> |
| </div> |
| <div class="section" id="psa_aead_set_lengths"> |
| <span id="c.psa_aead_set_lengths"></span><h3><code class="docutils literal"><span class="pre">psa_aead_set_lengths</span></code> (function)</h3> |
| <p>Declare the lengths of the message and additional data for AEAD.</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_aead_set_lengths" title="psa_aead_set_lengths">psa_aead_set_lengths</a>(<a class="reference internal" href="#c.psa_aead_operation_t" title="psa_aead_operation_t">psa_aead_operation_t</a> * operation, |
| size_t ad_length, |
| size_t plaintext_length); |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">operation</span></code></dt> |
| <dd>Active AEAD operation.</dd> |
| <dt> <code class="docutils literal"><span class="pre">ad_length</span></code></dt> |
| <dd>Size of the non-encrypted additional authenticated data in bytes.</dd> |
| <dt> <code class="docutils literal"><span class="pre">plaintext_length</span></code></dt> |
| <dd>Size of the plaintext to encrypt 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, and <a class="reference internal" href="#c.psa_aead_set_nonce" title="psa_aead_set_nonce"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_set_nonce()</span></code></a> and <a class="reference internal" href="#c.psa_aead_generate_nonce" title="psa_aead_generate_nonce"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_generate_nonce()</span></code></a> must not have been called yet.</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><code class="docutils literal"><span class="pre">ad_length</span></code> or <code class="docutils literal"><span class="pre">plaintext_length</span></code> are too large for the chosen 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><code class="docutils literal"><span class="pre">ad_length</span></code> or <code class="docutils literal"><span class="pre">plaintext_length</span></code> are 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> |
| </dl> |
| <p class="rubric">Description</p> |
| <p>The application must call this function before calling <a class="reference internal" href="#c.psa_aead_set_nonce" title="psa_aead_set_nonce"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_set_nonce()</span></code></a> or <a class="reference internal" href="#c.psa_aead_generate_nonce" title="psa_aead_generate_nonce"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_generate_nonce()</span></code></a>, if the algorithm for the operation requires it. If the algorithm does not require it, calling this function is optional, but if this function is called then the implementation must enforce the lengths.</p> |
| <ul class="simple"> |
| <li>For <a class="reference internal" href="#c.PSA_ALG_CCM" title="PSA_ALG_CCM"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_CCM</span></code></a>, calling this function is required.</li> |
| <li>For the other AEAD algorithms defined in this specification, calling this function is not required.</li> |
| <li>For vendor-defined algorithm, refer to the vendor documentation.</li> |
| </ul> |
| <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_aead_abort" title="psa_aead_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_abort()</span></code></a>.</p> |
| </div> |
| <div class="section" id="psa_aead_generate_nonce"> |
| <span id="c.psa_aead_generate_nonce"></span><h3><code class="docutils literal"><span class="pre">psa_aead_generate_nonce</span></code> (function)</h3> |
| <p>Generate a random nonce for an authenticated encryption 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_aead_generate_nonce" title="psa_aead_generate_nonce">psa_aead_generate_nonce</a>(<a class="reference internal" href="#c.psa_aead_operation_t" title="psa_aead_operation_t">psa_aead_operation_t</a> * operation, |
| uint8_t * nonce, |
| size_t nonce_size, |
| size_t * nonce_length); |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">operation</span></code></dt> |
| <dd>Active AEAD operation.</dd> |
| <dt> <code class="docutils literal"><span class="pre">nonce</span></code></dt> |
| <dd>Buffer where the generated nonce is to be written.</dd> |
| <dt> <code class="docutils literal"><span class="pre">nonce_size</span></code></dt> |
| <dd><p class="first">Size of the <code class="docutils literal"><span class="pre">nonce</span></code> buffer in bytes. This must be appropriate for the selected algorithm and key:</p> |
| <ul class="last simple"> |
| <li>A sufficient output size is <a class="reference internal" href="#c.PSA_AEAD_NONCE_LENGTH" title="PSA_AEAD_NONCE_LENGTH"><code class="docutils literal"><span class="pre">PSA_AEAD_NONCE_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">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">key_type</span></code> is the type of key and <code class="docutils literal"><span class="pre">alg</span></code> is the algorithm that were used to set up the operation.</li> |
| <li><a class="reference internal" href="#c.PSA_AEAD_NONCE_MAX_SIZE" title="PSA_AEAD_NONCE_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_NONCE_MAX_SIZE</span></code></a> evaluates to a sufficient output size for any supported AEAD algorithm.</li> |
| </ul> |
| </dd> |
| <dt> <code class="docutils literal"><span class="pre">nonce_length</span></code></dt> |
| <dd>On success, the number of bytes of the generated nonce.</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">(*nonce_length)</span></code> bytes of <code class="docutils literal"><span class="pre">nonce</span></code> contain the generated nonce.</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 AEAD encryption operation, with no nonce set.</li> |
| <li>The operation state is not valid: this is an algorithm which requires <a class="reference internal" href="#c.psa_aead_set_lengths" title="psa_aead_set_lengths"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_set_lengths()</span></code></a> to be called before setting the nonce.</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">nonce</span></code> buffer is too small. <a class="reference internal" href="#c.PSA_AEAD_NONCE_LENGTH" title="PSA_AEAD_NONCE_LENGTH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_NONCE_LENGTH()</span></code></a> or <a class="reference internal" href="#c.PSA_AEAD_NONCE_MAX_SIZE" title="PSA_AEAD_NONCE_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_NONCE_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_ENTROPY" title="PSA_ERROR_INSUFFICIENT_ENTROPY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_ENTROPY</span></code></a></dt> |
| <dd></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 generates a random nonce for the authenticated encryption operation with an appropriate size for the chosen algorithm, key type and key size.</p> |
| <p>Most algorithms generate a default-length nonce, as returned by <a class="reference internal" href="#c.PSA_AEAD_NONCE_LENGTH" title="PSA_AEAD_NONCE_LENGTH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_NONCE_LENGTH()</span></code></a>. Some algorithms can return a shorter nonce from <a class="reference internal" href="#c.psa_aead_generate_nonce" title="psa_aead_generate_nonce"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_generate_nonce()</span></code></a>, see the individual algorithm descriptions for details.</p> |
| <p>The application must call <a class="reference internal" href="#c.psa_aead_encrypt_setup" title="psa_aead_encrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_encrypt_setup()</span></code></a> before calling this function. If applicable for the algorithm, the application must call <a class="reference internal" href="#c.psa_aead_set_lengths" title="psa_aead_set_lengths"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_set_lengths()</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_aead_abort" title="psa_aead_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_abort()</span></code></a>.</p> |
| </div> |
| <div class="section" id="psa_aead_set_nonce"> |
| <span id="c.psa_aead_set_nonce"></span><h3><code class="docutils literal"><span class="pre">psa_aead_set_nonce</span></code> (function)</h3> |
| <p>Set the nonce for an authenticated encryption or decryption 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_aead_set_nonce" title="psa_aead_set_nonce">psa_aead_set_nonce</a>(<a class="reference internal" href="#c.psa_aead_operation_t" title="psa_aead_operation_t">psa_aead_operation_t</a> * operation, |
| const uint8_t * nonce, |
| size_t nonce_length); |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">operation</span></code></dt> |
| <dd>Active AEAD operation.</dd> |
| <dt> <code class="docutils literal"><span class="pre">nonce</span></code></dt> |
| <dd>Buffer containing the nonce to use.</dd> |
| <dt> <code class="docutils literal"><span class="pre">nonce_length</span></code></dt> |
| <dd>Size of the nonce in bytes. This must be a valid nonce size for the chosen algorithm. The default nonce size is <a class="reference internal" href="#c.PSA_AEAD_NONCE_LENGTH" title="PSA_AEAD_NONCE_LENGTH"><code class="docutils literal"><span class="pre">PSA_AEAD_NONCE_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">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">alg</span></code> are type of key and the algorithm respectively that were used to set up the AEAD 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.</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, with no nonce set.</li> |
| <li>The operation state is not valid: this is an algorithm which requires <a class="reference internal" href="#c.psa_aead_set_lengths" title="psa_aead_set_lengths"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_set_lengths()</span></code></a> to be called before setting the nonce.</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><code class="docutils literal"><span class="pre">nonce_length</span></code> is not valid for the chosen 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><code class="docutils literal"><span class="pre">nonce_length</span></code> is not supported for use with the operation’s algorithm and key.</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 the nonce for the authenticated encryption or decryption operation.</p> |
| <p>The application must call <a class="reference internal" href="#c.psa_aead_encrypt_setup" title="psa_aead_encrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_encrypt_setup()</span></code></a> or <a class="reference internal" href="#c.psa_aead_decrypt_setup" title="psa_aead_decrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_decrypt_setup()</span></code></a> before calling this function. If applicable for the algorithm, the application must call <a class="reference internal" href="#c.psa_aead_set_lengths" title="psa_aead_set_lengths"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_set_lengths()</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_aead_abort" title="psa_aead_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_abort()</span></code></a>.</p> |
| <div class="admonition note"> |
| <p class="first admonition-title">Note</p> |
| <p class="last">When encrypting, <a class="reference internal" href="#c.psa_aead_generate_nonce" title="psa_aead_generate_nonce"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_generate_nonce()</span></code></a> is recommended instead of using this function, unless implementing a protocol that requires a non-random IV.</p> |
| </div> |
| </div> |
| <div class="section" id="psa_aead_update_ad"> |
| <span id="c.psa_aead_update_ad"></span><h3><code class="docutils literal"><span class="pre">psa_aead_update_ad</span></code> (function)</h3> |
| <p>Pass additional data to an active AEAD 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_aead_update_ad" title="psa_aead_update_ad">psa_aead_update_ad</a>(<a class="reference internal" href="#c.psa_aead_operation_t" title="psa_aead_operation_t">psa_aead_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 AEAD operation.</dd> |
| <dt> <code class="docutils literal"><span class="pre">input</span></code></dt> |
| <dd>Buffer containing the fragment of additional data.</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><p class="first">Success.</p> |
| <div class="last admonition warning"> |
| <p class="first admonition-title">Warning</p> |
| <p>When decrypting, do not trust the additional data until <a class="reference internal" href="#c.psa_aead_verify" title="psa_aead_verify"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_verify()</span></code></a> succeeds.</p> |
| <p class="last">See the <a class="reference internal" href="#aead-multi-part-warning"><span class="std std-ref">detailed warning</span></a>.</p> |
| </div> |
| </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, have a nonce set, have lengths set if required by the algorithm, and <a class="reference internal" href="#c.psa_aead_update" title="psa_aead_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_update()</span></code></a> must not have been called yet.</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>Excess additional data: the total input length to <a class="reference internal" href="#c.psa_aead_update_ad" title="psa_aead_update_ad"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_update_ad()</span></code></a> is greater than the additional data length that was previously specified with <a class="reference internal" href="#c.psa_aead_set_lengths" title="psa_aead_set_lengths"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_set_lengths()</span></code></a>, or is too large for the chosen AEAD 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 additional data length 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>Additional data is authenticated, but not encrypted.</p> |
| <p>This function can be called multiple times to pass successive fragments of the additional data. This function must not be called after passing data to encrypt or decrypt with <a class="reference internal" href="#c.psa_aead_update" title="psa_aead_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_update()</span></code></a>.</p> |
| <p>The following must occur before calling this function:</p> |
| <ol class="arabic simple"> |
| <li>Call either <a class="reference internal" href="#c.psa_aead_encrypt_setup" title="psa_aead_encrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_encrypt_setup()</span></code></a> or <a class="reference internal" href="#c.psa_aead_decrypt_setup" title="psa_aead_decrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_decrypt_setup()</span></code></a>.</li> |
| <li>Set the nonce with <a class="reference internal" href="#c.psa_aead_generate_nonce" title="psa_aead_generate_nonce"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_generate_nonce()</span></code></a> or <a class="reference internal" href="#c.psa_aead_set_nonce" title="psa_aead_set_nonce"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_set_nonce()</span></code></a>.</li> |
| </ol> |
| <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_aead_abort" title="psa_aead_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_abort()</span></code></a>.</p> |
| </div> |
| <div class="section" id="psa_aead_update"> |
| <span id="c.psa_aead_update"></span><h3><code class="docutils literal"><span class="pre">psa_aead_update</span></code> (function)</h3> |
| <p>Encrypt or decrypt a message fragment in an active AEAD 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_aead_update" title="psa_aead_update">psa_aead_update</a>(<a class="reference internal" href="#c.psa_aead_operation_t" title="psa_aead_operation_t">psa_aead_operation_t</a> * operation, |
| const uint8_t * input, |
| size_t input_length, |
| uint8_t * output, |
| size_t output_size, |
| size_t * output_length); |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">operation</span></code></dt> |
| <dd>Active AEAD operation.</dd> |
| <dt> <code class="docutils literal"><span class="pre">input</span></code></dt> |
| <dd>Buffer containing the message fragment to encrypt or decrypt.</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">output</span></code></dt> |
| <dd>Buffer where the output is to be written.</dd> |
| <dt> <code class="docutils literal"><span class="pre">output_size</span></code></dt> |
| <dd><p class="first">Size of the <code class="docutils literal"><span class="pre">output</span></code> buffer in bytes. This must be appropriate for the selected algorithm and key:</p> |
| <ul class="last simple"> |
| <li>A sufficient output size is <a class="reference internal" href="#c.PSA_AEAD_UPDATE_OUTPUT_SIZE" title="PSA_AEAD_UPDATE_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_AEAD_UPDATE_OUTPUT_SIZE</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">alg</span></code><code class="docutils literal"><span class="pre">,</span> </code><code class="docutils literal"><span class="pre">input_length</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">key_type</span></code> is the type of key and <code class="docutils literal"><span class="pre">alg</span></code> is the algorithm that were used to set up the operation.</li> |
| <li><a class="reference internal" href="#c.PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE" title="PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE"><code class="docutils literal"><span class="pre">PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">input_length</span></code><code class="docutils literal"><span class="pre">)</span></code> evaluates to the maximum output size of any supported AEAD algorithm.</li> |
| </ul> |
| </dd> |
| <dt> <code class="docutils literal"><span class="pre">output_length</span></code></dt> |
| <dd>On success, the number of bytes that make up the returned output.</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><p class="first">Success. |
| The first <code class="docutils literal"><span class="pre">(*output_length)</span></code> of <code class="docutils literal"><span class="pre">output</span></code> contains the output data.</p> |
| <div class="last admonition warning"> |
| <p class="first admonition-title">Warning</p> |
| <p>When decrypting, do not use the output until <a class="reference internal" href="#c.psa_aead_verify" title="psa_aead_verify"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_verify()</span></code></a> succeeds.</p> |
| <p class="last">See the <a class="reference internal" href="#aead-multi-part-warning"><span class="std std-ref">detailed warning</span></a>.</p> |
| </div> |
| </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, have a nonce set, and have lengths set if required by the algorithm.</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">output</span></code> buffer is too small. <a class="reference internal" href="#c.PSA_AEAD_UPDATE_OUTPUT_SIZE" title="PSA_AEAD_UPDATE_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_UPDATE_OUTPUT_SIZE()</span></code></a> or <a class="reference internal" href="#c.PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE" title="PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_UPDATE_OUTPUT_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>Incomplete additional data: the total length of input to <a class="reference internal" href="#c.psa_aead_update_ad" title="psa_aead_update_ad"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_update_ad()</span></code></a> is less than the additional data length that was previously specified with <a class="reference internal" href="#c.psa_aead_set_lengths" title="psa_aead_set_lengths"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_set_lengths()</span></code></a>.</li> |
| <li>Excess input data: the total length of input to <a class="reference internal" href="#c.psa_aead_update" title="psa_aead_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_update()</span></code></a> is greater than the plaintext length that was previously specified with <a class="reference internal" href="#c.psa_aead_set_lengths" title="psa_aead_set_lengths"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_set_lengths()</span></code></a>, or is too large for the specific AEAD algorithm.</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>The total input length 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 following must occur before calling this function:</p> |
| <ol class="arabic simple"> |
| <li>Call either <a class="reference internal" href="#c.psa_aead_encrypt_setup" title="psa_aead_encrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_encrypt_setup()</span></code></a> or <a class="reference internal" href="#c.psa_aead_decrypt_setup" title="psa_aead_decrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_decrypt_setup()</span></code></a>. The choice of setup function determines whether this function encrypts or decrypts its input.</li> |
| <li>Set the nonce with <a class="reference internal" href="#c.psa_aead_generate_nonce" title="psa_aead_generate_nonce"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_generate_nonce()</span></code></a> or <a class="reference internal" href="#c.psa_aead_set_nonce" title="psa_aead_set_nonce"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_set_nonce()</span></code></a>.</li> |
| <li>Call <a class="reference internal" href="#c.psa_aead_update_ad" title="psa_aead_update_ad"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_update_ad()</span></code></a> to pass all the additional data.</li> |
| </ol> |
| <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_aead_abort" title="psa_aead_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_abort()</span></code></a>.</p> |
| <p>This function does not require the input to be aligned to any particular block boundary. If the implementation can only process a whole block at a time, it must consume all the input provided, but it might delay the end of the corresponding output until a subsequent call to <a class="reference internal" href="#c.psa_aead_update" title="psa_aead_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_update()</span></code></a>, <a class="reference internal" href="#c.psa_aead_finish" title="psa_aead_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_finish()</span></code></a> or <a class="reference internal" href="#c.psa_aead_verify" title="psa_aead_verify"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_verify()</span></code></a> provides sufficient input. The amount of data that can be delayed in this way is bounded by <a class="reference internal" href="#c.PSA_AEAD_UPDATE_OUTPUT_SIZE" title="PSA_AEAD_UPDATE_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_UPDATE_OUTPUT_SIZE()</span></code></a>.</p> |
| </div> |
| <div class="section" id="psa_aead_finish"> |
| <span id="c.psa_aead_finish"></span><h3><code class="docutils literal"><span class="pre">psa_aead_finish</span></code> (function)</h3> |
| <p>Finish encrypting a message in an AEAD 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_aead_finish" title="psa_aead_finish">psa_aead_finish</a>(<a class="reference internal" href="#c.psa_aead_operation_t" title="psa_aead_operation_t">psa_aead_operation_t</a> * operation, |
| uint8_t * ciphertext, |
| size_t ciphertext_size, |
| size_t * ciphertext_length, |
| uint8_t * tag, |
| size_t tag_size, |
| size_t * tag_length); |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">operation</span></code></dt> |
| <dd>Active AEAD operation.</dd> |
| <dt> <code class="docutils literal"><span class="pre">ciphertext</span></code></dt> |
| <dd>Buffer where the last part of the ciphertext is to be written.</dd> |
| <dt> <code class="docutils literal"><span class="pre">ciphertext_size</span></code></dt> |
| <dd><p class="first">Size of the <code class="docutils literal"><span class="pre">ciphertext</span></code> buffer in bytes. This must be appropriate for the selected algorithm and key:</p> |
| <ul class="last simple"> |
| <li>A sufficient output size is <a class="reference internal" href="#c.PSA_AEAD_FINISH_OUTPUT_SIZE" title="PSA_AEAD_FINISH_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_AEAD_FINISH_OUTPUT_SIZE</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">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">key_type</span></code> is the type of key and <code class="docutils literal"><span class="pre">alg</span></code> is the algorithm that were used to set up the operation.</li> |
| <li><a class="reference internal" href="#c.PSA_AEAD_FINISH_OUTPUT_MAX_SIZE" title="PSA_AEAD_FINISH_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_FINISH_OUTPUT_MAX_SIZE</span></code></a> evaluates to the maximum output size of any supported AEAD algorithm.</li> |
| </ul> |
| </dd> |
| <dt> <code class="docutils literal"><span class="pre">ciphertext_length</span></code></dt> |
| <dd>On success, the number of bytes of returned ciphertext.</dd> |
| <dt> <code class="docutils literal"><span class="pre">tag</span></code></dt> |
| <dd>Buffer where the authentication tag is to be written.</dd> |
| <dt> <code class="docutils literal"><span class="pre">tag_size</span></code></dt> |
| <dd><p class="first">Size of the <code class="docutils literal"><span class="pre">tag</span></code> buffer in bytes. |
| This must be appropriate for the selected algorithm and key:</p> |
| <ul class="last simple"> |
| <li>The exact tag size is <a class="reference internal" href="#c.PSA_AEAD_TAG_LENGTH" title="PSA_AEAD_TAG_LENGTH"><code class="docutils literal"><span class="pre">PSA_AEAD_TAG_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 the type and bit-size of the key, and <code class="docutils literal"><span class="pre">alg</span></code> is the algorithm that were used in the call to <a class="reference internal" href="#c.psa_aead_encrypt_setup" title="psa_aead_encrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_encrypt_setup()</span></code></a>.</li> |
| <li><a class="reference internal" href="#c.PSA_AEAD_TAG_MAX_SIZE" title="PSA_AEAD_TAG_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_TAG_MAX_SIZE</span></code></a> evaluates to the maximum tag size of any supported AEAD algorithm.</li> |
| </ul> |
| </dd> |
| <dt> <code class="docutils literal"><span class="pre">tag_length</span></code></dt> |
| <dd>On success, the number of bytes that make up the returned tag.</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">(*tag_length)</span></code> bytes of <code class="docutils literal"><span class="pre">tag</span></code> contain the authentication tag.</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 encryption operation with a nonce set.</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">ciphertext</span></code> or <code class="docutils literal"><span class="pre">tag</span></code> buffer is too small. |
| <a class="reference internal" href="#c.PSA_AEAD_FINISH_OUTPUT_SIZE" title="PSA_AEAD_FINISH_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_FINISH_OUTPUT_SIZE()</span></code></a> or <a class="reference internal" href="#c.PSA_AEAD_FINISH_OUTPUT_MAX_SIZE" title="PSA_AEAD_FINISH_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_FINISH_OUTPUT_MAX_SIZE</span></code></a> can be used to determine the required <code class="docutils literal"><span class="pre">ciphertext</span></code> buffer size. |
| <a class="reference internal" href="#c.PSA_AEAD_TAG_LENGTH" title="PSA_AEAD_TAG_LENGTH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_TAG_LENGTH()</span></code></a> or <a class="reference internal" href="#c.PSA_AEAD_TAG_MAX_SIZE" title="PSA_AEAD_TAG_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_TAG_MAX_SIZE</span></code></a> can be used to determine the required <code class="docutils literal"><span class="pre">tag</span></code> 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>Incomplete additional data: the total length of input to <a class="reference internal" href="#c.psa_aead_update_ad" title="psa_aead_update_ad"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_update_ad()</span></code></a> is less than the additional data length that was previously specified with <a class="reference internal" href="#c.psa_aead_set_lengths" title="psa_aead_set_lengths"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_set_lengths()</span></code></a>.</li> |
| <li>Incomplete plaintext: the total length of input to <a class="reference internal" href="#c.psa_aead_update" title="psa_aead_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_update()</span></code></a> is less than the plaintext length that was previously specified with <a class="reference internal" href="#c.psa_aead_set_lengths" title="psa_aead_set_lengths"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_set_lengths()</span></code></a>.</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>The operation must have been set up with <a class="reference internal" href="#c.psa_aead_encrypt_setup" title="psa_aead_encrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_encrypt_setup()</span></code></a>.</p> |
| <p>This function finishes the authentication of the additional data formed by concatenating the inputs passed to preceding calls to <a class="reference internal" href="#c.psa_aead_update_ad" title="psa_aead_update_ad"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_update_ad()</span></code></a> with the plaintext formed by concatenating the inputs passed to preceding calls to <a class="reference internal" href="#c.psa_aead_update" title="psa_aead_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_update()</span></code></a>.</p> |
| <p>This function has two output buffers:</p> |
| <ul class="simple"> |
| <li><code class="docutils literal"><span class="pre">ciphertext</span></code> contains trailing ciphertext that was buffered from preceding calls to <a class="reference internal" href="#c.psa_aead_update" title="psa_aead_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_update()</span></code></a>.</li> |
| <li><code class="docutils literal"><span class="pre">tag</span></code> contains the authentication tag.</li> |
| </ul> |
| <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_aead_abort" title="psa_aead_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_abort()</span></code></a>.</p> |
| </div> |
| <div class="section" id="psa_aead_verify"> |
| <span id="c.psa_aead_verify"></span><h3><code class="docutils literal"><span class="pre">psa_aead_verify</span></code> (function)</h3> |
| <p>Finish authenticating and decrypting a message in an AEAD 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_aead_verify" title="psa_aead_verify">psa_aead_verify</a>(<a class="reference internal" href="#c.psa_aead_operation_t" title="psa_aead_operation_t">psa_aead_operation_t</a> * operation, |
| uint8_t * plaintext, |
| size_t plaintext_size, |
| size_t * plaintext_length, |
| const uint8_t * tag, |
| size_t tag_length); |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">operation</span></code></dt> |
| <dd>Active AEAD operation.</dd> |
| <dt> <code class="docutils literal"><span class="pre">plaintext</span></code></dt> |
| <dd>Buffer where the last part of the plaintext is to be written. This is the remaining data from previous calls to <a class="reference internal" href="#c.psa_aead_update" title="psa_aead_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_update()</span></code></a> that could not be processed until the end of the input.</dd> |
| <dt> <code class="docutils literal"><span class="pre">plaintext_size</span></code></dt> |
| <dd><p class="first">Size of the <code class="docutils literal"><span class="pre">plaintext</span></code> buffer in bytes. This must be appropriate for the selected algorithm and key:</p> |
| <ul class="last simple"> |
| <li>A sufficient output size is <a class="reference internal" href="#c.PSA_AEAD_VERIFY_OUTPUT_SIZE" title="PSA_AEAD_VERIFY_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_AEAD_VERIFY_OUTPUT_SIZE</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">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">key_type</span></code> is the type of key and <code class="docutils literal"><span class="pre">alg</span></code> is the algorithm that were used to set up the operation.</li> |
| <li><a class="reference internal" href="#c.PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE" title="PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE</span></code></a> evaluates to the maximum output size of any supported AEAD algorithm.</li> |
| </ul> |
| </dd> |
| <dt> <code class="docutils literal"><span class="pre">plaintext_length</span></code></dt> |
| <dd>On success, the number of bytes of returned plaintext.</dd> |
| <dt> <code class="docutils literal"><span class="pre">tag</span></code></dt> |
| <dd>Buffer containing the expected authentication tag.</dd> |
| <dt> <code class="docutils literal"><span class="pre">tag_length</span></code></dt> |
| <dd>Size of the <code class="docutils literal"><span class="pre">tag</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. |
| For a decryption operation, it is now safe to use the additional data and the plaintext output.</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 decryption operation with a nonce set.</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 authentication tag does not match the value in <code class="docutils literal"><span class="pre">tag</span></code>.</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">plaintext</span></code> buffer is too small. <a class="reference internal" href="#c.PSA_AEAD_VERIFY_OUTPUT_SIZE" title="PSA_AEAD_VERIFY_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_VERIFY_OUTPUT_SIZE()</span></code></a> or <a class="reference internal" href="#c.PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE" title="PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_VERIFY_OUTPUT_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>Incomplete additional data: the total length of input to <a class="reference internal" href="#c.psa_aead_update_ad" title="psa_aead_update_ad"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_update_ad()</span></code></a> is less than the additional data length that was previously specified with <a class="reference internal" href="#c.psa_aead_set_lengths" title="psa_aead_set_lengths"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_set_lengths()</span></code></a>.</li> |
| <li>Incomplete ciphertext: the total length of input to <a class="reference internal" href="#c.psa_aead_update" title="psa_aead_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_update()</span></code></a> is less than the plaintext length that was previously specified with <a class="reference internal" href="#c.psa_aead_set_lengths" title="psa_aead_set_lengths"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_set_lengths()</span></code></a>.</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>The operation must have been set up with <a class="reference internal" href="#c.psa_aead_decrypt_setup" title="psa_aead_decrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_decrypt_setup()</span></code></a>.</p> |
| <p>This function finishes the authenticated decryption of the message components:</p> |
| <ul class="simple"> |
| <li>The additional data consisting of the concatenation of the inputs passed to preceding calls to <a class="reference internal" href="#c.psa_aead_update_ad" title="psa_aead_update_ad"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_update_ad()</span></code></a>.</li> |
| <li>The ciphertext consisting of the concatenation of the inputs passed to preceding calls to <a class="reference internal" href="#c.psa_aead_update" title="psa_aead_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_update()</span></code></a>.</li> |
| <li>The tag passed to this function call.</li> |
| </ul> |
| <p>If the authentication tag is correct, this function outputs any remaining plaintext and reports success. If the authentication tag is not correct, this function returns <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_SIGNATURE" title="PSA_ERROR_INVALID_SIGNATURE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ERROR_INVALID_SIGNATURE</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_aead_abort" title="psa_aead_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_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 tag and the expected tag is performed in constant time.</p> |
| </div> |
| </div> |
| <div class="section" id="psa_aead_abort"> |
| <span id="c.psa_aead_abort"></span><h3><code class="docutils literal"><span class="pre">psa_aead_abort</span></code> (function)</h3> |
| <p>Abort an AEAD 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_aead_abort" title="psa_aead_abort">psa_aead_abort</a>(<a class="reference internal" href="#c.psa_aead_operation_t" title="psa_aead_operation_t">psa_aead_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 AEAD 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_aead_encrypt_setup" title="psa_aead_encrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_encrypt_setup()</span></code></a> or <a class="reference internal" href="#c.psa_aead_decrypt_setup" title="psa_aead_decrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_decrypt_setup()</span></code></a> again.</p> |
| <p>This function can be called any time after the operation object has been initialized as described in <a class="reference internal" href="#c.psa_aead_operation_t" title="psa_aead_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_aead_operation_t</span></code></a>.</p> |
| <p>In particular, calling <a class="reference internal" href="#c.psa_aead_abort" title="psa_aead_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_abort()</span></code></a> after the operation has been terminated by a call to <a class="reference internal" href="#c.psa_aead_abort" title="psa_aead_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_abort()</span></code></a>, <a class="reference internal" href="#c.psa_aead_finish" title="psa_aead_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_finish()</span></code></a> or <a class="reference internal" href="#c.psa_aead_verify" title="psa_aead_verify"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_verify()</span></code></a> is safe and has no effect.</p> |
| </div> |
| </div> |
| <div class="section" id="support-macros"> |
| <h2>10.5.4. Support macros</h2> |
| <div class="section" id="PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER"> |
| <span id="c.PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER</span></code> (macro)</h3> |
| <p>Whether the specified algorithm is an AEAD mode on a block cipher.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER" title="PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER">PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER</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 AEAD algorithm which is an AEAD mode based on a block cipher, <code class="docutils literal"><span class="pre">0</span></code> otherwise.</p> |
| <p>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_AEAD_ENCRYPT_OUTPUT_SIZE"> |
| <span id="c.PSA_AEAD_ENCRYPT_OUTPUT_SIZE"></span><h3><code class="docutils literal"><span class="pre">PSA_AEAD_ENCRYPT_OUTPUT_SIZE</span></code> (macro)</h3> |
| <p>A sufficient ciphertext buffer size for <a class="reference internal" href="#c.psa_aead_encrypt" title="psa_aead_encrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_encrypt()</span></code></a>, in bytes.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_AEAD_ENCRYPT_OUTPUT_SIZE" title="PSA_AEAD_ENCRYPT_OUTPUT_SIZE">PSA_AEAD_ENCRYPT_OUTPUT_SIZE</a>(key_type, alg, plaintext_length) \ |
| <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>A symmetric key type that is compatible with algorithm <code class="docutils literal"><span class="pre">alg</span></code>.</dd> |
| <dt> <code class="docutils literal"><span class="pre">alg</span></code></dt> |
| <dd>An AEAD 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_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</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">plaintext_length</span></code></dt> |
| <dd>Size of the plaintext in bytes.</dd> |
| </dl> |
| <p class="rubric">Returns</p> |
| <p>The AEAD ciphertext size for the specified key type and algorithm. If the key type or AEAD algorithm is not recognized, or the parameters are incompatible, return <code class="docutils literal"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal"><span class="pre">0</span></code> or a correct size for a key type and AEAD algorithm that it recognizes, but does not support.</p> |
| <p class="rubric">Description</p> |
| <p>If the size of the ciphertext buffer is at least this large, it is guaranteed that <a class="reference internal" href="#c.psa_aead_encrypt" title="psa_aead_encrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_encrypt()</span></code></a> will not fail due to an insufficient buffer size. Depending on the algorithm, the actual size of the ciphertext might be smaller.</p> |
| <p>See also <a class="reference internal" href="#c.PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE" title="PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE</span></code></a>.</p> |
| </div> |
| <div class="section" id="PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE"> |
| <span id="c.PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE"></span><h3><code class="docutils literal"><span class="pre">PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE</span></code> (macro)</h3> |
| <p>A sufficient ciphertext buffer size for <a class="reference internal" href="#c.psa_aead_encrypt" title="psa_aead_encrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_encrypt()</span></code></a>, for any of the supported key types and AEAD algorithms.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE" title="PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE">PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE</a>(plaintext_length) \ |
| <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">plaintext_length</span></code></dt> |
| <dd>Size of the plaintext in bytes.</dd> |
| </dl> |
| <p class="rubric">Description</p> |
| <p>If the size of the ciphertext buffer is at least this large, it is guaranteed that <a class="reference internal" href="#c.psa_aead_encrypt" title="psa_aead_encrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_encrypt()</span></code></a> will not fail due to an insufficient buffer size.</p> |
| <p>See also <a class="reference internal" href="#c.PSA_AEAD_ENCRYPT_OUTPUT_SIZE" title="PSA_AEAD_ENCRYPT_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_ENCRYPT_OUTPUT_SIZE()</span></code></a>.</p> |
| </div> |
| <div class="section" id="PSA_AEAD_DECRYPT_OUTPUT_SIZE"> |
| <span id="c.PSA_AEAD_DECRYPT_OUTPUT_SIZE"></span><h3><code class="docutils literal"><span class="pre">PSA_AEAD_DECRYPT_OUTPUT_SIZE</span></code> (macro)</h3> |
| <p>A sufficient plaintext buffer size for <a class="reference internal" href="#c.psa_aead_decrypt" title="psa_aead_decrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_decrypt()</span></code></a>, in bytes.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_AEAD_DECRYPT_OUTPUT_SIZE" title="PSA_AEAD_DECRYPT_OUTPUT_SIZE">PSA_AEAD_DECRYPT_OUTPUT_SIZE</a>(key_type, alg, ciphertext_length) \ |
| <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>A symmetric key type that is compatible with algorithm <code class="docutils literal"><span class="pre">alg</span></code>.</dd> |
| <dt> <code class="docutils literal"><span class="pre">alg</span></code></dt> |
| <dd>An AEAD 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_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</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">ciphertext_length</span></code></dt> |
| <dd>Size of the ciphertext in bytes.</dd> |
| </dl> |
| <p class="rubric">Returns</p> |
| <p>The AEAD plaintext size for the specified key type and algorithm. If the key type or AEAD algorithm is not recognized, or the parameters are incompatible, return <code class="docutils literal"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal"><span class="pre">0</span></code> or a correct size for a key type and AEAD algorithm that it recognizes, but does not support.</p> |
| <p class="rubric">Description</p> |
| <p>If the size of the plaintext buffer is at least this large, it is guaranteed that <a class="reference internal" href="#c.psa_aead_decrypt" title="psa_aead_decrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_decrypt()</span></code></a> will not fail due to an insufficient buffer size. Depending on the algorithm, the actual size of the plaintext might be smaller.</p> |
| <p>See also <a class="reference internal" href="#c.PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE" title="PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE</span></code></a>.</p> |
| </div> |
| <div class="section" id="PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE"> |
| <span id="c.PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE"></span><h3><code class="docutils literal"><span class="pre">PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE</span></code> (macro)</h3> |
| <p>A sufficient plaintext buffer size for <a class="reference internal" href="#c.psa_aead_decrypt" title="psa_aead_decrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_decrypt()</span></code></a>, for any of the supported key types and AEAD algorithms.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE" title="PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE">PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE</a>(ciphertext_length) \ |
| <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">ciphertext_length</span></code></dt> |
| <dd>Size of the ciphertext in bytes.</dd> |
| </dl> |
| <p class="rubric">Description</p> |
| <p>If the size of the plaintext buffer is at least this large, it is guaranteed that <a class="reference internal" href="#c.psa_aead_decrypt" title="psa_aead_decrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_decrypt()</span></code></a> will not fail due to an insufficient buffer size.</p> |
| <p>See also <a class="reference internal" href="#c.PSA_AEAD_DECRYPT_OUTPUT_SIZE" title="PSA_AEAD_DECRYPT_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_DECRYPT_OUTPUT_SIZE()</span></code></a>.</p> |
| </div> |
| <div class="section" id="PSA_AEAD_NONCE_LENGTH"> |
| <span id="c.PSA_AEAD_NONCE_LENGTH"></span><h3><code class="docutils literal"><span class="pre">PSA_AEAD_NONCE_LENGTH</span></code> (macro)</h3> |
| <p>The default nonce size for an AEAD algorithm, in bytes.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_AEAD_NONCE_LENGTH" title="PSA_AEAD_NONCE_LENGTH">PSA_AEAD_NONCE_LENGTH</a>(key_type, 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>A symmetric key type that is compatible with algorithm <code class="docutils literal"><span class="pre">alg</span></code>.</dd> |
| <dt> <code class="docutils literal"><span class="pre">alg</span></code></dt> |
| <dd>An AEAD 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_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</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 default nonce size for the specified key type and algorithm. If the key type or AEAD algorithm is not recognized, or the parameters are incompatible, return <code class="docutils literal"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal"><span class="pre">0</span></code> or a correct size for a key type and AEAD algorithm that it recognizes, but does not support.</p> |
| <p class="rubric">Description</p> |
| <p>If the size of the nonce buffer is at least this large, it is guaranteed that <a class="reference internal" href="#c.psa_aead_generate_nonce" title="psa_aead_generate_nonce"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_generate_nonce()</span></code></a> will not fail due to an insufficient buffer size.</p> |
| <p>For most AEAD algorithms, <a class="reference internal" href="#c.PSA_AEAD_NONCE_LENGTH" title="PSA_AEAD_NONCE_LENGTH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_NONCE_LENGTH()</span></code></a> evaluates to the exact size of the nonce generated by <a class="reference internal" href="#c.psa_aead_generate_nonce" title="psa_aead_generate_nonce"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_generate_nonce()</span></code></a>.</p> |
| <p>See also <a class="reference internal" href="#c.PSA_AEAD_NONCE_MAX_SIZE" title="PSA_AEAD_NONCE_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_NONCE_MAX_SIZE</span></code></a>.</p> |
| </div> |
| <div class="section" id="PSA_AEAD_NONCE_MAX_SIZE"> |
| <span id="c.PSA_AEAD_NONCE_MAX_SIZE"></span><h3><code class="docutils literal"><span class="pre">PSA_AEAD_NONCE_MAX_SIZE</span></code> (macro)</h3> |
| <p>A sufficient buffer size for storing the nonce generated by <a class="reference internal" href="#c.psa_aead_generate_nonce" title="psa_aead_generate_nonce"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_generate_nonce()</span></code></a>, for any of the supported key types and AEAD algorithms.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_AEAD_NONCE_MAX_SIZE" title="PSA_AEAD_NONCE_MAX_SIZE">PSA_AEAD_NONCE_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 nonce buffer is at least this large, it is guaranteed that <a class="reference internal" href="#c.psa_aead_generate_nonce" title="psa_aead_generate_nonce"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_generate_nonce()</span></code></a> will not fail due to an insufficient buffer size.</p> |
| <p>See also <a class="reference internal" href="#c.PSA_AEAD_NONCE_LENGTH" title="PSA_AEAD_NONCE_LENGTH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_NONCE_LENGTH()</span></code></a>.</p> |
| </div> |
| <div class="section" id="PSA_AEAD_UPDATE_OUTPUT_SIZE"> |
| <span id="c.PSA_AEAD_UPDATE_OUTPUT_SIZE"></span><h3><code class="docutils literal"><span class="pre">PSA_AEAD_UPDATE_OUTPUT_SIZE</span></code> (macro)</h3> |
| <p>A sufficient output buffer size for <a class="reference internal" href="#c.psa_aead_update" title="psa_aead_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_update()</span></code></a>.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_AEAD_UPDATE_OUTPUT_SIZE" title="PSA_AEAD_UPDATE_OUTPUT_SIZE">PSA_AEAD_UPDATE_OUTPUT_SIZE</a>(key_type, alg, input_length) \ |
| <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>A symmetric key type that is compatible with algorithm <code class="docutils literal"><span class="pre">alg</span></code>.</dd> |
| <dt> <code class="docutils literal"><span class="pre">alg</span></code></dt> |
| <dd>An AEAD 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_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</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_length</span></code></dt> |
| <dd>Size of the input in bytes.</dd> |
| </dl> |
| <p class="rubric">Returns</p> |
| <p>A sufficient output buffer size for the specified key type and algorithm. If the key type or AEAD algorithm is not recognized, or the parameters are incompatible, return <code class="docutils literal"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal"><span class="pre">0</span></code> or a correct size for a key type and AEAD algorithm that it recognizes, but does not support.</p> |
| <p class="rubric">Description</p> |
| <p>If the size of the output buffer is at least this large, it is guaranteed that <a class="reference internal" href="#c.psa_aead_update" title="psa_aead_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_update()</span></code></a> will not fail due to an insufficient buffer size. The actual size of the output might be smaller in any given call.</p> |
| <p>See also <a class="reference internal" href="#c.PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE" title="PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE</span></code></a>.</p> |
| </div> |
| <div class="section" id="PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE"> |
| <span id="c.PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE"></span><h3><code class="docutils literal"><span class="pre">PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE</span></code> (macro)</h3> |
| <p>A sufficient output buffer size for <a class="reference internal" href="#c.psa_aead_update" title="psa_aead_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_update()</span></code></a>, for any of the supported key types and AEAD algorithms.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE" title="PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE">PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE</a>(input_length) \ |
| <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">input_length</span></code></dt> |
| <dd>Size of the input in bytes.</dd> |
| </dl> |
| <p class="rubric">Description</p> |
| <p>If the size of the output buffer is at least this large, it is guaranteed that <a class="reference internal" href="#c.psa_aead_update" title="psa_aead_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_update()</span></code></a> will not fail due to an insufficient buffer size.</p> |
| <p>See also <a class="reference internal" href="#c.PSA_AEAD_UPDATE_OUTPUT_SIZE" title="PSA_AEAD_UPDATE_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_UPDATE_OUTPUT_SIZE()</span></code></a>.</p> |
| </div> |
| <div class="section" id="PSA_AEAD_FINISH_OUTPUT_SIZE"> |
| <span id="c.PSA_AEAD_FINISH_OUTPUT_SIZE"></span><h3><code class="docutils literal"><span class="pre">PSA_AEAD_FINISH_OUTPUT_SIZE</span></code> (macro)</h3> |
| <p>A sufficient ciphertext buffer size for <a class="reference internal" href="#c.psa_aead_finish" title="psa_aead_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_finish()</span></code></a>.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_AEAD_FINISH_OUTPUT_SIZE" title="PSA_AEAD_FINISH_OUTPUT_SIZE">PSA_AEAD_FINISH_OUTPUT_SIZE</a>(key_type, 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>A symmetric key type that is compatible with algorithm <code class="docutils literal"><span class="pre">alg</span></code>.</dd> |
| <dt> <code class="docutils literal"><span class="pre">alg</span></code></dt> |
| <dd>An AEAD 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_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</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>A sufficient ciphertext buffer size for the specified key type and algorithm. If the key type or AEAD algorithm is not recognized, or the parameters are incompatible, return <code class="docutils literal"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal"><span class="pre">0</span></code> or a correct size for a key type and AEAD algorithm that it recognizes, but does not support.</p> |
| <p class="rubric">Description</p> |
| <p>If the size of the ciphertext buffer is at least this large, it is guaranteed that <a class="reference internal" href="#c.psa_aead_finish" title="psa_aead_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_finish()</span></code></a> will not fail due to an insufficient ciphertext buffer size. The actual size of the output might be smaller in any given call.</p> |
| <p>See also <a class="reference internal" href="#c.PSA_AEAD_FINISH_OUTPUT_MAX_SIZE" title="PSA_AEAD_FINISH_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_FINISH_OUTPUT_MAX_SIZE</span></code></a>.</p> |
| </div> |
| <div class="section" id="PSA_AEAD_FINISH_OUTPUT_MAX_SIZE"> |
| <span id="c.PSA_AEAD_FINISH_OUTPUT_MAX_SIZE"></span><h3><code class="docutils literal"><span class="pre">PSA_AEAD_FINISH_OUTPUT_MAX_SIZE</span></code> (macro)</h3> |
| <p>A sufficient ciphertext buffer size for <a class="reference internal" href="#c.psa_aead_finish" title="psa_aead_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_finish()</span></code></a>, for any of the supported key types and AEAD algorithms.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_AEAD_FINISH_OUTPUT_MAX_SIZE" title="PSA_AEAD_FINISH_OUTPUT_MAX_SIZE">PSA_AEAD_FINISH_OUTPUT_MAX_SIZE</a> <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em> |
| </pre> |
| <p>If the size of the ciphertext buffer is at least this large, it is guaranteed that <a class="reference internal" href="#c.psa_aead_finish" title="psa_aead_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_finish()</span></code></a> will not fail due to an insufficient ciphertext buffer size.</p> |
| <p>See also <a class="reference internal" href="#c.PSA_AEAD_FINISH_OUTPUT_SIZE" title="PSA_AEAD_FINISH_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_FINISH_OUTPUT_SIZE()</span></code></a>.</p> |
| </div> |
| <div class="section" id="PSA_AEAD_TAG_LENGTH"> |
| <span id="c.PSA_AEAD_TAG_LENGTH"></span><h3><code class="docutils literal"><span class="pre">PSA_AEAD_TAG_LENGTH</span></code> (macro)</h3> |
| <p>The length of a tag for an AEAD algorithm, in bytes.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_AEAD_TAG_LENGTH" title="PSA_AEAD_TAG_LENGTH">PSA_AEAD_TAG_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 AEAD key.</dd> |
| <dt> <code class="docutils literal"><span class="pre">key_bits</span></code></dt> |
| <dd>The size of the AEAD key in bits.</dd> |
| <dt> <code class="docutils literal"><span class="pre">alg</span></code></dt> |
| <dd>An AEAD 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_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</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 tag length for the specified algorithm and key. |
| If the AEAD algorithm does not have an identified tag that can be distinguished from the rest of the ciphertext, return <code class="docutils literal"><span class="pre">0</span></code>. If the AEAD algorithm is not recognized, return <code class="docutils literal"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal"><span class="pre">0</span></code> or a correct size for an AEAD algorithm that it recognizes, but does not support.</p> |
| <p class="rubric">Description</p> |
| <p>This is the size of the tag output from <a class="reference internal" href="#c.psa_aead_finish" title="psa_aead_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_finish()</span></code></a>.</p> |
| <p>If the size of the tag buffer is at least this large, it is guaranteed that <a class="reference internal" href="#c.psa_aead_finish" title="psa_aead_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_finish()</span></code></a> will not fail due to an insufficient tag buffer size.</p> |
| <p>See also <a class="reference internal" href="#c.PSA_AEAD_TAG_MAX_SIZE" title="PSA_AEAD_TAG_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_TAG_MAX_SIZE</span></code></a>.</p> |
| </div> |
| <div class="section" id="PSA_AEAD_TAG_MAX_SIZE"> |
| <span id="c.PSA_AEAD_TAG_MAX_SIZE"></span><h3><code class="docutils literal"><span class="pre">PSA_AEAD_TAG_MAX_SIZE</span></code> (macro)</h3> |
| <p>A sufficient buffer size for storing the tag output by <a class="reference internal" href="#c.psa_aead_finish" title="psa_aead_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_finish()</span></code></a>, for any of the supported key types and AEAD algorithms.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_AEAD_TAG_MAX_SIZE" title="PSA_AEAD_TAG_MAX_SIZE">PSA_AEAD_TAG_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 tag buffer is at least this large, it is guaranteed that <a class="reference internal" href="#c.psa_aead_finish" title="psa_aead_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_finish()</span></code></a> will not fail due to an insufficient buffer size.</p> |
| <p>See also <a class="reference internal" href="#c.PSA_AEAD_TAG_LENGTH" title="PSA_AEAD_TAG_LENGTH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_TAG_LENGTH()</span></code></a>.</p> |
| </div> |
| <div class="section" id="PSA_AEAD_VERIFY_OUTPUT_SIZE"> |
| <span id="c.PSA_AEAD_VERIFY_OUTPUT_SIZE"></span><h3><code class="docutils literal"><span class="pre">PSA_AEAD_VERIFY_OUTPUT_SIZE</span></code> (macro)</h3> |
| <p>A sufficient plaintext buffer size for <a class="reference internal" href="#c.psa_aead_verify" title="psa_aead_verify"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_verify()</span></code></a>, in bytes.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_AEAD_VERIFY_OUTPUT_SIZE" title="PSA_AEAD_VERIFY_OUTPUT_SIZE">PSA_AEAD_VERIFY_OUTPUT_SIZE</a>(key_type, 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>A symmetric key type that is compatible with algorithm <code class="docutils literal"><span class="pre">alg</span></code>.</dd> |
| <dt> <code class="docutils literal"><span class="pre">alg</span></code></dt> |
| <dd>An AEAD 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_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</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>A sufficient plaintext buffer size for the specified key type and algorithm. If the key type or AEAD algorithm is not recognized, or the parameters are incompatible, return <code class="docutils literal"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal"><span class="pre">0</span></code> or a correct size for a key type and AEAD algorithm that it recognizes, but does not support.</p> |
| <p class="rubric">Description</p> |
| <p>If the size of the plaintext buffer is at least this large, it is guaranteed that <a class="reference internal" href="#c.psa_aead_verify" title="psa_aead_verify"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_verify()</span></code></a> will not fail due to an insufficient plaintext buffer size. The actual size of the output might be smaller in any given call.</p> |
| <p>See also <a class="reference internal" href="#c.PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE" title="PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE</span></code></a>.</p> |
| </div> |
| <div class="section" id="PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE"> |
| <span id="c.PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE"></span><h3><code class="docutils literal"><span class="pre">PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE</span></code> (macro)</h3> |
| <p>A sufficient plaintext buffer size for <a class="reference internal" href="#c.psa_aead_verify" title="psa_aead_verify"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_verify()</span></code></a>, for any of the supported key types and AEAD algorithms.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE" title="PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE">PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE</a> <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em> |
| </pre> |
| <p>If the size of the plaintext buffer is at least this large, it is guaranteed that <a class="reference internal" href="#c.psa_aead_verify" title="psa_aead_verify"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_verify()</span></code></a> will not fail due to an insufficient buffer size.</p> |
| <p>See also <a class="reference internal" href="#c.PSA_AEAD_VERIFY_OUTPUT_SIZE" title="PSA_AEAD_VERIFY_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_VERIFY_OUTPUT_SIZE()</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"><a class="reference internal" href="macs.html">10.3. Message authentication codes (MAC)</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="ciphers.html">10.4. Unauthenticated ciphers</a></li> |
| <li class="toctree-l2 current"><a class="current reference internal" href="#">10.5. Authenticated encryption with associated data (AEAD)</a><ul> |
| <li class="toctree-l3"><a class="reference internal" href="#aead-algorithms">10.5.1. AEAD algorithms</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#single-part-aead-functions">10.5.2. Single-part AEAD functions</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#multi-part-aead-operations">10.5.3. Multi-part AEAD operations</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#support-macros">10.5.4. Support macros</a></li> |
| </ul> |
| </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> |