TrustedFirmware Git Browser
Code Review Sign In
review.trustedfirmware.org / mirror / mbed-crypto / 0f4df8f3e48921cf9577526366e94a6f0f3ec37c / . / docs / html / api / ops / ciphers.html
blob: 7826c9496cc91324cf34f8c0c870bb3596decbfb [file] [log] [blame]
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]1
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
3 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
4
5<html xmlns="http://www.w3.org/1999/xhtml">
6 <head>
7 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
8 <title>Unauthenticated ciphers &#8212; PSA Crypto API 1.0.0 documentation</title>
9 <link rel="stylesheet" href="../../_static/alabaster.css" type="text/css" />
10 <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
11 <script type="text/javascript">
12 var DOCUMENTATION_OPTIONS = {
13 URL_ROOT: '../../',
14 VERSION: '1.0.0',
15 COLLAPSE_INDEX: false,
16 FILE_SUFFIX: '.html',
17 HAS_SOURCE: true,
18 SOURCELINK_SUFFIX: '.txt'
19 };
20 </script>
21 <script type="text/javascript" src="../../_static/jquery.js"></script>
22 <script type="text/javascript" src="../../_static/underscore.js"></script>
23 <script type="text/javascript" src="../../_static/doctools.js"></script>
24 <link rel="index" title="Index" href="../../genindex.html" />
25 <link rel="search" title="Search" href="../../search.html" />
26 <link rel="next" title="Authenticated encryption with associated data (AEAD)" href="aead.html" />
27 <link rel="prev" title="Message authentication codes (MAC)" href="macs.html" />
28
29 <link rel="stylesheet" href="../../_static/custom.css" type="text/css" />
30
31 <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
32
33 </head>
34 <body>
35
36
37 <div class="document">
38 <div class="documentwrapper">
39 <div class="bodywrapper">
40 <div class="body" role="main">
41
42 <div class="section" id="unauthenticated-ciphers">
43<span id="ciphers"></span><h1>Unauthenticated ciphers</h1>
44<div class="admonition warning">
45<p class="first admonition-title">Warning</p>
46<p>The unauthenticated cipher API is provided to implement legacy protocols and
47for use cases where the data integrity and authenticity is guaranteed by
48non-cryptographic means.</p>
49<p class="last">It is recommended that newer protocols use <em><a class="reference internal" href="aead.html#aead"><span class="std std-ref">Authenticated encryption with associated data (AEAD)</span></a></em>.</p>
50</div>
51<div class="section" id="cipher-algorithms">
52<span id="id1"></span><h2>Cipher algorithms</h2>
53<div class="section" id="PSA_ALG_STREAM_CIPHER">
54<span id="c.PSA_ALG_STREAM_CIPHER"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_STREAM_CIPHER</span></code> (macro)</h3>
55<p>The stream cipher mode of a stream cipher algorithm.</p>
56<pre class="literal-block">
57#define <a class="reference internal" href="#c.PSA_ALG_STREAM_CIPHER" title="PSA_ALG_STREAM_CIPHER">PSA_ALG_STREAM_CIPHER</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x04800100)
58</pre>
59<p>The underlying stream cipher is determined by the key type:</p>
60<ul class="simple">
61<li>To use ChaCha20, use a key type of <a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_CHACHA20" title="PSA_KEY_TYPE_CHACHA20"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_CHACHA20</span></code></a> and algorithm id <a class="reference internal" href="#c.PSA_ALG_STREAM_CIPHER" title="PSA_ALG_STREAM_CIPHER"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_STREAM_CIPHER</span></code></a>.</li>
62<li>To use ARC4, use a key type of <a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_ARC4" title="PSA_KEY_TYPE_ARC4"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_ARC4</span></code></a> and algorithm id <a class="reference internal" href="#c.PSA_ALG_STREAM_CIPHER" title="PSA_ALG_STREAM_CIPHER"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_STREAM_CIPHER</span></code></a>.</li>
63</ul>
64</div>
65<div class="section" id="PSA_ALG_CTR">
66<span id="c.PSA_ALG_CTR"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_CTR</span></code> (macro)</h3>
67<p>A stream cipher built using the Counter (CTR) mode of a block cipher.</p>
68<pre class="literal-block">
69#define <a class="reference internal" href="#c.PSA_ALG_CTR" title="PSA_ALG_CTR">PSA_ALG_CTR</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x04c01000)
70</pre>
71<p>CTR is a stream cipher which is built from a block cipher. The underlying block cipher is determined by the key type. For example, to use AES-128-CTR, use this algorithm with a key of type <a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_AES" title="PSA_KEY_TYPE_AES"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_AES</span></code></a> and a length of 128 bits (16 bytes).</p>
72</div>
73<div class="section" id="PSA_ALG_CFB">
74<span id="c.PSA_ALG_CFB"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_CFB</span></code> (macro)</h3>
75<p>A stream cipher built using the Cipher Feedback (CFB) mode of a block cipher.</p>
76<pre class="literal-block">
77#define <a class="reference internal" href="#c.PSA_ALG_CFB" title="PSA_ALG_CFB">PSA_ALG_CFB</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x04c01100)
78</pre>
79<p>The underlying block cipher is determined by the key type.</p>
80</div>
81<div class="section" id="PSA_ALG_OFB">
82<span id="c.PSA_ALG_OFB"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_OFB</span></code> (macro)</h3>
83<p>A stream cipher built using the Output Feedback (OFB) mode of a block cipher.</p>
84<pre class="literal-block">
85#define <a class="reference internal" href="#c.PSA_ALG_OFB" title="PSA_ALG_OFB">PSA_ALG_OFB</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x04c01200)
86</pre>
87<p>The underlying block cipher is determined by the key type.</p>
88</div>
89<div class="section" id="PSA_ALG_XTS">
90<span id="c.PSA_ALG_XTS"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_XTS</span></code> (macro)</h3>
91<p>The XTS cipher mode of a block cipher.</p>
92<pre class="literal-block">
93#define <a class="reference internal" href="#c.PSA_ALG_XTS" title="PSA_ALG_XTS">PSA_ALG_XTS</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x0440ff00)
94</pre>
95<p>XTS is a cipher mode which is built from a block cipher. It requires at least one full block of input, but beyond this minimum the input does not need to be a whole number of blocks.</p>
96</div>
97<div class="section" id="PSA_ALG_ECB_NO_PADDING">
98<span id="c.PSA_ALG_ECB_NO_PADDING"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_ECB_NO_PADDING</span></code> (macro)</h3>
99<p>The Electronic Code Book (ECB) mode of a block cipher, with no padding.</p>
100<pre class="literal-block">
101#define <a class="reference internal" href="#c.PSA_ALG_ECB_NO_PADDING" title="PSA_ALG_ECB_NO_PADDING">PSA_ALG_ECB_NO_PADDING</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x04404400)
102</pre>
103<div class="admonition warning">
104<p class="first admonition-title">Warning</p>
105<p class="last">ECB mode does not protect the confidentiality of the encrypted data except in extremely narrow circumstances. It is recommended that applications only use ECB if they need to construct an operating mode that the implementation does not provide. Implementations are encouraged to provide the modes that applications need in preference to supporting direct access to ECB.</p>
106</div>
107<p>The underlying block cipher is determined by the key type.</p>
108<p>This symmetric cipher mode can only be used with messages whose lengths are whole number of blocks for the chosen block cipher.</p>
109<p>ECB mode does not accept an initialization vector (IV). When using a multi-part cipher operation with this algorithm, <a class="reference internal" href="#c.psa_cipher_generate_iv" title="psa_cipher_generate_iv"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_generate_iv()</span></code></a> and <a class="reference internal" href="#c.psa_cipher_set_iv" title="psa_cipher_set_iv"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_set_iv()</span></code></a> must not be called.</p>
110</div>
111<div class="section" id="PSA_ALG_CBC_NO_PADDING">
112<span id="c.PSA_ALG_CBC_NO_PADDING"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_CBC_NO_PADDING</span></code> (macro)</h3>
113<p>The Cipher Block Chaining (CBC) mode of a block cipher, with no padding.</p>
114<pre class="literal-block">
115#define <a class="reference internal" href="#c.PSA_ALG_CBC_NO_PADDING" title="PSA_ALG_CBC_NO_PADDING">PSA_ALG_CBC_NO_PADDING</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x04404000)
116</pre>
117<p>The underlying block cipher is determined by the key type.</p>
118<p>This symmetric cipher mode can only be used with messages whose lengths are whole number of blocks for the chosen block cipher.</p>
119</div>
120<div class="section" id="PSA_ALG_CBC_PKCS7">
121<span id="c.PSA_ALG_CBC_PKCS7"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_CBC_PKCS7</span></code> (macro)</h3>
122<p>The Cipher Block Chaining (CBC) mode of a block cipher, with PKCS#7 padding.</p>
123<pre class="literal-block">
124#define <a class="reference internal" href="#c.PSA_ALG_CBC_PKCS7" title="PSA_ALG_CBC_PKCS7">PSA_ALG_CBC_PKCS7</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x04404100)
125</pre>
126<p>The underlying block cipher is determined by the key type.</p>
127<p>This is the padding method defined by PKCS#7 <a class="reference external" href="https://tools.ietf.org/html/rfc2315.html#section-10.3">RFC 2315 §10.3</a>.</p>
128</div>
129</div>
130<div class="section" id="single-part-cipher-functions">
131<h2>Single-part cipher functions</h2>
132<div class="section" id="psa_cipher_encrypt">
133<span id="c.psa_cipher_encrypt"></span><h3><code class="docutils literal"><span class="pre">psa_cipher_encrypt</span></code> (function)</h3>
134<p>Encrypt a message using a symmetric cipher.</p>
135<pre class="literal-block">
136<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_cipher_encrypt" title="psa_cipher_encrypt">psa_cipher_encrypt</a>(<a class="reference internal" href="../keys/attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
137 <a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
138 const uint8_t * input,
139 size_t input_length,
140 uint8_t * output,
141 size_t output_size,
142 size_t * output_length);
143</pre>
144<p class="rubric">Parameters</p>
145<dl class="docutils">
146<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
147<dd>Identifier of the key to use for the operation.
148It must allow the usage <a class="reference internal" href="../keys/usage.html#c.PSA_KEY_USAGE_ENCRYPT" title="PSA_KEY_USAGE_ENCRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_ENCRYPT</span></code></a>.</dd>
149<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
150<dd>The cipher algorithm to compute (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_CIPHER" title="PSA_ALG_IS_CIPHER"><code class="docutils literal"><span class="pre">PSA_ALG_IS_CIPHER</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
151<dt> <code class="docutils literal"><span class="pre">input</span></code></dt>
152<dd>Buffer containing the message to encrypt.</dd>
153<dt> <code class="docutils literal"><span class="pre">input_length</span></code></dt>
154<dd>Size of the <code class="docutils literal"><span class="pre">input</span></code> buffer in bytes.</dd>
155<dt> <code class="docutils literal"><span class="pre">output</span></code></dt>
156<dd>Buffer where the output is to be written. The output contains the IV followed by the ciphertext proper.</dd>
157<dt> <code class="docutils literal"><span class="pre">output_size</span></code></dt>
158<dd><p class="first">Size of the <code class="docutils literal"><span class="pre">output</span></code> buffer in bytes. This must be appropriate for the selected algorithm and key:</p>
159<ul class="last simple">
160<li>A sufficient output size is <a class="reference internal" href="#c.PSA_CIPHER_ENCRYPT_OUTPUT_SIZE" title="PSA_CIPHER_ENCRYPT_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_CIPHER_ENCRYPT_OUTPUT_SIZE</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">key_type</span></code><code class="docutils literal"><span class="pre">,</span> </code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">,</span> </code><code class="docutils literal"><span class="pre">input_length</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">key_type</span></code> is the type of <code class="docutils literal"><span class="pre">key</span></code>.</li>
161<li><a class="reference internal" href="#c.PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE" title="PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE"><code class="docutils literal"><span class="pre">PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">input_length</span></code><code class="docutils literal"><span class="pre">)</span></code> evaluates to the maximum output size of any supported cipher encryption.</li>
162</ul>
163</dd>
164<dt> <code class="docutils literal"><span class="pre">output_length</span></code></dt>
165<dd>On success, the number of bytes that make up the output.</dd>
166</dl>
167<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
168<dl class="docutils">
169<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
170<dd>Success.</dd>
171<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
172<dd></dd>
173<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
174<dd>The key does not have the <a class="reference internal" href="../keys/usage.html#c.PSA_KEY_USAGE_ENCRYPT" title="PSA_KEY_USAGE_ENCRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_ENCRYPT</span></code></a> flag, or it does not permit the requested algorithm.</dd>
175<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
176<dd><code class="docutils literal"><span class="pre">key</span></code> is not compatible with <code class="docutils literal"><span class="pre">alg</span></code>.</dd>
177<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
178<dd><code class="docutils literal"><span class="pre">alg</span></code> is not supported or is not a cipher algorithm.</dd>
179<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BUFFER_TOO_SMALL" title="PSA_ERROR_BUFFER_TOO_SMALL"><code class="docutils literal"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a></dt>
180<dd><code class="docutils literal"><span class="pre">output_size</span></code> is too small. <a class="reference internal" href="#c.PSA_CIPHER_ENCRYPT_OUTPUT_SIZE" title="PSA_CIPHER_ENCRYPT_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_CIPHER_ENCRYPT_OUTPUT_SIZE()</span></code></a> or <a class="reference internal" href="#c.PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE" title="PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE()</span></code></a> can be used to determine the required buffer size.</dd>
181<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt>
182<dd></dd>
183<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
184<dd></dd>
185<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt>
186<dd></dd>
187<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
188<dd></dd>
189<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt>
190<dd></dd>
191<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt>
192<dd></dd>
193<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt>
194<dd></dd>
195<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
196<dd>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</dd>
197</dl>
198<p class="rubric">Description</p>
199<p>This function encrypts a message with a random initialization vector (IV).
200The length of the IV is <a class="reference internal" href="#c.PSA_CIPHER_IV_LENGTH" title="PSA_CIPHER_IV_LENGTH"><code class="docutils literal"><span class="pre">PSA_CIPHER_IV_LENGTH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">key_type</span></code><code class="docutils literal"><span class="pre">,</span> </code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">key_type</span></code> is the type of <code class="docutils literal"><span class="pre">key</span></code>.
201The output of <a class="reference internal" href="#c.psa_cipher_encrypt" title="psa_cipher_encrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_encrypt()</span></code></a> is the IV followed by the ciphertext.</p>
202<p>Use the multi-part operation interface with a <a class="reference internal" href="#c.psa_cipher_operation_t" title="psa_cipher_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_cipher_operation_t</span></code></a> object to provide other forms of IV or to manage the IV and ciphertext independently.</p>
203</div>
204<div class="section" id="psa_cipher_decrypt">
205<span id="c.psa_cipher_decrypt"></span><h3><code class="docutils literal"><span class="pre">psa_cipher_decrypt</span></code> (function)</h3>
206<p>Decrypt a message using a symmetric cipher.</p>
207<pre class="literal-block">
208<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_cipher_decrypt" title="psa_cipher_decrypt">psa_cipher_decrypt</a>(<a class="reference internal" href="../keys/attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
209 <a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
210 const uint8_t * input,
211 size_t input_length,
212 uint8_t * output,
213 size_t output_size,
214 size_t * output_length);
215</pre>
216<p class="rubric">Parameters</p>
217<dl class="docutils">
218<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
219<dd>Identifier of the key to use for the operation. It must remain valid until the operation terminates.
220It must allow the usage <a class="reference internal" href="../keys/usage.html#c.PSA_KEY_USAGE_DECRYPT" title="PSA_KEY_USAGE_DECRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DECRYPT</span></code></a>.</dd>
221<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
222<dd>The cipher algorithm to compute (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_CIPHER" title="PSA_ALG_IS_CIPHER"><code class="docutils literal"><span class="pre">PSA_ALG_IS_CIPHER</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
223<dt> <code class="docutils literal"><span class="pre">input</span></code></dt>
224<dd>Buffer containing the message to decrypt. This consists of the IV followed by the ciphertext proper.</dd>
225<dt> <code class="docutils literal"><span class="pre">input_length</span></code></dt>
226<dd>Size of the <code class="docutils literal"><span class="pre">input</span></code> buffer in bytes.</dd>
227<dt> <code class="docutils literal"><span class="pre">output</span></code></dt>
228<dd>Buffer where the plaintext is to be written.</dd>
229<dt> <code class="docutils literal"><span class="pre">output_size</span></code></dt>
230<dd><p class="first">Size of the <code class="docutils literal"><span class="pre">output</span></code> buffer in bytes. This must be appropriate for the selected algorithm and key:</p>
231<ul class="last simple">
232<li>A sufficient output size is <a class="reference internal" href="#c.PSA_CIPHER_DECRYPT_OUTPUT_SIZE" title="PSA_CIPHER_DECRYPT_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_CIPHER_DECRYPT_OUTPUT_SIZE</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">key_type</span></code><code class="docutils literal"><span class="pre">,</span> </code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">,</span> </code><code class="docutils literal"><span class="pre">input_length</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">key_type</span></code> is the type of <code class="docutils literal"><span class="pre">key</span></code>.</li>
233<li><a class="reference internal" href="#c.PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE" title="PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE"><code class="docutils literal"><span class="pre">PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">input_length</span></code><code class="docutils literal"><span class="pre">)</span></code> evaluates to the maximum output size of any supported cipher decryption.</li>
234</ul>
235</dd>
236<dt> <code class="docutils literal"><span class="pre">output_length</span></code></dt>
237<dd>On success, the number of bytes that make up the output.</dd>
238</dl>
239<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
240<dl class="docutils">
241<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
242<dd>Success.</dd>
243<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
244<dd></dd>
245<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
246<dd>The key does not have the <a class="reference internal" href="../keys/usage.html#c.PSA_KEY_USAGE_DECRYPT" title="PSA_KEY_USAGE_DECRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DECRYPT</span></code></a> flag, or it does not permit the requested algorithm.</dd>
247<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
248<dd><code class="docutils literal"><span class="pre">key</span></code> is not compatible with <code class="docutils literal"><span class="pre">alg</span></code>.</dd>
249<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
250<dd><code class="docutils literal"><span class="pre">alg</span></code> is not supported or is not a cipher algorithm.</dd>
251<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BUFFER_TOO_SMALL" title="PSA_ERROR_BUFFER_TOO_SMALL"><code class="docutils literal"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a></dt>
252<dd><code class="docutils literal"><span class="pre">output_size</span></code> is too small. <a class="reference internal" href="#c.PSA_CIPHER_DECRYPT_OUTPUT_SIZE" title="PSA_CIPHER_DECRYPT_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_CIPHER_DECRYPT_OUTPUT_SIZE()</span></code></a> or <a class="reference internal" href="#c.PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE" title="PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE()</span></code></a> can be used to determine the required buffer size.</dd>
253<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt>
254<dd></dd>
255<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
256<dd></dd>
257<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt>
258<dd></dd>
259<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt>
260<dd></dd>
261<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt>
262<dd></dd>
263<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt>
264<dd></dd>
265<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
266<dd></dd>
267<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
268<dd>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</dd>
269</dl>
270<p class="rubric">Description</p>
271<p>This function decrypts a message encrypted with a symmetric cipher.</p>
272<p>The input to this function must contain the IV followed by the ciphertext, as output by <a class="reference internal" href="#c.psa_cipher_encrypt" title="psa_cipher_encrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_encrypt()</span></code></a>. The IV must be <a class="reference internal" href="#c.PSA_CIPHER_IV_LENGTH" title="PSA_CIPHER_IV_LENGTH"><code class="docutils literal"><span class="pre">PSA_CIPHER_IV_LENGTH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">key_type</span></code><code class="docutils literal"><span class="pre">,</span> </code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> bytes in length, where <code class="docutils literal"><span class="pre">key_type</span></code> is the type of <code class="docutils literal"><span class="pre">key</span></code>.</p>
273<p>Use the multi-part operation interface with a <a class="reference internal" href="#c.psa_cipher_operation_t" title="psa_cipher_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_cipher_operation_t</span></code></a> object to decrypt data which is not in the expected input format.</p>
274</div>
275</div>
276<div class="section" id="multi-part-cipher-operations">
277<h2>Multi-part cipher operations</h2>
278<div class="section" id="psa_cipher_operation_t">
279<span id="c.psa_cipher_operation_t"></span><h3><code class="docutils literal"><span class="pre">psa_cipher_operation_t</span></code> (type)</h3>
280<p>The type of the state object for multi-part cipher operations.</p>
281<pre class="literal-block">
282typedef <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_cipher_operation_t" title="psa_cipher_operation_t">psa_cipher_operation_t</a>;
283</pre>
284<p>Before calling any function on a cipher operation object, the application must initialize it by any of the following means:</p>
285<ul>
286<li><p class="first">Set the object to all-bits-zero, for example:</p>
287<pre class="literal-block">
288<a class="reference internal" href="#c.psa_cipher_operation_t" title="psa_cipher_operation_t">psa_cipher_operation_t</a> operation;
289memset(&amp;operation, 0, sizeof(operation));
290</pre>
291</li>
292<li><p class="first">Initialize the object to logical zero values by declaring the object as static or global without an explicit initializer, for example:</p>
293<pre class="literal-block">
294static <a class="reference internal" href="#c.psa_cipher_operation_t" title="psa_cipher_operation_t">psa_cipher_operation_t</a> operation;
295</pre>
296</li>
297<li><p class="first">Initialize the object to the initializer <a class="reference internal" href="#c.PSA_CIPHER_OPERATION_INIT" title="PSA_CIPHER_OPERATION_INIT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_CIPHER_OPERATION_INIT</span></code></a>, for example:</p>
298<pre class="literal-block">
299<a class="reference internal" href="#c.psa_cipher_operation_t" title="psa_cipher_operation_t">psa_cipher_operation_t</a> operation = <a class="reference internal" href="#c.PSA_CIPHER_OPERATION_INIT" title="PSA_CIPHER_OPERATION_INIT">PSA_CIPHER_OPERATION_INIT</a>;
300</pre>
301</li>
302<li><p class="first">Assign the result of the function <a class="reference internal" href="#c.psa_cipher_operation_init" title="psa_cipher_operation_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_operation_init()</span></code></a> to the object, for example:</p>
303<pre class="literal-block">
304<a class="reference internal" href="#c.psa_cipher_operation_t" title="psa_cipher_operation_t">psa_cipher_operation_t</a> operation;
305operation = <a class="reference internal" href="#c.psa_cipher_operation_init" title="psa_cipher_operation_init">psa_cipher_operation_init</a>();
306</pre>
307</li>
308</ul>
309<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>
310</div>
311<div class="section" id="PSA_CIPHER_OPERATION_INIT">
312<span id="c.PSA_CIPHER_OPERATION_INIT"></span><h3><code class="docutils literal"><span class="pre">PSA_CIPHER_OPERATION_INIT</span></code> (macro)</h3>
313<p>This macro returns a suitable initializer for a cipher operation object of type <a class="reference internal" href="#c.psa_cipher_operation_t" title="psa_cipher_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_cipher_operation_t</span></code></a>.</p>
314<pre class="literal-block">
315#define <a class="reference internal" href="#c.PSA_CIPHER_OPERATION_INIT" title="PSA_CIPHER_OPERATION_INIT">PSA_CIPHER_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>
316</pre>
317</div>
318<div class="section" id="psa_cipher_operation_init">
319<span id="c.psa_cipher_operation_init"></span><h3><code class="docutils literal"><span class="pre">psa_cipher_operation_init</span></code> (function)</h3>
320<p>Return an initial value for a cipher operation object.</p>
321<pre class="literal-block">
322<a class="reference internal" href="#c.psa_cipher_operation_t" title="psa_cipher_operation_t">psa_cipher_operation_t</a> <a class="reference internal" href="#c.psa_cipher_operation_init" title="psa_cipher_operation_init">psa_cipher_operation_init</a>(void);
323</pre>
324<p class="rubric">Returns: <a class="reference internal" href="#c.psa_cipher_operation_t" title="psa_cipher_operation_t"><code class="docutils literal"><span class="pre">psa_cipher_operation_t</span></code></a></p>
325</div>
326<div class="section" id="psa_cipher_encrypt_setup">
327<span id="c.psa_cipher_encrypt_setup"></span><h3><code class="docutils literal"><span class="pre">psa_cipher_encrypt_setup</span></code> (function)</h3>
328<p>Set the key for a multi-part symmetric encryption operation.</p>
329<pre class="literal-block">
330<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_cipher_encrypt_setup" title="psa_cipher_encrypt_setup">psa_cipher_encrypt_setup</a>(<a class="reference internal" href="#c.psa_cipher_operation_t" title="psa_cipher_operation_t">psa_cipher_operation_t</a> * operation,
331 <a class="reference internal" href="../keys/attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
332 <a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg);
333</pre>
334<p class="rubric">Parameters</p>
335<dl class="docutils">
336<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
337<dd>The operation object to set up. It must have been initialized as per the documentation for <a class="reference internal" href="#c.psa_cipher_operation_t" title="psa_cipher_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_cipher_operation_t</span></code></a> and not yet in use.</dd>
338<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
339<dd>Identifier of the key to use for the operation. It must remain valid until the operation terminates.
340It must allow the usage <a class="reference internal" href="../keys/usage.html#c.PSA_KEY_USAGE_ENCRYPT" title="PSA_KEY_USAGE_ENCRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_ENCRYPT</span></code></a>.</dd>
341<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
342<dd>The cipher algorithm to compute (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_CIPHER" title="PSA_ALG_IS_CIPHER"><code class="docutils literal"><span class="pre">PSA_ALG_IS_CIPHER</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
343</dl>
344<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
345<dl class="docutils">
346<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
347<dd>Success.</dd>
348<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
349<dd></dd>
350<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
351<dd>The key does not have the <a class="reference internal" href="../keys/usage.html#c.PSA_KEY_USAGE_ENCRYPT" title="PSA_KEY_USAGE_ENCRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_ENCRYPT</span></code></a> flag, or it does not permit the requested algorithm.</dd>
352<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
353<dd><code class="docutils literal"><span class="pre">key</span></code> is not compatible with <code class="docutils literal"><span class="pre">alg</span></code>.</dd>
354<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
355<dd><code class="docutils literal"><span class="pre">alg</span></code> is not supported or is not a cipher algorithm.</dd>
356<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt>
357<dd></dd>
358<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
359<dd></dd>
360<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt>
361<dd></dd>
362<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
363<dd></dd>
364<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt>
365<dd></dd>
366<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt>
367<dd></dd>
368<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt>
369<dd></dd>
370<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
371<dd>The operation state is not valid: it must be inactive.</dd>
372<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
373<dd>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</dd>
374</dl>
375<p class="rubric">Description</p>
376<p>The sequence of operations to encrypt a message with a symmetric cipher is as follows:</p>
377<ol class="arabic simple">
378<li>Allocate an operation object which will be passed to all the functions listed here.</li>
379<li>Initialize the operation object with one of the methods described in the documentation for <a class="reference internal" href="#c.psa_cipher_operation_t" title="psa_cipher_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_cipher_operation_t</span></code></a>, e.g. <a class="reference internal" href="#c.PSA_CIPHER_OPERATION_INIT" title="PSA_CIPHER_OPERATION_INIT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_CIPHER_OPERATION_INIT</span></code></a>.</li>
380<li>Call <a class="reference internal" href="#c.psa_cipher_encrypt_setup" title="psa_cipher_encrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_encrypt_setup()</span></code></a> to specify the algorithm and key.</li>
381<li>Call either <a class="reference internal" href="#c.psa_cipher_generate_iv" title="psa_cipher_generate_iv"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_generate_iv()</span></code></a> or <a class="reference internal" href="#c.psa_cipher_set_iv" title="psa_cipher_set_iv"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_set_iv()</span></code></a> to generate or set the initialization vector (IV), if the algorithm requires one. It is recommended to use <a class="reference internal" href="#c.psa_cipher_generate_iv" title="psa_cipher_generate_iv"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_generate_iv()</span></code></a> unless the protocol being implemented requires a specific IV value.</li>
382<li>Call <a class="reference internal" href="#c.psa_cipher_update" title="psa_cipher_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_update()</span></code></a> zero, one or more times, passing a fragment of the message each time.</li>
383<li>Call <a class="reference internal" href="#c.psa_cipher_finish" title="psa_cipher_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_finish()</span></code></a>.</li>
384</ol>
385<p>If an error occurs at any step after a call to <a class="reference internal" href="#c.psa_cipher_encrypt_setup" title="psa_cipher_encrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_encrypt_setup()</span></code></a>, the operation will need to be reset by a call to <a class="reference internal" href="#c.psa_cipher_abort" title="psa_cipher_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_abort()</span></code></a>. The application can call <a class="reference internal" href="#c.psa_cipher_abort" title="psa_cipher_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_abort()</span></code></a> at any time after the operation has been initialized.</p>
386<p>After a successful call to <a class="reference internal" href="#c.psa_cipher_encrypt_setup" title="psa_cipher_encrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_encrypt_setup()</span></code></a>, the application must eventually terminate the operation. The following events terminate an operation:</p>
387<ul class="simple">
388<li>A successful call to <a class="reference internal" href="#c.psa_cipher_finish" title="psa_cipher_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_finish()</span></code></a>.</li>
389<li>A call to <a class="reference internal" href="#c.psa_cipher_abort" title="psa_cipher_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_abort()</span></code></a>.</li>
390</ul>
391</div>
392<div class="section" id="psa_cipher_decrypt_setup">
393<span id="c.psa_cipher_decrypt_setup"></span><h3><code class="docutils literal"><span class="pre">psa_cipher_decrypt_setup</span></code> (function)</h3>
394<p>Set the key for a multi-part symmetric decryption operation.</p>
395<pre class="literal-block">
396<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_cipher_decrypt_setup" title="psa_cipher_decrypt_setup">psa_cipher_decrypt_setup</a>(<a class="reference internal" href="#c.psa_cipher_operation_t" title="psa_cipher_operation_t">psa_cipher_operation_t</a> * operation,
397 <a class="reference internal" href="../keys/attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
398 <a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg);
399</pre>
400<p class="rubric">Parameters</p>
401<dl class="docutils">
402<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
403<dd>The operation object to set up. It must have been initialized as per the documentation for <a class="reference internal" href="#c.psa_cipher_operation_t" title="psa_cipher_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_cipher_operation_t</span></code></a> and not yet in use.</dd>
404<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
405<dd>Identifier of the key to use for the operation. It must remain valid until the operation terminates.
406It must allow the usage <a class="reference internal" href="../keys/usage.html#c.PSA_KEY_USAGE_DECRYPT" title="PSA_KEY_USAGE_DECRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DECRYPT</span></code></a>.</dd>
407<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
408<dd>The cipher algorithm to compute (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_CIPHER" title="PSA_ALG_IS_CIPHER"><code class="docutils literal"><span class="pre">PSA_ALG_IS_CIPHER</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
409</dl>
410<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
411<dl class="docutils">
412<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
413<dd>Success.</dd>
414<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
415<dd></dd>
416<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
417<dd>The key does not have the <a class="reference internal" href="../keys/usage.html#c.PSA_KEY_USAGE_DECRYPT" title="PSA_KEY_USAGE_DECRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DECRYPT</span></code></a> flag, or it does not permit the requested algorithm.</dd>
418<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
419<dd><code class="docutils literal"><span class="pre">key</span></code> is not compatible with <code class="docutils literal"><span class="pre">alg</span></code>.</dd>
420<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
421<dd><code class="docutils literal"><span class="pre">alg</span></code> is not supported or is not a cipher algorithm.</dd>
422<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt>
423<dd></dd>
424<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
425<dd></dd>
426<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt>
427<dd></dd>
428<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
429<dd></dd>
430<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt>
431<dd></dd>
432<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt>
433<dd></dd>
434<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt>
435<dd></dd>
436<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
437<dd>The operation state is not valid: it must be inactive.</dd>
438<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
439<dd>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</dd>
440</dl>
441<p class="rubric">Description</p>
442<p>The sequence of operations to decrypt a message with a symmetric cipher is as follows:</p>
443<ol class="arabic simple">
444<li>Allocate an operation object which will be passed to all the functions listed here.</li>
445<li>Initialize the operation object with one of the methods described in the documentation for <a class="reference internal" href="#c.psa_cipher_operation_t" title="psa_cipher_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_cipher_operation_t</span></code></a>, e.g. <a class="reference internal" href="#c.PSA_CIPHER_OPERATION_INIT" title="PSA_CIPHER_OPERATION_INIT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_CIPHER_OPERATION_INIT</span></code></a>.</li>
446<li>Call <a class="reference internal" href="#c.psa_cipher_decrypt_setup" title="psa_cipher_decrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_decrypt_setup()</span></code></a> to specify the algorithm and key.</li>
447<li>Call <a class="reference internal" href="#c.psa_cipher_set_iv" title="psa_cipher_set_iv"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_set_iv()</span></code></a> with the initialization vector (IV) for the decryption, if the algorithm requires one. This must match the IV used for the encryption.</li>
448<li>Call <a class="reference internal" href="#c.psa_cipher_update" title="psa_cipher_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_update()</span></code></a> zero, one or more times, passing a fragment of the message each time.</li>
449<li>Call <a class="reference internal" href="#c.psa_cipher_finish" title="psa_cipher_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_finish()</span></code></a>.</li>
450</ol>
451<p>If an error occurs at any step after a call to <a class="reference internal" href="#c.psa_cipher_decrypt_setup" title="psa_cipher_decrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_decrypt_setup()</span></code></a>, the operation will need to be reset by a call to <a class="reference internal" href="#c.psa_cipher_abort" title="psa_cipher_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_abort()</span></code></a>. The application can call <a class="reference internal" href="#c.psa_cipher_abort" title="psa_cipher_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_abort()</span></code></a> at any time after the operation has been initialized.</p>
452<p>After a successful call to <a class="reference internal" href="#c.psa_cipher_decrypt_setup" title="psa_cipher_decrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_decrypt_setup()</span></code></a>, the application must eventually terminate the operation. The following events terminate an operation:</p>
453<ul class="simple">
454<li>A successful call to <a class="reference internal" href="#c.psa_cipher_finish" title="psa_cipher_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_finish()</span></code></a>.</li>
455<li>A call to <a class="reference internal" href="#c.psa_cipher_abort" title="psa_cipher_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_abort()</span></code></a>.</li>
456</ul>
457</div>
458<div class="section" id="psa_cipher_generate_iv">
459<span id="c.psa_cipher_generate_iv"></span><h3><code class="docutils literal"><span class="pre">psa_cipher_generate_iv</span></code> (function)</h3>
460<p>Generate an initialization vector (IV) for a symmetric encryption operation.</p>
461<pre class="literal-block">
462<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_cipher_generate_iv" title="psa_cipher_generate_iv">psa_cipher_generate_iv</a>(<a class="reference internal" href="#c.psa_cipher_operation_t" title="psa_cipher_operation_t">psa_cipher_operation_t</a> * operation,
463 uint8_t * iv,
464 size_t iv_size,
465 size_t * iv_length);
466</pre>
467<p class="rubric">Parameters</p>
468<dl class="docutils">
469<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
470<dd>Active cipher operation.</dd>
471<dt> <code class="docutils literal"><span class="pre">iv</span></code></dt>
472<dd>Buffer where the generated IV is to be written.</dd>
473<dt> <code class="docutils literal"><span class="pre">iv_size</span></code></dt>
474<dd>Size of the <code class="docutils literal"><span class="pre">iv</span></code> buffer in bytes. This must be at least <a class="reference internal" href="#c.PSA_CIPHER_IV_LENGTH" title="PSA_CIPHER_IV_LENGTH"><code class="docutils literal"><span class="pre">PSA_CIPHER_IV_LENGTH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">key_type</span></code><code class="docutils literal"><span class="pre">,</span> </code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">key_type</span></code> and <code class="docutils literal"><span class="pre">alg</span></code> are type of key and the algorithm respectively that were used to set up the cipher operation.</dd>
475<dt> <code class="docutils literal"><span class="pre">iv_length</span></code></dt>
476<dd>On success, the number of bytes of the generated IV.</dd>
477</dl>
478<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
479<dl class="docutils">
480<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
481<dd>Success.</dd>
482<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
483<dd><p class="first">Either:</p>
484<ul class="last simple">
485<li>The cipher algorithm does not use an IV.</li>
486<li>The operation state is not valid: it must be active, with no IV set.</li>
487</ul>
488</dd>
489<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BUFFER_TOO_SMALL" title="PSA_ERROR_BUFFER_TOO_SMALL"><code class="docutils literal"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a></dt>
490<dd>The size of the <code class="docutils literal"><span class="pre">iv</span></code> buffer is too small. <a class="reference internal" href="#c.PSA_CIPHER_IV_LENGTH" title="PSA_CIPHER_IV_LENGTH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_CIPHER_IV_LENGTH()</span></code></a> or <a class="reference internal" href="#c.PSA_CIPHER_IV_MAX_SIZE" title="PSA_CIPHER_IV_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_CIPHER_IV_MAX_SIZE</span></code></a> can be used to determine the required buffer size.</dd>
491<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt>
492<dd></dd>
493<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
494<dd></dd>
495<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt>
496<dd></dd>
497<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
498<dd></dd>
499<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt>
500<dd></dd>
501<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt>
502<dd></dd>
503<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt>
504<dd></dd>
505<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
506<dd>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</dd>
507</dl>
508<p class="rubric">Description</p>
509<p>This function generates a random IV, nonce or initial counter value for the encryption operation as appropriate for the chosen algorithm, key type and key size.</p>
510<p>The generated IV is always the default length for the key and algorithm: <a class="reference internal" href="#c.PSA_CIPHER_IV_LENGTH" title="PSA_CIPHER_IV_LENGTH"><code class="docutils literal"><span class="pre">PSA_CIPHER_IV_LENGTH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">key_type</span></code><code class="docutils literal"><span class="pre">,</span> </code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code>, where <code class="docutils literal"><span class="pre">key_type</span></code> is the type of key and <code class="docutils literal"><span class="pre">alg</span></code> is the algorithm that were used to set up the operation. To generate different lengths of IV, use <a class="reference internal" href="rng.html#c.psa_generate_random" title="psa_generate_random"><code class="xref any c c-func docutils literal"><span class="pre">psa_generate_random()</span></code></a> and <a class="reference internal" href="#c.psa_cipher_set_iv" title="psa_cipher_set_iv"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_set_iv()</span></code></a>.</p>
511<p>If the cipher algorithm does not use an IV, calling this function returns a <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a> error. For these algorithms, <a class="reference internal" href="#c.PSA_CIPHER_IV_LENGTH" title="PSA_CIPHER_IV_LENGTH"><code class="docutils literal"><span class="pre">PSA_CIPHER_IV_LENGTH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">key_type</span></code><code class="docutils literal"><span class="pre">,</span> </code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> will be zero.</p>
512<p>The application must call <a class="reference internal" href="#c.psa_cipher_encrypt_setup" title="psa_cipher_encrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_encrypt_setup()</span></code></a> before calling this function.</p>
513<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_cipher_abort" title="psa_cipher_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_abort()</span></code></a>.</p>
514</div>
515<div class="section" id="psa_cipher_set_iv">
516<span id="c.psa_cipher_set_iv"></span><h3><code class="docutils literal"><span class="pre">psa_cipher_set_iv</span></code> (function)</h3>
517<p>Set the initialization vector (IV) for a symmetric encryption or decryption operation.</p>
518<pre class="literal-block">
519<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_cipher_set_iv" title="psa_cipher_set_iv">psa_cipher_set_iv</a>(<a class="reference internal" href="#c.psa_cipher_operation_t" title="psa_cipher_operation_t">psa_cipher_operation_t</a> * operation,
520 const uint8_t * iv,
521 size_t iv_length);
522</pre>
523<p class="rubric">Parameters</p>
524<dl class="docutils">
525<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
526<dd>Active cipher operation.</dd>
527<dt> <code class="docutils literal"><span class="pre">iv</span></code></dt>
528<dd>Buffer containing the IV to use.</dd>
529<dt> <code class="docutils literal"><span class="pre">iv_length</span></code></dt>
530<dd>Size of the IV in bytes.</dd>
531</dl>
532<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
533<dl class="docutils">
534<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
535<dd>Success.</dd>
536<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
537<dd><p class="first">Either:</p>
538<ul class="last simple">
539<li>The cipher algorithm does not use an IV.</li>
540<li>The operation state is not valid: it must be an active cipher encrypt operation, with no IV set.</li>
541</ul>
542</dd>
543<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
544<dd>The size of <code class="docutils literal"><span class="pre">iv</span></code> is not acceptable for the chosen algorithm, or the chosen algorithm does not use an IV.</dd>
545<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt>
546<dd></dd>
547<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
548<dd></dd>
549<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt>
550<dd></dd>
551<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
552<dd></dd>
553<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt>
554<dd></dd>
555<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt>
556<dd></dd>
557<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt>
558<dd></dd>
559<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
560<dd>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</dd>
561</dl>
562<p class="rubric">Description</p>
563<p>This function sets the IV, nonce or initial counter value for the encryption or decryption operation.</p>
564<p>If the cipher algorithm does not use an IV, calling this function returns a <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a> error. For these algorithms, <a class="reference internal" href="#c.PSA_CIPHER_IV_LENGTH" title="PSA_CIPHER_IV_LENGTH"><code class="docutils literal"><span class="pre">PSA_CIPHER_IV_LENGTH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">key_type</span></code><code class="docutils literal"><span class="pre">,</span> </code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> will be zero.</p>
565<p>The application must call <a class="reference internal" href="#c.psa_cipher_encrypt_setup" title="psa_cipher_encrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_encrypt_setup()</span></code></a> or <a class="reference internal" href="#c.psa_cipher_decrypt_setup" title="psa_cipher_decrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_decrypt_setup()</span></code></a> before calling this function.</p>
566<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_cipher_abort" title="psa_cipher_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_abort()</span></code></a>.</p>
567<div class="admonition note">
568<p class="first admonition-title">Note</p>
569<p class="last">When encrypting, <a class="reference internal" href="#c.psa_cipher_generate_iv" title="psa_cipher_generate_iv"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_generate_iv()</span></code></a> is recommended instead of using this function, unless implementing a protocol that requires a non-random IV.</p>
570</div>
571</div>
572<div class="section" id="psa_cipher_update">
573<span id="c.psa_cipher_update"></span><h3><code class="docutils literal"><span class="pre">psa_cipher_update</span></code> (function)</h3>
574<p>Encrypt or decrypt a message fragment in an active cipher operation.</p>
575<pre class="literal-block">
576<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_cipher_update" title="psa_cipher_update">psa_cipher_update</a>(<a class="reference internal" href="#c.psa_cipher_operation_t" title="psa_cipher_operation_t">psa_cipher_operation_t</a> * operation,
577 const uint8_t * input,
578 size_t input_length,
579 uint8_t * output,
580 size_t output_size,
581 size_t * output_length);
582</pre>
583<p class="rubric">Parameters</p>
584<dl class="docutils">
585<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
586<dd>Active cipher operation.</dd>
587<dt> <code class="docutils literal"><span class="pre">input</span></code></dt>
588<dd>Buffer containing the message fragment to encrypt or decrypt.</dd>
589<dt> <code class="docutils literal"><span class="pre">input_length</span></code></dt>
590<dd>Size of the <code class="docutils literal"><span class="pre">input</span></code> buffer in bytes.</dd>
591<dt> <code class="docutils literal"><span class="pre">output</span></code></dt>
592<dd>Buffer where the output is to be written.</dd>
593<dt> <code class="docutils literal"><span class="pre">output_size</span></code></dt>
594<dd><p class="first">Size of the <code class="docutils literal"><span class="pre">output</span></code> buffer in bytes. This must be appropriate for the selected algorithm and key:</p>
595<ul class="last simple">
596<li>A sufficient output size is <a class="reference internal" href="#c.PSA_CIPHER_UPDATE_OUTPUT_SIZE" title="PSA_CIPHER_UPDATE_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_CIPHER_UPDATE_OUTPUT_SIZE</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">key_type</span></code><code class="docutils literal"><span class="pre">,</span> </code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">,</span> </code><code class="docutils literal"><span class="pre">input_length</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">key_type</span></code> is the type of key and <code class="docutils literal"><span class="pre">alg</span></code> is the algorithm that were used to set up the operation.</li>
597<li><a class="reference internal" href="#c.PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE" title="PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE"><code class="docutils literal"><span class="pre">PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">input_length</span></code><code class="docutils literal"><span class="pre">)</span></code> evaluates to the maximum output size of any supported cipher algorithm.</li>
598</ul>
599</dd>
600<dt> <code class="docutils literal"><span class="pre">output_length</span></code></dt>
601<dd>On success, the number of bytes that make up the returned output.</dd>
602</dl>
603<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
604<dl class="docutils">
605<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
606<dd>Success.</dd>
607<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
608<dd>The operation state is not valid: it must be active, with an IV set if required for the algorithm.</dd>
609<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BUFFER_TOO_SMALL" title="PSA_ERROR_BUFFER_TOO_SMALL"><code class="docutils literal"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a></dt>
610<dd>The size of the <code class="docutils literal"><span class="pre">output</span></code> buffer is too small. <a class="reference internal" href="#c.PSA_CIPHER_UPDATE_OUTPUT_SIZE" title="PSA_CIPHER_UPDATE_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_CIPHER_UPDATE_OUTPUT_SIZE()</span></code></a> or <a class="reference internal" href="#c.PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE" title="PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE()</span></code></a> can be used to determine the required buffer size.</dd>
611<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt>
612<dd></dd>
613<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
614<dd></dd>
615<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt>
616<dd></dd>
617<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
618<dd></dd>
619<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt>
620<dd></dd>
621<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt>
622<dd></dd>
623<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt>
624<dd></dd>
625<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
626<dd>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</dd>
627</dl>
628<p class="rubric">Description</p>
629<p>The following must occur before calling this function:</p>
630<ol class="arabic simple">
631<li>Call either <a class="reference internal" href="#c.psa_cipher_encrypt_setup" title="psa_cipher_encrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_encrypt_setup()</span></code></a> or <a class="reference internal" href="#c.psa_cipher_decrypt_setup" title="psa_cipher_decrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_decrypt_setup()</span></code></a>. The choice of setup function determines whether this function encrypts or decrypts its input.</li>
632<li>If the algorithm requires an IV, call <a class="reference internal" href="#c.psa_cipher_generate_iv" title="psa_cipher_generate_iv"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_generate_iv()</span></code></a> or <a class="reference internal" href="#c.psa_cipher_set_iv" title="psa_cipher_set_iv"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_set_iv()</span></code></a>. <a class="reference internal" href="#c.psa_cipher_generate_iv" title="psa_cipher_generate_iv"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_generate_iv()</span></code></a> is recommended when encrypting.</li>
633</ol>
634<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_cipher_abort" title="psa_cipher_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_abort()</span></code></a>.</p>
635</div>
636<div class="section" id="psa_cipher_finish">
637<span id="c.psa_cipher_finish"></span><h3><code class="docutils literal"><span class="pre">psa_cipher_finish</span></code> (function)</h3>
638<p>Finish encrypting or decrypting a message in a cipher operation.</p>
639<pre class="literal-block">
640<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_cipher_finish" title="psa_cipher_finish">psa_cipher_finish</a>(<a class="reference internal" href="#c.psa_cipher_operation_t" title="psa_cipher_operation_t">psa_cipher_operation_t</a> * operation,
641 uint8_t * output,
642 size_t output_size,
643 size_t * output_length);
644</pre>
645<p class="rubric">Parameters</p>
646<dl class="docutils">
647<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
648<dd>Active cipher operation.</dd>
649<dt> <code class="docutils literal"><span class="pre">output</span></code></dt>
650<dd>Buffer where the output is to be written.</dd>
651<dt> <code class="docutils literal"><span class="pre">output_size</span></code></dt>
652<dd><p class="first">Size of the <code class="docutils literal"><span class="pre">output</span></code> buffer in bytes. This must be appropriate for the selected algorithm and key:</p>
653<ul class="last simple">
654<li>A sufficient output size is <a class="reference internal" href="#c.PSA_CIPHER_FINISH_OUTPUT_SIZE" title="PSA_CIPHER_FINISH_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_CIPHER_FINISH_OUTPUT_SIZE</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">key_type</span></code><code class="docutils literal"><span class="pre">,</span> </code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">key_type</span></code> is the type of key and <code class="docutils literal"><span class="pre">alg</span></code> is the algorithm that were used to set up the operation.</li>
655<li><a class="reference internal" href="#c.PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE" title="PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE</span></code></a> evaluates to the maximum output size of any supported cipher algorithm.</li>
656</ul>
657</dd>
658<dt> <code class="docutils literal"><span class="pre">output_length</span></code></dt>
659<dd>On success, the number of bytes that make up the returned output.</dd>
660</dl>
661<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
662<dl class="docutils">
663<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
664<dd>Success.</dd>
665<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
666<dd>The total input size passed to this operation is not valid for this particular algorithm. For example, the algorithm is a based on block cipher and requires a whole number of blocks, but the total input size is not a multiple of the block size.</dd>
667<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_PADDING" title="PSA_ERROR_INVALID_PADDING"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_PADDING</span></code></a></dt>
668<dd>This is a decryption operation for an algorithm that includes padding, and the ciphertext does not contain valid padding.</dd>
669<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
670<dd>The operation state is not valid: it must be active, with an IV set if required for the algorithm.</dd>
671<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BUFFER_TOO_SMALL" title="PSA_ERROR_BUFFER_TOO_SMALL"><code class="docutils literal"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a></dt>
672<dd>The size of the <code class="docutils literal"><span class="pre">output</span></code> buffer is too small. <a class="reference internal" href="#c.PSA_CIPHER_FINISH_OUTPUT_SIZE" title="PSA_CIPHER_FINISH_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_CIPHER_FINISH_OUTPUT_SIZE()</span></code></a> or <a class="reference internal" href="#c.PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE" title="PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE</span></code></a> can be used to determine the required buffer size.</dd>
673<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt>
674<dd></dd>
675<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
676<dd></dd>
677<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt>
678<dd></dd>
679<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
680<dd></dd>
681<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt>
682<dd></dd>
683<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt>
684<dd></dd>
685<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt>
686<dd></dd>
687<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
688<dd>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</dd>
689</dl>
690<p class="rubric">Description</p>
691<p>The application must call <a class="reference internal" href="#c.psa_cipher_encrypt_setup" title="psa_cipher_encrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_encrypt_setup()</span></code></a> or <a class="reference internal" href="#c.psa_cipher_decrypt_setup" title="psa_cipher_decrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_decrypt_setup()</span></code></a> before calling this function. The choice of setup function determines whether this function encrypts or decrypts its input.</p>
692<p>This function finishes the encryption or decryption of the message formed by concatenating the inputs passed to preceding calls to <a class="reference internal" href="#c.psa_cipher_update" title="psa_cipher_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_update()</span></code></a>.</p>
693<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_cipher_abort" title="psa_cipher_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_abort()</span></code></a>.</p>
694</div>
695<div class="section" id="psa_cipher_abort">
696<span id="c.psa_cipher_abort"></span><h3><code class="docutils literal"><span class="pre">psa_cipher_abort</span></code> (function)</h3>
697<p>Abort a cipher operation.</p>
698<pre class="literal-block">
699<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_cipher_abort" title="psa_cipher_abort">psa_cipher_abort</a>(<a class="reference internal" href="#c.psa_cipher_operation_t" title="psa_cipher_operation_t">psa_cipher_operation_t</a> * operation);
700</pre>
701<p class="rubric">Parameters</p>
702<dl class="docutils">
703<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
704<dd>Initialized cipher operation.</dd>
705</dl>
706<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
707<dl class="docutils">
708<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
709<dd></dd>
710<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
711<dd></dd>
712<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt>
713<dd></dd>
714<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
715<dd></dd>
716<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
717<dd>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</dd>
718</dl>
719<p class="rubric">Description</p>
720<p>Aborting an operation frees all associated resources except for the <code class="docutils literal"><span class="pre">operation</span></code> object itself. Once aborted, the operation object can be reused for another operation by calling <a class="reference internal" href="#c.psa_cipher_encrypt_setup" title="psa_cipher_encrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_encrypt_setup()</span></code></a> or <a class="reference internal" href="#c.psa_cipher_decrypt_setup" title="psa_cipher_decrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_decrypt_setup()</span></code></a> again.</p>
721<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_cipher_operation_t" title="psa_cipher_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_cipher_operation_t</span></code></a>.</p>
722<p>In particular, calling <a class="reference internal" href="#c.psa_cipher_abort" title="psa_cipher_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_abort()</span></code></a> after the operation has been terminated by a call to <a class="reference internal" href="#c.psa_cipher_abort" title="psa_cipher_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_abort()</span></code></a> or <a class="reference internal" href="#c.psa_cipher_finish" title="psa_cipher_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_finish()</span></code></a> is safe and has no effect.</p>
723</div>
724</div>
725<div class="section" id="support-macros">
726<h2>Support macros</h2>
727<div class="section" id="PSA_ALG_IS_STREAM_CIPHER">
728<span id="c.PSA_ALG_IS_STREAM_CIPHER"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_STREAM_CIPHER</span></code> (macro)</h3>
729<p>Whether the specified algorithm is a stream cipher.</p>
730<pre class="literal-block">
731#define <a class="reference internal" href="#c.PSA_ALG_IS_STREAM_CIPHER" title="PSA_ALG_IS_STREAM_CIPHER">PSA_ALG_IS_STREAM_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>
732</pre>
733<p class="rubric">Parameters</p>
734<dl class="docutils">
735<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
736<dd>An algorithm identifier (value of type <a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>).</dd>
737</dl>
738<p class="rubric">Returns</p>
739<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a stream cipher algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise. This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported algorithm identifier or if it is not a symmetric cipher algorithm.</p>
740<p class="rubric">Description</p>
741<p>A stream cipher is a symmetric cipher that encrypts or decrypts messages by applying a bitwise-xor with a stream of bytes that is generated from a key.</p>
742</div>
743<div class="section" id="PSA_CIPHER_ENCRYPT_OUTPUT_SIZE">
744<span id="c.PSA_CIPHER_ENCRYPT_OUTPUT_SIZE"></span><h3><code class="docutils literal"><span class="pre">PSA_CIPHER_ENCRYPT_OUTPUT_SIZE</span></code> (macro)</h3>
745<p>The maximum size of the output of <a class="reference internal" href="#c.psa_cipher_encrypt" title="psa_cipher_encrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_encrypt()</span></code></a>, in bytes.</p>
746<pre class="literal-block">
747#define <a class="reference internal" href="#c.PSA_CIPHER_ENCRYPT_OUTPUT_SIZE" title="PSA_CIPHER_ENCRYPT_OUTPUT_SIZE">PSA_CIPHER_ENCRYPT_OUTPUT_SIZE</a>(key_type, alg, input_length) \
748 <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em>
749</pre>
750<p class="rubric">Parameters</p>
751<dl class="docutils">
752<dt> <code class="docutils literal"><span class="pre">key_type</span></code></dt>
753<dd>A symmetric key type that is compatible with algorithm <code class="docutils literal"><span class="pre">alg</span></code>.</dd>
754<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
755<dd>A cipher algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_CIPHER" title="PSA_ALG_IS_CIPHER"><code class="docutils literal"><span class="pre">PSA_ALG_IS_CIPHER</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
756<dt> <code class="docutils literal"><span class="pre">input_length</span></code></dt>
757<dd>Size of the input in bytes.</dd>
758</dl>
759<p class="rubric">Returns</p>
760<p>A sufficient output size for the specified key type and algorithm. If the key type or cipher algorithm is not recognized, or the parameters are incompatible, return <code class="docutils literal"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal"><span class="pre">0</span></code> or a correct size for a key type and cipher algorithm that it recognizes, but does not support.</p>
761<p class="rubric">Description</p>
762<p>If the size of the output buffer is at least this large, it is guaranteed that <a class="reference internal" href="#c.psa_cipher_encrypt" title="psa_cipher_encrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_encrypt()</span></code></a> will not fail due to an insufficient buffer size. Depending on the algorithm, the actual size of the output might be smaller.</p>
763<p>See also <a class="reference internal" href="#c.PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE" title="PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE</span></code></a>.</p>
764</div>
765<div class="section" id="PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE">
766<span id="c.PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE"></span><h3><code class="docutils literal"><span class="pre">PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE</span></code> (macro)</h3>
767<p>A sufficient output buffer size for <a class="reference internal" href="#c.psa_cipher_encrypt" title="psa_cipher_encrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_encrypt()</span></code></a>, for any of the supported key types and cipher algorithms.</p>
768<pre class="literal-block">
769#define <a class="reference internal" href="#c.PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE" title="PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE">PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE</a>(input_length) \
770 <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em>
771</pre>
772<p class="rubric">Parameters</p>
773<dl class="docutils">
774<dt> <code class="docutils literal"><span class="pre">input_length</span></code></dt>
775<dd>Size of the input in bytes.</dd>
776</dl>
777<p class="rubric">Description</p>
778<p>If the size of the output buffer is at least this large, it is guaranteed that <a class="reference internal" href="#c.psa_cipher_encrypt" title="psa_cipher_encrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_encrypt()</span></code></a> will not fail due to an insufficient buffer size.</p>
779<p>See also <a class="reference internal" href="#c.PSA_CIPHER_ENCRYPT_OUTPUT_SIZE" title="PSA_CIPHER_ENCRYPT_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_CIPHER_ENCRYPT_OUTPUT_SIZE()</span></code></a>.</p>
780</div>
781<div class="section" id="PSA_CIPHER_DECRYPT_OUTPUT_SIZE">
782<span id="c.PSA_CIPHER_DECRYPT_OUTPUT_SIZE"></span><h3><code class="docutils literal"><span class="pre">PSA_CIPHER_DECRYPT_OUTPUT_SIZE</span></code> (macro)</h3>
783<p>The maximum size of the output of <a class="reference internal" href="#c.psa_cipher_decrypt" title="psa_cipher_decrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_decrypt()</span></code></a>, in bytes.</p>
784<pre class="literal-block">
785#define <a class="reference internal" href="#c.PSA_CIPHER_DECRYPT_OUTPUT_SIZE" title="PSA_CIPHER_DECRYPT_OUTPUT_SIZE">PSA_CIPHER_DECRYPT_OUTPUT_SIZE</a>(key_type, alg, input_length) \
786 <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em>
787</pre>
788<p class="rubric">Parameters</p>
789<dl class="docutils">
790<dt> <code class="docutils literal"><span class="pre">key_type</span></code></dt>
791<dd>A symmetric key type that is compatible with algorithm <code class="docutils literal"><span class="pre">alg</span></code>.</dd>
792<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
793<dd>A cipher algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_CIPHER" title="PSA_ALG_IS_CIPHER"><code class="docutils literal"><span class="pre">PSA_ALG_IS_CIPHER</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
794<dt> <code class="docutils literal"><span class="pre">input_length</span></code></dt>
795<dd>Size of the input in bytes.</dd>
796</dl>
797<p class="rubric">Returns</p>
798<p>A sufficient output size for the specified key type and algorithm. If the key type or cipher algorithm is not recognized, or the parameters are incompatible, return <code class="docutils literal"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal"><span class="pre">0</span></code> or a correct size for a key type and cipher algorithm that it recognizes, but does not support.</p>
799<p class="rubric">Description</p>
800<p>If the size of the output buffer is at least this large, it is guaranteed that <a class="reference internal" href="#c.psa_cipher_decrypt" title="psa_cipher_decrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_decrypt()</span></code></a> will not fail due to an insufficient buffer size. Depending on the algorithm, the actual size of the output might be smaller.</p>
801<p>See also <a class="reference internal" href="#c.PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE" title="PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE</span></code></a>.</p>
802</div>
803<div class="section" id="PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE">
804<span id="c.PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE"></span><h3><code class="docutils literal"><span class="pre">PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE</span></code> (macro)</h3>
805<p>A sufficient output buffer size for <a class="reference internal" href="#c.psa_cipher_decrypt" title="psa_cipher_decrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_decrypt()</span></code></a>, for any of the supported key types and cipher algorithms.</p>
806<pre class="literal-block">
807#define <a class="reference internal" href="#c.PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE" title="PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE">PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE</a>(input_length) \
808 <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em>
809</pre>
810<p class="rubric">Parameters</p>
811<dl class="docutils">
812<dt> <code class="docutils literal"><span class="pre">input_length</span></code></dt>
813<dd>Size of the input in bytes.</dd>
814</dl>
815<p class="rubric">Description</p>
816<p>If the size of the output buffer is at least this large, it is guaranteed that <a class="reference internal" href="#c.psa_cipher_decrypt" title="psa_cipher_decrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_decrypt()</span></code></a> will not fail due to an insufficient buffer size.</p>
817<p>See also <a class="reference internal" href="#c.PSA_CIPHER_DECRYPT_OUTPUT_SIZE" title="PSA_CIPHER_DECRYPT_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_CIPHER_DECRYPT_OUTPUT_SIZE()</span></code></a>.</p>
818</div>
819<div class="section" id="PSA_CIPHER_IV_LENGTH">
820<span id="c.PSA_CIPHER_IV_LENGTH"></span><h3><code class="docutils literal"><span class="pre">PSA_CIPHER_IV_LENGTH</span></code> (macro)</h3>
821<p>The default IV size for a cipher algorithm, in bytes.</p>
822<pre class="literal-block">
823#define <a class="reference internal" href="#c.PSA_CIPHER_IV_LENGTH" title="PSA_CIPHER_IV_LENGTH">PSA_CIPHER_IV_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>
824</pre>
825<p class="rubric">Parameters</p>
826<dl class="docutils">
827<dt> <code class="docutils literal"><span class="pre">key_type</span></code></dt>
828<dd>A symmetric key type that is compatible with algorithm <code class="docutils literal"><span class="pre">alg</span></code>.</dd>
829<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
830<dd>A cipher algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_CIPHER" title="PSA_ALG_IS_CIPHER"><code class="docutils literal"><span class="pre">PSA_ALG_IS_CIPHER</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
831</dl>
832<p class="rubric">Returns</p>
833<p>The default IV size for the specified key type and algorithm.
834If the algorithm does not use an IV, return <code class="docutils literal"><span class="pre">0</span></code>.
835If the key type or cipher algorithm is not recognized, or the parameters are incompatible, return <code class="docutils literal"><span class="pre">0</span></code>.
836An implementation can return either <code class="docutils literal"><span class="pre">0</span></code> or a correct size for a key type and cipher algorithm that it recognizes, but does not support.</p>
837<p class="rubric">Description</p>
838<p>The IV that is generated as part of a call to <a class="reference internal" href="#c.psa_cipher_encrypt" title="psa_cipher_encrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_encrypt()</span></code></a> is always the default IV length for the algorithm.</p>
839<p>This macro can be used to allocate a buffer of sufficient size to store the IV output from <a class="reference internal" href="#c.psa_cipher_generate_iv" title="psa_cipher_generate_iv"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_generate_iv()</span></code></a> when using a multi-part cipher operation.</p>
840<p>See also <a class="reference internal" href="#c.PSA_CIPHER_IV_MAX_SIZE" title="PSA_CIPHER_IV_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_CIPHER_IV_MAX_SIZE</span></code></a>.</p>
841</div>
842<div class="section" id="PSA_CIPHER_IV_MAX_SIZE">
843<span id="c.PSA_CIPHER_IV_MAX_SIZE"></span><h3><code class="docutils literal"><span class="pre">PSA_CIPHER_IV_MAX_SIZE</span></code> (macro)</h3>
844<p>The maximum IV size for all supported cipher algorithms, in bytes.</p>
845<pre class="literal-block">
846#define <a class="reference internal" href="#c.PSA_CIPHER_IV_MAX_SIZE" title="PSA_CIPHER_IV_MAX_SIZE">PSA_CIPHER_IV_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>
847</pre>
848<p>See also <a class="reference internal" href="#c.PSA_CIPHER_IV_LENGTH" title="PSA_CIPHER_IV_LENGTH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_CIPHER_IV_LENGTH()</span></code></a>.</p>
849</div>
850<div class="section" id="PSA_CIPHER_UPDATE_OUTPUT_SIZE">
851<span id="c.PSA_CIPHER_UPDATE_OUTPUT_SIZE"></span><h3><code class="docutils literal"><span class="pre">PSA_CIPHER_UPDATE_OUTPUT_SIZE</span></code> (macro)</h3>
852<p>A sufficient output buffer size for <a class="reference internal" href="#c.psa_cipher_update" title="psa_cipher_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_update()</span></code></a>.</p>
853<pre class="literal-block">
854#define <a class="reference internal" href="#c.PSA_CIPHER_UPDATE_OUTPUT_SIZE" title="PSA_CIPHER_UPDATE_OUTPUT_SIZE">PSA_CIPHER_UPDATE_OUTPUT_SIZE</a>(key_type, alg, input_length) \
855 <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em>
856</pre>
857<p class="rubric">Parameters</p>
858<dl class="docutils">
859<dt> <code class="docutils literal"><span class="pre">key_type</span></code></dt>
860<dd>A symmetric key type that is compatible with algorithm <code class="docutils literal"><span class="pre">alg</span></code>.</dd>
861<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
862<dd>A cipher algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_CIPHER" title="PSA_ALG_IS_CIPHER"><code class="docutils literal"><span class="pre">PSA_ALG_IS_CIPHER</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
863<dt> <code class="docutils literal"><span class="pre">input_length</span></code></dt>
864<dd>Size of the input in bytes.</dd>
865</dl>
866<p class="rubric">Returns</p>
867<p>A sufficient output size for the specified key type and algorithm. If the key type or cipher algorithm is not recognized, or the parameters are incompatible, return <code class="docutils literal"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal"><span class="pre">0</span></code> or a correct size for a key type and cipher algorithm that it recognizes, but does not support.</p>
868<p class="rubric">Description</p>
869<p>If the size of the output buffer is at least this large, it is guaranteed that <a class="reference internal" href="#c.psa_cipher_update" title="psa_cipher_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_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>
870<p>See also <a class="reference internal" href="#c.PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE" title="PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE</span></code></a>.</p>
871</div>
872<div class="section" id="PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE">
873<span id="c.PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE"></span><h3><code class="docutils literal"><span class="pre">PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE</span></code> (macro)</h3>
874<p>A sufficient output buffer size for <a class="reference internal" href="#c.psa_cipher_update" title="psa_cipher_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_update()</span></code></a>, for any of the supported key types and cipher algorithms.</p>
875<pre class="literal-block">
876#define <a class="reference internal" href="#c.PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE" title="PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE">PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE</a>(input_length) \
877 <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em>
878</pre>
879<p class="rubric">Parameters</p>
880<dl class="docutils">
881<dt> <code class="docutils literal"><span class="pre">input_length</span></code></dt>
882<dd>Size of the input in bytes.</dd>
883</dl>
884<p class="rubric">Description</p>
885<p>If the size of the output buffer is at least this large, it is guaranteed that <a class="reference internal" href="#c.psa_cipher_update" title="psa_cipher_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_update()</span></code></a> will not fail due to an insufficient buffer size.</p>
886<p>See also <a class="reference internal" href="#c.PSA_CIPHER_UPDATE_OUTPUT_SIZE" title="PSA_CIPHER_UPDATE_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_CIPHER_UPDATE_OUTPUT_SIZE()</span></code></a>.</p>
887</div>
888<div class="section" id="PSA_CIPHER_FINISH_OUTPUT_SIZE">
889<span id="c.PSA_CIPHER_FINISH_OUTPUT_SIZE"></span><h3><code class="docutils literal"><span class="pre">PSA_CIPHER_FINISH_OUTPUT_SIZE</span></code> (macro)</h3>
890<p>A sufficient ciphertext buffer size for <a class="reference internal" href="#c.psa_cipher_finish" title="psa_cipher_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_finish()</span></code></a>.</p>
891<pre class="literal-block">
892#define <a class="reference internal" href="#c.PSA_CIPHER_FINISH_OUTPUT_SIZE" title="PSA_CIPHER_FINISH_OUTPUT_SIZE">PSA_CIPHER_FINISH_OUTPUT_SIZE</a>(key_type, alg) \
893 <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em>
894</pre>
895<p class="rubric">Parameters</p>
896<dl class="docutils">
897<dt> <code class="docutils literal"><span class="pre">key_type</span></code></dt>
898<dd>A symmetric key type that is compatible with algorithm <code class="docutils literal"><span class="pre">alg</span></code>.</dd>
899<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
900<dd>A cipher algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_CIPHER" title="PSA_ALG_IS_CIPHER"><code class="docutils literal"><span class="pre">PSA_ALG_IS_CIPHER</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
901</dl>
902<p class="rubric">Returns</p>
903<p>A sufficient output size for the specified key type and algorithm. If the key type or cipher algorithm is not recognized, or the parameters are incompatible, return <code class="docutils literal"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal"><span class="pre">0</span></code> or a correct size for a key type and cipher algorithm that it recognizes, but does not support.</p>
904<p class="rubric">Description</p>
905<p>If the size of the ciphertext buffer is at least this large, it is guaranteed that <a class="reference internal" href="#c.psa_cipher_finish" title="psa_cipher_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_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>
906<p>See also <a class="reference internal" href="#c.PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE" title="PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE</span></code></a>.</p>
907</div>
908<div class="section" id="PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE">
909<span id="c.PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE"></span><h3><code class="docutils literal"><span class="pre">PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE</span></code> (macro)</h3>
910<p>A sufficient ciphertext buffer size for <a class="reference internal" href="#c.psa_cipher_finish" title="psa_cipher_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_finish()</span></code></a>, for any of the supported key types and cipher algorithms.</p>
911<pre class="literal-block">
912#define <a class="reference internal" href="#c.PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE" title="PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE">PSA_CIPHER_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>
913</pre>
914<p>See also <a class="reference internal" href="#c.PSA_CIPHER_FINISH_OUTPUT_SIZE" title="PSA_CIPHER_FINISH_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_CIPHER_FINISH_OUTPUT_SIZE()</span></code></a>.</p>
915</div>
916<div class="section" id="PSA_BLOCK_CIPHER_BLOCK_LENGTH">
917<span id="c.PSA_BLOCK_CIPHER_BLOCK_LENGTH"></span><h3><code class="docutils literal"><span class="pre">PSA_BLOCK_CIPHER_BLOCK_LENGTH</span></code> (macro)</h3>
918<p>The block size of a block cipher.</p>
919<pre class="literal-block">
920#define <a class="reference internal" href="#c.PSA_BLOCK_CIPHER_BLOCK_LENGTH" title="PSA_BLOCK_CIPHER_BLOCK_LENGTH">PSA_BLOCK_CIPHER_BLOCK_LENGTH</a>(type) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
921</pre>
922<p class="rubric">Parameters</p>
923<dl class="docutils">
924<dt> <code class="docutils literal"><span class="pre">type</span></code></dt>
925<dd>A cipher key type (value of type <a class="reference internal" href="../keys/attributes.html#c.psa_key_type_t" title="psa_key_type_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_type_t</span></code></a>).</dd>
926</dl>
927<p class="rubric">Returns</p>
928<p>The block size for a block cipher, or <code class="docutils literal"><span class="pre">1</span></code> for a stream cipher. The return value is undefined if <code class="docutils literal"><span class="pre">type</span></code> is not a supported cipher key type.</p>
929<p class="rubric">Description</p>
930<div class="admonition note">
931<p class="first admonition-title">Note</p>
932<p class="last">It is possible to build stream cipher algorithms on top of a block cipher, for example CTR mode (<a class="reference internal" href="#c.PSA_ALG_CTR" title="PSA_ALG_CTR"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_CTR</span></code></a>). This macro only takes the key type into account, so it cannot be used to determine the size of the data that <a class="reference internal" href="#c.psa_cipher_update" title="psa_cipher_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_update()</span></code></a> might buffer for future processing in general.</p>
933</div>
934<div class="admonition note">
935<p class="first admonition-title">Note</p>
936<p class="last">This macro expression is a compile-time constant if <code class="docutils literal"><span class="pre">type</span></code> is a compile-time constant.</p>
937</div>
938<div class="admonition warning">
939<p class="first admonition-title">Warning</p>
940<p class="last">This macro is permitted to evaluate its argument multiple times.</p>
941</div>
942<p>See also <a class="reference internal" href="#c.PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE" title="PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE</span></code></a>.</p>
943</div>
944<div class="section" id="PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE">
945<span id="c.PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE"></span><h3><code class="docutils literal"><span class="pre">PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE</span></code> (macro)</h3>
946<p>The maximum size of a block cipher supported by the implementation.</p>
947<pre class="literal-block">
948#define <a class="reference internal" href="#c.PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE" title="PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE">PSA_BLOCK_CIPHER_BLOCK_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>
949</pre>
950<p>See also <a class="reference internal" href="#c.PSA_BLOCK_CIPHER_BLOCK_LENGTH" title="PSA_BLOCK_CIPHER_BLOCK_LENGTH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_BLOCK_CIPHER_BLOCK_LENGTH()</span></code></a>.</p>
951</div>
952</div>
953</div>
954
955
956 </div>
957 </div>
958 </div>
959 <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
960 <div class="sphinxsidebarwrapper">
961 <h3><a href="../../index.html">Table Of Contents</a></h3>
962 <ul>
963<li><a class="reference internal" href="#">Unauthenticated ciphers</a><ul>
964<li><a class="reference internal" href="#cipher-algorithms">Cipher algorithms</a><ul>
965<li><a class="reference internal" href="#PSA_ALG_STREAM_CIPHER"><code class="docutils literal"><span class="pre">PSA_ALG_STREAM_CIPHER</span></code> (macro)</a></li>
966<li><a class="reference internal" href="#PSA_ALG_CTR"><code class="docutils literal"><span class="pre">PSA_ALG_CTR</span></code> (macro)</a></li>
967<li><a class="reference internal" href="#PSA_ALG_CFB"><code class="docutils literal"><span class="pre">PSA_ALG_CFB</span></code> (macro)</a></li>
968<li><a class="reference internal" href="#PSA_ALG_OFB"><code class="docutils literal"><span class="pre">PSA_ALG_OFB</span></code> (macro)</a></li>
969<li><a class="reference internal" href="#PSA_ALG_XTS"><code class="docutils literal"><span class="pre">PSA_ALG_XTS</span></code> (macro)</a></li>
970<li><a class="reference internal" href="#PSA_ALG_ECB_NO_PADDING"><code class="docutils literal"><span class="pre">PSA_ALG_ECB_NO_PADDING</span></code> (macro)</a></li>
971<li><a class="reference internal" href="#PSA_ALG_CBC_NO_PADDING"><code class="docutils literal"><span class="pre">PSA_ALG_CBC_NO_PADDING</span></code> (macro)</a></li>
972<li><a class="reference internal" href="#PSA_ALG_CBC_PKCS7"><code class="docutils literal"><span class="pre">PSA_ALG_CBC_PKCS7</span></code> (macro)</a></li>
973</ul>
974</li>
975<li><a class="reference internal" href="#single-part-cipher-functions">Single-part cipher functions</a><ul>
976<li><a class="reference internal" href="#psa_cipher_encrypt"><code class="docutils literal"><span class="pre">psa_cipher_encrypt</span></code> (function)</a></li>
977<li><a class="reference internal" href="#psa_cipher_decrypt"><code class="docutils literal"><span class="pre">psa_cipher_decrypt</span></code> (function)</a></li>
978</ul>
979</li>
980<li><a class="reference internal" href="#multi-part-cipher-operations">Multi-part cipher operations</a><ul>
981<li><a class="reference internal" href="#psa_cipher_operation_t"><code class="docutils literal"><span class="pre">psa_cipher_operation_t</span></code> (type)</a></li>
982<li><a class="reference internal" href="#PSA_CIPHER_OPERATION_INIT"><code class="docutils literal"><span class="pre">PSA_CIPHER_OPERATION_INIT</span></code> (macro)</a></li>
983<li><a class="reference internal" href="#psa_cipher_operation_init"><code class="docutils literal"><span class="pre">psa_cipher_operation_init</span></code> (function)</a></li>
984<li><a class="reference internal" href="#psa_cipher_encrypt_setup"><code class="docutils literal"><span class="pre">psa_cipher_encrypt_setup</span></code> (function)</a></li>
985<li><a class="reference internal" href="#psa_cipher_decrypt_setup"><code class="docutils literal"><span class="pre">psa_cipher_decrypt_setup</span></code> (function)</a></li>
986<li><a class="reference internal" href="#psa_cipher_generate_iv"><code class="docutils literal"><span class="pre">psa_cipher_generate_iv</span></code> (function)</a></li>
987<li><a class="reference internal" href="#psa_cipher_set_iv"><code class="docutils literal"><span class="pre">psa_cipher_set_iv</span></code> (function)</a></li>
988<li><a class="reference internal" href="#psa_cipher_update"><code class="docutils literal"><span class="pre">psa_cipher_update</span></code> (function)</a></li>
989<li><a class="reference internal" href="#psa_cipher_finish"><code class="docutils literal"><span class="pre">psa_cipher_finish</span></code> (function)</a></li>
990<li><a class="reference internal" href="#psa_cipher_abort"><code class="docutils literal"><span class="pre">psa_cipher_abort</span></code> (function)</a></li>
991</ul>
992</li>
993<li><a class="reference internal" href="#support-macros">Support macros</a><ul>
994<li><a class="reference internal" href="#PSA_ALG_IS_STREAM_CIPHER"><code class="docutils literal"><span class="pre">PSA_ALG_IS_STREAM_CIPHER</span></code> (macro)</a></li>
995<li><a class="reference internal" href="#PSA_CIPHER_ENCRYPT_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_CIPHER_ENCRYPT_OUTPUT_SIZE</span></code> (macro)</a></li>
996<li><a class="reference internal" href="#PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE"><code class="docutils literal"><span class="pre">PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE</span></code> (macro)</a></li>
997<li><a class="reference internal" href="#PSA_CIPHER_DECRYPT_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_CIPHER_DECRYPT_OUTPUT_SIZE</span></code> (macro)</a></li>
998<li><a class="reference internal" href="#PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE"><code class="docutils literal"><span class="pre">PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE</span></code> (macro)</a></li>
999<li><a class="reference internal" href="#PSA_CIPHER_IV_LENGTH"><code class="docutils literal"><span class="pre">PSA_CIPHER_IV_LENGTH</span></code> (macro)</a></li>
1000<li><a class="reference internal" href="#PSA_CIPHER_IV_MAX_SIZE"><code class="docutils literal"><span class="pre">PSA_CIPHER_IV_MAX_SIZE</span></code> (macro)</a></li>
1001<li><a class="reference internal" href="#PSA_CIPHER_UPDATE_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_CIPHER_UPDATE_OUTPUT_SIZE</span></code> (macro)</a></li>
1002<li><a class="reference internal" href="#PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE"><code class="docutils literal"><span class="pre">PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE</span></code> (macro)</a></li>
1003<li><a class="reference internal" href="#PSA_CIPHER_FINISH_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_CIPHER_FINISH_OUTPUT_SIZE</span></code> (macro)</a></li>
1004<li><a class="reference internal" href="#PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE"><code class="docutils literal"><span class="pre">PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE</span></code> (macro)</a></li>
1005<li><a class="reference internal" href="#PSA_BLOCK_CIPHER_BLOCK_LENGTH"><code class="docutils literal"><span class="pre">PSA_BLOCK_CIPHER_BLOCK_LENGTH</span></code> (macro)</a></li>
1006<li><a class="reference internal" href="#PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE"><code class="docutils literal"><span class="pre">PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE</span></code> (macro)</a></li>
1007</ul>
1008</li>
1009</ul>
1010</li>
1011</ul>
1012<div class="relations">
1013<h3>Related Topics</h3>
1014<ul>
1015 <li><a href="../../index.html">Documentation overview</a><ul>
1016 <li><a href="index.html">Cryptographic operation reference</a><ul>
1017 <li>Previous: <a href="macs.html" title="previous chapter">Message authentication codes (MAC)</a></li>
1018 <li>Next: <a href="aead.html" title="next chapter">Authenticated encryption with associated data (AEAD)</a></li>
1019 </ul></li>
1020 </ul></li>
1021</ul>
1022</div>
1023 <div role="note" aria-label="source link">
1024 <h3>This Page</h3>
1025 <ul class="this-page-menu">
1026 <li><a href="../../_sources/api/ops/ciphers.rst.txt"
1027 rel="nofollow">Show Source</a></li>
1028 </ul>
1029 </div>
1030<div id="searchbox" style="display: none" role="search">
1031 <h3>Quick search</h3>
1032 <form class="search" action="../../search.html" method="get">
1033 <div><input type="text" name="q" /></div>
1034 <div><input type="submit" value="Go" /></div>
1035 <input type="hidden" name="check_keywords" value="yes" />
1036 <input type="hidden" name="area" value="default" />
1037 </form>
1038</div>
1039<script type="text/javascript">$('#searchbox').show(0);</script>
1040 </div>
1041 </div>
1042 <div class="clearer"></div>
1043 </div>
1044 <div class="footer">
1045 &copy; 2019-2020, Arm Limited or its affiliates. All rights reserved.
1046
1047 |
1048 Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
1049 &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
1050
1051 |
1052 <a href="../../_sources/api/ops/ciphers.rst.txt"
1053 rel="nofollow">Page source</a>
1054 </div>
1055
1056
1057
1058
1059 </body>
1060</html>