TrustedFirmware Git Browser
Code Review Sign In
review.trustedfirmware.org / mirror / mbed-crypto / c6b75f89526b234e1bc6a8a8f0c0e57624372954 / . / docs / 1.0.1 / html / api / ops / aead.html
blob: af4bf31e6aa226ddd15c579a96205f86f2c319f6 [file] [log] [blame]
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]1
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]2<!DOCTYPE html>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]3
4<html xmlns="http://www.w3.org/1999/xhtml">
5 <head>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]6 <meta charset="utf-8" />
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]7 <title>10.5. Authenticated encryption with associated data (AEAD) &#8212; PSA Crypto API 1.0.1 documentation</title>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]8 <link rel="stylesheet" href="../../_static/alabaster.css" type="text/css" />
9 <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]10 <script type="text/javascript" id="documentation_options" data-url_root="../../" src="../../_static/documentation_options.js"></script>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]11 <script type="text/javascript" src="../../_static/jquery.js"></script>
12 <script type="text/javascript" src="../../_static/underscore.js"></script>
13 <script type="text/javascript" src="../../_static/doctools.js"></script>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]14 <script type="text/javascript" src="../../_static/language_data.js"></script>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]15 <link rel="author" title="About these documents" href="../../about.html" />
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]16 <link rel="index" title="Index" href="../../genindex.html" />
17 <link rel="search" title="Search" href="../../search.html" />
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]18 <link rel="next" title="10.6. Key derivation" href="kdf.html" />
19 <link rel="prev" title="10.4. Unauthenticated ciphers" href="ciphers.html" />
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]20
21 <link rel="stylesheet" href="../../_static/custom.css" type="text/css" />
22
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]23
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]24 <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
25
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]26 </head><body>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]27
28
29 <div class="document">
30 <div class="documentwrapper">
31 <div class="bodywrapper">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]32
33
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]34 <div class="body" role="main">
35
36 <div class="section" id="authenticated-encryption-with-associated-data-aead">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]37<span id="aead"></span><h1>10.5. Authenticated encryption with associated data (AEAD)</h1>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]38<div class="section" id="aead-algorithms">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]39<span id="id1"></span><h2>10.5.1. AEAD algorithms</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]40<div class="section" id="PSA_ALG_CCM">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]41<span id="c.PSA_ALG_CCM"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_ALG_CCM</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]42<p>The <em>Counter with CBC-MAC</em> (CCM) authenticated encryption algorithm.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]43<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>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]44<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>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]45<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 notranslate"><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 notranslate"><span class="pre">psa_aead_set_lengths()</span></code></a> before providing the nonce, the additional data and plaintext to the operation.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]46<p>CCM requires a nonce of between 7 and 13 bytes in length. The length of the nonce depends on the length of the plaintext:</p>
47<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]48<li><p>CCM encodes the plaintext length <em>pLen</em> in <em>L</em> octets, with <em>L</em> the smallest integer &gt;= 2 where <em>pLen</em> &lt; 2^(8<em>L</em>).</p></li>
49<li><p>The nonce length is then 15 - <em>L</em> bytes.</p></li>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]50</ul>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]51<p>If the application is generating a random nonce using <a class="reference internal" href="#c.psa_aead_generate_nonce" title="psa_aead_generate_nonce"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_aead_generate_nonce()</span></code></a>, the size of the generated nonce is 15 - <em>L</em> bytes.</p>
52<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 notranslate"><span class="pre">PSA_ALG_AEAD_WITH_SHORTENED_TAG</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><a class="reference internal" href="#c.PSA_ALG_CCM" title="PSA_ALG_CCM"><code class="docutils literal notranslate"><span class="pre">PSA_ALG_CCM</span></code></a><code class="docutils literal notranslate"><span class="pre">,</span> </code><code class="docutils literal notranslate"><span class="pre">tag_length</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code>, where <code class="docutils literal notranslate"><span class="pre">tag_length</span></code> is a valid CCM tag length.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]53<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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]54</div>
55<div class="section" id="PSA_ALG_GCM">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]56<span id="c.PSA_ALG_GCM"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_ALG_GCM</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]57<p>The <em>Galois/Counter Mode</em> (GCM) authenticated encryption algorithm.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]58<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>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]59<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>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]60<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 notranslate"><span class="pre">psa_aead_generate_nonce()</span></code></a> will generate a random 12-byte nonce.</p>
61<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 notranslate"><span class="pre">PSA_ALG_AEAD_WITH_SHORTENED_TAG</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><a class="reference internal" href="#c.PSA_ALG_GCM" title="PSA_ALG_GCM"><code class="docutils literal notranslate"><span class="pre">PSA_ALG_GCM</span></code></a><code class="docutils literal notranslate"><span class="pre">,</span> </code><code class="docutils literal notranslate"><span class="pre">tag_length</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code>, where <code class="docutils literal notranslate"><span class="pre">tag_length</span></code> is a valid GCM tag length.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]62<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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]63</div>
64<div class="section" id="PSA_ALG_CHACHA20_POLY1305">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]65<span id="c.PSA_ALG_CHACHA20_POLY1305"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_ALG_CHACHA20_POLY1305</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]66<p>The ChaCha20-Poly1305 AEAD algorithm.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]67<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>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]68<p>There are two defined variants of ChaCha20-Poly1305:</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]69<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]70<li><p>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.</p></li>
71<li><p>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.</p></li>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]72</ul>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]73<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 notranslate"><span class="pre">PSA_ALG_CHACHA20_POLY1305</span></code></a>:</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]74<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]75<li><p>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 notranslate"><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 notranslate"><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 notranslate"><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.</p></li>
76<li><p>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 notranslate"><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.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]77</ul>
78<p>Implementations must support 16-byte tags. It is recommended that truncated tag sizes are rejected.</p>
79</div>
80<div class="section" id="PSA_ALG_AEAD_WITH_SHORTENED_TAG">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]81<span id="c.PSA_ALG_AEAD_WITH_SHORTENED_TAG"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_ALG_AEAD_WITH_SHORTENED_TAG</span></code> (macro)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]82<p>Macro to build a AEAD algorithm with a shortened tag.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]83<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) \
84 <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em></pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]85<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]86<dl class="simple">
87<dt> <code class="docutils literal notranslate"><span class="pre">aead_alg</span></code></dt><dd><p>An AEAD algorithm identifier (value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal notranslate"><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 notranslate"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> is true).</p>
88</dd>
89<dt> <code class="docutils literal notranslate"><span class="pre">tag_length</span></code></dt><dd><p>Desired length of the authentication tag in bytes.</p>
90</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]91</dl>
92<p class="rubric">Returns</p>
93<p>The corresponding AEAD algorithm with the specified tag length.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]94<p>Unspecified if <code class="docutils literal notranslate"><span class="pre">alg</span></code> is not a supported AEAD algorithm or if <code class="docutils literal notranslate"><span class="pre">tag_length</span></code> is not valid for the specified AEAD algorithm.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]95<p class="rubric">Description</p>
96<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>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]97<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 notranslate"><span class="pre">PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]98</div>
99</div>
100<div class="section" id="single-part-aead-functions">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]101<h2>10.5.2. Single-part AEAD functions</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]102<div class="section" id="psa_aead_encrypt">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]103<span id="c.psa_aead_encrypt"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_aead_encrypt</span></code> (function)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]104<p>Process an authenticated encryption operation.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]105<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,
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]106 <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]107 const uint8_t * nonce,
108 size_t nonce_length,
109 const uint8_t * additional_data,
110 size_t additional_data_length,
111 const uint8_t * plaintext,
112 size_t plaintext_length,
113 uint8_t * ciphertext,
114 size_t ciphertext_size,
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]115 size_t * ciphertext_length);</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]116<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]117<dl class="simple">
118<dt> <code class="docutils literal notranslate"><span class="pre">key</span></code></dt><dd><p>Identifier of the key to use for the operation.
119It 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 notranslate"><span class="pre">PSA_KEY_USAGE_ENCRYPT</span></code></a>.</p>
120</dd>
121<dt> <code class="docutils literal notranslate"><span class="pre">alg</span></code></dt><dd><p>The AEAD algorithm to compute (<code class="docutils literal notranslate"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal notranslate"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> is true).</p>
122</dd>
123<dt> <code class="docutils literal notranslate"><span class="pre">nonce</span></code></dt><dd><p>Nonce or IV to use.</p>
124</dd>
125<dt> <code class="docutils literal notranslate"><span class="pre">nonce_length</span></code></dt><dd><p>Size of the <code class="docutils literal notranslate"><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 notranslate"><span class="pre">PSA_AEAD_NONCE_LENGTH</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">key_type</span></code><code class="docutils literal notranslate"><span class="pre">,</span> </code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> where <code class="docutils literal notranslate"><span class="pre">key_type</span></code> is the type of <code class="docutils literal notranslate"><span class="pre">key</span></code>.</p>
126</dd>
127<dt> <code class="docutils literal notranslate"><span class="pre">additional_data</span></code></dt><dd><p>Additional data that will be authenticated but not encrypted.</p>
128</dd>
129<dt> <code class="docutils literal notranslate"><span class="pre">additional_data_length</span></code></dt><dd><p>Size of <code class="docutils literal notranslate"><span class="pre">additional_data</span></code> in bytes.</p>
130</dd>
131<dt> <code class="docutils literal notranslate"><span class="pre">plaintext</span></code></dt><dd><p>Data that will be authenticated and encrypted.</p>
132</dd>
133<dt> <code class="docutils literal notranslate"><span class="pre">plaintext_length</span></code></dt><dd><p>Size of <code class="docutils literal notranslate"><span class="pre">plaintext</span></code> in bytes.</p>
134</dd>
135<dt> <code class="docutils literal notranslate"><span class="pre">ciphertext</span></code></dt><dd><p>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.</p>
136</dd>
137<dt> <code class="docutils literal notranslate"><span class="pre">ciphertext_size</span></code></dt><dd><p>Size of the <code class="docutils literal notranslate"><span class="pre">ciphertext</span></code> buffer in bytes. This must be appropriate for the selected algorithm and key:</p>
138<ul class="simple">
139<li><p>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 notranslate"><span class="pre">PSA_AEAD_ENCRYPT_OUTPUT_SIZE</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">key_type</span></code><code class="docutils literal notranslate"><span class="pre">,</span> </code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">,</span> </code><code class="docutils literal notranslate"><span class="pre">plaintext_length</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> where <code class="docutils literal notranslate"><span class="pre">key_type</span></code> is the type of <code class="docutils literal notranslate"><span class="pre">key</span></code>.</p></li>
140<li><p><a class="reference internal" href="#c.PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE" title="PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE"><code class="docutils literal notranslate"><span class="pre">PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">plaintext_length</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> evaluates to the maximum ciphertext size of any supported AEAD encryption.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]141</ul>
142</dd>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]143<dt> <code class="docutils literal notranslate"><span class="pre">ciphertext_length</span></code></dt><dd><p>On success, the size of the output in the <code class="docutils literal notranslate"><span class="pre">ciphertext</span></code> buffer.</p>
144</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]145</dl>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]146<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code></a></p>
147<dl class="simple">
148<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code></a></dt><dd><p>Success.</p>
149</dd>
150<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt><dd></dd>
151<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt><dd><p>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 notranslate"><span class="pre">PSA_KEY_USAGE_ENCRYPT</span></code></a> flag, or it does not permit the requested algorithm.</p>
152</dd>
153<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt><dd><p><code class="docutils literal notranslate"><span class="pre">key</span></code> is not compatible with <code class="docutils literal notranslate"><span class="pre">alg</span></code>.</p>
154</dd>
155<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt><dd><p><code class="docutils literal notranslate"><span class="pre">alg</span></code> is not supported or is not an AEAD algorithm.</p>
156</dd>
157<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt><dd></dd>
158<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 notranslate"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a></dt><dd><p><code class="docutils literal notranslate"><span class="pre">ciphertext_size</span></code> 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 notranslate"><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 notranslate"><span class="pre">PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE()</span></code></a> can be used to determine the required buffer size.</p>
159</dd>
160<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt><dd></dd>
161<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt><dd></dd>
162<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt><dd></dd>
163<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt><dd></dd>
164<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt><dd></dd>
165<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt><dd></dd>
166<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</p>
167</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]168</dl>
169</div>
170<div class="section" id="psa_aead_decrypt">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]171<span id="c.psa_aead_decrypt"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_aead_decrypt</span></code> (function)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]172<p>Process an authenticated decryption operation.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]173<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,
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]174 <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]175 const uint8_t * nonce,
176 size_t nonce_length,
177 const uint8_t * additional_data,
178 size_t additional_data_length,
179 const uint8_t * ciphertext,
180 size_t ciphertext_length,
181 uint8_t * plaintext,
182 size_t plaintext_size,
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]183 size_t * plaintext_length);</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]184<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]185<dl class="simple">
186<dt> <code class="docutils literal notranslate"><span class="pre">key</span></code></dt><dd><p>Identifier of the key to use for the operation.
187It 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 notranslate"><span class="pre">PSA_KEY_USAGE_DECRYPT</span></code></a>.</p>
188</dd>
189<dt> <code class="docutils literal notranslate"><span class="pre">alg</span></code></dt><dd><p>The AEAD algorithm to compute (<code class="docutils literal notranslate"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal notranslate"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> is true).</p>
190</dd>
191<dt> <code class="docutils literal notranslate"><span class="pre">nonce</span></code></dt><dd><p>Nonce or IV to use.</p>
192</dd>
193<dt> <code class="docutils literal notranslate"><span class="pre">nonce_length</span></code></dt><dd><p>Size of the <code class="docutils literal notranslate"><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 notranslate"><span class="pre">PSA_AEAD_NONCE_LENGTH</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">key_type</span></code><code class="docutils literal notranslate"><span class="pre">,</span> </code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> where <code class="docutils literal notranslate"><span class="pre">key_type</span></code> is the type of <code class="docutils literal notranslate"><span class="pre">key</span></code>.</p>
194</dd>
195<dt> <code class="docutils literal notranslate"><span class="pre">additional_data</span></code></dt><dd><p>Additional data that has been authenticated but not encrypted.</p>
196</dd>
197<dt> <code class="docutils literal notranslate"><span class="pre">additional_data_length</span></code></dt><dd><p>Size of <code class="docutils literal notranslate"><span class="pre">additional_data</span></code> in bytes.</p>
198</dd>
199<dt> <code class="docutils literal notranslate"><span class="pre">ciphertext</span></code></dt><dd><p>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.</p>
200</dd>
201<dt> <code class="docutils literal notranslate"><span class="pre">ciphertext_length</span></code></dt><dd><p>Size of <code class="docutils literal notranslate"><span class="pre">ciphertext</span></code> in bytes.</p>
202</dd>
203<dt> <code class="docutils literal notranslate"><span class="pre">plaintext</span></code></dt><dd><p>Output buffer for the decrypted data.</p>
204</dd>
205<dt> <code class="docutils literal notranslate"><span class="pre">plaintext_size</span></code></dt><dd><p>Size of the <code class="docutils literal notranslate"><span class="pre">plaintext</span></code> buffer in bytes. This must be appropriate for the selected algorithm and key:</p>
206<ul class="simple">
207<li><p>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 notranslate"><span class="pre">PSA_AEAD_DECRYPT_OUTPUT_SIZE</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">key_type</span></code><code class="docutils literal notranslate"><span class="pre">,</span> </code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">,</span> </code><code class="docutils literal notranslate"><span class="pre">ciphertext_length</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> where <code class="docutils literal notranslate"><span class="pre">key_type</span></code> is the type of <code class="docutils literal notranslate"><span class="pre">key</span></code>.</p></li>
208<li><p><a class="reference internal" href="#c.PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE" title="PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE"><code class="docutils literal notranslate"><span class="pre">PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">ciphertext_length</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> evaluates to the maximum plaintext size of any supported AEAD decryption.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]209</ul>
210</dd>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]211<dt> <code class="docutils literal notranslate"><span class="pre">plaintext_length</span></code></dt><dd><p>On success, the size of the output in the <code class="docutils literal notranslate"><span class="pre">plaintext</span></code> buffer.</p>
212</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]213</dl>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]214<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code></a></p>
215<dl class="simple">
216<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code></a></dt><dd><p>Success.</p>
217</dd>
218<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt><dd></dd>
219<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_SIGNATURE" title="PSA_ERROR_INVALID_SIGNATURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_SIGNATURE</span></code></a></dt><dd><p>The ciphertext is not authentic.</p>
220</dd>
221<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt><dd><p>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 notranslate"><span class="pre">PSA_KEY_USAGE_DECRYPT</span></code></a> flag, or it does not permit the requested algorithm.</p>
222</dd>
223<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt><dd><p><code class="docutils literal notranslate"><span class="pre">key</span></code> is not compatible with <code class="docutils literal notranslate"><span class="pre">alg</span></code>.</p>
224</dd>
225<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt><dd><p><code class="docutils literal notranslate"><span class="pre">alg</span></code> is not supported or is not an AEAD algorithm.</p>
226</dd>
227<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt><dd></dd>
228<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 notranslate"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a></dt><dd><p><code class="docutils literal notranslate"><span class="pre">plaintext_size</span></code> 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 notranslate"><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 notranslate"><span class="pre">PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE()</span></code></a> can be used to determine the required buffer size.</p>
229</dd>
230<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt><dd></dd>
231<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt><dd></dd>
232<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt><dd></dd>
233<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt><dd></dd>
234<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt><dd></dd>
235<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt><dd></dd>
236<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</p>
237</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]238</dl>
239</div>
240</div>
241<div class="section" id="multi-part-aead-operations">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]242<h2>10.5.3. Multi-part AEAD operations</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]243<div class="admonition warning" id="aead-multi-part-warning">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]244<p class="admonition-title">Warning</p>
245<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 notranslate"><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 notranslate"><span class="pre">PSA_SUCCESS</span></code></a>.</p>
246<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 notranslate"><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 notranslate"><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 notranslate"><span class="pre">PSA_SUCCESS</span></code></a> <strong>does not</strong> indicate that the input and output is valid.</p>
247<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 notranslate"><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 notranslate"><span class="pre">PSA_SUCCESS</span></code></a>, the following rules apply to input and output data from a multi-part AEAD operation:</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]248<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]249<li><p>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.</p></li>
250<li><p>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.</p></li>
251<li><p>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.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]252</ul>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]253<p>An application that does not follow these rules might be vulnerable to maliciously constructed AEAD input data.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]254</div>
255<div class="section" id="psa_aead_operation_t">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]256<span id="c.psa_aead_operation_t"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_aead_operation_t</span></code> (type)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]257<p>The type of the state object for multi-part AEAD operations.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]258<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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]259<p>Before calling any function on an AEAD operation object, the application must initialize it by any of the following means:</p>
260<ul>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]261<li><p>Set the object to all-bits-zero, for example:</p>
262<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;
263memset(&amp;operation, 0, sizeof(operation));</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]264</li>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]265<li><p>Initialize the object to logical zero values by declaring the object as static or global without an explicit initializer, for example:</p>
266<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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]267</li>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]268<li><p>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 notranslate"><span class="pre">PSA_AEAD_OPERATION_INIT</span></code></a>, for example:</p>
269<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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]270</li>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]271<li><p>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 notranslate"><span class="pre">psa_aead_operation_init()</span></code></a> to the object, for example:</p>
272<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;
273operation = <a class="reference internal" href="#c.psa_aead_operation_init" title="psa_aead_operation_init">psa_aead_operation_init</a>();</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]274</li>
275</ul>
276<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>
277</div>
278<div class="section" id="PSA_AEAD_OPERATION_INIT">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]279<span id="c.PSA_AEAD_OPERATION_INIT"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_AEAD_OPERATION_INIT</span></code> (macro)</h3>
280<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 notranslate"><span class="pre">psa_aead_operation_t</span></code></a>.</p>
281<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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]282</div>
283<div class="section" id="psa_aead_operation_init">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]284<span id="c.psa_aead_operation_init"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_aead_operation_init</span></code> (function)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]285<p>Return an initial value for an AEAD operation object.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]286<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>
287<p class="rubric">Returns: <a class="reference internal" href="#c.psa_aead_operation_t" title="psa_aead_operation_t"><code class="docutils literal notranslate"><span class="pre">psa_aead_operation_t</span></code></a></p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]288</div>
289<div class="section" id="psa_aead_encrypt_setup">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]290<span id="c.psa_aead_encrypt_setup"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_aead_encrypt_setup</span></code> (function)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]291<p>Set the key for a multi-part authenticated encryption operation.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]292<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,
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]293 <a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]294 <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg);</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]295<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]296<dl class="simple">
297<dt> <code class="docutils literal notranslate"><span class="pre">operation</span></code></dt><dd><p>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 notranslate"><span class="pre">psa_aead_operation_t</span></code></a> and not yet in use.</p>
298</dd>
299<dt> <code class="docutils literal notranslate"><span class="pre">key</span></code></dt><dd><p>Identifier of the key to use for the operation. It must remain valid until the operation terminates.
300It 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 notranslate"><span class="pre">PSA_KEY_USAGE_ENCRYPT</span></code></a>.</p>
301</dd>
302<dt> <code class="docutils literal notranslate"><span class="pre">alg</span></code></dt><dd><p>The AEAD algorithm to compute (<code class="docutils literal notranslate"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal notranslate"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> is true).</p>
303</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]304</dl>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]305<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code></a></p>
306<dl class="simple">
307<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code></a></dt><dd><p>Success.</p>
308</dd>
309<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The operation state is not valid: it must be inactive.</p>
310</dd>
311<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt><dd></dd>
312<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt><dd><p>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 notranslate"><span class="pre">PSA_KEY_USAGE_ENCRYPT</span></code></a> flag, or it does not permit the requested algorithm.</p>
313</dd>
314<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt><dd><p><code class="docutils literal notranslate"><span class="pre">key</span></code> is not compatible with <code class="docutils literal notranslate"><span class="pre">alg</span></code>.</p>
315</dd>
316<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt><dd><p><code class="docutils literal notranslate"><span class="pre">alg</span></code> is not supported or is not an AEAD algorithm.</p>
317</dd>
318<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt><dd></dd>
319<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt><dd></dd>
320<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt><dd></dd>
321<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt><dd></dd>
322<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt><dd></dd>
323<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt><dd></dd>
324<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt><dd></dd>
325<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</p>
326</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]327</dl>
328<p class="rubric">Description</p>
329<p>The sequence of operations to encrypt a message with authentication is as follows:</p>
330<ol class="arabic simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]331<li><p>Allocate an operation object which will be passed to all the functions listed here.</p></li>
332<li><p>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 notranslate"><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 notranslate"><span class="pre">PSA_AEAD_OPERATION_INIT</span></code></a>.</p></li>
333<li><p>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 notranslate"><span class="pre">psa_aead_encrypt_setup()</span></code></a> to specify the algorithm and key.</p></li>
334<li><p>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 notranslate"><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 notranslate"><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 notranslate"><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 notranslate"><span class="pre">psa_aead_set_lengths()</span></code></a> for details.</p></li>
335<li><p>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 notranslate"><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 notranslate"><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 notranslate"><span class="pre">psa_aead_generate_nonce()</span></code></a> unless the protocol being implemented requires a specific nonce value.</p></li>
336<li><p>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 notranslate"><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.</p></li>
337<li><p>Call <a class="reference internal" href="#c.psa_aead_update" title="psa_aead_update"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_aead_update()</span></code></a> zero, one or more times, passing a fragment of the message to encrypt each time.</p></li>
338<li><p>Call <a class="reference internal" href="#c.psa_aead_finish" title="psa_aead_finish"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_aead_finish()</span></code></a>.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]339</ol>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]340<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 notranslate"><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 notranslate"><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 notranslate"><span class="pre">psa_aead_abort()</span></code></a> at any time after the operation has been initialized.</p>
341<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 notranslate"><span class="pre">psa_aead_encrypt_setup()</span></code></a>, the application must eventually terminate the operation. The following events terminate an operation:</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]342<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]343<li><p>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 notranslate"><span class="pre">psa_aead_finish()</span></code></a>.</p></li>
344<li><p>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 notranslate"><span class="pre">psa_aead_abort()</span></code></a>.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]345</ul>
346</div>
347<div class="section" id="psa_aead_decrypt_setup">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]348<span id="c.psa_aead_decrypt_setup"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_aead_decrypt_setup</span></code> (function)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]349<p>Set the key for a multi-part authenticated decryption operation.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]350<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,
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]351 <a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]352 <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg);</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]353<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]354<dl class="simple">
355<dt> <code class="docutils literal notranslate"><span class="pre">operation</span></code></dt><dd><p>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 notranslate"><span class="pre">psa_aead_operation_t</span></code></a> and not yet in use.</p>
356</dd>
357<dt> <code class="docutils literal notranslate"><span class="pre">key</span></code></dt><dd><p>Identifier of the key to use for the operation. It must remain valid until the operation terminates.
358It 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 notranslate"><span class="pre">PSA_KEY_USAGE_DECRYPT</span></code></a>.</p>
359</dd>
360<dt> <code class="docutils literal notranslate"><span class="pre">alg</span></code></dt><dd><p>The AEAD algorithm to compute (<code class="docutils literal notranslate"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal notranslate"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> is true).</p>
361</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]362</dl>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]363<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code></a></p>
364<dl class="simple">
365<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code></a></dt><dd><p>Success.</p>
366</dd>
367<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The operation state is not valid: it must be inactive.</p>
368</dd>
369<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt><dd></dd>
370<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt><dd><p>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 notranslate"><span class="pre">PSA_KEY_USAGE_DECRYPT</span></code></a> flag, or it does not permit the requested algorithm.</p>
371</dd>
372<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt><dd><p><code class="docutils literal notranslate"><span class="pre">key</span></code> is not compatible with <code class="docutils literal notranslate"><span class="pre">alg</span></code>.</p>
373</dd>
374<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt><dd><p><code class="docutils literal notranslate"><span class="pre">alg</span></code> is not supported or is not an AEAD algorithm.</p>
375</dd>
376<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt><dd></dd>
377<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt><dd></dd>
378<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt><dd></dd>
379<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt><dd></dd>
380<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt><dd></dd>
381<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt><dd></dd>
382<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt><dd></dd>
383<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</p>
384</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]385</dl>
386<p class="rubric">Description</p>
387<p>The sequence of operations to decrypt a message with authentication is as follows:</p>
388<ol class="arabic simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]389<li><p>Allocate an operation object which will be passed to all the functions listed here.</p></li>
390<li><p>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 notranslate"><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 notranslate"><span class="pre">PSA_AEAD_OPERATION_INIT</span></code></a>.</p></li>
391<li><p>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 notranslate"><span class="pre">psa_aead_decrypt_setup()</span></code></a> to specify the algorithm and key.</p></li>
392<li><p>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 notranslate"><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 notranslate"><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 notranslate"><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 notranslate"><span class="pre">psa_aead_set_lengths()</span></code></a> for details.</p></li>
393<li><p>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 notranslate"><span class="pre">psa_aead_set_nonce()</span></code></a> with the nonce for the decryption.</p></li>
394<li><p>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 notranslate"><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.</p></li>
395<li><p>Call <a class="reference internal" href="#c.psa_aead_update" title="psa_aead_update"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_aead_update()</span></code></a> zero, one or more times, passing a fragment of the ciphertext to decrypt each time.</p></li>
396<li><p>Call <a class="reference internal" href="#c.psa_aead_verify" title="psa_aead_verify"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_aead_verify()</span></code></a>.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]397</ol>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]398<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 notranslate"><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 notranslate"><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 notranslate"><span class="pre">psa_aead_abort()</span></code></a> at any time after the operation has been initialized.</p>
399<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 notranslate"><span class="pre">psa_aead_decrypt_setup()</span></code></a>, the application must eventually terminate the operation. The following events terminate an operation:</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]400<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]401<li><p>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 notranslate"><span class="pre">psa_aead_verify()</span></code></a>.</p></li>
402<li><p>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 notranslate"><span class="pre">psa_aead_abort()</span></code></a>.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]403</ul>
404</div>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]405<div class="section" id="psa_aead_set_lengths">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]406<span id="c.psa_aead_set_lengths"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_aead_set_lengths</span></code> (function)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]407<p>Declare the lengths of the message and additional data for AEAD.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]408<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,
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]409 size_t ad_length,
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]410 size_t plaintext_length);</pre>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]411<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]412<dl class="simple">
413<dt> <code class="docutils literal notranslate"><span class="pre">operation</span></code></dt><dd><p>Active AEAD operation.</p>
414</dd>
415<dt> <code class="docutils literal notranslate"><span class="pre">ad_length</span></code></dt><dd><p>Size of the non-encrypted additional authenticated data in bytes.</p>
416</dd>
417<dt> <code class="docutils literal notranslate"><span class="pre">plaintext_length</span></code></dt><dd><p>Size of the plaintext to encrypt in bytes.</p>
418</dd>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]419</dl>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]420<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code></a></p>
421<dl class="simple">
422<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code></a></dt><dd><p>Success.</p>
423</dd>
424<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>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 notranslate"><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 notranslate"><span class="pre">psa_aead_generate_nonce()</span></code></a> must not have been called yet.</p>
425</dd>
426<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt><dd><p>At least one of the lengths is not acceptable for the chosen algorithm.</p>
427</dd>
428<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt><dd></dd>
429<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt><dd></dd>
430<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt><dd></dd>
431<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt><dd></dd>
432<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</p>
433</dd>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]434</dl>
435<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]436<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 notranslate"><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 notranslate"><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>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]437<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]438<li><p>For <a class="reference internal" href="#c.PSA_ALG_CCM" title="PSA_ALG_CCM"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_ALG_CCM</span></code></a>, calling this function is required.</p></li>
439<li><p>For the other AEAD algorithms defined in this specification, calling this function is not required.</p></li>
440<li><p>For vendor-defined algorithm, refer to the vendor documentation.</p></li>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]441</ul>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]442<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 notranslate"><span class="pre">psa_aead_abort()</span></code></a>.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]443</div>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]444<div class="section" id="psa_aead_generate_nonce">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]445<span id="c.psa_aead_generate_nonce"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_aead_generate_nonce</span></code> (function)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]446<p>Generate a random nonce for an authenticated encryption operation.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]447<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,
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]448 uint8_t * nonce,
449 size_t nonce_size,
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]450 size_t * nonce_length);</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]451<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]452<dl class="simple">
453<dt> <code class="docutils literal notranslate"><span class="pre">operation</span></code></dt><dd><p>Active AEAD operation.</p>
454</dd>
455<dt> <code class="docutils literal notranslate"><span class="pre">nonce</span></code></dt><dd><p>Buffer where the generated nonce is to be written.</p>
456</dd>
457<dt> <code class="docutils literal notranslate"><span class="pre">nonce_size</span></code></dt><dd><p>Size of the <code class="docutils literal notranslate"><span class="pre">nonce</span></code> buffer in bytes. This must be at least <a class="reference internal" href="#c.PSA_AEAD_NONCE_LENGTH" title="PSA_AEAD_NONCE_LENGTH"><code class="docutils literal notranslate"><span class="pre">PSA_AEAD_NONCE_LENGTH</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">key_type</span></code><code class="docutils literal notranslate"><span class="pre">,</span> </code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> where <code class="docutils literal notranslate"><span class="pre">key_type</span></code> and <code class="docutils literal notranslate"><span class="pre">alg</span></code> are type of key and the algorithm respectively that were used to set up the AEAD operation.</p>
458</dd>
459<dt> <code class="docutils literal notranslate"><span class="pre">nonce_length</span></code></dt><dd><p>On success, the number of bytes of the generated nonce.</p>
460</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]461</dl>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]462<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code></a></p>
463<dl class="simple">
464<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code></a></dt><dd><p>Success.</p>
465</dd>
466<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The operation state is not valid: it must be an active AEAD encryption operation, with no nonce set.</p>
467</dd>
468<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>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 notranslate"><span class="pre">psa_aead_set_lengths()</span></code></a> to be called before setting the nonce.</p>
469</dd>
470<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 notranslate"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a></dt><dd><p>The size of the <code class="docutils literal notranslate"><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 notranslate"><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 notranslate"><span class="pre">PSA_AEAD_NONCE_MAX_SIZE</span></code></a> can be used to determine the required buffer size.</p>
471</dd>
472<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt><dd></dd>
473<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt><dd></dd>
474<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt><dd></dd>
475<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt><dd></dd>
476<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt><dd></dd>
477<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt><dd></dd>
478<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt><dd></dd>
479<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</p>
480</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]481</dl>
482<p class="rubric">Description</p>
483<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>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]484<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 notranslate"><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 notranslate"><span class="pre">psa_aead_set_lengths()</span></code></a> before calling this function.</p>
485<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 notranslate"><span class="pre">psa_aead_abort()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]486</div>
487<div class="section" id="psa_aead_set_nonce">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]488<span id="c.psa_aead_set_nonce"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_aead_set_nonce</span></code> (function)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]489<p>Set the nonce for an authenticated encryption or decryption operation.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]490<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,
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]491 const uint8_t * nonce,
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]492 size_t nonce_length);</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]493<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]494<dl class="simple">
495<dt> <code class="docutils literal notranslate"><span class="pre">operation</span></code></dt><dd><p>Active AEAD operation.</p>
496</dd>
497<dt> <code class="docutils literal notranslate"><span class="pre">nonce</span></code></dt><dd><p>Buffer containing the nonce to use.</p>
498</dd>
499<dt> <code class="docutils literal notranslate"><span class="pre">nonce_length</span></code></dt><dd><p>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 notranslate"><span class="pre">PSA_AEAD_NONCE_LENGTH</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">key_type</span></code><code class="docutils literal notranslate"><span class="pre">,</span> </code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> where <code class="docutils literal notranslate"><span class="pre">key_type</span></code> and <code class="docutils literal notranslate"><span class="pre">alg</span></code> are type of key and the algorithm respectively that were used to set up the AEAD operation.</p>
500</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]501</dl>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]502<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code></a></p>
503<dl class="simple">
504<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code></a></dt><dd><p>Success.</p>
505</dd>
506<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The operation state is not valid: it must be active, with no nonce set.</p>
507</dd>
508<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>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 notranslate"><span class="pre">psa_aead_set_lengths()</span></code></a> to be called before setting the nonce.</p>
509</dd>
510<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt><dd><p>The size of <code class="docutils literal notranslate"><span class="pre">nonce</span></code> is not acceptable for the chosen algorithm.</p>
511</dd>
512<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt><dd></dd>
513<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt><dd></dd>
514<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt><dd></dd>
515<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt><dd></dd>
516<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt><dd></dd>
517<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt><dd></dd>
518<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt><dd></dd>
519<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</p>
520</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]521</dl>
522<p class="rubric">Description</p>
523<p>This function sets the nonce for the authenticated encryption or decryption operation.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]524<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 notranslate"><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 notranslate"><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 notranslate"><span class="pre">psa_aead_set_lengths()</span></code></a> before calling this function.</p>
525<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 notranslate"><span class="pre">psa_aead_abort()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]526<div class="admonition note">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]527<p class="admonition-title">Note</p>
528<p>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 notranslate"><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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]529</div>
530</div>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]531<div class="section" id="psa_aead_update_ad">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]532<span id="c.psa_aead_update_ad"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_aead_update_ad</span></code> (function)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]533<p>Pass additional data to an active AEAD operation.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]534<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,
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]535 const uint8_t * input,
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]536 size_t input_length);</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]537<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]538<dl class="simple">
539<dt> <code class="docutils literal notranslate"><span class="pre">operation</span></code></dt><dd><p>Active AEAD operation.</p>
540</dd>
541<dt> <code class="docutils literal notranslate"><span class="pre">input</span></code></dt><dd><p>Buffer containing the fragment of additional data.</p>
542</dd>
543<dt> <code class="docutils literal notranslate"><span class="pre">input_length</span></code></dt><dd><p>Size of the <code class="docutils literal notranslate"><span class="pre">input</span></code> buffer in bytes.</p>
544</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]545</dl>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]546<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code></a></p>
547<dl>
548<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code></a></dt><dd><p>Success.</p>
549<div class="admonition warning">
550<p class="admonition-title">Warning</p>
551<p>When decrypting, do not trust the input until <a class="reference internal" href="#c.psa_aead_verify" title="psa_aead_verify"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_aead_verify()</span></code></a> succeeds.</p>
552<p>See the <a class="reference internal" href="#aead-multi-part-warning"><span class="std std-ref">detailed warning</span></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]553</div>
554</dd>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]555<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>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 notranslate"><span class="pre">psa_aead_update()</span></code></a> must not have been called yet.</p>
556</dd>
557<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt><dd><p>The total input length overflows 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 notranslate"><span class="pre">psa_aead_set_lengths()</span></code></a>.</p>
558</dd>
559<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt><dd></dd>
560<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt><dd></dd>
561<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt><dd></dd>
562<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt><dd></dd>
563<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt><dd></dd>
564<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt><dd></dd>
565<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt><dd></dd>
566<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</p>
567</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]568</dl>
569<p class="rubric">Description</p>
570<p>Additional data is authenticated, but not encrypted.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]571<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 notranslate"><span class="pre">psa_aead_update()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]572<p>The following must occur before calling this function:</p>
573<ol class="arabic simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]574<li><p>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 notranslate"><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 notranslate"><span class="pre">psa_aead_decrypt_setup()</span></code></a>.</p></li>
575<li><p>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 notranslate"><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 notranslate"><span class="pre">psa_aead_set_nonce()</span></code></a>.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]576</ol>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]577<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 notranslate"><span class="pre">psa_aead_abort()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]578</div>
579<div class="section" id="psa_aead_update">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]580<span id="c.psa_aead_update"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_aead_update</span></code> (function)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]581<p>Encrypt or decrypt a message fragment in an active AEAD operation.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]582<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,
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]583 const uint8_t * input,
584 size_t input_length,
585 uint8_t * output,
586 size_t output_size,
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]587 size_t * output_length);</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]588<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]589<dl class="simple">
590<dt> <code class="docutils literal notranslate"><span class="pre">operation</span></code></dt><dd><p>Active AEAD operation.</p>
591</dd>
592<dt> <code class="docutils literal notranslate"><span class="pre">input</span></code></dt><dd><p>Buffer containing the message fragment to encrypt or decrypt.</p>
593</dd>
594<dt> <code class="docutils literal notranslate"><span class="pre">input_length</span></code></dt><dd><p>Size of the <code class="docutils literal notranslate"><span class="pre">input</span></code> buffer in bytes.</p>
595</dd>
596<dt> <code class="docutils literal notranslate"><span class="pre">output</span></code></dt><dd><p>Buffer where the output is to be written.</p>
597</dd>
598<dt> <code class="docutils literal notranslate"><span class="pre">output_size</span></code></dt><dd><p>Size of the <code class="docutils literal notranslate"><span class="pre">output</span></code> buffer in bytes. This must be appropriate for the selected algorithm and key:</p>
599<ul class="simple">
600<li><p>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 notranslate"><span class="pre">PSA_AEAD_UPDATE_OUTPUT_SIZE</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">key_type</span></code><code class="docutils literal notranslate"><span class="pre">,</span> </code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">,</span> </code><code class="docutils literal notranslate"><span class="pre">input_length</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> where <code class="docutils literal notranslate"><span class="pre">key_type</span></code> is the type of key and <code class="docutils literal notranslate"><span class="pre">alg</span></code> is the algorithm that were used to set up the operation.</p></li>
601<li><p><a class="reference internal" href="#c.PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE" title="PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE"><code class="docutils literal notranslate"><span class="pre">PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">input_length</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> evaluates to the maximum output size of any supported AEAD algorithm.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]602</ul>
603</dd>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]604<dt> <code class="docutils literal notranslate"><span class="pre">output_length</span></code></dt><dd><p>On success, the number of bytes that make up the returned output.</p>
605</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]606</dl>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]607<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code></a></p>
608<dl>
609<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code></a></dt><dd><p>Success.</p>
610<div class="admonition warning">
611<p class="admonition-title">Warning</p>
612<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 notranslate"><span class="pre">psa_aead_verify()</span></code></a> succeeds.</p>
613<p>See the <a class="reference internal" href="#aead-multi-part-warning"><span class="std std-ref">detailed warning</span></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]614</div>
615</dd>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]616<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The operation state is not valid: it must be active, have a nonce set, and have lengths set if required by the algorithm.</p>
617</dd>
618<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 notranslate"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a></dt><dd><p>The size of the <code class="docutils literal notranslate"><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 notranslate"><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 notranslate"><span class="pre">PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE()</span></code></a> can be used to determine the required buffer size.</p>
619</dd>
620<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt><dd><p>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 notranslate"><span class="pre">psa_aead_update_ad()</span></code></a> so far 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 notranslate"><span class="pre">psa_aead_set_lengths()</span></code></a>.</p>
621</dd>
622<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt><dd><p>The total input length overflows 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 notranslate"><span class="pre">psa_aead_set_lengths()</span></code></a>.</p>
623</dd>
624<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt><dd></dd>
625<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt><dd></dd>
626<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt><dd></dd>
627<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt><dd></dd>
628<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt><dd></dd>
629<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt><dd></dd>
630<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt><dd></dd>
631<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</p>
632</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]633</dl>
634<p class="rubric">Description</p>
635<p>The following must occur before calling this function:</p>
636<ol class="arabic simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]637<li><p>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 notranslate"><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 notranslate"><span class="pre">psa_aead_decrypt_setup()</span></code></a>. The choice of setup function determines whether this function encrypts or decrypts its input.</p></li>
638<li><p>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 notranslate"><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 notranslate"><span class="pre">psa_aead_set_nonce()</span></code></a>.</p></li>
639<li><p>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 notranslate"><span class="pre">psa_aead_update_ad()</span></code></a> to pass all the additional data.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]640</ol>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]641<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 notranslate"><span class="pre">psa_aead_abort()</span></code></a>.</p>
642<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 notranslate"><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 notranslate"><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 notranslate"><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 notranslate"><span class="pre">PSA_AEAD_UPDATE_OUTPUT_SIZE()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]643</div>
644<div class="section" id="psa_aead_finish">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]645<span id="c.psa_aead_finish"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_aead_finish</span></code> (function)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]646<p>Finish encrypting a message in an AEAD operation.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]647<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,
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]648 uint8_t * ciphertext,
649 size_t ciphertext_size,
650 size_t * ciphertext_length,
651 uint8_t * tag,
652 size_t tag_size,
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]653 size_t * tag_length);</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]654<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]655<dl class="simple">
656<dt> <code class="docutils literal notranslate"><span class="pre">operation</span></code></dt><dd><p>Active AEAD operation.</p>
657</dd>
658<dt> <code class="docutils literal notranslate"><span class="pre">ciphertext</span></code></dt><dd><p>Buffer where the last part of the ciphertext is to be written.</p>
659</dd>
660<dt> <code class="docutils literal notranslate"><span class="pre">ciphertext_size</span></code></dt><dd><p>Size of the <code class="docutils literal notranslate"><span class="pre">ciphertext</span></code> buffer in bytes. This must be appropriate for the selected algorithm and key:</p>
661<ul class="simple">
662<li><p>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 notranslate"><span class="pre">PSA_AEAD_FINISH_OUTPUT_SIZE</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">key_type</span></code><code class="docutils literal notranslate"><span class="pre">,</span> </code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> where <code class="docutils literal notranslate"><span class="pre">key_type</span></code> is the type of key and <code class="docutils literal notranslate"><span class="pre">alg</span></code> is the algorithm that were used to set up the operation.</p></li>
663<li><p><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 notranslate"><span class="pre">PSA_AEAD_FINISH_OUTPUT_MAX_SIZE</span></code></a> evaluates to the maximum output size of any supported AEAD algorithm.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]664</ul>
665</dd>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]666<dt> <code class="docutils literal notranslate"><span class="pre">ciphertext_length</span></code></dt><dd><p>On success, the number of bytes of returned ciphertext.</p>
667</dd>
668<dt> <code class="docutils literal notranslate"><span class="pre">tag</span></code></dt><dd><p>Buffer where the authentication tag is to be written.</p>
669</dd>
670<dt> <code class="docutils literal notranslate"><span class="pre">tag_size</span></code></dt><dd><p>Size of the <code class="docutils literal notranslate"><span class="pre">tag</span></code> buffer in bytes.
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]671This must be appropriate for the selected algorithm and key:</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]672<ul class="simple">
673<li><p>The exact tag size is <a class="reference internal" href="#c.PSA_AEAD_TAG_LENGTH" title="PSA_AEAD_TAG_LENGTH"><code class="docutils literal notranslate"><span class="pre">PSA_AEAD_TAG_LENGTH</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">key_type</span></code><code class="docutils literal notranslate"><span class="pre">,</span> </code><code class="docutils literal notranslate"><span class="pre">key_bits</span></code><code class="docutils literal notranslate"><span class="pre">,</span> </code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> where <code class="docutils literal notranslate"><span class="pre">key_type</span></code> and <code class="docutils literal notranslate"><span class="pre">key_bits</span></code> are the type and bit-size of the key, and <code class="docutils literal notranslate"><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 notranslate"><span class="pre">psa_aead_encrypt_setup()</span></code></a>.</p></li>
674<li><p><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 notranslate"><span class="pre">PSA_AEAD_TAG_MAX_SIZE</span></code></a> evaluates to the maximum tag size of any supported AEAD algorithm.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]675</ul>
676</dd>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]677<dt> <code class="docutils literal notranslate"><span class="pre">tag_length</span></code></dt><dd><p>On success, the number of bytes that make up the returned tag.</p>
678</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]679</dl>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]680<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code></a></p>
681<dl class="simple">
682<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code></a></dt><dd><p>Success.</p>
683</dd>
684<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The operation state is not valid: it must be an active encryption operation with a nonce set.</p>
685</dd>
686<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 notranslate"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a></dt><dd><p>The size of the <code class="docutils literal notranslate"><span class="pre">ciphertext</span></code> or <code class="docutils literal notranslate"><span class="pre">tag</span></code> buffer is too small.
687<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 notranslate"><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 notranslate"><span class="pre">PSA_AEAD_FINISH_OUTPUT_MAX_SIZE</span></code></a> can be used to determine the required <code class="docutils literal notranslate"><span class="pre">ciphertext</span></code> buffer size.
688<a class="reference internal" href="#c.PSA_AEAD_TAG_LENGTH" title="PSA_AEAD_TAG_LENGTH"><code class="xref any c c-macro docutils literal notranslate"><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 notranslate"><span class="pre">PSA_AEAD_TAG_MAX_SIZE</span></code></a> can be used to determine the required <code class="docutils literal notranslate"><span class="pre">tag</span></code> buffer size.</p>
689</dd>
690<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt><dd><p>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 notranslate"><span class="pre">psa_aead_update_ad()</span></code></a> so far 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 notranslate"><span class="pre">psa_aead_set_lengths()</span></code></a>.</p>
691</dd>
692<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt><dd><p>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 notranslate"><span class="pre">psa_aead_update()</span></code></a> so far 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 notranslate"><span class="pre">psa_aead_set_lengths()</span></code></a>.</p>
693</dd>
694<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt><dd></dd>
695<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt><dd></dd>
696<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt><dd></dd>
697<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt><dd></dd>
698<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt><dd></dd>
699<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt><dd></dd>
700<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt><dd></dd>
701<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</p>
702</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]703</dl>
704<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]705<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 notranslate"><span class="pre">psa_aead_encrypt_setup()</span></code></a>.</p>
706<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 notranslate"><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 notranslate"><span class="pre">psa_aead_update()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]707<p>This function has two output buffers:</p>
708<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]709<li><p><code class="docutils literal notranslate"><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 notranslate"><span class="pre">psa_aead_update()</span></code></a>.</p></li>
710<li><p><code class="docutils literal notranslate"><span class="pre">tag</span></code> contains the authentication tag.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]711</ul>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]712<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 notranslate"><span class="pre">psa_aead_abort()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]713</div>
714<div class="section" id="psa_aead_verify">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]715<span id="c.psa_aead_verify"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_aead_verify</span></code> (function)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]716<p>Finish authenticating and decrypting a message in an AEAD operation.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]717<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,
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]718 uint8_t * plaintext,
719 size_t plaintext_size,
720 size_t * plaintext_length,
721 const uint8_t * tag,
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]722 size_t tag_length);</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]723<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]724<dl class="simple">
725<dt> <code class="docutils literal notranslate"><span class="pre">operation</span></code></dt><dd><p>Active AEAD operation.</p>
726</dd>
727<dt> <code class="docutils literal notranslate"><span class="pre">plaintext</span></code></dt><dd><p>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 notranslate"><span class="pre">psa_aead_update()</span></code></a> that could not be processed until the end of the input.</p>
728</dd>
729<dt> <code class="docutils literal notranslate"><span class="pre">plaintext_size</span></code></dt><dd><p>Size of the <code class="docutils literal notranslate"><span class="pre">plaintext</span></code> buffer in bytes. This must be appropriate for the selected algorithm and key:</p>
730<ul class="simple">
731<li><p>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 notranslate"><span class="pre">PSA_AEAD_VERIFY_OUTPUT_SIZE</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">key_type</span></code><code class="docutils literal notranslate"><span class="pre">,</span> </code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> where <code class="docutils literal notranslate"><span class="pre">key_type</span></code> is the type of key and <code class="docutils literal notranslate"><span class="pre">alg</span></code> is the algorithm that were used to set up the operation.</p></li>
732<li><p><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 notranslate"><span class="pre">PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE</span></code></a> evaluates to the maximum output size of any supported AEAD algorithm.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]733</ul>
734</dd>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]735<dt> <code class="docutils literal notranslate"><span class="pre">plaintext_length</span></code></dt><dd><p>On success, the number of bytes of returned plaintext.</p>
736</dd>
737<dt> <code class="docutils literal notranslate"><span class="pre">tag</span></code></dt><dd><p>Buffer containing the authentication tag.</p>
738</dd>
739<dt> <code class="docutils literal notranslate"><span class="pre">tag_length</span></code></dt><dd><p>Size of the <code class="docutils literal notranslate"><span class="pre">tag</span></code> buffer in bytes.</p>
740</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]741</dl>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]742<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code></a></p>
743<dl class="simple">
744<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code></a></dt><dd><p>Success.</p>
745</dd>
746<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_SIGNATURE" title="PSA_ERROR_INVALID_SIGNATURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_SIGNATURE</span></code></a></dt><dd><p>The calculations were successful, but the authentication tag is not correct.</p>
747</dd>
748<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The operation state is not valid: it must be an active decryption operation with a nonce set.</p>
749</dd>
750<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 notranslate"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a></dt><dd><p>The size of the <code class="docutils literal notranslate"><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 notranslate"><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 notranslate"><span class="pre">PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE</span></code></a> can be used to determine the required buffer size.</p>
751</dd>
752<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt><dd><p>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 notranslate"><span class="pre">psa_aead_update_ad()</span></code></a> so far 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 notranslate"><span class="pre">psa_aead_set_lengths()</span></code></a>.</p>
753</dd>
754<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt><dd><p>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 notranslate"><span class="pre">psa_aead_update()</span></code></a> so far 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 notranslate"><span class="pre">psa_aead_set_lengths()</span></code></a>.</p>
755</dd>
756<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt><dd></dd>
757<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt><dd></dd>
758<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt><dd></dd>
759<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt><dd></dd>
760<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt><dd></dd>
761<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt><dd></dd>
762<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt><dd></dd>
763<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</p>
764</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]765</dl>
766<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]767<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 notranslate"><span class="pre">psa_aead_decrypt_setup()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]768<p>This function finishes the authenticated decryption of the message components:</p>
769<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]770<li><p>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 notranslate"><span class="pre">psa_aead_update_ad()</span></code></a>.</p></li>
771<li><p>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 notranslate"><span class="pre">psa_aead_update()</span></code></a>.</p></li>
772<li><p>The tag passed to this function call.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]773</ul>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]774<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 notranslate"><span class="pre">PSA_ERROR_INVALID_SIGNATURE</span></code></a>.</p>
775<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 notranslate"><span class="pre">psa_aead_abort()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]776<div class="admonition note">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]777<p class="admonition-title">Note</p>
778<p>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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]779</div>
780</div>
781<div class="section" id="psa_aead_abort">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]782<span id="c.psa_aead_abort"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_aead_abort</span></code> (function)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]783<p>Abort an AEAD operation.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]784<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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]785<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]786<dl class="simple">
787<dt> <code class="docutils literal notranslate"><span class="pre">operation</span></code></dt><dd><p>Initialized AEAD operation.</p>
788</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]789</dl>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]790<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code></a></p>
791<dl class="simple">
792<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code></a></dt><dd></dd>
793<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt><dd></dd>
794<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt><dd></dd>
795<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt><dd></dd>
796<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</p>
797</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]798</dl>
799<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]800<p>Aborting an operation frees all associated resources except for the <code class="docutils literal notranslate"><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 notranslate"><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 notranslate"><span class="pre">psa_aead_decrypt_setup()</span></code></a> again.</p>
801<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 notranslate"><span class="pre">psa_aead_operation_t</span></code></a>.</p>
802<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 notranslate"><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 notranslate"><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 notranslate"><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 notranslate"><span class="pre">psa_aead_verify()</span></code></a> is safe and has no effect.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]803</div>
804</div>
805<div class="section" id="support-macros">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]806<h2>10.5.4. Support macros</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]807<div class="section" id="PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]808<span id="c.PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER</span></code> (macro)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]809<p>Whether the specified algorithm is an AEAD mode on a block cipher.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]810<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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]811<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]812<dl class="simple">
813<dt> <code class="docutils literal notranslate"><span class="pre">alg</span></code></dt><dd><p>An algorithm identifier (value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal notranslate"><span class="pre">psa_algorithm_t</span></code></a>).</p>
814</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]815</dl>
816<p class="rubric">Returns</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]817<p><code class="docutils literal notranslate"><span class="pre">1</span></code> if <code class="docutils literal notranslate"><span class="pre">alg</span></code> is an AEAD algorithm which is an AEAD mode based on a block cipher, <code class="docutils literal notranslate"><span class="pre">0</span></code> otherwise.</p>
818<p>This macro can return either <code class="docutils literal notranslate"><span class="pre">0</span></code> or <code class="docutils literal notranslate"><span class="pre">1</span></code> if <code class="docutils literal notranslate"><span class="pre">alg</span></code> is not a supported algorithm identifier.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]819</div>
820<div class="section" id="PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]821<span id="c.PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG</span></code> (macro)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]822<p>An AEAD algorithm with the default tag length.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]823<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) \
824 <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em></pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]825<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]826<dl class="simple">
827<dt> <code class="docutils literal notranslate"><span class="pre">aead_alg</span></code></dt><dd><p>An AEAD algorithm (<code class="docutils literal notranslate"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal notranslate"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> is true).</p>
828</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]829</dl>
830<p class="rubric">Returns</p>
831<p>The corresponding AEAD algorithm with the default tag length for that algorithm.</p>
832<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]833<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 notranslate"><span class="pre">PSA_ALG_AEAD_WITH_SHORTENED_TAG()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]834</div>
835<div class="section" id="PSA_AEAD_ENCRYPT_OUTPUT_SIZE">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]836<span id="c.PSA_AEAD_ENCRYPT_OUTPUT_SIZE"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_AEAD_ENCRYPT_OUTPUT_SIZE</span></code> (macro)</h3>
837<p>The maximum size of the output of <a class="reference internal" href="#c.psa_aead_encrypt" title="psa_aead_encrypt"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_aead_encrypt()</span></code></a>, in bytes.</p>
838<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) \
839 <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em></pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]840<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]841<dl class="simple">
842<dt> <code class="docutils literal notranslate"><span class="pre">key_type</span></code></dt><dd><p>A symmetric key type that is compatible with algorithm <code class="docutils literal notranslate"><span class="pre">alg</span></code>.</p>
843</dd>
844<dt> <code class="docutils literal notranslate"><span class="pre">alg</span></code></dt><dd><p>An AEAD algorithm (<code class="docutils literal notranslate"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal notranslate"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> is true).</p>
845</dd>
846<dt> <code class="docutils literal notranslate"><span class="pre">plaintext_length</span></code></dt><dd><p>Size of the plaintext in bytes.</p>
847</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]848</dl>
849<p class="rubric">Returns</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]850<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 notranslate"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal notranslate"><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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]851<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]852<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 notranslate"><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>
853<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 notranslate"><span class="pre">PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]854</div>
855<div class="section" id="PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]856<span id="c.PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE</span></code> (macro)</h3>
857<p>A sufficient output 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 notranslate"><span class="pre">psa_aead_encrypt()</span></code></a>, for any of the supported key types and AEAD algorithms.</p>
858<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) \
859 <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em></pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]860<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]861<dl class="simple">
862<dt> <code class="docutils literal notranslate"><span class="pre">plaintext_length</span></code></dt><dd><p>Size of the plaintext in bytes.</p>
863</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]864</dl>
865<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]866<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 notranslate"><span class="pre">psa_aead_encrypt()</span></code></a> will not fail due to an insufficient buffer size.</p>
867<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 notranslate"><span class="pre">PSA_AEAD_ENCRYPT_OUTPUT_SIZE()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]868</div>
869<div class="section" id="PSA_AEAD_DECRYPT_OUTPUT_SIZE">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]870<span id="c.PSA_AEAD_DECRYPT_OUTPUT_SIZE"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_AEAD_DECRYPT_OUTPUT_SIZE</span></code> (macro)</h3>
871<p>The maximum size of the output of <a class="reference internal" href="#c.psa_aead_decrypt" title="psa_aead_decrypt"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_aead_decrypt()</span></code></a>, in bytes.</p>
872<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) \
873 <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em></pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]874<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]875<dl class="simple">
876<dt> <code class="docutils literal notranslate"><span class="pre">key_type</span></code></dt><dd><p>A symmetric key type that is compatible with algorithm <code class="docutils literal notranslate"><span class="pre">alg</span></code>.</p>
877</dd>
878<dt> <code class="docutils literal notranslate"><span class="pre">alg</span></code></dt><dd><p>An AEAD algorithm (<code class="docutils literal notranslate"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal notranslate"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> is true).</p>
879</dd>
880<dt> <code class="docutils literal notranslate"><span class="pre">ciphertext_length</span></code></dt><dd><p>Size of the ciphertext in bytes.</p>
881</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]882</dl>
883<p class="rubric">Returns</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]884<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 notranslate"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal notranslate"><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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]885<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]886<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 notranslate"><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>
887<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 notranslate"><span class="pre">PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]888</div>
889<div class="section" id="PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]890<span id="c.PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE</span></code> (macro)</h3>
891<p>A sufficient output 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 notranslate"><span class="pre">psa_aead_decrypt()</span></code></a>, for any of the supported key types and AEAD algorithms.</p>
892<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) \
893 <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em></pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]894<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]895<dl class="simple">
896<dt> <code class="docutils literal notranslate"><span class="pre">ciphertext_length</span></code></dt><dd><p>Size of the ciphertext in bytes.</p>
897</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]898</dl>
899<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]900<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 notranslate"><span class="pre">psa_aead_decrypt()</span></code></a> will not fail due to an insufficient buffer size.</p>
901<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 notranslate"><span class="pre">PSA_AEAD_DECRYPT_OUTPUT_SIZE()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]902</div>
903<div class="section" id="PSA_AEAD_NONCE_LENGTH">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]904<span id="c.PSA_AEAD_NONCE_LENGTH"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_AEAD_NONCE_LENGTH</span></code> (macro)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]905<p>The default nonce size for an AEAD algorithm, in bytes.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]906<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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]907<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]908<dl class="simple">
909<dt> <code class="docutils literal notranslate"><span class="pre">key_type</span></code></dt><dd><p>A symmetric key type that is compatible with algorithm <code class="docutils literal notranslate"><span class="pre">alg</span></code>.</p>
910</dd>
911<dt> <code class="docutils literal notranslate"><span class="pre">alg</span></code></dt><dd><p>An AEAD algorithm (<code class="docutils literal notranslate"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal notranslate"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> is true).</p>
912</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]913</dl>
914<p class="rubric">Returns</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]915<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 notranslate"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal notranslate"><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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]916<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]917<p>This macro can be used to allocate a buffer of sufficient size to store the nonce output 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 notranslate"><span class="pre">psa_aead_generate_nonce()</span></code></a>.</p>
918<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 notranslate"><span class="pre">PSA_AEAD_NONCE_MAX_SIZE</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]919</div>
920<div class="section" id="PSA_AEAD_NONCE_MAX_SIZE">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]921<span id="c.PSA_AEAD_NONCE_MAX_SIZE"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_AEAD_NONCE_MAX_SIZE</span></code> (macro)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]922<p>The maximum nonce size for all supported AEAD algorithms, in bytes.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]923<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>
924<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 notranslate"><span class="pre">PSA_AEAD_NONCE_LENGTH()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]925</div>
926<div class="section" id="PSA_AEAD_UPDATE_OUTPUT_SIZE">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]927<span id="c.PSA_AEAD_UPDATE_OUTPUT_SIZE"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_AEAD_UPDATE_OUTPUT_SIZE</span></code> (macro)</h3>
928<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 notranslate"><span class="pre">psa_aead_update()</span></code></a>.</p>
929<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) \
930 <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em></pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]931<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]932<dl class="simple">
933<dt> <code class="docutils literal notranslate"><span class="pre">key_type</span></code></dt><dd><p>A symmetric key type that is compatible with algorithm <code class="docutils literal notranslate"><span class="pre">alg</span></code>.</p>
934</dd>
935<dt> <code class="docutils literal notranslate"><span class="pre">alg</span></code></dt><dd><p>An AEAD algorithm (<code class="docutils literal notranslate"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal notranslate"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> is true).</p>
936</dd>
937<dt> <code class="docutils literal notranslate"><span class="pre">input_length</span></code></dt><dd><p>Size of the input in bytes.</p>
938</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]939</dl>
940<p class="rubric">Returns</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]941<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 notranslate"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal notranslate"><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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]942<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]943<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 notranslate"><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>
944<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 notranslate"><span class="pre">PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]945</div>
946<div class="section" id="PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]947<span id="c.PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE</span></code> (macro)</h3>
948<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 notranslate"><span class="pre">psa_aead_update()</span></code></a>, for any of the supported key types and AEAD algorithms.</p>
949<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) \
950 <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em></pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]951<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]952<dl class="simple">
953<dt> <code class="docutils literal notranslate"><span class="pre">input_length</span></code></dt><dd><p>Size of the input in bytes.</p>
954</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]955</dl>
956<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]957<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 notranslate"><span class="pre">psa_aead_update()</span></code></a> will not fail due to an insufficient buffer size.</p>
958<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 notranslate"><span class="pre">PSA_AEAD_UPDATE_OUTPUT_SIZE()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]959</div>
960<div class="section" id="PSA_AEAD_FINISH_OUTPUT_SIZE">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]961<span id="c.PSA_AEAD_FINISH_OUTPUT_SIZE"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_AEAD_FINISH_OUTPUT_SIZE</span></code> (macro)</h3>
962<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 notranslate"><span class="pre">psa_aead_finish()</span></code></a>.</p>
963<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) \
964 <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em></pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]965<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]966<dl class="simple">
967<dt> <code class="docutils literal notranslate"><span class="pre">key_type</span></code></dt><dd><p>A symmetric key type that is compatible with algorithm <code class="docutils literal notranslate"><span class="pre">alg</span></code>.</p>
968</dd>
969<dt> <code class="docutils literal notranslate"><span class="pre">alg</span></code></dt><dd><p>An AEAD algorithm (<code class="docutils literal notranslate"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal notranslate"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> is true).</p>
970</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]971</dl>
972<p class="rubric">Returns</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]973<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 notranslate"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal notranslate"><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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]974<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]975<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 notranslate"><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>
976<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 notranslate"><span class="pre">PSA_AEAD_FINISH_OUTPUT_MAX_SIZE</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]977</div>
978<div class="section" id="PSA_AEAD_FINISH_OUTPUT_MAX_SIZE">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]979<span id="c.PSA_AEAD_FINISH_OUTPUT_MAX_SIZE"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_AEAD_FINISH_OUTPUT_MAX_SIZE</span></code> (macro)</h3>
980<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 notranslate"><span class="pre">psa_aead_finish()</span></code></a>, for any of the supported key types and AEAD algorithms.</p>
981<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>
982<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 notranslate"><span class="pre">PSA_AEAD_FINISH_OUTPUT_SIZE()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]983</div>
984<div class="section" id="PSA_AEAD_TAG_LENGTH">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]985<span id="c.PSA_AEAD_TAG_LENGTH"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_AEAD_TAG_LENGTH</span></code> (macro)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]986<p>The length of a tag for an AEAD algorithm, in bytes.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]987<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) \
988 <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em></pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]989<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]990<dl class="simple">
991<dt> <code class="docutils literal notranslate"><span class="pre">key_type</span></code></dt><dd><p>The type of the AEAD key.</p>
992</dd>
993<dt> <code class="docutils literal notranslate"><span class="pre">key_bits</span></code></dt><dd><p>The size of the AEAD key in bits.</p>
994</dd>
995<dt> <code class="docutils literal notranslate"><span class="pre">alg</span></code></dt><dd><p>An AEAD algorithm (<code class="docutils literal notranslate"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal notranslate"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> is true).</p>
996</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]997</dl>
998<p class="rubric">Returns</p>
999<p>The tag length for the specified algorithm and key.
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]1000If the AEAD algorithm does not have an identified tag that can be distinguished from the rest of the ciphertext, return <code class="docutils literal notranslate"><span class="pre">0</span></code>. If the AEAD algorithm is not recognized, return <code class="docutils literal notranslate"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal notranslate"><span class="pre">0</span></code> or a correct size for an AEAD algorithm that it recognizes, but does not support.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]1001<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]1002<p>This macro can be used to allocate a buffer of sufficient size to store 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 notranslate"><span class="pre">psa_aead_finish()</span></code></a>.</p>
1003<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 notranslate"><span class="pre">PSA_AEAD_TAG_MAX_SIZE</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]1004</div>
1005<div class="section" id="PSA_AEAD_TAG_MAX_SIZE">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]1006<span id="c.PSA_AEAD_TAG_MAX_SIZE"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_AEAD_TAG_MAX_SIZE</span></code> (macro)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]1007<p>The maximum tag size for all supported AEAD algorithms, in bytes.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]1008<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>
1009<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 notranslate"><span class="pre">PSA_AEAD_TAG_LENGTH()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]1010</div>
1011<div class="section" id="PSA_AEAD_VERIFY_OUTPUT_SIZE">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]1012<span id="c.PSA_AEAD_VERIFY_OUTPUT_SIZE"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_AEAD_VERIFY_OUTPUT_SIZE</span></code> (macro)</h3>
1013<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 notranslate"><span class="pre">psa_aead_verify()</span></code></a>.</p>
1014<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) \
1015 <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em></pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]1016<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]1017<dl class="simple">
1018<dt> <code class="docutils literal notranslate"><span class="pre">key_type</span></code></dt><dd><p>A symmetric key type that is compatible with algorithm <code class="docutils literal notranslate"><span class="pre">alg</span></code>.</p>
1019</dd>
1020<dt> <code class="docutils literal notranslate"><span class="pre">alg</span></code></dt><dd><p>An AEAD algorithm (<code class="docutils literal notranslate"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal notranslate"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> is true).</p>
1021</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]1022</dl>
1023<p class="rubric">Returns</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]1024<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 notranslate"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal notranslate"><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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]1025<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]1026<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 notranslate"><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>
1027<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 notranslate"><span class="pre">PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]1028</div>
1029<div class="section" id="PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]1030<span id="c.PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE</span></code> (macro)</h3>
1031<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 notranslate"><span class="pre">psa_aead_verify()</span></code></a>, for any of the supported key types and AEAD algorithms.</p>
1032<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>
1033<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 notranslate"><span class="pre">PSA_AEAD_VERIFY_OUTPUT_SIZE()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]1034</div>
1035</div>
1036</div>
1037
1038
1039 </div>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]1040
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]1041 </div>
1042 </div>
1043 <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]1044 <div class="sphinxsidebarwrapper"><h3><a href="../../index.html"><b>PSA Crypto API</b></a></h3>
1045IHI 0086<br/>
1046Non-confidential<br/>
1047Version 1.0.1
1048<span style="color: red; font-weight: bold;"></span>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]1049<ul>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]1050<li class="toctree-l1"><a class="reference internal" href="../../about.html">About this document</a></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]1051</ul>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]1052<ul class="current">
1053<li class="toctree-l1"><a class="reference internal" href="../../overview/intro.html">1. Introduction</a></li>
1054<li class="toctree-l1"><a class="reference internal" href="../../overview/goals.html">2. Design goals</a></li>
1055<li class="toctree-l1"><a class="reference internal" href="../../overview/functionality.html">3. Functionality overview</a></li>
1056<li class="toctree-l1"><a class="reference internal" href="../../overview/sample-arch.html">4. Sample architectures</a></li>
1057<li class="toctree-l1"><a class="reference internal" href="../../overview/conventions.html">5. Library conventions</a></li>
1058<li class="toctree-l1"><a class="reference internal" href="../../overview/implementation.html">6. Implementation considerations</a></li>
1059<li class="toctree-l1"><a class="reference internal" href="../../overview/usage.html">7. Usage considerations</a></li>
1060<li class="toctree-l1"><a class="reference internal" href="../library/index.html">8. Library management reference</a></li>
1061<li class="toctree-l1"><a class="reference internal" href="../keys/index.html">9. Key management reference</a></li>
1062<li class="toctree-l1 current"><a class="reference internal" href="index.html">10. Cryptographic operation reference</a><ul class="current">
1063<li class="toctree-l2"><a class="reference internal" href="algorithms.html">10.1. Algorithms</a></li>
1064<li class="toctree-l2"><a class="reference internal" href="hashes.html">10.2. Message digests</a></li>
1065<li class="toctree-l2"><a class="reference internal" href="macs.html">10.3. Message authentication codes (MAC)</a></li>
1066<li class="toctree-l2"><a class="reference internal" href="ciphers.html">10.4. Unauthenticated ciphers</a></li>
1067<li class="toctree-l2 current"><a class="current reference internal" href="#">10.5. Authenticated encryption with associated data (AEAD)</a><ul>
1068<li class="toctree-l3"><a class="reference internal" href="#aead-algorithms">10.5.1. AEAD algorithms</a></li>
1069<li class="toctree-l3"><a class="reference internal" href="#single-part-aead-functions">10.5.2. Single-part AEAD functions</a></li>
1070<li class="toctree-l3"><a class="reference internal" href="#multi-part-aead-operations">10.5.3. Multi-part AEAD operations</a></li>
1071<li class="toctree-l3"><a class="reference internal" href="#support-macros">10.5.4. Support macros</a></li>
1072</ul>
1073</li>
1074<li class="toctree-l2"><a class="reference internal" href="kdf.html">10.6. Key derivation</a></li>
1075<li class="toctree-l2"><a class="reference internal" href="sign.html">10.7. Asymmetric signature</a></li>
1076<li class="toctree-l2"><a class="reference internal" href="pke.html">10.8. Asymmetric encryption</a></li>
1077<li class="toctree-l2"><a class="reference internal" href="ka.html">10.9. Key agreement</a></li>
1078<li class="toctree-l2"><a class="reference internal" href="rng.html">10.10. Other cryptographic services</a></li>
1079</ul>
1080</li>
1081</ul>
1082<ul>
1083<li class="toctree-l1"><a class="reference internal" href="../../appendix/example_header.html">Example header file</a></li>
1084<li class="toctree-l1"><a class="reference internal" href="../../appendix/specdef_values.html">Example macro implementations</a></li>
1085<li class="toctree-l1"><a class="reference internal" href="../../appendix/history.html">Changes to the API</a></li>
1086</ul>
1087<ul>
1088<li class="toctree-l1"><a class="reference internal" href="../../psa_c-identifiers.html">Index of API elements</a></li>
1089</ul>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]1090<div id="searchbox" style="display: none" role="search">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]1091 <h3 id="searchlabel">Quick search</h3>
1092 <div class="searchformwrapper">
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]1093 <form class="search" action="../../search.html" method="get">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]1094 <input type="text" name="q" aria-labelledby="searchlabel" />
1095 <input type="submit" value="Go" />
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]1096 </form>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]1097 </div>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]1098</div>
1099<script type="text/javascript">$('#searchbox').show(0);</script>
1100 </div>
1101 </div>
1102 <div class="clearer"></div>
1103 </div>
1104 <div class="footer">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]1105 &copy; 2018-2020, Arm Limited or its affiliates. All rights reserved.
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]1106
1107 |
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]1108 Powered by <a href="http://sphinx-doc.org/">Sphinx 2.1.2</a>
1109 &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]1110
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]1111 </div>
1112
1113
1114
1115
1116 </body>
1117</html>