TrustedFirmware Git Browser
Code Review Sign In
review.trustedfirmware.org / mirror / mbed-crypto / a8992df78a641eb5008f7946d007da08aba47b6d / . / docs / html / group__aead.html
blob: 487b5e63d9b71903790248963d31f2fba1031448 [file] [log] [blame]
Jaeden Ameroe54e6932018-08-06 16:19:58 +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.13"/>
7<meta name="viewport" content="width=device-width, initial-scale=1"/>
8<title>Platform Security Architecture — cryptography and keystore interface: Authenticated encryption with associated data (AEAD)</title>
9<link href="tabs.css" rel="stylesheet" type="text/css"/>
10<script type="text/javascript" src="jquery.js"></script>
11<script type="text/javascript" src="dynsections.js"></script>
12<link href="search/search.css" rel="stylesheet" type="text/css"/>
13<script type="text/javascript" src="search/searchdata.js"></script>
14<script type="text/javascript" src="search/search.js"></script>
15<link href="doxygen.css" rel="stylesheet" type="text/css" />
16</head>
17<body>
18<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
19<div id="titlearea">
20<table cellspacing="0" cellpadding="0">
21 <tbody>
22 <tr style="height: 56px;">
23 <td id="projectalign" style="padding-left: 0.5em;">
24 <div id="projectname">Platform Security Architecture — cryptography and keystore interface
25 &#160;<span id="projectnumber">Working draft</span>
26 </div>
27 </td>
28 </tr>
29 </tbody>
30</table>
31</div>
32<!-- end header part -->
33<!-- Generated by Doxygen 1.8.13 -->
34<script type="text/javascript">
35var searchBox = new SearchBox("searchBox", "search",false,'Search');
36</script>
37<script type="text/javascript" src="menudata.js"></script>
38<script type="text/javascript" src="menu.js"></script>
39<script type="text/javascript">
40$(function() {
41 initMenu('',true,false,'search.php','Search');
42 $(document).ready(function() { init_search(); });
43});
44</script>
45<div id="main-nav"></div>
46</div><!-- top -->
47<!-- window showing the filter options -->
48<div id="MSearchSelectWindow"
49 onmouseover="return searchBox.OnSearchSelectShow()"
50 onmouseout="return searchBox.OnSearchSelectHide()"
51 onkeydown="return searchBox.OnSearchSelectKey(event)">
52</div>
53
54<!-- iframe showing the search results (closed by default) -->
55<div id="MSearchResultsWindow">
56<iframe src="javascript:void(0)" frameborder="0"
57 name="MSearchResults" id="MSearchResults">
58</iframe>
59</div>
60
61<div class="header">
62 <div class="summary">
63<a href="#define-members">Macros</a> &#124;
64<a href="#func-members">Functions</a> </div>
65 <div class="headertitle">
66<div class="title">Authenticated encryption with associated data (AEAD)</div> </div>
67</div><!--header-->
68<div class="contents">
69<table class="memberdecls">
70<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="define-members"></a>
71Macros</h2></td></tr>
72<tr class="memitem:ga337ef01fe3c9f71d62ccced33e8917f4"><td class="memItemLeft" align="right" valign="top">#define&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__aead.html#ga337ef01fe3c9f71d62ccced33e8917f4">PSA_AEAD_TAG_SIZE</a>(alg)</td></tr>
73<tr class="separator:ga337ef01fe3c9f71d62ccced33e8917f4"><td class="memSeparator" colspan="2">&#160;</td></tr>
74</table><table class="memberdecls">
75<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="func-members"></a>
76Functions</h2></td></tr>
77<tr class="memitem:ga14e4068a3d328515a4884f3037904d54"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__basic.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__aead.html#ga14e4068a3d328515a4884f3037904d54">psa_aead_encrypt</a> (<a class="el" href="group__platform.html#gac3da92a6b8a7f0c01dc348f8e0432e4c">psa_key_slot_t</a> key, <a class="el" href="group__crypto__types.html#gac2e4d47f1300d73c2f829a6d99252d69">psa_algorithm_t</a> alg, const uint8_t *nonce, size_t nonce_length, const uint8_t *additional_data, size_t additional_data_length, const uint8_t *plaintext, size_t plaintext_length, uint8_t *ciphertext, size_t ciphertext_size, size_t *ciphertext_length)</td></tr>
78<tr class="separator:ga14e4068a3d328515a4884f3037904d54"><td class="memSeparator" colspan="2">&#160;</td></tr>
79<tr class="memitem:ga5b88ad2cfbf2e98039858416fa3ebd7a"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__basic.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__aead.html#ga5b88ad2cfbf2e98039858416fa3ebd7a">psa_aead_decrypt</a> (<a class="el" href="group__platform.html#gac3da92a6b8a7f0c01dc348f8e0432e4c">psa_key_slot_t</a> key, <a class="el" href="group__crypto__types.html#gac2e4d47f1300d73c2f829a6d99252d69">psa_algorithm_t</a> alg, const uint8_t *nonce, size_t nonce_length, const uint8_t *additional_data, size_t additional_data_length, const uint8_t *ciphertext, size_t ciphertext_length, uint8_t *plaintext, size_t plaintext_size, size_t *plaintext_length)</td></tr>
80<tr class="separator:ga5b88ad2cfbf2e98039858416fa3ebd7a"><td class="memSeparator" colspan="2">&#160;</td></tr>
81</table>
82<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
83<h2 class="groupheader">Macro Definition Documentation</h2>
84<a id="ga337ef01fe3c9f71d62ccced33e8917f4"></a>
85<h2 class="memtitle"><span class="permalink"><a href="#ga337ef01fe3c9f71d62ccced33e8917f4">&#9670;&nbsp;</a></span>PSA_AEAD_TAG_SIZE</h2>
86
87<div class="memitem">
88<div class="memproto">
89 <table class="memname">
90 <tr>
91 <td class="memname">#define PSA_AEAD_TAG_SIZE</td>
92 <td>(</td>
93 <td class="paramtype">&#160;</td>
94 <td class="paramname">alg</td><td>)</td>
95 <td></td>
96 </tr>
97 </table>
98</div><div class="memdoc">
99<b>Value:</b><div class="fragment"><div class="line">((alg) == PSA_ALG_GCM ? 16 : \</div><div class="line"> (alg) == PSA_ALG_CCM ? 16 : \</div><div class="line"> 0)</div></div><!-- fragment --><p>The tag size for an AEAD algorithm, in bytes.</p>
100<dl class="params"><dt>Parameters</dt><dd>
101 <table class="params">
102 <tr><td class="paramname">alg</td><td>An AEAD algorithm (<code>PSA_ALG_XXX</code> value such that <a class="el" href="group__crypto__types.html#ga1d44829d60065eaa4ac9a703e7d6abc8">PSA_ALG_IS_AEAD</a>(<code>alg</code>) is true).</td></tr>
103 </table>
104 </dd>
105</dl>
106<dl class="section return"><dt>Returns</dt><dd>The tag size for the specified algorithm. If the AEAD algorithm does not have an identified tag that can be distinguished from the rest of the ciphertext, return 0. If the AEAD algorithm is not recognized, return 0. An implementation may return either 0 or a correct size for an AEAD algorithm that it recognizes, but does not support. </dd></dl>
107
108</div>
109</div>
110<h2 class="groupheader">Function Documentation</h2>
111<a id="ga5b88ad2cfbf2e98039858416fa3ebd7a"></a>
112<h2 class="memtitle"><span class="permalink"><a href="#ga5b88ad2cfbf2e98039858416fa3ebd7a">&#9670;&nbsp;</a></span>psa_aead_decrypt()</h2>
113
114<div class="memitem">
115<div class="memproto">
116 <table class="memname">
117 <tr>
118 <td class="memname"><a class="el" href="group__basic.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a> psa_aead_decrypt </td>
119 <td>(</td>
120 <td class="paramtype"><a class="el" href="group__platform.html#gac3da92a6b8a7f0c01dc348f8e0432e4c">psa_key_slot_t</a>&#160;</td>
121 <td class="paramname"><em>key</em>, </td>
122 </tr>
123 <tr>
124 <td class="paramkey"></td>
125 <td></td>
126 <td class="paramtype"><a class="el" href="group__crypto__types.html#gac2e4d47f1300d73c2f829a6d99252d69">psa_algorithm_t</a>&#160;</td>
127 <td class="paramname"><em>alg</em>, </td>
128 </tr>
129 <tr>
130 <td class="paramkey"></td>
131 <td></td>
132 <td class="paramtype">const uint8_t *&#160;</td>
133 <td class="paramname"><em>nonce</em>, </td>
134 </tr>
135 <tr>
136 <td class="paramkey"></td>
137 <td></td>
138 <td class="paramtype">size_t&#160;</td>
139 <td class="paramname"><em>nonce_length</em>, </td>
140 </tr>
141 <tr>
142 <td class="paramkey"></td>
143 <td></td>
144 <td class="paramtype">const uint8_t *&#160;</td>
145 <td class="paramname"><em>additional_data</em>, </td>
146 </tr>
147 <tr>
148 <td class="paramkey"></td>
149 <td></td>
150 <td class="paramtype">size_t&#160;</td>
151 <td class="paramname"><em>additional_data_length</em>, </td>
152 </tr>
153 <tr>
154 <td class="paramkey"></td>
155 <td></td>
156 <td class="paramtype">const uint8_t *&#160;</td>
157 <td class="paramname"><em>ciphertext</em>, </td>
158 </tr>
159 <tr>
160 <td class="paramkey"></td>
161 <td></td>
162 <td class="paramtype">size_t&#160;</td>
163 <td class="paramname"><em>ciphertext_length</em>, </td>
164 </tr>
165 <tr>
166 <td class="paramkey"></td>
167 <td></td>
168 <td class="paramtype">uint8_t *&#160;</td>
169 <td class="paramname"><em>plaintext</em>, </td>
170 </tr>
171 <tr>
172 <td class="paramkey"></td>
173 <td></td>
174 <td class="paramtype">size_t&#160;</td>
175 <td class="paramname"><em>plaintext_size</em>, </td>
176 </tr>
177 <tr>
178 <td class="paramkey"></td>
179 <td></td>
180 <td class="paramtype">size_t *&#160;</td>
181 <td class="paramname"><em>plaintext_length</em>&#160;</td>
182 </tr>
183 <tr>
184 <td></td>
185 <td>)</td>
186 <td></td><td></td>
187 </tr>
188 </table>
189</div><div class="memdoc">
190<p>Process an authenticated decryption operation.</p>
191<dl class="params"><dt>Parameters</dt><dd>
192 <table class="params">
193 <tr><td class="paramdir"></td><td class="paramname">key</td><td>Slot containing the key to use. </td></tr>
194 <tr><td class="paramdir"></td><td class="paramname">alg</td><td>The AEAD algorithm to compute (<code>PSA_ALG_XXX</code> value such that <a class="el" href="group__crypto__types.html#ga1d44829d60065eaa4ac9a703e7d6abc8">PSA_ALG_IS_AEAD</a>(<code>alg</code>) is true). </td></tr>
195 <tr><td class="paramdir">[in]</td><td class="paramname">nonce</td><td>Nonce or IV to use. </td></tr>
196 <tr><td class="paramdir"></td><td class="paramname">nonce_length</td><td>Size of the <code>nonce</code> buffer in bytes. </td></tr>
197 <tr><td class="paramdir">[in]</td><td class="paramname">additional_data</td><td>Additional data that has been authenticated but not encrypted. </td></tr>
198 <tr><td class="paramdir"></td><td class="paramname">additional_data_length</td><td>Size of <code>additional_data</code> in bytes. </td></tr>
199 <tr><td class="paramdir">[in]</td><td class="paramname">ciphertext</td><td>Data that has been authenticated and encrypted. For algorithms where the encrypted data and the authentication tag are defined as separate inputs, the buffer must contain the encrypted data followed by the authentication tag. </td></tr>
200 <tr><td class="paramdir"></td><td class="paramname">ciphertext_length</td><td>Size of <code>ciphertext</code> in bytes. </td></tr>
201 <tr><td class="paramdir">[out]</td><td class="paramname">plaintext</td><td>Output buffer for the decrypted data. </td></tr>
202 <tr><td class="paramdir"></td><td class="paramname">plaintext_size</td><td>Size of the <code>plaintext</code> buffer in bytes. This must be at least <a class="el" href="crypto__sizes_8h.html#a1d057796166c16eb673ad1997e48a60b">PSA_AEAD_DECRYPT_OUTPUT_SIZE</a>(<code>alg</code>, <code>ciphertext_length</code>). </td></tr>
203 <tr><td class="paramdir">[out]</td><td class="paramname">plaintext_length</td><td>On success, the size of the output in the <b>plaintext</b> buffer.</td></tr>
204 </table>
205 </dd>
206</dl>
207<dl class="retval"><dt>Return values</dt><dd>
208 <table class="retval">
209 <tr><td class="paramname"><a class="el" href="group__basic.html#ga4cc859e2c66ca381c7418db3527a65e1">PSA_SUCCESS</a></td><td>Success. </td></tr>
210 <tr><td class="paramname"><a class="el" href="group__basic.html#gaba00e3e6ceb2b12965a81e5ac02ae040">PSA_ERROR_EMPTY_SLOT</a></td><td></td></tr>
211 <tr><td class="paramname"><a class="el" href="group__basic.html#ga35927f755d232c4766de600f2c49e9f2">PSA_ERROR_INVALID_SIGNATURE</a></td><td>The ciphertext is not authentic. </td></tr>
212 <tr><td class="paramname"><a class="el" href="group__basic.html#ga4d1b8dd8526177a15a210b7afc1accb1">PSA_ERROR_NOT_PERMITTED</a></td><td></td></tr>
213 <tr><td class="paramname"><a class="el" href="group__basic.html#ga798df25a505ebf931f7bec1f80f1f85f">PSA_ERROR_INVALID_ARGUMENT</a></td><td><code>key</code> is not compatible with <code>alg</code>. </td></tr>
214 <tr><td class="paramname"><a class="el" href="group__basic.html#ga1dcc6d130633ed5db8942257581b55dd">PSA_ERROR_NOT_SUPPORTED</a></td><td><code>alg</code> is not supported or is not an AEAD algorithm. </td></tr>
215 <tr><td class="paramname"><a class="el" href="group__basic.html#ga91b2ad8a867517a2651f1b076c5216e5">PSA_ERROR_INSUFFICIENT_MEMORY</a></td><td></td></tr>
216 <tr><td class="paramname"><a class="el" href="group__basic.html#ga5cdb6948371d49e916106249020ea3f7">PSA_ERROR_COMMUNICATION_FAILURE</a></td><td></td></tr>
217 <tr><td class="paramname"><a class="el" href="group__basic.html#ga08b10e70fa5ff0b05c631d9f8f6b2c6b">PSA_ERROR_HARDWARE_FAILURE</a></td><td></td></tr>
218 <tr><td class="paramname"><a class="el" href="group__basic.html#ga2c5dda1485cb54f2385cb9c1279a7004">PSA_ERROR_TAMPERING_DETECTED</a></td><td></td></tr>
219 </table>
220 </dd>
221</dl>
222
223</div>
224</div>
225<a id="ga14e4068a3d328515a4884f3037904d54"></a>
226<h2 class="memtitle"><span class="permalink"><a href="#ga14e4068a3d328515a4884f3037904d54">&#9670;&nbsp;</a></span>psa_aead_encrypt()</h2>
227
228<div class="memitem">
229<div class="memproto">
230 <table class="memname">
231 <tr>
232 <td class="memname"><a class="el" href="group__basic.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a> psa_aead_encrypt </td>
233 <td>(</td>
234 <td class="paramtype"><a class="el" href="group__platform.html#gac3da92a6b8a7f0c01dc348f8e0432e4c">psa_key_slot_t</a>&#160;</td>
235 <td class="paramname"><em>key</em>, </td>
236 </tr>
237 <tr>
238 <td class="paramkey"></td>
239 <td></td>
240 <td class="paramtype"><a class="el" href="group__crypto__types.html#gac2e4d47f1300d73c2f829a6d99252d69">psa_algorithm_t</a>&#160;</td>
241 <td class="paramname"><em>alg</em>, </td>
242 </tr>
243 <tr>
244 <td class="paramkey"></td>
245 <td></td>
246 <td class="paramtype">const uint8_t *&#160;</td>
247 <td class="paramname"><em>nonce</em>, </td>
248 </tr>
249 <tr>
250 <td class="paramkey"></td>
251 <td></td>
252 <td class="paramtype">size_t&#160;</td>
253 <td class="paramname"><em>nonce_length</em>, </td>
254 </tr>
255 <tr>
256 <td class="paramkey"></td>
257 <td></td>
258 <td class="paramtype">const uint8_t *&#160;</td>
259 <td class="paramname"><em>additional_data</em>, </td>
260 </tr>
261 <tr>
262 <td class="paramkey"></td>
263 <td></td>
264 <td class="paramtype">size_t&#160;</td>
265 <td class="paramname"><em>additional_data_length</em>, </td>
266 </tr>
267 <tr>
268 <td class="paramkey"></td>
269 <td></td>
270 <td class="paramtype">const uint8_t *&#160;</td>
271 <td class="paramname"><em>plaintext</em>, </td>
272 </tr>
273 <tr>
274 <td class="paramkey"></td>
275 <td></td>
276 <td class="paramtype">size_t&#160;</td>
277 <td class="paramname"><em>plaintext_length</em>, </td>
278 </tr>
279 <tr>
280 <td class="paramkey"></td>
281 <td></td>
282 <td class="paramtype">uint8_t *&#160;</td>
283 <td class="paramname"><em>ciphertext</em>, </td>
284 </tr>
285 <tr>
286 <td class="paramkey"></td>
287 <td></td>
288 <td class="paramtype">size_t&#160;</td>
289 <td class="paramname"><em>ciphertext_size</em>, </td>
290 </tr>
291 <tr>
292 <td class="paramkey"></td>
293 <td></td>
294 <td class="paramtype">size_t *&#160;</td>
295 <td class="paramname"><em>ciphertext_length</em>&#160;</td>
296 </tr>
297 <tr>
298 <td></td>
299 <td>)</td>
300 <td></td><td></td>
301 </tr>
302 </table>
303</div><div class="memdoc">
304<p>Process an authenticated encryption operation.</p>
305<dl class="params"><dt>Parameters</dt><dd>
306 <table class="params">
307 <tr><td class="paramdir"></td><td class="paramname">key</td><td>Slot containing the key to use. </td></tr>
308 <tr><td class="paramdir"></td><td class="paramname">alg</td><td>The AEAD algorithm to compute (<code>PSA_ALG_XXX</code> value such that <a class="el" href="group__crypto__types.html#ga1d44829d60065eaa4ac9a703e7d6abc8">PSA_ALG_IS_AEAD</a>(<code>alg</code>) is true). </td></tr>
309 <tr><td class="paramdir">[in]</td><td class="paramname">nonce</td><td>Nonce or IV to use. </td></tr>
310 <tr><td class="paramdir"></td><td class="paramname">nonce_length</td><td>Size of the <code>nonce</code> buffer in bytes. </td></tr>
311 <tr><td class="paramdir">[in]</td><td class="paramname">additional_data</td><td>Additional data that will be authenticated but not encrypted. </td></tr>
312 <tr><td class="paramdir"></td><td class="paramname">additional_data_length</td><td>Size of <code>additional_data</code> in bytes. </td></tr>
313 <tr><td class="paramdir">[in]</td><td class="paramname">plaintext</td><td>Data that will be authenticated and encrypted. </td></tr>
314 <tr><td class="paramdir"></td><td class="paramname">plaintext_length</td><td>Size of <code>plaintext</code> in bytes. </td></tr>
315 <tr><td class="paramdir">[out]</td><td class="paramname">ciphertext</td><td>Output buffer for the authenticated and encrypted data. The additional data is not part of this output. For algorithms where the encrypted data and the authentication tag are defined as separate outputs, the authentication tag is appended to the encrypted data. </td></tr>
316 <tr><td class="paramdir"></td><td class="paramname">ciphertext_size</td><td>Size of the <code>ciphertext</code> buffer in bytes. This must be at least <a class="el" href="crypto__sizes_8h.html#a85667d47a7aa6c7b99a80e5273671266">PSA_AEAD_ENCRYPT_OUTPUT_SIZE</a>(<code>alg</code>, <code>plaintext_length</code>). </td></tr>
317 <tr><td class="paramdir">[out]</td><td class="paramname">ciphertext_length</td><td>On success, the size of the output in the <b>ciphertext</b> buffer.</td></tr>
318 </table>
319 </dd>
320</dl>
321<dl class="retval"><dt>Return values</dt><dd>
322 <table class="retval">
323 <tr><td class="paramname"><a class="el" href="group__basic.html#ga4cc859e2c66ca381c7418db3527a65e1">PSA_SUCCESS</a></td><td>Success. </td></tr>
324 <tr><td class="paramname"><a class="el" href="group__basic.html#gaba00e3e6ceb2b12965a81e5ac02ae040">PSA_ERROR_EMPTY_SLOT</a></td><td></td></tr>
325 <tr><td class="paramname"><a class="el" href="group__basic.html#ga4d1b8dd8526177a15a210b7afc1accb1">PSA_ERROR_NOT_PERMITTED</a></td><td></td></tr>
326 <tr><td class="paramname"><a class="el" href="group__basic.html#ga798df25a505ebf931f7bec1f80f1f85f">PSA_ERROR_INVALID_ARGUMENT</a></td><td><code>key</code> is not compatible with <code>alg</code>. </td></tr>
327 <tr><td class="paramname"><a class="el" href="group__basic.html#ga1dcc6d130633ed5db8942257581b55dd">PSA_ERROR_NOT_SUPPORTED</a></td><td><code>alg</code> is not supported or is not an AEAD algorithm. </td></tr>
328 <tr><td class="paramname"><a class="el" href="group__basic.html#ga91b2ad8a867517a2651f1b076c5216e5">PSA_ERROR_INSUFFICIENT_MEMORY</a></td><td></td></tr>
329 <tr><td class="paramname"><a class="el" href="group__basic.html#ga5cdb6948371d49e916106249020ea3f7">PSA_ERROR_COMMUNICATION_FAILURE</a></td><td></td></tr>
330 <tr><td class="paramname"><a class="el" href="group__basic.html#ga08b10e70fa5ff0b05c631d9f8f6b2c6b">PSA_ERROR_HARDWARE_FAILURE</a></td><td></td></tr>
331 <tr><td class="paramname"><a class="el" href="group__basic.html#ga2c5dda1485cb54f2385cb9c1279a7004">PSA_ERROR_TAMPERING_DETECTED</a></td><td></td></tr>
332 </table>
333 </dd>
334</dl>
335
336</div>
337</div>
338</div><!-- contents -->
339<!-- start footer part -->
340<hr class="footer"/><address class="footer"><small>
341Generated by &#160;<a href="http://www.doxygen.org/index.html">
342<img class="footer" src="doxygen.png" alt="doxygen"/>
343</a> 1.8.13
344</small></address>
345</body>
346</html>