TrustedFirmware Git Browser
Code Review Sign In
review.trustedfirmware.org / mirror / mbed-crypto / 734477057b893e5a2e941d7e8fdbeb1e0328409d / . / docs / html / group__cipher.html
blob: 0853f6df034c9492aab1366ac1ddc674e320e9cb [file] [log] [blame]
Gilles Peskine89f0a532019-01-31 11:47:57 +0100[diff] [blame]1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2<html xmlns="http://www.w3.org/1999/xhtml">
3<head>
4<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
5<meta http-equiv="X-UA-Compatible" content="IE=9"/>
6<meta name="generator" content="Doxygen 1.8.11"/>
7<title>Platform Security Architecture — cryptography and keystore interface: Symmetric ciphers</title>
8<link href="tabs.css" rel="stylesheet" type="text/css"/>
9<script type="text/javascript" src="jquery.js"></script>
10<script type="text/javascript" src="dynsections.js"></script>
11<link href="search/search.css" rel="stylesheet" type="text/css"/>
12<script type="text/javascript" src="search/searchdata.js"></script>
13<script type="text/javascript" src="search/search.js"></script>
14<script type="text/javascript">
15 $(document).ready(function() { init_search(); });
16</script>
17<link href="doxygen.css" rel="stylesheet" type="text/css" />
18</head>
19<body>
20<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
21<div id="titlearea">
22<table cellspacing="0" cellpadding="0">
23 <tbody>
24 <tr style="height: 56px;">
25 <td id="projectalign" style="padding-left: 0.5em;">
26 <div id="projectname">Platform Security Architecture — cryptography and keystore interface
27 &#160;<span id="projectnumber">beta 1 — 2019-01-21</span>
28 </div>
29 </td>
30 </tr>
31 </tbody>
32</table>
33</div>
34<!-- end header part -->
35<!-- Generated by Doxygen 1.8.11 -->
36<script type="text/javascript">
37var searchBox = new SearchBox("searchBox", "search",false,'Search');
38</script>
39 <div id="navrow1" class="tabs">
40 <ul class="tablist">
41 <li><a href="index.html"><span>Main&#160;Page</span></a></li>
42 <li class="current"><a href="modules.html"><span>Modules</span></a></li>
43 <li><a href="annotated.html"><span>Classes</span></a></li>
44 <li><a href="files.html"><span>Files</span></a></li>
45 <li>
46 <div id="MSearchBox" class="MSearchBoxInactive">
47 <span class="left">
48 <img id="MSearchSelect" src="search/mag_sel.png"
49 onmouseover="return searchBox.OnSearchSelectShow()"
50 onmouseout="return searchBox.OnSearchSelectHide()"
51 alt=""/>
52 <input type="text" id="MSearchField" value="Search" accesskey="S"
53 onfocus="searchBox.OnSearchFieldFocus(true)"
54 onblur="searchBox.OnSearchFieldFocus(false)"
55 onkeyup="searchBox.OnSearchFieldChange(event)"/>
56 </span><span class="right">
57 <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
58 </span>
59 </div>
60 </li>
61 </ul>
62 </div>
63</div><!-- top -->
64<!-- window showing the filter options -->
65<div id="MSearchSelectWindow"
66 onmouseover="return searchBox.OnSearchSelectShow()"
67 onmouseout="return searchBox.OnSearchSelectHide()"
68 onkeydown="return searchBox.OnSearchSelectKey(event)">
69</div>
70
71<!-- iframe showing the search results (closed by default) -->
72<div id="MSearchResultsWindow">
73<iframe src="javascript:void(0)" frameborder="0"
74 name="MSearchResults" id="MSearchResults">
75</iframe>
76</div>
77
78<div class="header">
79 <div class="summary">
80<a href="#define-members">Macros</a> &#124;
81<a href="#typedef-members">Typedefs</a> &#124;
82<a href="#func-members">Functions</a> </div>
83 <div class="headertitle">
84<div class="title">Symmetric ciphers</div> </div>
85</div><!--header-->
86<div class="contents">
87<table class="memberdecls">
88<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="define-members"></a>
89Macros</h2></td></tr>
90<tr class="memitem:ga2da0541aabf9a4995cf2004e36311919"><td class="memItemLeft" align="right" valign="top">#define&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__cipher.html#ga2da0541aabf9a4995cf2004e36311919">PSA_CIPHER_OPERATION_INIT</a>&#160;&#160;&#160;{0}</td></tr>
91<tr class="separator:ga2da0541aabf9a4995cf2004e36311919"><td class="memSeparator" colspan="2">&#160;</td></tr>
92</table><table class="memberdecls">
93<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="typedef-members"></a>
94Typedefs</h2></td></tr>
95<tr class="memitem:ga1399de29db657e3737bb09927aae51fa"><td class="memItemLeft" align="right" valign="top">typedef struct psa_cipher_operation_s&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__cipher.html#ga1399de29db657e3737bb09927aae51fa">psa_cipher_operation_t</a></td></tr>
96<tr class="separator:ga1399de29db657e3737bb09927aae51fa"><td class="memSeparator" colspan="2">&#160;</td></tr>
97</table><table class="memberdecls">
98<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="func-members"></a>
99Functions</h2></td></tr>
100<tr class="memitem:gac76dda492d9a1ba6b327bff610ec17b2"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__error.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__cipher.html#gac76dda492d9a1ba6b327bff610ec17b2">psa_cipher_encrypt</a> (<a class="el" href="group__platform.html#gabf6d5fd4e2ea89ecd425c88f057e7f75">psa_key_handle_t</a> handle, <a class="el" href="group__crypto__types.html#gac2e4d47f1300d73c2f829a6d99252d69">psa_algorithm_t</a> alg, const uint8_t *input, size_t input_length, uint8_t *output, size_t output_size, size_t *output_length)</td></tr>
101<tr class="separator:gac76dda492d9a1ba6b327bff610ec17b2"><td class="memSeparator" colspan="2">&#160;</td></tr>
102<tr class="memitem:ga43d5991711ec45c98af0c1d99f6e0216"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__error.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__cipher.html#ga43d5991711ec45c98af0c1d99f6e0216">psa_cipher_decrypt</a> (<a class="el" href="group__platform.html#gabf6d5fd4e2ea89ecd425c88f057e7f75">psa_key_handle_t</a> handle, <a class="el" href="group__crypto__types.html#gac2e4d47f1300d73c2f829a6d99252d69">psa_algorithm_t</a> alg, const uint8_t *input, size_t input_length, uint8_t *output, size_t output_size, size_t *output_length)</td></tr>
103<tr class="separator:ga43d5991711ec45c98af0c1d99f6e0216"><td class="memSeparator" colspan="2">&#160;</td></tr>
104<tr class="memitem:ga2a7fc79a9d150d42dba99f40ee3a185e"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__error.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__cipher.html#ga2a7fc79a9d150d42dba99f40ee3a185e">psa_cipher_encrypt_setup</a> (<a class="el" href="group__cipher.html#ga1399de29db657e3737bb09927aae51fa">psa_cipher_operation_t</a> *operation, <a class="el" href="group__platform.html#gabf6d5fd4e2ea89ecd425c88f057e7f75">psa_key_handle_t</a> handle, <a class="el" href="group__crypto__types.html#gac2e4d47f1300d73c2f829a6d99252d69">psa_algorithm_t</a> alg)</td></tr>
105<tr class="separator:ga2a7fc79a9d150d42dba99f40ee3a185e"><td class="memSeparator" colspan="2">&#160;</td></tr>
106<tr class="memitem:gaddf8504e5367cd0efb4415bdec004f44"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__error.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__cipher.html#gaddf8504e5367cd0efb4415bdec004f44">psa_cipher_decrypt_setup</a> (<a class="el" href="group__cipher.html#ga1399de29db657e3737bb09927aae51fa">psa_cipher_operation_t</a> *operation, <a class="el" href="group__platform.html#gabf6d5fd4e2ea89ecd425c88f057e7f75">psa_key_handle_t</a> handle, <a class="el" href="group__crypto__types.html#gac2e4d47f1300d73c2f829a6d99252d69">psa_algorithm_t</a> alg)</td></tr>
107<tr class="separator:gaddf8504e5367cd0efb4415bdec004f44"><td class="memSeparator" colspan="2">&#160;</td></tr>
108<tr class="memitem:ga44857cf5e0c3d134a3c560f8ff5b50aa"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__error.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__cipher.html#ga44857cf5e0c3d134a3c560f8ff5b50aa">psa_cipher_generate_iv</a> (<a class="el" href="group__cipher.html#ga1399de29db657e3737bb09927aae51fa">psa_cipher_operation_t</a> *operation, unsigned char *iv, size_t iv_size, size_t *iv_length)</td></tr>
109<tr class="separator:ga44857cf5e0c3d134a3c560f8ff5b50aa"><td class="memSeparator" colspan="2">&#160;</td></tr>
110<tr class="memitem:ga1359b2101f31637496ce7cc36c6e3d42"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__error.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__cipher.html#ga1359b2101f31637496ce7cc36c6e3d42">psa_cipher_set_iv</a> (<a class="el" href="group__cipher.html#ga1399de29db657e3737bb09927aae51fa">psa_cipher_operation_t</a> *operation, const unsigned char *iv, size_t iv_length)</td></tr>
111<tr class="separator:ga1359b2101f31637496ce7cc36c6e3d42"><td class="memSeparator" colspan="2">&#160;</td></tr>
112<tr class="memitem:gafd0caea99cf1052527e4089d37f5ab91"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__error.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__cipher.html#gafd0caea99cf1052527e4089d37f5ab91">psa_cipher_update</a> (<a class="el" href="group__cipher.html#ga1399de29db657e3737bb09927aae51fa">psa_cipher_operation_t</a> *operation, const uint8_t *input, size_t input_length, unsigned char *output, size_t output_size, size_t *output_length)</td></tr>
113<tr class="separator:gafd0caea99cf1052527e4089d37f5ab91"><td class="memSeparator" colspan="2">&#160;</td></tr>
114<tr class="memitem:ga1dcb58b8befe23f8a4d7a1d49c99249b"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__error.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__cipher.html#ga1dcb58b8befe23f8a4d7a1d49c99249b">psa_cipher_finish</a> (<a class="el" href="group__cipher.html#ga1399de29db657e3737bb09927aae51fa">psa_cipher_operation_t</a> *operation, uint8_t *output, size_t output_size, size_t *output_length)</td></tr>
115<tr class="separator:ga1dcb58b8befe23f8a4d7a1d49c99249b"><td class="memSeparator" colspan="2">&#160;</td></tr>
116<tr class="memitem:gaad482cdca2098bca0620596aaa02eaa4"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__error.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__cipher.html#gaad482cdca2098bca0620596aaa02eaa4">psa_cipher_abort</a> (<a class="el" href="group__cipher.html#ga1399de29db657e3737bb09927aae51fa">psa_cipher_operation_t</a> *operation)</td></tr>
117<tr class="separator:gaad482cdca2098bca0620596aaa02eaa4"><td class="memSeparator" colspan="2">&#160;</td></tr>
118</table>
119<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
120<h2 class="groupheader">Macro Definition Documentation</h2>
121<a class="anchor" id="ga2da0541aabf9a4995cf2004e36311919"></a>
122<div class="memitem">
123<div class="memproto">
124 <table class="memname">
125 <tr>
126 <td class="memname">#define PSA_CIPHER_OPERATION_INIT&#160;&#160;&#160;{0}</td>
127 </tr>
128 </table>
129</div><div class="memdoc">
130<p>This macro returns a suitable initializer for a cipher operation object of type <a class="el" href="group__cipher.html#ga1399de29db657e3737bb09927aae51fa">psa_cipher_operation_t</a>. </p>
131
132</div>
133</div>
134<h2 class="groupheader">Typedef Documentation</h2>
135<a class="anchor" id="ga1399de29db657e3737bb09927aae51fa"></a>
136<div class="memitem">
137<div class="memproto">
138 <table class="memname">
139 <tr>
140 <td class="memname">typedef struct psa_cipher_operation_s <a class="el" href="group__cipher.html#ga1399de29db657e3737bb09927aae51fa">psa_cipher_operation_t</a></td>
141 </tr>
142 </table>
143</div><div class="memdoc">
144<p>The type of the state data structure for multipart cipher operations.</p>
145<p>Before calling any function on a cipher operation object, the application must initialize it by any of the following means:</p><ul>
146<li>Set the structure to all-bits-zero, for example: <div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno"> 1</span>&#160;psa_cipher_operation_t operation;</div><div class="line"><a name="l00002"></a><span class="lineno"> 2</span>&#160;memset(&amp;operation, 0, sizeof(operation));</div></div><!-- fragment --></li>
147<li>Initialize the structure to logical zero values, for example: <div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno"> 1</span>&#160;psa_cipher_operation_t operation = {0};</div></div><!-- fragment --></li>
148<li>Initialize the structure to the initializer <a class="el" href="group__cipher.html#ga2da0541aabf9a4995cf2004e36311919">PSA_CIPHER_OPERATION_INIT</a>, for example: <div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno"> 1</span>&#160;psa_cipher_operation_t operation = PSA_CIPHER_OPERATION_INIT;</div></div><!-- fragment --></li>
149<li>Assign the result of the function psa_cipher_operation_init() to the structure, for example: <div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno"> 1</span>&#160;psa_cipher_operation_t operation;</div><div class="line"><a name="l00002"></a><span class="lineno"> 2</span>&#160;operation = psa_cipher_operation_init();</div></div><!-- fragment --></li>
150</ul>
151<p>This is an implementation-defined <code>struct</code>. Applications should not make any assumptions about the content of this structure except as directed by the documentation of a specific implementation. </p>
152
153</div>
154</div>
155<h2 class="groupheader">Function Documentation</h2>
156<a class="anchor" id="gaad482cdca2098bca0620596aaa02eaa4"></a>
157<div class="memitem">
158<div class="memproto">
159 <table class="memname">
160 <tr>
161 <td class="memname"><a class="el" href="group__error.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a> psa_cipher_abort </td>
162 <td>(</td>
163 <td class="paramtype"><a class="el" href="group__cipher.html#ga1399de29db657e3737bb09927aae51fa">psa_cipher_operation_t</a> *&#160;</td>
164 <td class="paramname"><em>operation</em></td><td>)</td>
165 <td></td>
166 </tr>
167 </table>
168</div><div class="memdoc">
169<p>Abort a cipher operation.</p>
170<p>Aborting an operation frees all associated resources except for the <code>operation</code> structure itself. Once aborted, the operation object can be reused for another operation by calling <a class="el" href="group__cipher.html#ga2a7fc79a9d150d42dba99f40ee3a185e">psa_cipher_encrypt_setup()</a> or <a class="el" href="group__cipher.html#gaddf8504e5367cd0efb4415bdec004f44">psa_cipher_decrypt_setup()</a> again.</p>
171<p>You may call this function any time after the operation object has been initialized by any of the following methods:</p><ul>
172<li>A call to <a class="el" href="group__cipher.html#ga2a7fc79a9d150d42dba99f40ee3a185e">psa_cipher_encrypt_setup()</a> or <a class="el" href="group__cipher.html#gaddf8504e5367cd0efb4415bdec004f44">psa_cipher_decrypt_setup()</a>, whether it succeeds or not.</li>
173<li>Initializing the <code>struct</code> to all-bits-zero.</li>
174<li>Initializing the <code>struct</code> to logical zeros, e.g. <code>psa_cipher_operation_t operation = {0}</code>.</li>
175</ul>
176<p>In particular, calling <a class="el" href="group__cipher.html#gaad482cdca2098bca0620596aaa02eaa4">psa_cipher_abort()</a> after the operation has been terminated by a call to <a class="el" href="group__cipher.html#gaad482cdca2098bca0620596aaa02eaa4">psa_cipher_abort()</a> or <a class="el" href="group__cipher.html#ga1dcb58b8befe23f8a4d7a1d49c99249b">psa_cipher_finish()</a> is safe and has no effect.</p>
177<dl class="params"><dt>Parameters</dt><dd>
178 <table class="params">
179 <tr><td class="paramdir">[in,out]</td><td class="paramname">operation</td><td>Initialized cipher operation.</td></tr>
180 </table>
181 </dd>
182</dl>
183<dl class="retval"><dt>Return values</dt><dd>
184 <table class="retval">
185 <tr><td class="paramname"><a class="el" href="group__error.html#ga4cc859e2c66ca381c7418db3527a65e1">PSA_SUCCESS</a></td><td></td></tr>
186 <tr><td class="paramname"><a class="el" href="group__error.html#ga933d40fa2a591004f2e93aa91e11db84">PSA_ERROR_BAD_STATE</a></td><td><code>operation</code> is not an active cipher operation. </td></tr>
187 <tr><td class="paramname"><a class="el" href="group__error.html#ga5cdb6948371d49e916106249020ea3f7">PSA_ERROR_COMMUNICATION_FAILURE</a></td><td></td></tr>
188 <tr><td class="paramname"><a class="el" href="group__error.html#ga08b10e70fa5ff0b05c631d9f8f6b2c6b">PSA_ERROR_HARDWARE_FAILURE</a></td><td></td></tr>
189 <tr><td class="paramname"><a class="el" href="group__error.html#ga2c5dda1485cb54f2385cb9c1279a7004">PSA_ERROR_TAMPERING_DETECTED</a></td><td></td></tr>
190 </table>
191 </dd>
192</dl>
193
194</div>
195</div>
196<a class="anchor" id="ga43d5991711ec45c98af0c1d99f6e0216"></a>
197<div class="memitem">
198<div class="memproto">
199 <table class="memname">
200 <tr>
201 <td class="memname"><a class="el" href="group__error.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a> psa_cipher_decrypt </td>
202 <td>(</td>
203 <td class="paramtype"><a class="el" href="group__platform.html#gabf6d5fd4e2ea89ecd425c88f057e7f75">psa_key_handle_t</a>&#160;</td>
204 <td class="paramname"><em>handle</em>, </td>
205 </tr>
206 <tr>
207 <td class="paramkey"></td>
208 <td></td>
209 <td class="paramtype"><a class="el" href="group__crypto__types.html#gac2e4d47f1300d73c2f829a6d99252d69">psa_algorithm_t</a>&#160;</td>
210 <td class="paramname"><em>alg</em>, </td>
211 </tr>
212 <tr>
213 <td class="paramkey"></td>
214 <td></td>
215 <td class="paramtype">const uint8_t *&#160;</td>
216 <td class="paramname"><em>input</em>, </td>
217 </tr>
218 <tr>
219 <td class="paramkey"></td>
220 <td></td>
221 <td class="paramtype">size_t&#160;</td>
222 <td class="paramname"><em>input_length</em>, </td>
223 </tr>
224 <tr>
225 <td class="paramkey"></td>
226 <td></td>
227 <td class="paramtype">uint8_t *&#160;</td>
228 <td class="paramname"><em>output</em>, </td>
229 </tr>
230 <tr>
231 <td class="paramkey"></td>
232 <td></td>
233 <td class="paramtype">size_t&#160;</td>
234 <td class="paramname"><em>output_size</em>, </td>
235 </tr>
236 <tr>
237 <td class="paramkey"></td>
238 <td></td>
239 <td class="paramtype">size_t *&#160;</td>
240 <td class="paramname"><em>output_length</em>&#160;</td>
241 </tr>
242 <tr>
243 <td></td>
244 <td>)</td>
245 <td></td><td></td>
246 </tr>
247 </table>
248</div><div class="memdoc">
249<p>Decrypt a message using a symmetric cipher.</p>
250<p>This function decrypts a message encrypted with a symmetric cipher.</p>
251<dl class="params"><dt>Parameters</dt><dd>
252 <table class="params">
253 <tr><td class="paramdir"></td><td class="paramname">handle</td><td>Handle to the key to use for the operation. It must remain valid until the operation terminates. </td></tr>
254 <tr><td class="paramdir"></td><td class="paramname">alg</td><td>The cipher algorithm to compute (<code>PSA_ALG_XXX</code> value such that <a class="el" href="group__crypto__types.html#ga1d1a5a402ad89a2e68f12bfb535490eb">PSA_ALG_IS_CIPHER</a>(<code>alg</code>) is true). </td></tr>
255 <tr><td class="paramdir">[in]</td><td class="paramname">input</td><td>Buffer containing the message to decrypt. This consists of the IV followed by the ciphertext proper. </td></tr>
256 <tr><td class="paramdir"></td><td class="paramname">input_length</td><td>Size of the <code>input</code> buffer in bytes. </td></tr>
257 <tr><td class="paramdir">[out]</td><td class="paramname">output</td><td>Buffer where the plaintext is to be written. </td></tr>
258 <tr><td class="paramdir"></td><td class="paramname">output_size</td><td>Size of the <code>output</code> buffer in bytes. </td></tr>
259 <tr><td class="paramdir">[out]</td><td class="paramname">output_length</td><td>On success, the number of bytes that make up the output.</td></tr>
260 </table>
261 </dd>
262</dl>
263<dl class="retval"><dt>Return values</dt><dd>
264 <table class="retval">
265 <tr><td class="paramname"><a class="el" href="group__error.html#ga4cc859e2c66ca381c7418db3527a65e1">PSA_SUCCESS</a></td><td>Success. </td></tr>
266 <tr><td class="paramname"><a class="el" href="group__error.html#gadf22718935657c2c3168c228204085f9">PSA_ERROR_INVALID_HANDLE</a></td><td></td></tr>
267 <tr><td class="paramname"><a class="el" href="group__error.html#gaba00e3e6ceb2b12965a81e5ac02ae040">PSA_ERROR_EMPTY_SLOT</a></td><td></td></tr>
268 <tr><td class="paramname"><a class="el" href="group__error.html#ga4d1b8dd8526177a15a210b7afc1accb1">PSA_ERROR_NOT_PERMITTED</a></td><td></td></tr>
269 <tr><td class="paramname"><a class="el" href="group__error.html#ga798df25a505ebf931f7bec1f80f1f85f">PSA_ERROR_INVALID_ARGUMENT</a></td><td><code>key</code> is not compatible with <code>alg</code>. </td></tr>
270 <tr><td class="paramname"><a class="el" href="group__error.html#ga1dcc6d130633ed5db8942257581b55dd">PSA_ERROR_NOT_SUPPORTED</a></td><td><code>alg</code> is not supported or is not a cipher algorithm. </td></tr>
271 <tr><td class="paramname"><a class="el" href="group__error.html#ga695025f4ec11249aee7ea3d0f65e01c8">PSA_ERROR_BUFFER_TOO_SMALL</a></td><td></td></tr>
272 <tr><td class="paramname"><a class="el" href="group__error.html#ga91b2ad8a867517a2651f1b076c5216e5">PSA_ERROR_INSUFFICIENT_MEMORY</a></td><td></td></tr>
273 <tr><td class="paramname"><a class="el" href="group__error.html#ga5cdb6948371d49e916106249020ea3f7">PSA_ERROR_COMMUNICATION_FAILURE</a></td><td></td></tr>
274 <tr><td class="paramname"><a class="el" href="group__error.html#ga08b10e70fa5ff0b05c631d9f8f6b2c6b">PSA_ERROR_HARDWARE_FAILURE</a></td><td></td></tr>
275 <tr><td class="paramname"><a class="el" href="group__error.html#ga2c5dda1485cb54f2385cb9c1279a7004">PSA_ERROR_TAMPERING_DETECTED</a></td><td></td></tr>
276 </table>
277 </dd>
278</dl>
279
280</div>
281</div>
282<a class="anchor" id="gaddf8504e5367cd0efb4415bdec004f44"></a>
283<div class="memitem">
284<div class="memproto">
285 <table class="memname">
286 <tr>
287 <td class="memname"><a class="el" href="group__error.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a> psa_cipher_decrypt_setup </td>
288 <td>(</td>
289 <td class="paramtype"><a class="el" href="group__cipher.html#ga1399de29db657e3737bb09927aae51fa">psa_cipher_operation_t</a> *&#160;</td>
290 <td class="paramname"><em>operation</em>, </td>
291 </tr>
292 <tr>
293 <td class="paramkey"></td>
294 <td></td>
295 <td class="paramtype"><a class="el" href="group__platform.html#gabf6d5fd4e2ea89ecd425c88f057e7f75">psa_key_handle_t</a>&#160;</td>
296 <td class="paramname"><em>handle</em>, </td>
297 </tr>
298 <tr>
299 <td class="paramkey"></td>
300 <td></td>
301 <td class="paramtype"><a class="el" href="group__crypto__types.html#gac2e4d47f1300d73c2f829a6d99252d69">psa_algorithm_t</a>&#160;</td>
302 <td class="paramname"><em>alg</em>&#160;</td>
303 </tr>
304 <tr>
305 <td></td>
306 <td>)</td>
307 <td></td><td></td>
308 </tr>
309 </table>
310</div><div class="memdoc">
311<p>Set the key for a multipart symmetric decryption operation.</p>
312<p>The sequence of operations to decrypt a message with a symmetric cipher is as follows:</p><ol type="1">
313<li>Allocate an operation object which will be passed to all the functions listed here.</li>
314<li>Initialize the operation object with one of the methods described in the documentation for <a class="el" href="group__cipher.html#ga1399de29db657e3737bb09927aae51fa">psa_cipher_operation_t</a>, e.g. PSA_CIPHER_OPERATION_INIT.</li>
315<li>Call <a class="el" href="group__cipher.html#gaddf8504e5367cd0efb4415bdec004f44">psa_cipher_decrypt_setup()</a> to specify the algorithm and key.</li>
316<li>Call <a class="el" href="group__cipher.html#ga1359b2101f31637496ce7cc36c6e3d42">psa_cipher_set_iv()</a> with the IV (initialization vector) for the decryption. If the IV is prepended to the ciphertext, you can call <a class="el" href="group__cipher.html#gafd0caea99cf1052527e4089d37f5ab91">psa_cipher_update()</a> on a buffer containing the IV followed by the beginning of the message.</li>
317<li>Call <a class="el" href="group__cipher.html#gafd0caea99cf1052527e4089d37f5ab91">psa_cipher_update()</a> zero, one or more times, passing a fragment of the message each time.</li>
318<li>Call <a class="el" href="group__cipher.html#ga1dcb58b8befe23f8a4d7a1d49c99249b">psa_cipher_finish()</a>.</li>
319</ol>
320<p>The application may call <a class="el" href="group__cipher.html#gaad482cdca2098bca0620596aaa02eaa4">psa_cipher_abort()</a> at any time after the operation has been initialized.</p>
321<p>After a successful call to <a class="el" href="group__cipher.html#gaddf8504e5367cd0efb4415bdec004f44">psa_cipher_decrypt_setup()</a>, the application must eventually terminate the operation. The following events terminate an operation:</p><ul>
322<li>A failed call to any of the <code>psa_cipher_xxx</code> functions.</li>
323<li>A call to <a class="el" href="group__cipher.html#ga1dcb58b8befe23f8a4d7a1d49c99249b">psa_cipher_finish()</a> or <a class="el" href="group__cipher.html#gaad482cdca2098bca0620596aaa02eaa4">psa_cipher_abort()</a>.</li>
324</ul>
325<dl class="params"><dt>Parameters</dt><dd>
326 <table class="params">
327 <tr><td class="paramdir">[in,out]</td><td class="paramname">operation</td><td>The operation object to set up. It must have been initialized as per the documentation for <a class="el" href="group__cipher.html#ga1399de29db657e3737bb09927aae51fa">psa_cipher_operation_t</a> and not yet in use. </td></tr>
328 <tr><td class="paramdir"></td><td class="paramname">handle</td><td>Handle to the key to use for the operation. It must remain valid until the operation terminates. </td></tr>
329 <tr><td class="paramdir"></td><td class="paramname">alg</td><td>The cipher algorithm to compute (<code>PSA_ALG_XXX</code> value such that <a class="el" href="group__crypto__types.html#ga1d1a5a402ad89a2e68f12bfb535490eb">PSA_ALG_IS_CIPHER</a>(<code>alg</code>) is true).</td></tr>
330 </table>
331 </dd>
332</dl>
333<dl class="retval"><dt>Return values</dt><dd>
334 <table class="retval">
335 <tr><td class="paramname"><a class="el" href="group__error.html#ga4cc859e2c66ca381c7418db3527a65e1">PSA_SUCCESS</a></td><td>Success. </td></tr>
336 <tr><td class="paramname"><a class="el" href="group__error.html#gadf22718935657c2c3168c228204085f9">PSA_ERROR_INVALID_HANDLE</a></td><td></td></tr>
337 <tr><td class="paramname"><a class="el" href="group__error.html#gaba00e3e6ceb2b12965a81e5ac02ae040">PSA_ERROR_EMPTY_SLOT</a></td><td></td></tr>
338 <tr><td class="paramname"><a class="el" href="group__error.html#ga4d1b8dd8526177a15a210b7afc1accb1">PSA_ERROR_NOT_PERMITTED</a></td><td></td></tr>
339 <tr><td class="paramname"><a class="el" href="group__error.html#ga798df25a505ebf931f7bec1f80f1f85f">PSA_ERROR_INVALID_ARGUMENT</a></td><td><code>key</code> is not compatible with <code>alg</code>. </td></tr>
340 <tr><td class="paramname"><a class="el" href="group__error.html#ga1dcc6d130633ed5db8942257581b55dd">PSA_ERROR_NOT_SUPPORTED</a></td><td><code>alg</code> is not supported or is not a cipher algorithm. </td></tr>
341 <tr><td class="paramname"><a class="el" href="group__error.html#ga91b2ad8a867517a2651f1b076c5216e5">PSA_ERROR_INSUFFICIENT_MEMORY</a></td><td></td></tr>
342 <tr><td class="paramname"><a class="el" href="group__error.html#ga5cdb6948371d49e916106249020ea3f7">PSA_ERROR_COMMUNICATION_FAILURE</a></td><td></td></tr>
343 <tr><td class="paramname"><a class="el" href="group__error.html#ga08b10e70fa5ff0b05c631d9f8f6b2c6b">PSA_ERROR_HARDWARE_FAILURE</a></td><td></td></tr>
344 <tr><td class="paramname"><a class="el" href="group__error.html#ga2c5dda1485cb54f2385cb9c1279a7004">PSA_ERROR_TAMPERING_DETECTED</a></td><td></td></tr>
345 <tr><td class="paramname"><a class="el" href="group__error.html#ga933d40fa2a591004f2e93aa91e11db84">PSA_ERROR_BAD_STATE</a></td><td>The library has not been previously initialized by <a class="el" href="group__initialization.html#ga2de150803fc2f7dc6101d5af7e921dd9" title="Library initialization. ">psa_crypto_init()</a>. It is implementation-dependent whether a failure to initialize results in this error code. </td></tr>
346 </table>
347 </dd>
348</dl>
349
350</div>
351</div>
352<a class="anchor" id="gac76dda492d9a1ba6b327bff610ec17b2"></a>
353<div class="memitem">
354<div class="memproto">
355 <table class="memname">
356 <tr>
357 <td class="memname"><a class="el" href="group__error.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a> psa_cipher_encrypt </td>
358 <td>(</td>
359 <td class="paramtype"><a class="el" href="group__platform.html#gabf6d5fd4e2ea89ecd425c88f057e7f75">psa_key_handle_t</a>&#160;</td>
360 <td class="paramname"><em>handle</em>, </td>
361 </tr>
362 <tr>
363 <td class="paramkey"></td>
364 <td></td>
365 <td class="paramtype"><a class="el" href="group__crypto__types.html#gac2e4d47f1300d73c2f829a6d99252d69">psa_algorithm_t</a>&#160;</td>
366 <td class="paramname"><em>alg</em>, </td>
367 </tr>
368 <tr>
369 <td class="paramkey"></td>
370 <td></td>
371 <td class="paramtype">const uint8_t *&#160;</td>
372 <td class="paramname"><em>input</em>, </td>
373 </tr>
374 <tr>
375 <td class="paramkey"></td>
376 <td></td>
377 <td class="paramtype">size_t&#160;</td>
378 <td class="paramname"><em>input_length</em>, </td>
379 </tr>
380 <tr>
381 <td class="paramkey"></td>
382 <td></td>
383 <td class="paramtype">uint8_t *&#160;</td>
384 <td class="paramname"><em>output</em>, </td>
385 </tr>
386 <tr>
387 <td class="paramkey"></td>
388 <td></td>
389 <td class="paramtype">size_t&#160;</td>
390 <td class="paramname"><em>output_size</em>, </td>
391 </tr>
392 <tr>
393 <td class="paramkey"></td>
394 <td></td>
395 <td class="paramtype">size_t *&#160;</td>
396 <td class="paramname"><em>output_length</em>&#160;</td>
397 </tr>
398 <tr>
399 <td></td>
400 <td>)</td>
401 <td></td><td></td>
402 </tr>
403 </table>
404</div><div class="memdoc">
405<p>Encrypt a message using a symmetric cipher.</p>
406<p>This function encrypts a message with a random IV (initialization vector).</p>
407<dl class="params"><dt>Parameters</dt><dd>
408 <table class="params">
409 <tr><td class="paramdir"></td><td class="paramname">handle</td><td>Handle to the key to use for the operation. It must remain valid until the operation terminates. </td></tr>
410 <tr><td class="paramdir"></td><td class="paramname">alg</td><td>The cipher algorithm to compute (<code>PSA_ALG_XXX</code> value such that <a class="el" href="group__crypto__types.html#ga1d1a5a402ad89a2e68f12bfb535490eb">PSA_ALG_IS_CIPHER</a>(<code>alg</code>) is true). </td></tr>
411 <tr><td class="paramdir">[in]</td><td class="paramname">input</td><td>Buffer containing the message to encrypt. </td></tr>
412 <tr><td class="paramdir"></td><td class="paramname">input_length</td><td>Size of the <code>input</code> buffer in bytes. </td></tr>
413 <tr><td class="paramdir">[out]</td><td class="paramname">output</td><td>Buffer where the output is to be written. The output contains the IV followed by the ciphertext proper. </td></tr>
414 <tr><td class="paramdir"></td><td class="paramname">output_size</td><td>Size of the <code>output</code> buffer in bytes. </td></tr>
415 <tr><td class="paramdir">[out]</td><td class="paramname">output_length</td><td>On success, the number of bytes that make up the output.</td></tr>
416 </table>
417 </dd>
418</dl>
419<dl class="retval"><dt>Return values</dt><dd>
420 <table class="retval">
421 <tr><td class="paramname"><a class="el" href="group__error.html#ga4cc859e2c66ca381c7418db3527a65e1">PSA_SUCCESS</a></td><td>Success. </td></tr>
422 <tr><td class="paramname"><a class="el" href="group__error.html#gadf22718935657c2c3168c228204085f9">PSA_ERROR_INVALID_HANDLE</a></td><td></td></tr>
423 <tr><td class="paramname"><a class="el" href="group__error.html#gaba00e3e6ceb2b12965a81e5ac02ae040">PSA_ERROR_EMPTY_SLOT</a></td><td></td></tr>
424 <tr><td class="paramname"><a class="el" href="group__error.html#ga4d1b8dd8526177a15a210b7afc1accb1">PSA_ERROR_NOT_PERMITTED</a></td><td></td></tr>
425 <tr><td class="paramname"><a class="el" href="group__error.html#ga798df25a505ebf931f7bec1f80f1f85f">PSA_ERROR_INVALID_ARGUMENT</a></td><td><code>key</code> is not compatible with <code>alg</code>. </td></tr>
426 <tr><td class="paramname"><a class="el" href="group__error.html#ga1dcc6d130633ed5db8942257581b55dd">PSA_ERROR_NOT_SUPPORTED</a></td><td><code>alg</code> is not supported or is not a cipher algorithm. </td></tr>
427 <tr><td class="paramname"><a class="el" href="group__error.html#ga695025f4ec11249aee7ea3d0f65e01c8">PSA_ERROR_BUFFER_TOO_SMALL</a></td><td></td></tr>
428 <tr><td class="paramname"><a class="el" href="group__error.html#ga91b2ad8a867517a2651f1b076c5216e5">PSA_ERROR_INSUFFICIENT_MEMORY</a></td><td></td></tr>
429 <tr><td class="paramname"><a class="el" href="group__error.html#ga5cdb6948371d49e916106249020ea3f7">PSA_ERROR_COMMUNICATION_FAILURE</a></td><td></td></tr>
430 <tr><td class="paramname"><a class="el" href="group__error.html#ga08b10e70fa5ff0b05c631d9f8f6b2c6b">PSA_ERROR_HARDWARE_FAILURE</a></td><td></td></tr>
431 <tr><td class="paramname"><a class="el" href="group__error.html#ga2c5dda1485cb54f2385cb9c1279a7004">PSA_ERROR_TAMPERING_DETECTED</a></td><td></td></tr>
432 </table>
433 </dd>
434</dl>
435
436</div>
437</div>
438<a class="anchor" id="ga2a7fc79a9d150d42dba99f40ee3a185e"></a>
439<div class="memitem">
440<div class="memproto">
441 <table class="memname">
442 <tr>
443 <td class="memname"><a class="el" href="group__error.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a> psa_cipher_encrypt_setup </td>
444 <td>(</td>
445 <td class="paramtype"><a class="el" href="group__cipher.html#ga1399de29db657e3737bb09927aae51fa">psa_cipher_operation_t</a> *&#160;</td>
446 <td class="paramname"><em>operation</em>, </td>
447 </tr>
448 <tr>
449 <td class="paramkey"></td>
450 <td></td>
451 <td class="paramtype"><a class="el" href="group__platform.html#gabf6d5fd4e2ea89ecd425c88f057e7f75">psa_key_handle_t</a>&#160;</td>
452 <td class="paramname"><em>handle</em>, </td>
453 </tr>
454 <tr>
455 <td class="paramkey"></td>
456 <td></td>
457 <td class="paramtype"><a class="el" href="group__crypto__types.html#gac2e4d47f1300d73c2f829a6d99252d69">psa_algorithm_t</a>&#160;</td>
458 <td class="paramname"><em>alg</em>&#160;</td>
459 </tr>
460 <tr>
461 <td></td>
462 <td>)</td>
463 <td></td><td></td>
464 </tr>
465 </table>
466</div><div class="memdoc">
467<p>Set the key for a multipart symmetric encryption operation.</p>
468<p>The sequence of operations to encrypt a message with a symmetric cipher is as follows:</p><ol type="1">
469<li>Allocate an operation object which will be passed to all the functions listed here.</li>
470<li>Initialize the operation object with one of the methods described in the documentation for <a class="el" href="group__cipher.html#ga1399de29db657e3737bb09927aae51fa">psa_cipher_operation_t</a>, e.g. PSA_CIPHER_OPERATION_INIT.</li>
471<li>Call <a class="el" href="group__cipher.html#ga2a7fc79a9d150d42dba99f40ee3a185e">psa_cipher_encrypt_setup()</a> to specify the algorithm and key.</li>
472<li>Call either <a class="el" href="group__cipher.html#ga44857cf5e0c3d134a3c560f8ff5b50aa">psa_cipher_generate_iv()</a> or <a class="el" href="group__cipher.html#ga1359b2101f31637496ce7cc36c6e3d42">psa_cipher_set_iv()</a> to generate or set the IV (initialization vector). You should use <a class="el" href="group__cipher.html#ga44857cf5e0c3d134a3c560f8ff5b50aa">psa_cipher_generate_iv()</a> unless the protocol you are implementing requires a specific IV value.</li>
473<li>Call <a class="el" href="group__cipher.html#gafd0caea99cf1052527e4089d37f5ab91">psa_cipher_update()</a> zero, one or more times, passing a fragment of the message each time.</li>
474<li>Call <a class="el" href="group__cipher.html#ga1dcb58b8befe23f8a4d7a1d49c99249b">psa_cipher_finish()</a>.</li>
475</ol>
476<p>The application may call <a class="el" href="group__cipher.html#gaad482cdca2098bca0620596aaa02eaa4">psa_cipher_abort()</a> at any time after the operation has been initialized.</p>
477<p>After a successful call to <a class="el" href="group__cipher.html#ga2a7fc79a9d150d42dba99f40ee3a185e">psa_cipher_encrypt_setup()</a>, the application must eventually terminate the operation. The following events terminate an operation:</p><ul>
478<li>A failed call to any of the <code>psa_cipher_xxx</code> functions.</li>
479<li>A call to <a class="el" href="group__cipher.html#ga1dcb58b8befe23f8a4d7a1d49c99249b">psa_cipher_finish()</a> or <a class="el" href="group__cipher.html#gaad482cdca2098bca0620596aaa02eaa4">psa_cipher_abort()</a>.</li>
480</ul>
481<dl class="params"><dt>Parameters</dt><dd>
482 <table class="params">
483 <tr><td class="paramdir">[in,out]</td><td class="paramname">operation</td><td>The operation object to set up. It must have been initialized as per the documentation for <a class="el" href="group__cipher.html#ga1399de29db657e3737bb09927aae51fa">psa_cipher_operation_t</a> and not yet in use. </td></tr>
484 <tr><td class="paramdir"></td><td class="paramname">handle</td><td>Handle to the key to use for the operation. It must remain valid until the operation terminates. </td></tr>
485 <tr><td class="paramdir"></td><td class="paramname">alg</td><td>The cipher algorithm to compute (<code>PSA_ALG_XXX</code> value such that <a class="el" href="group__crypto__types.html#ga1d1a5a402ad89a2e68f12bfb535490eb">PSA_ALG_IS_CIPHER</a>(<code>alg</code>) is true).</td></tr>
486 </table>
487 </dd>
488</dl>
489<dl class="retval"><dt>Return values</dt><dd>
490 <table class="retval">
491 <tr><td class="paramname"><a class="el" href="group__error.html#ga4cc859e2c66ca381c7418db3527a65e1">PSA_SUCCESS</a></td><td>Success. </td></tr>
492 <tr><td class="paramname"><a class="el" href="group__error.html#gadf22718935657c2c3168c228204085f9">PSA_ERROR_INVALID_HANDLE</a></td><td></td></tr>
493 <tr><td class="paramname"><a class="el" href="group__error.html#gaba00e3e6ceb2b12965a81e5ac02ae040">PSA_ERROR_EMPTY_SLOT</a></td><td></td></tr>
494 <tr><td class="paramname"><a class="el" href="group__error.html#ga4d1b8dd8526177a15a210b7afc1accb1">PSA_ERROR_NOT_PERMITTED</a></td><td></td></tr>
495 <tr><td class="paramname"><a class="el" href="group__error.html#ga798df25a505ebf931f7bec1f80f1f85f">PSA_ERROR_INVALID_ARGUMENT</a></td><td><code>key</code> is not compatible with <code>alg</code>. </td></tr>
496 <tr><td class="paramname"><a class="el" href="group__error.html#ga1dcc6d130633ed5db8942257581b55dd">PSA_ERROR_NOT_SUPPORTED</a></td><td><code>alg</code> is not supported or is not a cipher algorithm. </td></tr>
497 <tr><td class="paramname"><a class="el" href="group__error.html#ga91b2ad8a867517a2651f1b076c5216e5">PSA_ERROR_INSUFFICIENT_MEMORY</a></td><td></td></tr>
498 <tr><td class="paramname"><a class="el" href="group__error.html#ga5cdb6948371d49e916106249020ea3f7">PSA_ERROR_COMMUNICATION_FAILURE</a></td><td></td></tr>
499 <tr><td class="paramname"><a class="el" href="group__error.html#ga08b10e70fa5ff0b05c631d9f8f6b2c6b">PSA_ERROR_HARDWARE_FAILURE</a></td><td></td></tr>
500 <tr><td class="paramname"><a class="el" href="group__error.html#ga2c5dda1485cb54f2385cb9c1279a7004">PSA_ERROR_TAMPERING_DETECTED</a></td><td></td></tr>
501 <tr><td class="paramname"><a class="el" href="group__error.html#ga933d40fa2a591004f2e93aa91e11db84">PSA_ERROR_BAD_STATE</a></td><td>The library has not been previously initialized by <a class="el" href="group__initialization.html#ga2de150803fc2f7dc6101d5af7e921dd9" title="Library initialization. ">psa_crypto_init()</a>. It is implementation-dependent whether a failure to initialize results in this error code. </td></tr>
502 </table>
503 </dd>
504</dl>
505
506</div>
507</div>
508<a class="anchor" id="ga1dcb58b8befe23f8a4d7a1d49c99249b"></a>
509<div class="memitem">
510<div class="memproto">
511 <table class="memname">
512 <tr>
513 <td class="memname"><a class="el" href="group__error.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a> psa_cipher_finish </td>
514 <td>(</td>
515 <td class="paramtype"><a class="el" href="group__cipher.html#ga1399de29db657e3737bb09927aae51fa">psa_cipher_operation_t</a> *&#160;</td>
516 <td class="paramname"><em>operation</em>, </td>
517 </tr>
518 <tr>
519 <td class="paramkey"></td>
520 <td></td>
521 <td class="paramtype">uint8_t *&#160;</td>
522 <td class="paramname"><em>output</em>, </td>
523 </tr>
524 <tr>
525 <td class="paramkey"></td>
526 <td></td>
527 <td class="paramtype">size_t&#160;</td>
528 <td class="paramname"><em>output_size</em>, </td>
529 </tr>
530 <tr>
531 <td class="paramkey"></td>
532 <td></td>
533 <td class="paramtype">size_t *&#160;</td>
534 <td class="paramname"><em>output_length</em>&#160;</td>
535 </tr>
536 <tr>
537 <td></td>
538 <td>)</td>
539 <td></td><td></td>
540 </tr>
541 </table>
542</div><div class="memdoc">
543<p>Finish encrypting or decrypting a message in a cipher operation.</p>
544<p>The application must call <a class="el" href="group__cipher.html#ga2a7fc79a9d150d42dba99f40ee3a185e">psa_cipher_encrypt_setup()</a> or <a class="el" href="group__cipher.html#gaddf8504e5367cd0efb4415bdec004f44">psa_cipher_decrypt_setup()</a> before calling this function. The choice of setup function determines whether this function encrypts or decrypts its input.</p>
545<p>This function finishes the encryption or decryption of the message formed by concatenating the inputs passed to preceding calls to <a class="el" href="group__cipher.html#gafd0caea99cf1052527e4089d37f5ab91">psa_cipher_update()</a>.</p>
546<p>When this function returns, the operation becomes inactive.</p>
547<dl class="params"><dt>Parameters</dt><dd>
548 <table class="params">
549 <tr><td class="paramdir">[in,out]</td><td class="paramname">operation</td><td>Active cipher operation. </td></tr>
550 <tr><td class="paramdir">[out]</td><td class="paramname">output</td><td>Buffer where the output is to be written. </td></tr>
551 <tr><td class="paramdir"></td><td class="paramname">output_size</td><td>Size of the <code>output</code> buffer in bytes. </td></tr>
552 <tr><td class="paramdir">[out]</td><td class="paramname">output_length</td><td>On success, the number of bytes that make up the returned output.</td></tr>
553 </table>
554 </dd>
555</dl>
556<dl class="retval"><dt>Return values</dt><dd>
557 <table class="retval">
558 <tr><td class="paramname"><a class="el" href="group__error.html#ga4cc859e2c66ca381c7418db3527a65e1">PSA_SUCCESS</a></td><td>Success. </td></tr>
559 <tr><td class="paramname"><a class="el" href="group__error.html#ga933d40fa2a591004f2e93aa91e11db84">PSA_ERROR_BAD_STATE</a></td><td>The operation state is not valid (not set up, IV required but not set, or already completed). </td></tr>
560 <tr><td class="paramname"><a class="el" href="group__error.html#ga695025f4ec11249aee7ea3d0f65e01c8">PSA_ERROR_BUFFER_TOO_SMALL</a></td><td>The size of the <code>output</code> buffer is too small. </td></tr>
561 <tr><td class="paramname"><a class="el" href="group__error.html#ga91b2ad8a867517a2651f1b076c5216e5">PSA_ERROR_INSUFFICIENT_MEMORY</a></td><td></td></tr>
562 <tr><td class="paramname"><a class="el" href="group__error.html#ga5cdb6948371d49e916106249020ea3f7">PSA_ERROR_COMMUNICATION_FAILURE</a></td><td></td></tr>
563 <tr><td class="paramname"><a class="el" href="group__error.html#ga08b10e70fa5ff0b05c631d9f8f6b2c6b">PSA_ERROR_HARDWARE_FAILURE</a></td><td></td></tr>
564 <tr><td class="paramname"><a class="el" href="group__error.html#ga2c5dda1485cb54f2385cb9c1279a7004">PSA_ERROR_TAMPERING_DETECTED</a></td><td></td></tr>
565 </table>
566 </dd>
567</dl>
568
569</div>
570</div>
571<a class="anchor" id="ga44857cf5e0c3d134a3c560f8ff5b50aa"></a>
572<div class="memitem">
573<div class="memproto">
574 <table class="memname">
575 <tr>
576 <td class="memname"><a class="el" href="group__error.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a> psa_cipher_generate_iv </td>
577 <td>(</td>
578 <td class="paramtype"><a class="el" href="group__cipher.html#ga1399de29db657e3737bb09927aae51fa">psa_cipher_operation_t</a> *&#160;</td>
579 <td class="paramname"><em>operation</em>, </td>
580 </tr>
581 <tr>
582 <td class="paramkey"></td>
583 <td></td>
584 <td class="paramtype">unsigned char *&#160;</td>
585 <td class="paramname"><em>iv</em>, </td>
586 </tr>
587 <tr>
588 <td class="paramkey"></td>
589 <td></td>
590 <td class="paramtype">size_t&#160;</td>
591 <td class="paramname"><em>iv_size</em>, </td>
592 </tr>
593 <tr>
594 <td class="paramkey"></td>
595 <td></td>
596 <td class="paramtype">size_t *&#160;</td>
597 <td class="paramname"><em>iv_length</em>&#160;</td>
598 </tr>
599 <tr>
600 <td></td>
601 <td>)</td>
602 <td></td><td></td>
603 </tr>
604 </table>
605</div><div class="memdoc">
606<p>Generate an IV for a symmetric encryption operation.</p>
607<p>This function generates a random IV (initialization vector), nonce or initial counter value for the encryption operation as appropriate for the chosen algorithm, key type and key size.</p>
608<p>The application must call <a class="el" href="group__cipher.html#ga2a7fc79a9d150d42dba99f40ee3a185e">psa_cipher_encrypt_setup()</a> before calling this function.</p>
609<p>If this function returns an error status, the operation becomes inactive.</p>
610<dl class="params"><dt>Parameters</dt><dd>
611 <table class="params">
612 <tr><td class="paramdir">[in,out]</td><td class="paramname">operation</td><td>Active cipher operation. </td></tr>
613 <tr><td class="paramdir">[out]</td><td class="paramname">iv</td><td>Buffer where the generated IV is to be written. </td></tr>
614 <tr><td class="paramdir"></td><td class="paramname">iv_size</td><td>Size of the <code>iv</code> buffer in bytes. </td></tr>
615 <tr><td class="paramdir">[out]</td><td class="paramname">iv_length</td><td>On success, the number of bytes of the generated IV.</td></tr>
616 </table>
617 </dd>
618</dl>
619<dl class="retval"><dt>Return values</dt><dd>
620 <table class="retval">
621 <tr><td class="paramname"><a class="el" href="group__error.html#ga4cc859e2c66ca381c7418db3527a65e1">PSA_SUCCESS</a></td><td>Success. </td></tr>
622 <tr><td class="paramname"><a class="el" href="group__error.html#ga933d40fa2a591004f2e93aa91e11db84">PSA_ERROR_BAD_STATE</a></td><td>The operation state is not valid (not set up, or IV already set). </td></tr>
623 <tr><td class="paramname"><a class="el" href="group__error.html#ga695025f4ec11249aee7ea3d0f65e01c8">PSA_ERROR_BUFFER_TOO_SMALL</a></td><td>The size of the <code>iv</code> buffer is too small. </td></tr>
624 <tr><td class="paramname"><a class="el" href="group__error.html#ga91b2ad8a867517a2651f1b076c5216e5">PSA_ERROR_INSUFFICIENT_MEMORY</a></td><td></td></tr>
625 <tr><td class="paramname"><a class="el" href="group__error.html#ga5cdb6948371d49e916106249020ea3f7">PSA_ERROR_COMMUNICATION_FAILURE</a></td><td></td></tr>
626 <tr><td class="paramname"><a class="el" href="group__error.html#ga08b10e70fa5ff0b05c631d9f8f6b2c6b">PSA_ERROR_HARDWARE_FAILURE</a></td><td></td></tr>
627 <tr><td class="paramname"><a class="el" href="group__error.html#ga2c5dda1485cb54f2385cb9c1279a7004">PSA_ERROR_TAMPERING_DETECTED</a></td><td></td></tr>
628 </table>
629 </dd>
630</dl>
631
632</div>
633</div>
634<a class="anchor" id="ga1359b2101f31637496ce7cc36c6e3d42"></a>
635<div class="memitem">
636<div class="memproto">
637 <table class="memname">
638 <tr>
639 <td class="memname"><a class="el" href="group__error.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a> psa_cipher_set_iv </td>
640 <td>(</td>
641 <td class="paramtype"><a class="el" href="group__cipher.html#ga1399de29db657e3737bb09927aae51fa">psa_cipher_operation_t</a> *&#160;</td>
642 <td class="paramname"><em>operation</em>, </td>
643 </tr>
644 <tr>
645 <td class="paramkey"></td>
646 <td></td>
647 <td class="paramtype">const unsigned char *&#160;</td>
648 <td class="paramname"><em>iv</em>, </td>
649 </tr>
650 <tr>
651 <td class="paramkey"></td>
652 <td></td>
653 <td class="paramtype">size_t&#160;</td>
654 <td class="paramname"><em>iv_length</em>&#160;</td>
655 </tr>
656 <tr>
657 <td></td>
658 <td>)</td>
659 <td></td><td></td>
660 </tr>
661 </table>
662</div><div class="memdoc">
663<p>Set the IV for a symmetric encryption or decryption operation.</p>
664<p>This function sets the IV (initialization vector), nonce or initial counter value for the encryption or decryption operation.</p>
665<p>The application must call <a class="el" href="group__cipher.html#ga2a7fc79a9d150d42dba99f40ee3a185e">psa_cipher_encrypt_setup()</a> before calling this function.</p>
666<p>If this function returns an error status, the operation becomes inactive.</p>
667<dl class="section note"><dt>Note</dt><dd>When encrypting, applications should use <a class="el" href="group__cipher.html#ga44857cf5e0c3d134a3c560f8ff5b50aa">psa_cipher_generate_iv()</a> instead of this function, unless implementing a protocol that requires a non-random IV.</dd></dl>
668<dl class="params"><dt>Parameters</dt><dd>
669 <table class="params">
670 <tr><td class="paramdir">[in,out]</td><td class="paramname">operation</td><td>Active cipher operation. </td></tr>
671 <tr><td class="paramdir">[in]</td><td class="paramname">iv</td><td>Buffer containing the IV to use. </td></tr>
672 <tr><td class="paramdir"></td><td class="paramname">iv_length</td><td>Size of the IV in bytes.</td></tr>
673 </table>
674 </dd>
675</dl>
676<dl class="retval"><dt>Return values</dt><dd>
677 <table class="retval">
678 <tr><td class="paramname"><a class="el" href="group__error.html#ga4cc859e2c66ca381c7418db3527a65e1">PSA_SUCCESS</a></td><td>Success. </td></tr>
679 <tr><td class="paramname"><a class="el" href="group__error.html#ga933d40fa2a591004f2e93aa91e11db84">PSA_ERROR_BAD_STATE</a></td><td>The operation state is not valid (not set up, or IV already set). </td></tr>
680 <tr><td class="paramname"><a class="el" href="group__error.html#ga798df25a505ebf931f7bec1f80f1f85f">PSA_ERROR_INVALID_ARGUMENT</a></td><td>The size of <code>iv</code> is not acceptable for the chosen algorithm, or the chosen algorithm does not use an IV. </td></tr>
681 <tr><td class="paramname"><a class="el" href="group__error.html#ga91b2ad8a867517a2651f1b076c5216e5">PSA_ERROR_INSUFFICIENT_MEMORY</a></td><td></td></tr>
682 <tr><td class="paramname"><a class="el" href="group__error.html#ga5cdb6948371d49e916106249020ea3f7">PSA_ERROR_COMMUNICATION_FAILURE</a></td><td></td></tr>
683 <tr><td class="paramname"><a class="el" href="group__error.html#ga08b10e70fa5ff0b05c631d9f8f6b2c6b">PSA_ERROR_HARDWARE_FAILURE</a></td><td></td></tr>
684 <tr><td class="paramname"><a class="el" href="group__error.html#ga2c5dda1485cb54f2385cb9c1279a7004">PSA_ERROR_TAMPERING_DETECTED</a></td><td></td></tr>
685 </table>
686 </dd>
687</dl>
688
689</div>
690</div>
691<a class="anchor" id="gafd0caea99cf1052527e4089d37f5ab91"></a>
692<div class="memitem">
693<div class="memproto">
694 <table class="memname">
695 <tr>
696 <td class="memname"><a class="el" href="group__error.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a> psa_cipher_update </td>
697 <td>(</td>
698 <td class="paramtype"><a class="el" href="group__cipher.html#ga1399de29db657e3737bb09927aae51fa">psa_cipher_operation_t</a> *&#160;</td>
699 <td class="paramname"><em>operation</em>, </td>
700 </tr>
701 <tr>
702 <td class="paramkey"></td>
703 <td></td>
704 <td class="paramtype">const uint8_t *&#160;</td>
705 <td class="paramname"><em>input</em>, </td>
706 </tr>
707 <tr>
708 <td class="paramkey"></td>
709 <td></td>
710 <td class="paramtype">size_t&#160;</td>
711 <td class="paramname"><em>input_length</em>, </td>
712 </tr>
713 <tr>
714 <td class="paramkey"></td>
715 <td></td>
716 <td class="paramtype">unsigned char *&#160;</td>
717 <td class="paramname"><em>output</em>, </td>
718 </tr>
719 <tr>
720 <td class="paramkey"></td>
721 <td></td>
722 <td class="paramtype">size_t&#160;</td>
723 <td class="paramname"><em>output_size</em>, </td>
724 </tr>
725 <tr>
726 <td class="paramkey"></td>
727 <td></td>
728 <td class="paramtype">size_t *&#160;</td>
729 <td class="paramname"><em>output_length</em>&#160;</td>
730 </tr>
731 <tr>
732 <td></td>
733 <td>)</td>
734 <td></td><td></td>
735 </tr>
736 </table>
737</div><div class="memdoc">
738<p>Encrypt or decrypt a message fragment in an active cipher operation.</p>
739<p>Before calling this function, you must:</p><ol type="1">
740<li>Call either <a class="el" href="group__cipher.html#ga2a7fc79a9d150d42dba99f40ee3a185e">psa_cipher_encrypt_setup()</a> or <a class="el" href="group__cipher.html#gaddf8504e5367cd0efb4415bdec004f44">psa_cipher_decrypt_setup()</a>. The choice of setup function determines whether this function encrypts or decrypts its input.</li>
741<li>If the algorithm requires an IV, call <a class="el" href="group__cipher.html#ga44857cf5e0c3d134a3c560f8ff5b50aa">psa_cipher_generate_iv()</a> (recommended when encrypting) or <a class="el" href="group__cipher.html#ga1359b2101f31637496ce7cc36c6e3d42">psa_cipher_set_iv()</a>.</li>
742</ol>
743<p>If this function returns an error status, the operation becomes inactive.</p>
744<dl class="params"><dt>Parameters</dt><dd>
745 <table class="params">
746 <tr><td class="paramdir">[in,out]</td><td class="paramname">operation</td><td>Active cipher operation. </td></tr>
747 <tr><td class="paramdir">[in]</td><td class="paramname">input</td><td>Buffer containing the message fragment to encrypt or decrypt. </td></tr>
748 <tr><td class="paramdir"></td><td class="paramname">input_length</td><td>Size of the <code>input</code> buffer in bytes. </td></tr>
749 <tr><td class="paramdir">[out]</td><td class="paramname">output</td><td>Buffer where the output is to be written. </td></tr>
750 <tr><td class="paramdir"></td><td class="paramname">output_size</td><td>Size of the <code>output</code> buffer in bytes. </td></tr>
751 <tr><td class="paramdir">[out]</td><td class="paramname">output_length</td><td>On success, the number of bytes that make up the returned output.</td></tr>
752 </table>
753 </dd>
754</dl>
755<dl class="retval"><dt>Return values</dt><dd>
756 <table class="retval">
757 <tr><td class="paramname"><a class="el" href="group__error.html#ga4cc859e2c66ca381c7418db3527a65e1">PSA_SUCCESS</a></td><td>Success. </td></tr>
758 <tr><td class="paramname"><a class="el" href="group__error.html#ga933d40fa2a591004f2e93aa91e11db84">PSA_ERROR_BAD_STATE</a></td><td>The operation state is not valid (not set up, IV required but not set, or already completed). </td></tr>
759 <tr><td class="paramname"><a class="el" href="group__error.html#ga695025f4ec11249aee7ea3d0f65e01c8">PSA_ERROR_BUFFER_TOO_SMALL</a></td><td>The size of the <code>output</code> buffer is too small. </td></tr>
760 <tr><td class="paramname"><a class="el" href="group__error.html#ga91b2ad8a867517a2651f1b076c5216e5">PSA_ERROR_INSUFFICIENT_MEMORY</a></td><td></td></tr>
761 <tr><td class="paramname"><a class="el" href="group__error.html#ga5cdb6948371d49e916106249020ea3f7">PSA_ERROR_COMMUNICATION_FAILURE</a></td><td></td></tr>
762 <tr><td class="paramname"><a class="el" href="group__error.html#ga08b10e70fa5ff0b05c631d9f8f6b2c6b">PSA_ERROR_HARDWARE_FAILURE</a></td><td></td></tr>
763 <tr><td class="paramname"><a class="el" href="group__error.html#ga2c5dda1485cb54f2385cb9c1279a7004">PSA_ERROR_TAMPERING_DETECTED</a></td><td></td></tr>
764 </table>
765 </dd>
766</dl>
767
768</div>
769</div>
770</div><!-- contents -->
771<!-- start footer part -->
772<hr class="footer"/><address class="footer"><small>
773Generated by &#160;<a href="http://www.doxygen.org/index.html">
774<img class="footer" src="doxygen.png" alt="doxygen"/>
775</a> 1.8.11
776</small></address>
777</body>
778</html>