TrustedFirmware Git Browser
Code Review Sign In
review.trustedfirmware.org / mirror / mbed-crypto / 45adc5bee5dff2fb34c33edc077bee34c85cd00c / . / docs / html / group__aead.html
blob: 9ff9a2150d47502a514d41082a9af4a2b8d3fc31 [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: Authenticated encryption with associated data (AEAD)</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
Gilles Peskine45adc5b2019-03-05 16:34:20 +0100[diff] [blame^]27 &#160;<span id="projectnumber">beta 2 — 2019-02-22</span>
Gilles Peskine89f0a532019-01-31 11:47:57 +0100[diff] [blame]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">Authenticated encryption with associated data (AEAD)</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:gaf52e036794c0dc6fbadd93a2b990f366"><td class="memItemLeft" align="right" valign="top">#define&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__aead.html#gaf52e036794c0dc6fbadd93a2b990f366">PSA_AEAD_OPERATION_INIT</a>&#160;&#160;&#160;{0}</td></tr>
91<tr class="separator:gaf52e036794c0dc6fbadd93a2b990f366"><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:ga14f6a01afbaa8c5b3d8c5d345cbaa3ed"><td class="memItemLeft" align="right" valign="top">typedef struct psa_aead_operation_s&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__aead.html#ga14f6a01afbaa8c5b3d8c5d345cbaa3ed">psa_aead_operation_t</a></td></tr>
96<tr class="separator:ga14f6a01afbaa8c5b3d8c5d345cbaa3ed"><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:ga44de092cf58bb6c820c5c80a6c51610d"><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__aead.html#ga44de092cf58bb6c820c5c80a6c51610d">psa_aead_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 *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>
101<tr class="separator:ga44de092cf58bb6c820c5c80a6c51610d"><td class="memSeparator" colspan="2">&#160;</td></tr>
102<tr class="memitem:gaa8ce6527f2e227f1071fadbf2099793b"><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__aead.html#gaa8ce6527f2e227f1071fadbf2099793b">psa_aead_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 *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>
103<tr class="separator:gaa8ce6527f2e227f1071fadbf2099793b"><td class="memSeparator" colspan="2">&#160;</td></tr>
104<tr class="memitem:ga47265dc4852f1476f852752218fd12b2"><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__aead.html#ga47265dc4852f1476f852752218fd12b2">psa_aead_encrypt_setup</a> (<a class="el" href="group__aead.html#ga14f6a01afbaa8c5b3d8c5d345cbaa3ed">psa_aead_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:ga47265dc4852f1476f852752218fd12b2"><td class="memSeparator" colspan="2">&#160;</td></tr>
106<tr class="memitem:ga439896519d4a367ec86b47f201884152"><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__aead.html#ga439896519d4a367ec86b47f201884152">psa_aead_decrypt_setup</a> (<a class="el" href="group__aead.html#ga14f6a01afbaa8c5b3d8c5d345cbaa3ed">psa_aead_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:ga439896519d4a367ec86b47f201884152"><td class="memSeparator" colspan="2">&#160;</td></tr>
108<tr class="memitem:ga3eadcf2a29f662129ea4fb3454969ba2"><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__aead.html#ga3eadcf2a29f662129ea4fb3454969ba2">psa_aead_generate_nonce</a> (<a class="el" href="group__aead.html#ga14f6a01afbaa8c5b3d8c5d345cbaa3ed">psa_aead_operation_t</a> *operation, unsigned char *nonce, size_t nonce_size, size_t *nonce_length)</td></tr>
109<tr class="separator:ga3eadcf2a29f662129ea4fb3454969ba2"><td class="memSeparator" colspan="2">&#160;</td></tr>
110<tr class="memitem:ga40641d0721ca7fe01bbcd9ef635fbc46"><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__aead.html#ga40641d0721ca7fe01bbcd9ef635fbc46">psa_aead_set_nonce</a> (<a class="el" href="group__aead.html#ga14f6a01afbaa8c5b3d8c5d345cbaa3ed">psa_aead_operation_t</a> *operation, const unsigned char *nonce, size_t nonce_length)</td></tr>
111<tr class="separator:ga40641d0721ca7fe01bbcd9ef635fbc46"><td class="memSeparator" colspan="2">&#160;</td></tr>
112<tr class="memitem:gad3431e28d05002c2a7b0760610176050"><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__aead.html#gad3431e28d05002c2a7b0760610176050">psa_aead_set_lengths</a> (<a class="el" href="group__aead.html#ga14f6a01afbaa8c5b3d8c5d345cbaa3ed">psa_aead_operation_t</a> *operation, size_t ad_length, size_t plaintext_length)</td></tr>
113<tr class="separator:gad3431e28d05002c2a7b0760610176050"><td class="memSeparator" colspan="2">&#160;</td></tr>
114<tr class="memitem:ga6d0eed03f832e5c9c91cb8adf2882569"><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__aead.html#ga6d0eed03f832e5c9c91cb8adf2882569">psa_aead_update_ad</a> (<a class="el" href="group__aead.html#ga14f6a01afbaa8c5b3d8c5d345cbaa3ed">psa_aead_operation_t</a> *operation, const uint8_t *input, size_t input_length)</td></tr>
115<tr class="separator:ga6d0eed03f832e5c9c91cb8adf2882569"><td class="memSeparator" colspan="2">&#160;</td></tr>
116<tr class="memitem:ga3b105de2088cef7c3d9e2fd8048c841c"><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__aead.html#ga3b105de2088cef7c3d9e2fd8048c841c">psa_aead_update</a> (<a class="el" href="group__aead.html#ga14f6a01afbaa8c5b3d8c5d345cbaa3ed">psa_aead_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>
117<tr class="separator:ga3b105de2088cef7c3d9e2fd8048c841c"><td class="memSeparator" colspan="2">&#160;</td></tr>
118<tr class="memitem:ga759791bbe1763b377c3b5447641f1fc8"><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__aead.html#ga759791bbe1763b377c3b5447641f1fc8">psa_aead_finish</a> (<a class="el" href="group__aead.html#ga14f6a01afbaa8c5b3d8c5d345cbaa3ed">psa_aead_operation_t</a> *operation, uint8_t *ciphertext, size_t ciphertext_size, size_t *ciphertext_length, uint8_t *tag, size_t tag_size, size_t *tag_length)</td></tr>
119<tr class="separator:ga759791bbe1763b377c3b5447641f1fc8"><td class="memSeparator" colspan="2">&#160;</td></tr>
120<tr class="memitem:gaaed211fc61977c859d6ff07f39f59219"><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__aead.html#gaaed211fc61977c859d6ff07f39f59219">psa_aead_verify</a> (<a class="el" href="group__aead.html#ga14f6a01afbaa8c5b3d8c5d345cbaa3ed">psa_aead_operation_t</a> *operation, const uint8_t *tag, size_t tag_length)</td></tr>
121<tr class="separator:gaaed211fc61977c859d6ff07f39f59219"><td class="memSeparator" colspan="2">&#160;</td></tr>
122<tr class="memitem:gae8a5f93d92318c8f592ee9fbb9d36ba0"><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__aead.html#gae8a5f93d92318c8f592ee9fbb9d36ba0">psa_aead_abort</a> (<a class="el" href="group__aead.html#ga14f6a01afbaa8c5b3d8c5d345cbaa3ed">psa_aead_operation_t</a> *operation)</td></tr>
123<tr class="separator:gae8a5f93d92318c8f592ee9fbb9d36ba0"><td class="memSeparator" colspan="2">&#160;</td></tr>
124</table>
125<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
126<h2 class="groupheader">Macro Definition Documentation</h2>
127<a class="anchor" id="gaf52e036794c0dc6fbadd93a2b990f366"></a>
128<div class="memitem">
129<div class="memproto">
130 <table class="memname">
131 <tr>
132 <td class="memname">#define PSA_AEAD_OPERATION_INIT&#160;&#160;&#160;{0}</td>
133 </tr>
134 </table>
135</div><div class="memdoc">
136<p>This macro returns a suitable initializer for an AEAD operation object of type <a class="el" href="group__aead.html#ga14f6a01afbaa8c5b3d8c5d345cbaa3ed">psa_aead_operation_t</a>. </p>
137
138</div>
139</div>
140<h2 class="groupheader">Typedef Documentation</h2>
141<a class="anchor" id="ga14f6a01afbaa8c5b3d8c5d345cbaa3ed"></a>
142<div class="memitem">
143<div class="memproto">
144 <table class="memname">
145 <tr>
146 <td class="memname">typedef struct psa_aead_operation_s <a class="el" href="group__aead.html#ga14f6a01afbaa8c5b3d8c5d345cbaa3ed">psa_aead_operation_t</a></td>
147 </tr>
148 </table>
149</div><div class="memdoc">
150<p>The type of the state data structure for multipart AEAD operations.</p>
151<p>Before calling any function on an AEAD operation object, the application must initialize it by any of the following means:</p><ul>
152<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_aead_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>
153<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_aead_operation_t operation = {0};</div></div><!-- fragment --></li>
154<li>Initialize the structure to the initializer <a class="el" href="group__aead.html#gaf52e036794c0dc6fbadd93a2b990f366">PSA_AEAD_OPERATION_INIT</a>, for example: <div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno"> 1</span>&#160;psa_aead_operation_t operation = PSA_AEAD_OPERATION_INIT;</div></div><!-- fragment --></li>
155<li>Assign the result of the function psa_aead_operation_init() to the structure, for example: <div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno"> 1</span>&#160;psa_aead_operation_t operation;</div><div class="line"><a name="l00002"></a><span class="lineno"> 2</span>&#160;operation = psa_aead_operation_init();</div></div><!-- fragment --></li>
156</ul>
157<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>
158
159</div>
160</div>
161<h2 class="groupheader">Function Documentation</h2>
162<a class="anchor" id="gae8a5f93d92318c8f592ee9fbb9d36ba0"></a>
163<div class="memitem">
164<div class="memproto">
165 <table class="memname">
166 <tr>
167 <td class="memname"><a class="el" href="group__error.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a> psa_aead_abort </td>
168 <td>(</td>
169 <td class="paramtype"><a class="el" href="group__aead.html#ga14f6a01afbaa8c5b3d8c5d345cbaa3ed">psa_aead_operation_t</a> *&#160;</td>
170 <td class="paramname"><em>operation</em></td><td>)</td>
171 <td></td>
172 </tr>
173 </table>
174</div><div class="memdoc">
175<p>Abort an AEAD operation.</p>
176<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__aead.html#ga47265dc4852f1476f852752218fd12b2">psa_aead_encrypt_setup()</a> or <a class="el" href="group__aead.html#ga439896519d4a367ec86b47f201884152">psa_aead_decrypt_setup()</a> again.</p>
177<p>You may call this function any time after the operation object has been initialized by any of the following methods:</p><ul>
178<li>A call to <a class="el" href="group__aead.html#ga47265dc4852f1476f852752218fd12b2">psa_aead_encrypt_setup()</a> or <a class="el" href="group__aead.html#ga439896519d4a367ec86b47f201884152">psa_aead_decrypt_setup()</a>, whether it succeeds or not.</li>
179<li>Initializing the <code>struct</code> to all-bits-zero.</li>
180<li>Initializing the <code>struct</code> to logical zeros, e.g. <code>psa_aead_operation_t operation = {0}</code>.</li>
181</ul>
182<p>In particular, calling <a class="el" href="group__aead.html#gae8a5f93d92318c8f592ee9fbb9d36ba0">psa_aead_abort()</a> after the operation has been terminated by a call to <a class="el" href="group__aead.html#gae8a5f93d92318c8f592ee9fbb9d36ba0">psa_aead_abort()</a> or <a class="el" href="group__aead.html#ga759791bbe1763b377c3b5447641f1fc8">psa_aead_finish()</a> is safe and has no effect.</p>
183<dl class="params"><dt>Parameters</dt><dd>
184 <table class="params">
185 <tr><td class="paramdir">[in,out]</td><td class="paramname">operation</td><td>Initialized AEAD operation.</td></tr>
186 </table>
187 </dd>
188</dl>
189<dl class="retval"><dt>Return values</dt><dd>
190 <table class="retval">
191 <tr><td class="paramname"><a class="el" href="group__error.html#ga4cc859e2c66ca381c7418db3527a65e1">PSA_SUCCESS</a></td><td></td></tr>
192 <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 AEAD operation. </td></tr>
193 <tr><td class="paramname"><a class="el" href="group__error.html#ga5cdb6948371d49e916106249020ea3f7">PSA_ERROR_COMMUNICATION_FAILURE</a></td><td></td></tr>
194 <tr><td class="paramname"><a class="el" href="group__error.html#ga08b10e70fa5ff0b05c631d9f8f6b2c6b">PSA_ERROR_HARDWARE_FAILURE</a></td><td></td></tr>
195 <tr><td class="paramname"><a class="el" href="group__error.html#ga2c5dda1485cb54f2385cb9c1279a7004">PSA_ERROR_TAMPERING_DETECTED</a></td><td></td></tr>
196 </table>
197 </dd>
198</dl>
199
200</div>
201</div>
202<a class="anchor" id="gaa8ce6527f2e227f1071fadbf2099793b"></a>
203<div class="memitem">
204<div class="memproto">
205 <table class="memname">
206 <tr>
207 <td class="memname"><a class="el" href="group__error.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a> psa_aead_decrypt </td>
208 <td>(</td>
209 <td class="paramtype"><a class="el" href="group__platform.html#gabf6d5fd4e2ea89ecd425c88f057e7f75">psa_key_handle_t</a>&#160;</td>
210 <td class="paramname"><em>handle</em>, </td>
211 </tr>
212 <tr>
213 <td class="paramkey"></td>
214 <td></td>
215 <td class="paramtype"><a class="el" href="group__crypto__types.html#gac2e4d47f1300d73c2f829a6d99252d69">psa_algorithm_t</a>&#160;</td>
216 <td class="paramname"><em>alg</em>, </td>
217 </tr>
218 <tr>
219 <td class="paramkey"></td>
220 <td></td>
221 <td class="paramtype">const uint8_t *&#160;</td>
222 <td class="paramname"><em>nonce</em>, </td>
223 </tr>
224 <tr>
225 <td class="paramkey"></td>
226 <td></td>
227 <td class="paramtype">size_t&#160;</td>
228 <td class="paramname"><em>nonce_length</em>, </td>
229 </tr>
230 <tr>
231 <td class="paramkey"></td>
232 <td></td>
233 <td class="paramtype">const uint8_t *&#160;</td>
234 <td class="paramname"><em>additional_data</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>additional_data_length</em>, </td>
241 </tr>
242 <tr>
243 <td class="paramkey"></td>
244 <td></td>
245 <td class="paramtype">const uint8_t *&#160;</td>
246 <td class="paramname"><em>ciphertext</em>, </td>
247 </tr>
248 <tr>
249 <td class="paramkey"></td>
250 <td></td>
251 <td class="paramtype">size_t&#160;</td>
252 <td class="paramname"><em>ciphertext_length</em>, </td>
253 </tr>
254 <tr>
255 <td class="paramkey"></td>
256 <td></td>
257 <td class="paramtype">uint8_t *&#160;</td>
258 <td class="paramname"><em>plaintext</em>, </td>
259 </tr>
260 <tr>
261 <td class="paramkey"></td>
262 <td></td>
263 <td class="paramtype">size_t&#160;</td>
264 <td class="paramname"><em>plaintext_size</em>, </td>
265 </tr>
266 <tr>
267 <td class="paramkey"></td>
268 <td></td>
269 <td class="paramtype">size_t *&#160;</td>
270 <td class="paramname"><em>plaintext_length</em>&#160;</td>
271 </tr>
272 <tr>
273 <td></td>
274 <td>)</td>
275 <td></td><td></td>
276 </tr>
277 </table>
278</div><div class="memdoc">
279<p>Process an authenticated decryption operation.</p>
280<dl class="params"><dt>Parameters</dt><dd>
281 <table class="params">
282 <tr><td class="paramdir"></td><td class="paramname">handle</td><td>Handle to the key to use for the operation. </td></tr>
283 <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>
284 <tr><td class="paramdir">[in]</td><td class="paramname">nonce</td><td>Nonce or IV to use. </td></tr>
285 <tr><td class="paramdir"></td><td class="paramname">nonce_length</td><td>Size of the <code>nonce</code> buffer in bytes. </td></tr>
286 <tr><td class="paramdir">[in]</td><td class="paramname">additional_data</td><td>Additional data that has been authenticated but not encrypted. </td></tr>
287 <tr><td class="paramdir"></td><td class="paramname">additional_data_length</td><td>Size of <code>additional_data</code> in bytes. </td></tr>
288 <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>
289 <tr><td class="paramdir"></td><td class="paramname">ciphertext_length</td><td>Size of <code>ciphertext</code> in bytes. </td></tr>
290 <tr><td class="paramdir">[out]</td><td class="paramname">plaintext</td><td>Output buffer for the decrypted data. </td></tr>
291 <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>
Gilles Peskine45adc5b2019-03-05 16:34:20 +0100[diff] [blame^]292 <tr><td class="paramdir">[out]</td><td class="paramname">plaintext_length</td><td>On success, the size of the output in the <code>plaintext</code> buffer.</td></tr>
Gilles Peskine89f0a532019-01-31 11:47:57 +0100[diff] [blame]293 </table>
294 </dd>
295</dl>
296<dl class="retval"><dt>Return values</dt><dd>
297 <table class="retval">
298 <tr><td class="paramname"><a class="el" href="group__error.html#ga4cc859e2c66ca381c7418db3527a65e1">PSA_SUCCESS</a></td><td>Success. </td></tr>
299 <tr><td class="paramname"><a class="el" href="group__error.html#gadf22718935657c2c3168c228204085f9">PSA_ERROR_INVALID_HANDLE</a></td><td></td></tr>
300 <tr><td class="paramname"><a class="el" href="group__error.html#gaba00e3e6ceb2b12965a81e5ac02ae040">PSA_ERROR_EMPTY_SLOT</a></td><td></td></tr>
301 <tr><td class="paramname"><a class="el" href="group__error.html#ga35927f755d232c4766de600f2c49e9f2">PSA_ERROR_INVALID_SIGNATURE</a></td><td>The ciphertext is not authentic. </td></tr>
302 <tr><td class="paramname"><a class="el" href="group__error.html#ga4d1b8dd8526177a15a210b7afc1accb1">PSA_ERROR_NOT_PERMITTED</a></td><td></td></tr>
303 <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>
304 <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 an AEAD algorithm. </td></tr>
305 <tr><td class="paramname"><a class="el" href="group__error.html#ga91b2ad8a867517a2651f1b076c5216e5">PSA_ERROR_INSUFFICIENT_MEMORY</a></td><td></td></tr>
306 <tr><td class="paramname"><a class="el" href="group__error.html#ga5cdb6948371d49e916106249020ea3f7">PSA_ERROR_COMMUNICATION_FAILURE</a></td><td></td></tr>
307 <tr><td class="paramname"><a class="el" href="group__error.html#ga08b10e70fa5ff0b05c631d9f8f6b2c6b">PSA_ERROR_HARDWARE_FAILURE</a></td><td></td></tr>
308 <tr><td class="paramname"><a class="el" href="group__error.html#ga2c5dda1485cb54f2385cb9c1279a7004">PSA_ERROR_TAMPERING_DETECTED</a></td><td></td></tr>
309 <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>
310 </table>
311 </dd>
312</dl>
313
314</div>
315</div>
316<a class="anchor" id="ga439896519d4a367ec86b47f201884152"></a>
317<div class="memitem">
318<div class="memproto">
319 <table class="memname">
320 <tr>
321 <td class="memname"><a class="el" href="group__error.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a> psa_aead_decrypt_setup </td>
322 <td>(</td>
323 <td class="paramtype"><a class="el" href="group__aead.html#ga14f6a01afbaa8c5b3d8c5d345cbaa3ed">psa_aead_operation_t</a> *&#160;</td>
324 <td class="paramname"><em>operation</em>, </td>
325 </tr>
326 <tr>
327 <td class="paramkey"></td>
328 <td></td>
329 <td class="paramtype"><a class="el" href="group__platform.html#gabf6d5fd4e2ea89ecd425c88f057e7f75">psa_key_handle_t</a>&#160;</td>
330 <td class="paramname"><em>handle</em>, </td>
331 </tr>
332 <tr>
333 <td class="paramkey"></td>
334 <td></td>
335 <td class="paramtype"><a class="el" href="group__crypto__types.html#gac2e4d47f1300d73c2f829a6d99252d69">psa_algorithm_t</a>&#160;</td>
336 <td class="paramname"><em>alg</em>&#160;</td>
337 </tr>
338 <tr>
339 <td></td>
340 <td>)</td>
341 <td></td><td></td>
342 </tr>
343 </table>
344</div><div class="memdoc">
345<p>Set the key for a multipart authenticated decryption operation.</p>
346<p>The sequence of operations to decrypt a message with authentication is as follows:</p><ol type="1">
347<li>Allocate an operation object which will be passed to all the functions listed here.</li>
348<li>Initialize the operation object with one of the methods described in the documentation for <a class="el" href="group__aead.html#ga14f6a01afbaa8c5b3d8c5d345cbaa3ed">psa_aead_operation_t</a>, e.g. PSA_AEAD_OPERATION_INIT.</li>
349<li>Call <a class="el" href="group__aead.html#ga439896519d4a367ec86b47f201884152">psa_aead_decrypt_setup()</a> to specify the algorithm and key.</li>
350<li>If needed, call <a class="el" href="group__aead.html#gad3431e28d05002c2a7b0760610176050">psa_aead_set_lengths()</a> to specify the length of the inputs to the subsequent calls to <a class="el" href="group__aead.html#ga6d0eed03f832e5c9c91cb8adf2882569">psa_aead_update_ad()</a> and <a class="el" href="group__aead.html#ga3b105de2088cef7c3d9e2fd8048c841c">psa_aead_update()</a>. See the documentation of <a class="el" href="group__aead.html#gad3431e28d05002c2a7b0760610176050">psa_aead_set_lengths()</a> for details.</li>
351<li>Call <a class="el" href="group__aead.html#ga40641d0721ca7fe01bbcd9ef635fbc46">psa_aead_set_nonce()</a> with the nonce for the decryption.</li>
352<li>Call <a class="el" href="group__aead.html#ga6d0eed03f832e5c9c91cb8adf2882569">psa_aead_update_ad()</a> zero, one or more times, passing a fragment of the non-encrypted additional authenticated data each time.</li>
353<li>Call <a class="el" href="group__aead.html#ga3b105de2088cef7c3d9e2fd8048c841c">psa_aead_update()</a> zero, one or more times, passing a fragment of the ciphertext to decrypt each time.</li>
354<li>Call <a class="el" href="group__aead.html#gaaed211fc61977c859d6ff07f39f59219">psa_aead_verify()</a>.</li>
355</ol>
356<p>The application may call <a class="el" href="group__aead.html#gae8a5f93d92318c8f592ee9fbb9d36ba0">psa_aead_abort()</a> at any time after the operation has been initialized.</p>
357<p>After a successful call to <a class="el" href="group__aead.html#ga439896519d4a367ec86b47f201884152">psa_aead_decrypt_setup()</a>, the application must eventually terminate the operation. The following events terminate an operation:</p><ul>
358<li>A failed call to any of the <code>psa_aead_xxx</code> functions.</li>
359<li>A call to <a class="el" href="group__aead.html#ga759791bbe1763b377c3b5447641f1fc8">psa_aead_finish()</a>, <a class="el" href="group__aead.html#gaaed211fc61977c859d6ff07f39f59219">psa_aead_verify()</a> or <a class="el" href="group__aead.html#gae8a5f93d92318c8f592ee9fbb9d36ba0">psa_aead_abort()</a>.</li>
360</ul>
361<dl class="params"><dt>Parameters</dt><dd>
362 <table class="params">
363 <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__aead.html#ga14f6a01afbaa8c5b3d8c5d345cbaa3ed">psa_aead_operation_t</a> and not yet in use. </td></tr>
364 <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>
365 <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>
366 </table>
367 </dd>
368</dl>
369<dl class="retval"><dt>Return values</dt><dd>
370 <table class="retval">
371 <tr><td class="paramname"><a class="el" href="group__error.html#ga4cc859e2c66ca381c7418db3527a65e1">PSA_SUCCESS</a></td><td>Success. </td></tr>
372 <tr><td class="paramname"><a class="el" href="group__error.html#gadf22718935657c2c3168c228204085f9">PSA_ERROR_INVALID_HANDLE</a></td><td></td></tr>
373 <tr><td class="paramname"><a class="el" href="group__error.html#gaba00e3e6ceb2b12965a81e5ac02ae040">PSA_ERROR_EMPTY_SLOT</a></td><td></td></tr>
374 <tr><td class="paramname"><a class="el" href="group__error.html#ga4d1b8dd8526177a15a210b7afc1accb1">PSA_ERROR_NOT_PERMITTED</a></td><td></td></tr>
375 <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>
376 <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 an AEAD algorithm. </td></tr>
377 <tr><td class="paramname"><a class="el" href="group__error.html#ga91b2ad8a867517a2651f1b076c5216e5">PSA_ERROR_INSUFFICIENT_MEMORY</a></td><td></td></tr>
378 <tr><td class="paramname"><a class="el" href="group__error.html#ga5cdb6948371d49e916106249020ea3f7">PSA_ERROR_COMMUNICATION_FAILURE</a></td><td></td></tr>
379 <tr><td class="paramname"><a class="el" href="group__error.html#ga08b10e70fa5ff0b05c631d9f8f6b2c6b">PSA_ERROR_HARDWARE_FAILURE</a></td><td></td></tr>
380 <tr><td class="paramname"><a class="el" href="group__error.html#ga2c5dda1485cb54f2385cb9c1279a7004">PSA_ERROR_TAMPERING_DETECTED</a></td><td></td></tr>
381 <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>
382 </table>
383 </dd>
384</dl>
385
386</div>
387</div>
388<a class="anchor" id="ga44de092cf58bb6c820c5c80a6c51610d"></a>
389<div class="memitem">
390<div class="memproto">
391 <table class="memname">
392 <tr>
393 <td class="memname"><a class="el" href="group__error.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a> psa_aead_encrypt </td>
394 <td>(</td>
395 <td class="paramtype"><a class="el" href="group__platform.html#gabf6d5fd4e2ea89ecd425c88f057e7f75">psa_key_handle_t</a>&#160;</td>
396 <td class="paramname"><em>handle</em>, </td>
397 </tr>
398 <tr>
399 <td class="paramkey"></td>
400 <td></td>
401 <td class="paramtype"><a class="el" href="group__crypto__types.html#gac2e4d47f1300d73c2f829a6d99252d69">psa_algorithm_t</a>&#160;</td>
402 <td class="paramname"><em>alg</em>, </td>
403 </tr>
404 <tr>
405 <td class="paramkey"></td>
406 <td></td>
407 <td class="paramtype">const uint8_t *&#160;</td>
408 <td class="paramname"><em>nonce</em>, </td>
409 </tr>
410 <tr>
411 <td class="paramkey"></td>
412 <td></td>
413 <td class="paramtype">size_t&#160;</td>
414 <td class="paramname"><em>nonce_length</em>, </td>
415 </tr>
416 <tr>
417 <td class="paramkey"></td>
418 <td></td>
419 <td class="paramtype">const uint8_t *&#160;</td>
420 <td class="paramname"><em>additional_data</em>, </td>
421 </tr>
422 <tr>
423 <td class="paramkey"></td>
424 <td></td>
425 <td class="paramtype">size_t&#160;</td>
426 <td class="paramname"><em>additional_data_length</em>, </td>
427 </tr>
428 <tr>
429 <td class="paramkey"></td>
430 <td></td>
431 <td class="paramtype">const uint8_t *&#160;</td>
432 <td class="paramname"><em>plaintext</em>, </td>
433 </tr>
434 <tr>
435 <td class="paramkey"></td>
436 <td></td>
437 <td class="paramtype">size_t&#160;</td>
438 <td class="paramname"><em>plaintext_length</em>, </td>
439 </tr>
440 <tr>
441 <td class="paramkey"></td>
442 <td></td>
443 <td class="paramtype">uint8_t *&#160;</td>
444 <td class="paramname"><em>ciphertext</em>, </td>
445 </tr>
446 <tr>
447 <td class="paramkey"></td>
448 <td></td>
449 <td class="paramtype">size_t&#160;</td>
450 <td class="paramname"><em>ciphertext_size</em>, </td>
451 </tr>
452 <tr>
453 <td class="paramkey"></td>
454 <td></td>
455 <td class="paramtype">size_t *&#160;</td>
456 <td class="paramname"><em>ciphertext_length</em>&#160;</td>
457 </tr>
458 <tr>
459 <td></td>
460 <td>)</td>
461 <td></td><td></td>
462 </tr>
463 </table>
464</div><div class="memdoc">
465<p>Process an authenticated encryption operation.</p>
466<dl class="params"><dt>Parameters</dt><dd>
467 <table class="params">
468 <tr><td class="paramdir"></td><td class="paramname">handle</td><td>Handle to the key to use for the operation. </td></tr>
469 <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>
470 <tr><td class="paramdir">[in]</td><td class="paramname">nonce</td><td>Nonce or IV to use. </td></tr>
471 <tr><td class="paramdir"></td><td class="paramname">nonce_length</td><td>Size of the <code>nonce</code> buffer in bytes. </td></tr>
472 <tr><td class="paramdir">[in]</td><td class="paramname">additional_data</td><td>Additional data that will be authenticated but not encrypted. </td></tr>
473 <tr><td class="paramdir"></td><td class="paramname">additional_data_length</td><td>Size of <code>additional_data</code> in bytes. </td></tr>
474 <tr><td class="paramdir">[in]</td><td class="paramname">plaintext</td><td>Data that will be authenticated and encrypted. </td></tr>
475 <tr><td class="paramdir"></td><td class="paramname">plaintext_length</td><td>Size of <code>plaintext</code> in bytes. </td></tr>
476 <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>
477 <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>
Gilles Peskine45adc5b2019-03-05 16:34:20 +0100[diff] [blame^]478 <tr><td class="paramdir">[out]</td><td class="paramname">ciphertext_length</td><td>On success, the size of the output in the <code>ciphertext</code> buffer.</td></tr>
Gilles Peskine89f0a532019-01-31 11:47:57 +0100[diff] [blame]479 </table>
480 </dd>
481</dl>
482<dl class="retval"><dt>Return values</dt><dd>
483 <table class="retval">
484 <tr><td class="paramname"><a class="el" href="group__error.html#ga4cc859e2c66ca381c7418db3527a65e1">PSA_SUCCESS</a></td><td>Success. </td></tr>
485 <tr><td class="paramname"><a class="el" href="group__error.html#gadf22718935657c2c3168c228204085f9">PSA_ERROR_INVALID_HANDLE</a></td><td></td></tr>
486 <tr><td class="paramname"><a class="el" href="group__error.html#gaba00e3e6ceb2b12965a81e5ac02ae040">PSA_ERROR_EMPTY_SLOT</a></td><td></td></tr>
487 <tr><td class="paramname"><a class="el" href="group__error.html#ga4d1b8dd8526177a15a210b7afc1accb1">PSA_ERROR_NOT_PERMITTED</a></td><td></td></tr>
488 <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>
489 <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 an AEAD algorithm. </td></tr>
490 <tr><td class="paramname"><a class="el" href="group__error.html#ga91b2ad8a867517a2651f1b076c5216e5">PSA_ERROR_INSUFFICIENT_MEMORY</a></td><td></td></tr>
491 <tr><td class="paramname"><a class="el" href="group__error.html#ga5cdb6948371d49e916106249020ea3f7">PSA_ERROR_COMMUNICATION_FAILURE</a></td><td></td></tr>
492 <tr><td class="paramname"><a class="el" href="group__error.html#ga08b10e70fa5ff0b05c631d9f8f6b2c6b">PSA_ERROR_HARDWARE_FAILURE</a></td><td></td></tr>
493 <tr><td class="paramname"><a class="el" href="group__error.html#ga2c5dda1485cb54f2385cb9c1279a7004">PSA_ERROR_TAMPERING_DETECTED</a></td><td></td></tr>
494 <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>
495 </table>
496 </dd>
497</dl>
498
499</div>
500</div>
501<a class="anchor" id="ga47265dc4852f1476f852752218fd12b2"></a>
502<div class="memitem">
503<div class="memproto">
504 <table class="memname">
505 <tr>
506 <td class="memname"><a class="el" href="group__error.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a> psa_aead_encrypt_setup </td>
507 <td>(</td>
508 <td class="paramtype"><a class="el" href="group__aead.html#ga14f6a01afbaa8c5b3d8c5d345cbaa3ed">psa_aead_operation_t</a> *&#160;</td>
509 <td class="paramname"><em>operation</em>, </td>
510 </tr>
511 <tr>
512 <td class="paramkey"></td>
513 <td></td>
514 <td class="paramtype"><a class="el" href="group__platform.html#gabf6d5fd4e2ea89ecd425c88f057e7f75">psa_key_handle_t</a>&#160;</td>
515 <td class="paramname"><em>handle</em>, </td>
516 </tr>
517 <tr>
518 <td class="paramkey"></td>
519 <td></td>
520 <td class="paramtype"><a class="el" href="group__crypto__types.html#gac2e4d47f1300d73c2f829a6d99252d69">psa_algorithm_t</a>&#160;</td>
521 <td class="paramname"><em>alg</em>&#160;</td>
522 </tr>
523 <tr>
524 <td></td>
525 <td>)</td>
526 <td></td><td></td>
527 </tr>
528 </table>
529</div><div class="memdoc">
530<p>Set the key for a multipart authenticated encryption operation.</p>
531<p>The sequence of operations to encrypt a message with authentication is as follows:</p><ol type="1">
532<li>Allocate an operation object which will be passed to all the functions listed here.</li>
533<li>Initialize the operation object with one of the methods described in the documentation for <a class="el" href="group__aead.html#ga14f6a01afbaa8c5b3d8c5d345cbaa3ed">psa_aead_operation_t</a>, e.g. PSA_AEAD_OPERATION_INIT.</li>
534<li>Call <a class="el" href="group__aead.html#ga47265dc4852f1476f852752218fd12b2">psa_aead_encrypt_setup()</a> to specify the algorithm and key.</li>
535<li>If needed, call <a class="el" href="group__aead.html#gad3431e28d05002c2a7b0760610176050">psa_aead_set_lengths()</a> to specify the length of the inputs to the subsequent calls to <a class="el" href="group__aead.html#ga6d0eed03f832e5c9c91cb8adf2882569">psa_aead_update_ad()</a> and <a class="el" href="group__aead.html#ga3b105de2088cef7c3d9e2fd8048c841c">psa_aead_update()</a>. See the documentation of <a class="el" href="group__aead.html#gad3431e28d05002c2a7b0760610176050">psa_aead_set_lengths()</a> for details.</li>
536<li>Call either <a class="el" href="group__aead.html#ga3eadcf2a29f662129ea4fb3454969ba2">psa_aead_generate_nonce()</a> or <a class="el" href="group__aead.html#ga40641d0721ca7fe01bbcd9ef635fbc46">psa_aead_set_nonce()</a> to generate or set the nonce. You should use <a class="el" href="group__aead.html#ga3eadcf2a29f662129ea4fb3454969ba2">psa_aead_generate_nonce()</a> unless the protocol you are implementing requires a specific nonce value.</li>
537<li>Call <a class="el" href="group__aead.html#ga6d0eed03f832e5c9c91cb8adf2882569">psa_aead_update_ad()</a> zero, one or more times, passing a fragment of the non-encrypted additional authenticated data each time.</li>
538<li>Call <a class="el" href="group__aead.html#ga3b105de2088cef7c3d9e2fd8048c841c">psa_aead_update()</a> zero, one or more times, passing a fragment of the message to encrypt each time.</li>
539<li>Call <a class="el" href="group__aead.html#ga759791bbe1763b377c3b5447641f1fc8">psa_aead_finish()</a>.</li>
540</ol>
541<p>The application may call <a class="el" href="group__aead.html#gae8a5f93d92318c8f592ee9fbb9d36ba0">psa_aead_abort()</a> at any time after the operation has been initialized.</p>
542<p>After a successful call to <a class="el" href="group__aead.html#ga47265dc4852f1476f852752218fd12b2">psa_aead_encrypt_setup()</a>, the application must eventually terminate the operation. The following events terminate an operation:</p><ul>
543<li>A failed call to any of the <code>psa_aead_xxx</code> functions.</li>
544<li>A call to <a class="el" href="group__aead.html#ga759791bbe1763b377c3b5447641f1fc8">psa_aead_finish()</a>, <a class="el" href="group__aead.html#gaaed211fc61977c859d6ff07f39f59219">psa_aead_verify()</a> or <a class="el" href="group__aead.html#gae8a5f93d92318c8f592ee9fbb9d36ba0">psa_aead_abort()</a>.</li>
545</ul>
546<dl class="params"><dt>Parameters</dt><dd>
547 <table class="params">
548 <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__aead.html#ga14f6a01afbaa8c5b3d8c5d345cbaa3ed">psa_aead_operation_t</a> and not yet in use. </td></tr>
549 <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>
550 <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>
551 </table>
552 </dd>
553</dl>
554<dl class="retval"><dt>Return values</dt><dd>
555 <table class="retval">
556 <tr><td class="paramname"><a class="el" href="group__error.html#ga4cc859e2c66ca381c7418db3527a65e1">PSA_SUCCESS</a></td><td>Success. </td></tr>
557 <tr><td class="paramname"><a class="el" href="group__error.html#gadf22718935657c2c3168c228204085f9">PSA_ERROR_INVALID_HANDLE</a></td><td></td></tr>
558 <tr><td class="paramname"><a class="el" href="group__error.html#gaba00e3e6ceb2b12965a81e5ac02ae040">PSA_ERROR_EMPTY_SLOT</a></td><td></td></tr>
559 <tr><td class="paramname"><a class="el" href="group__error.html#ga4d1b8dd8526177a15a210b7afc1accb1">PSA_ERROR_NOT_PERMITTED</a></td><td></td></tr>
560 <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>
561 <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 an AEAD algorithm. </td></tr>
562 <tr><td class="paramname"><a class="el" href="group__error.html#ga91b2ad8a867517a2651f1b076c5216e5">PSA_ERROR_INSUFFICIENT_MEMORY</a></td><td></td></tr>
563 <tr><td class="paramname"><a class="el" href="group__error.html#ga5cdb6948371d49e916106249020ea3f7">PSA_ERROR_COMMUNICATION_FAILURE</a></td><td></td></tr>
564 <tr><td class="paramname"><a class="el" href="group__error.html#ga08b10e70fa5ff0b05c631d9f8f6b2c6b">PSA_ERROR_HARDWARE_FAILURE</a></td><td></td></tr>
565 <tr><td class="paramname"><a class="el" href="group__error.html#ga2c5dda1485cb54f2385cb9c1279a7004">PSA_ERROR_TAMPERING_DETECTED</a></td><td></td></tr>
566 <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>
567 </table>
568 </dd>
569</dl>
570
571</div>
572</div>
573<a class="anchor" id="ga759791bbe1763b377c3b5447641f1fc8"></a>
574<div class="memitem">
575<div class="memproto">
576 <table class="memname">
577 <tr>
578 <td class="memname"><a class="el" href="group__error.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a> psa_aead_finish </td>
579 <td>(</td>
580 <td class="paramtype"><a class="el" href="group__aead.html#ga14f6a01afbaa8c5b3d8c5d345cbaa3ed">psa_aead_operation_t</a> *&#160;</td>
581 <td class="paramname"><em>operation</em>, </td>
582 </tr>
583 <tr>
584 <td class="paramkey"></td>
585 <td></td>
586 <td class="paramtype">uint8_t *&#160;</td>
587 <td class="paramname"><em>ciphertext</em>, </td>
588 </tr>
589 <tr>
590 <td class="paramkey"></td>
591 <td></td>
592 <td class="paramtype">size_t&#160;</td>
593 <td class="paramname"><em>ciphertext_size</em>, </td>
594 </tr>
595 <tr>
596 <td class="paramkey"></td>
597 <td></td>
598 <td class="paramtype">size_t *&#160;</td>
599 <td class="paramname"><em>ciphertext_length</em>, </td>
600 </tr>
601 <tr>
602 <td class="paramkey"></td>
603 <td></td>
604 <td class="paramtype">uint8_t *&#160;</td>
605 <td class="paramname"><em>tag</em>, </td>
606 </tr>
607 <tr>
608 <td class="paramkey"></td>
609 <td></td>
610 <td class="paramtype">size_t&#160;</td>
611 <td class="paramname"><em>tag_size</em>, </td>
612 </tr>
613 <tr>
614 <td class="paramkey"></td>
615 <td></td>
616 <td class="paramtype">size_t *&#160;</td>
617 <td class="paramname"><em>tag_length</em>&#160;</td>
618 </tr>
619 <tr>
620 <td></td>
621 <td>)</td>
622 <td></td><td></td>
623 </tr>
624 </table>
625</div><div class="memdoc">
626<p>Finish encrypting a message in an AEAD operation.</p>
627<p>The operation must have been set up with <a class="el" href="group__aead.html#ga47265dc4852f1476f852752218fd12b2">psa_aead_encrypt_setup()</a>.</p>
628<p>This function finishes the authentication of the additional data formed by concatenating the inputs passed to preceding calls to <a class="el" href="group__aead.html#ga6d0eed03f832e5c9c91cb8adf2882569">psa_aead_update_ad()</a> with the plaintext formed by concatenating the inputs passed to preceding calls to <a class="el" href="group__aead.html#ga3b105de2088cef7c3d9e2fd8048c841c">psa_aead_update()</a>.</p>
629<p>This function has two output buffers:</p><ul>
630<li><code>ciphertext</code> contains trailing ciphertext that was buffered from preceding calls to <a class="el" href="group__aead.html#ga3b105de2088cef7c3d9e2fd8048c841c">psa_aead_update()</a>. For all standard AEAD algorithms, <a class="el" href="group__aead.html#ga3b105de2088cef7c3d9e2fd8048c841c">psa_aead_update()</a> does not buffer any output and therefore <code>ciphertext</code> will not contain any output and can be a 0-sized buffer.</li>
631<li><code>tag</code> contains the authentication tag. Its length is always <a class="el" href="crypto__sizes_8h.html#a8e3079b2e624cb8d32b94843cddada49">PSA_AEAD_TAG_LENGTH</a>(<code>alg</code>) where <code>alg</code> is the AEAD algorithm that the operation performs.</li>
632</ul>
633<p>When this function returns, the operation becomes inactive.</p>
634<dl class="params"><dt>Parameters</dt><dd>
635 <table class="params">
636 <tr><td class="paramdir">[in,out]</td><td class="paramname">operation</td><td>Active AEAD operation. </td></tr>
637 <tr><td class="paramdir">[out]</td><td class="paramname">ciphertext</td><td>Buffer where the last part of the ciphertext is to be written. </td></tr>
638 <tr><td class="paramdir"></td><td class="paramname">ciphertext_size</td><td>Size of the <code>ciphertext</code> buffer in bytes. </td></tr>
639 <tr><td class="paramdir">[out]</td><td class="paramname">ciphertext_length</td><td>On success, the number of bytes of returned ciphertext. </td></tr>
640 <tr><td class="paramdir">[out]</td><td class="paramname">tag</td><td>Buffer where the authentication tag is to be written. </td></tr>
641 <tr><td class="paramdir"></td><td class="paramname">tag_size</td><td>Size of the <code>tag</code> buffer in bytes. </td></tr>
642 <tr><td class="paramdir">[out]</td><td class="paramname">tag_length</td><td>On success, the number of bytes that make up the returned tag.</td></tr>
643 </table>
644 </dd>
645</dl>
646<dl class="retval"><dt>Return values</dt><dd>
647 <table class="retval">
648 <tr><td class="paramname"><a class="el" href="group__error.html#ga4cc859e2c66ca381c7418db3527a65e1">PSA_SUCCESS</a></td><td>Success. </td></tr>
649 <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, nonce not set, decryption, or already completed). </td></tr>
650 <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>
651 <tr><td class="paramname"><a class="el" href="group__error.html#ga798df25a505ebf931f7bec1f80f1f85f">PSA_ERROR_INVALID_ARGUMENT</a></td><td>The total length of input to <a class="el" href="group__aead.html#ga6d0eed03f832e5c9c91cb8adf2882569">psa_aead_update_ad()</a> so far is less than the additional data length that was previously specified with <a class="el" href="group__aead.html#gad3431e28d05002c2a7b0760610176050">psa_aead_set_lengths()</a>. </td></tr>
652 <tr><td class="paramname"><a class="el" href="group__error.html#ga798df25a505ebf931f7bec1f80f1f85f">PSA_ERROR_INVALID_ARGUMENT</a></td><td>The total length of input to <a class="el" href="group__aead.html#ga3b105de2088cef7c3d9e2fd8048c841c">psa_aead_update()</a> so far is less than the plaintext length that was previously specified with <a class="el" href="group__aead.html#gad3431e28d05002c2a7b0760610176050">psa_aead_set_lengths()</a>. </td></tr>
653 <tr><td class="paramname"><a class="el" href="group__error.html#ga91b2ad8a867517a2651f1b076c5216e5">PSA_ERROR_INSUFFICIENT_MEMORY</a></td><td></td></tr>
654 <tr><td class="paramname"><a class="el" href="group__error.html#ga5cdb6948371d49e916106249020ea3f7">PSA_ERROR_COMMUNICATION_FAILURE</a></td><td></td></tr>
655 <tr><td class="paramname"><a class="el" href="group__error.html#ga08b10e70fa5ff0b05c631d9f8f6b2c6b">PSA_ERROR_HARDWARE_FAILURE</a></td><td></td></tr>
656 <tr><td class="paramname"><a class="el" href="group__error.html#ga2c5dda1485cb54f2385cb9c1279a7004">PSA_ERROR_TAMPERING_DETECTED</a></td><td></td></tr>
657 </table>
658 </dd>
659</dl>
660
661</div>
662</div>
663<a class="anchor" id="ga3eadcf2a29f662129ea4fb3454969ba2"></a>
664<div class="memitem">
665<div class="memproto">
666 <table class="memname">
667 <tr>
668 <td class="memname"><a class="el" href="group__error.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a> psa_aead_generate_nonce </td>
669 <td>(</td>
670 <td class="paramtype"><a class="el" href="group__aead.html#ga14f6a01afbaa8c5b3d8c5d345cbaa3ed">psa_aead_operation_t</a> *&#160;</td>
671 <td class="paramname"><em>operation</em>, </td>
672 </tr>
673 <tr>
674 <td class="paramkey"></td>
675 <td></td>
676 <td class="paramtype">unsigned char *&#160;</td>
677 <td class="paramname"><em>nonce</em>, </td>
678 </tr>
679 <tr>
680 <td class="paramkey"></td>
681 <td></td>
682 <td class="paramtype">size_t&#160;</td>
683 <td class="paramname"><em>nonce_size</em>, </td>
684 </tr>
685 <tr>
686 <td class="paramkey"></td>
687 <td></td>
688 <td class="paramtype">size_t *&#160;</td>
689 <td class="paramname"><em>nonce_length</em>&#160;</td>
690 </tr>
691 <tr>
692 <td></td>
693 <td>)</td>
694 <td></td><td></td>
695 </tr>
696 </table>
697</div><div class="memdoc">
698<p>Generate a random nonce for an authenticated encryption operation.</p>
699<p>This function generates a random nonce for the authenticated encryption operation with an appropriate size for the chosen algorithm, key type and key size.</p>
700<p>The application must call <a class="el" href="group__aead.html#ga47265dc4852f1476f852752218fd12b2">psa_aead_encrypt_setup()</a> before calling this function.</p>
701<p>If this function returns an error status, the operation becomes inactive.</p>
702<dl class="params"><dt>Parameters</dt><dd>
703 <table class="params">
704 <tr><td class="paramdir">[in,out]</td><td class="paramname">operation</td><td>Active AEAD operation. </td></tr>
705 <tr><td class="paramdir">[out]</td><td class="paramname">nonce</td><td>Buffer where the generated nonce is to be written. </td></tr>
706 <tr><td class="paramdir"></td><td class="paramname">nonce_size</td><td>Size of the <code>nonce</code> buffer in bytes. </td></tr>
707 <tr><td class="paramdir">[out]</td><td class="paramname">nonce_length</td><td>On success, the number of bytes of the generated nonce.</td></tr>
708 </table>
709 </dd>
710</dl>
711<dl class="retval"><dt>Return values</dt><dd>
712 <table class="retval">
713 <tr><td class="paramname"><a class="el" href="group__error.html#ga4cc859e2c66ca381c7418db3527a65e1">PSA_SUCCESS</a></td><td>Success. </td></tr>
714 <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 nonce already set). </td></tr>
715 <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>nonce</code> buffer is too small. </td></tr>
716 <tr><td class="paramname"><a class="el" href="group__error.html#ga91b2ad8a867517a2651f1b076c5216e5">PSA_ERROR_INSUFFICIENT_MEMORY</a></td><td></td></tr>
717 <tr><td class="paramname"><a class="el" href="group__error.html#ga5cdb6948371d49e916106249020ea3f7">PSA_ERROR_COMMUNICATION_FAILURE</a></td><td></td></tr>
718 <tr><td class="paramname"><a class="el" href="group__error.html#ga08b10e70fa5ff0b05c631d9f8f6b2c6b">PSA_ERROR_HARDWARE_FAILURE</a></td><td></td></tr>
719 <tr><td class="paramname"><a class="el" href="group__error.html#ga2c5dda1485cb54f2385cb9c1279a7004">PSA_ERROR_TAMPERING_DETECTED</a></td><td></td></tr>
720 </table>
721 </dd>
722</dl>
723
724</div>
725</div>
726<a class="anchor" id="gad3431e28d05002c2a7b0760610176050"></a>
727<div class="memitem">
728<div class="memproto">
729 <table class="memname">
730 <tr>
731 <td class="memname"><a class="el" href="group__error.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a> psa_aead_set_lengths </td>
732 <td>(</td>
733 <td class="paramtype"><a class="el" href="group__aead.html#ga14f6a01afbaa8c5b3d8c5d345cbaa3ed">psa_aead_operation_t</a> *&#160;</td>
734 <td class="paramname"><em>operation</em>, </td>
735 </tr>
736 <tr>
737 <td class="paramkey"></td>
738 <td></td>
739 <td class="paramtype">size_t&#160;</td>
740 <td class="paramname"><em>ad_length</em>, </td>
741 </tr>
742 <tr>
743 <td class="paramkey"></td>
744 <td></td>
745 <td class="paramtype">size_t&#160;</td>
746 <td class="paramname"><em>plaintext_length</em>&#160;</td>
747 </tr>
748 <tr>
749 <td></td>
750 <td>)</td>
751 <td></td><td></td>
752 </tr>
753 </table>
754</div><div class="memdoc">
755<p>Declare the lengths of the message and additional data for AEAD.</p>
756<p>The application must call this function before calling <a class="el" href="group__aead.html#ga6d0eed03f832e5c9c91cb8adf2882569">psa_aead_update_ad()</a> or <a class="el" href="group__aead.html#ga3b105de2088cef7c3d9e2fd8048c841c">psa_aead_update()</a> if the algorithm for the operation requires it. If the algorithm does not require it, calling this function is optional, but if this function is called then the implementation must enforce the lengths.</p>
757<p>You may call this function before or after setting the nonce with <a class="el" href="group__aead.html#ga40641d0721ca7fe01bbcd9ef635fbc46">psa_aead_set_nonce()</a> or <a class="el" href="group__aead.html#ga3eadcf2a29f662129ea4fb3454969ba2">psa_aead_generate_nonce()</a>.</p>
758<ul>
Gilles Peskine45adc5b2019-03-05 16:34:20 +0100[diff] [blame^]759<li>For <a class="el" href="group__crypto__types.html#gac2c0e7d21f1b2df5e76bcb4a8f84273c">PSA_ALG_CCM</a>, calling this function is required.</li>
Gilles Peskine89f0a532019-01-31 11:47:57 +0100[diff] [blame]760<li>For the other AEAD algorithms defined in this specification, calling this function is not required.</li>
761<li>For vendor-defined algorithm, refer to the vendor documentation.</li>
762</ul>
763<dl class="params"><dt>Parameters</dt><dd>
764 <table class="params">
765 <tr><td class="paramdir">[in,out]</td><td class="paramname">operation</td><td>Active AEAD operation. </td></tr>
766 <tr><td class="paramdir"></td><td class="paramname">ad_length</td><td>Size of the non-encrypted additional authenticated data in bytes. </td></tr>
767 <tr><td class="paramdir"></td><td class="paramname">plaintext_length</td><td>Size of the plaintext to encrypt in bytes.</td></tr>
768 </table>
769 </dd>
770</dl>
771<dl class="retval"><dt>Return values</dt><dd>
772 <table class="retval">
773 <tr><td class="paramname"><a class="el" href="group__error.html#ga4cc859e2c66ca381c7418db3527a65e1">PSA_SUCCESS</a></td><td>Success. </td></tr>
774 <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, already completed, or <a class="el" href="group__aead.html#ga6d0eed03f832e5c9c91cb8adf2882569">psa_aead_update_ad()</a> or <a class="el" href="group__aead.html#ga3b105de2088cef7c3d9e2fd8048c841c">psa_aead_update()</a> already called). </td></tr>
775 <tr><td class="paramname"><a class="el" href="group__error.html#ga798df25a505ebf931f7bec1f80f1f85f">PSA_ERROR_INVALID_ARGUMENT</a></td><td>At least one of the lengths is not acceptable for the chosen algorithm. </td></tr>
776 <tr><td class="paramname"><a class="el" href="group__error.html#ga91b2ad8a867517a2651f1b076c5216e5">PSA_ERROR_INSUFFICIENT_MEMORY</a></td><td></td></tr>
777 <tr><td class="paramname"><a class="el" href="group__error.html#ga5cdb6948371d49e916106249020ea3f7">PSA_ERROR_COMMUNICATION_FAILURE</a></td><td></td></tr>
778 <tr><td class="paramname"><a class="el" href="group__error.html#ga08b10e70fa5ff0b05c631d9f8f6b2c6b">PSA_ERROR_HARDWARE_FAILURE</a></td><td></td></tr>
779 <tr><td class="paramname"><a class="el" href="group__error.html#ga2c5dda1485cb54f2385cb9c1279a7004">PSA_ERROR_TAMPERING_DETECTED</a></td><td></td></tr>
780 </table>
781 </dd>
782</dl>
783
784</div>
785</div>
786<a class="anchor" id="ga40641d0721ca7fe01bbcd9ef635fbc46"></a>
787<div class="memitem">
788<div class="memproto">
789 <table class="memname">
790 <tr>
791 <td class="memname"><a class="el" href="group__error.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a> psa_aead_set_nonce </td>
792 <td>(</td>
793 <td class="paramtype"><a class="el" href="group__aead.html#ga14f6a01afbaa8c5b3d8c5d345cbaa3ed">psa_aead_operation_t</a> *&#160;</td>
794 <td class="paramname"><em>operation</em>, </td>
795 </tr>
796 <tr>
797 <td class="paramkey"></td>
798 <td></td>
799 <td class="paramtype">const unsigned char *&#160;</td>
800 <td class="paramname"><em>nonce</em>, </td>
801 </tr>
802 <tr>
803 <td class="paramkey"></td>
804 <td></td>
805 <td class="paramtype">size_t&#160;</td>
806 <td class="paramname"><em>nonce_length</em>&#160;</td>
807 </tr>
808 <tr>
809 <td></td>
810 <td>)</td>
811 <td></td><td></td>
812 </tr>
813 </table>
814</div><div class="memdoc">
815<p>Set the nonce for an authenticated encryption or decryption operation.</p>
816<p>This function sets the nonce for the authenticated encryption or decryption operation.</p>
817<p>The application must call <a class="el" href="group__aead.html#ga47265dc4852f1476f852752218fd12b2">psa_aead_encrypt_setup()</a> before calling this function.</p>
818<p>If this function returns an error status, the operation becomes inactive.</p>
819<dl class="section note"><dt>Note</dt><dd>When encrypting, applications should use <a class="el" href="group__aead.html#ga3eadcf2a29f662129ea4fb3454969ba2">psa_aead_generate_nonce()</a> instead of this function, unless implementing a protocol that requires a non-random IV.</dd></dl>
820<dl class="params"><dt>Parameters</dt><dd>
821 <table class="params">
822 <tr><td class="paramdir">[in,out]</td><td class="paramname">operation</td><td>Active AEAD operation. </td></tr>
823 <tr><td class="paramdir">[in]</td><td class="paramname">nonce</td><td>Buffer containing the nonce to use. </td></tr>
824 <tr><td class="paramdir"></td><td class="paramname">nonce_length</td><td>Size of the nonce in bytes.</td></tr>
825 </table>
826 </dd>
827</dl>
828<dl class="retval"><dt>Return values</dt><dd>
829 <table class="retval">
830 <tr><td class="paramname"><a class="el" href="group__error.html#ga4cc859e2c66ca381c7418db3527a65e1">PSA_SUCCESS</a></td><td>Success. </td></tr>
831 <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 nonce already set). </td></tr>
832 <tr><td class="paramname"><a class="el" href="group__error.html#ga798df25a505ebf931f7bec1f80f1f85f">PSA_ERROR_INVALID_ARGUMENT</a></td><td>The size of <code>nonce</code> is not acceptable for the chosen algorithm. </td></tr>
833 <tr><td class="paramname"><a class="el" href="group__error.html#ga91b2ad8a867517a2651f1b076c5216e5">PSA_ERROR_INSUFFICIENT_MEMORY</a></td><td></td></tr>
834 <tr><td class="paramname"><a class="el" href="group__error.html#ga5cdb6948371d49e916106249020ea3f7">PSA_ERROR_COMMUNICATION_FAILURE</a></td><td></td></tr>
835 <tr><td class="paramname"><a class="el" href="group__error.html#ga08b10e70fa5ff0b05c631d9f8f6b2c6b">PSA_ERROR_HARDWARE_FAILURE</a></td><td></td></tr>
836 <tr><td class="paramname"><a class="el" href="group__error.html#ga2c5dda1485cb54f2385cb9c1279a7004">PSA_ERROR_TAMPERING_DETECTED</a></td><td></td></tr>
837 </table>
838 </dd>
839</dl>
840
841</div>
842</div>
843<a class="anchor" id="ga3b105de2088cef7c3d9e2fd8048c841c"></a>
844<div class="memitem">
845<div class="memproto">
846 <table class="memname">
847 <tr>
848 <td class="memname"><a class="el" href="group__error.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a> psa_aead_update </td>
849 <td>(</td>
850 <td class="paramtype"><a class="el" href="group__aead.html#ga14f6a01afbaa8c5b3d8c5d345cbaa3ed">psa_aead_operation_t</a> *&#160;</td>
851 <td class="paramname"><em>operation</em>, </td>
852 </tr>
853 <tr>
854 <td class="paramkey"></td>
855 <td></td>
856 <td class="paramtype">const uint8_t *&#160;</td>
857 <td class="paramname"><em>input</em>, </td>
858 </tr>
859 <tr>
860 <td class="paramkey"></td>
861 <td></td>
862 <td class="paramtype">size_t&#160;</td>
863 <td class="paramname"><em>input_length</em>, </td>
864 </tr>
865 <tr>
866 <td class="paramkey"></td>
867 <td></td>
868 <td class="paramtype">unsigned char *&#160;</td>
869 <td class="paramname"><em>output</em>, </td>
870 </tr>
871 <tr>
872 <td class="paramkey"></td>
873 <td></td>
874 <td class="paramtype">size_t&#160;</td>
875 <td class="paramname"><em>output_size</em>, </td>
876 </tr>
877 <tr>
878 <td class="paramkey"></td>
879 <td></td>
880 <td class="paramtype">size_t *&#160;</td>
881 <td class="paramname"><em>output_length</em>&#160;</td>
882 </tr>
883 <tr>
884 <td></td>
885 <td>)</td>
886 <td></td><td></td>
887 </tr>
888 </table>
889</div><div class="memdoc">
890<p>Encrypt or decrypt a message fragment in an active AEAD operation.</p>
891<p>Before calling this function, you must:</p><ol type="1">
892<li>Call either <a class="el" href="group__aead.html#ga47265dc4852f1476f852752218fd12b2">psa_aead_encrypt_setup()</a> or <a class="el" href="group__aead.html#ga439896519d4a367ec86b47f201884152">psa_aead_decrypt_setup()</a>. The choice of setup function determines whether this function encrypts or decrypts its input.</li>
893<li>Set the nonce with <a class="el" href="group__aead.html#ga3eadcf2a29f662129ea4fb3454969ba2">psa_aead_generate_nonce()</a> or <a class="el" href="group__aead.html#ga40641d0721ca7fe01bbcd9ef635fbc46">psa_aead_set_nonce()</a>.</li>
894<li>Call <a class="el" href="group__aead.html#ga6d0eed03f832e5c9c91cb8adf2882569">psa_aead_update_ad()</a> to pass all the additional data.</li>
895</ol>
896<p>If this function returns an error status, the operation becomes inactive.</p>
897<dl class="section warning"><dt>Warning</dt><dd>When decrypting, until <a class="el" href="group__aead.html#gaaed211fc61977c859d6ff07f39f59219">psa_aead_verify()</a> has returned <a class="el" href="group__error.html#ga4cc859e2c66ca381c7418db3527a65e1">PSA_SUCCESS</a>, there is no guarantee that the input is valid. Therefore, until you have called <a class="el" href="group__aead.html#gaaed211fc61977c859d6ff07f39f59219">psa_aead_verify()</a> and it has returned <a class="el" href="group__error.html#ga4cc859e2c66ca381c7418db3527a65e1">PSA_SUCCESS</a>:<ul>
898<li>Do not use the output in any way other than storing it in a confidential location. If you take any action that depends on the tentative decrypted data, this action will need to be undone if the input turns out not to be valid. Furthermore, if an adversary can observe that this action took place (for example through timing), they may be able to use this fact as an oracle to decrypt any message encrypted with the same key.</li>
899<li>In particular, do not copy the output anywhere but to a memory or storage space that you have exclusive access to.</li>
900</ul>
901</dd></dl>
902<dl class="params"><dt>Parameters</dt><dd>
903 <table class="params">
904 <tr><td class="paramdir">[in,out]</td><td class="paramname">operation</td><td>Active AEAD operation. </td></tr>
905 <tr><td class="paramdir">[in]</td><td class="paramname">input</td><td>Buffer containing the message fragment to encrypt or decrypt. </td></tr>
906 <tr><td class="paramdir"></td><td class="paramname">input_length</td><td>Size of the <code>input</code> buffer in bytes. </td></tr>
907 <tr><td class="paramdir">[out]</td><td class="paramname">output</td><td>Buffer where the output is to be written. </td></tr>
908 <tr><td class="paramdir"></td><td class="paramname">output_size</td><td>Size of the <code>output</code> buffer in bytes. </td></tr>
909 <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>
910 </table>
911 </dd>
912</dl>
913<dl class="retval"><dt>Return values</dt><dd>
914 <table class="retval">
915 <tr><td class="paramname"><a class="el" href="group__error.html#ga4cc859e2c66ca381c7418db3527a65e1">PSA_SUCCESS</a></td><td>Success. </td></tr>
916 <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, nonce not set or already completed). </td></tr>
917 <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>
918 <tr><td class="paramname"><a class="el" href="group__error.html#ga798df25a505ebf931f7bec1f80f1f85f">PSA_ERROR_INVALID_ARGUMENT</a></td><td>The total length of input to <a class="el" href="group__aead.html#ga6d0eed03f832e5c9c91cb8adf2882569">psa_aead_update_ad()</a> so far is less than the additional data length that was previously specified with <a class="el" href="group__aead.html#gad3431e28d05002c2a7b0760610176050">psa_aead_set_lengths()</a>. </td></tr>
919 <tr><td class="paramname"><a class="el" href="group__error.html#ga798df25a505ebf931f7bec1f80f1f85f">PSA_ERROR_INVALID_ARGUMENT</a></td><td>The total input length overflows the plaintext length that was previously specified with <a class="el" href="group__aead.html#gad3431e28d05002c2a7b0760610176050">psa_aead_set_lengths()</a>. </td></tr>
920 <tr><td class="paramname"><a class="el" href="group__error.html#ga91b2ad8a867517a2651f1b076c5216e5">PSA_ERROR_INSUFFICIENT_MEMORY</a></td><td></td></tr>
921 <tr><td class="paramname"><a class="el" href="group__error.html#ga5cdb6948371d49e916106249020ea3f7">PSA_ERROR_COMMUNICATION_FAILURE</a></td><td></td></tr>
922 <tr><td class="paramname"><a class="el" href="group__error.html#ga08b10e70fa5ff0b05c631d9f8f6b2c6b">PSA_ERROR_HARDWARE_FAILURE</a></td><td></td></tr>
923 <tr><td class="paramname"><a class="el" href="group__error.html#ga2c5dda1485cb54f2385cb9c1279a7004">PSA_ERROR_TAMPERING_DETECTED</a></td><td></td></tr>
924 </table>
925 </dd>
926</dl>
927
928</div>
929</div>
930<a class="anchor" id="ga6d0eed03f832e5c9c91cb8adf2882569"></a>
931<div class="memitem">
932<div class="memproto">
933 <table class="memname">
934 <tr>
935 <td class="memname"><a class="el" href="group__error.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a> psa_aead_update_ad </td>
936 <td>(</td>
937 <td class="paramtype"><a class="el" href="group__aead.html#ga14f6a01afbaa8c5b3d8c5d345cbaa3ed">psa_aead_operation_t</a> *&#160;</td>
938 <td class="paramname"><em>operation</em>, </td>
939 </tr>
940 <tr>
941 <td class="paramkey"></td>
942 <td></td>
943 <td class="paramtype">const uint8_t *&#160;</td>
944 <td class="paramname"><em>input</em>, </td>
945 </tr>
946 <tr>
947 <td class="paramkey"></td>
948 <td></td>
949 <td class="paramtype">size_t&#160;</td>
950 <td class="paramname"><em>input_length</em>&#160;</td>
951 </tr>
952 <tr>
953 <td></td>
954 <td>)</td>
955 <td></td><td></td>
956 </tr>
957 </table>
958</div><div class="memdoc">
959<p>Pass additional data to an active AEAD operation.</p>
960<p>Additional data is authenticated, but not encrypted.</p>
961<p>You may call this function multiple times to pass successive fragments of the additional data. You may not call this function after passing data to encrypt or decrypt with <a class="el" href="group__aead.html#ga3b105de2088cef7c3d9e2fd8048c841c">psa_aead_update()</a>.</p>
962<p>Before calling this function, you must:</p><ol type="1">
963<li>Call either <a class="el" href="group__aead.html#ga47265dc4852f1476f852752218fd12b2">psa_aead_encrypt_setup()</a> or <a class="el" href="group__aead.html#ga439896519d4a367ec86b47f201884152">psa_aead_decrypt_setup()</a>.</li>
964<li>Set the nonce with <a class="el" href="group__aead.html#ga3eadcf2a29f662129ea4fb3454969ba2">psa_aead_generate_nonce()</a> or <a class="el" href="group__aead.html#ga40641d0721ca7fe01bbcd9ef635fbc46">psa_aead_set_nonce()</a>.</li>
965</ol>
966<p>If this function returns an error status, the operation becomes inactive.</p>
967<dl class="section warning"><dt>Warning</dt><dd>When decrypting, until <a class="el" href="group__aead.html#gaaed211fc61977c859d6ff07f39f59219">psa_aead_verify()</a> has returned <a class="el" href="group__error.html#ga4cc859e2c66ca381c7418db3527a65e1">PSA_SUCCESS</a>, there is no guarantee that the input is valid. Therefore, until you have called <a class="el" href="group__aead.html#gaaed211fc61977c859d6ff07f39f59219">psa_aead_verify()</a> and it has returned <a class="el" href="group__error.html#ga4cc859e2c66ca381c7418db3527a65e1">PSA_SUCCESS</a>, treat the input as untrusted and prepare to undo any action that depends on the input if <a class="el" href="group__aead.html#gaaed211fc61977c859d6ff07f39f59219">psa_aead_verify()</a> returns an error status.</dd></dl>
968<dl class="params"><dt>Parameters</dt><dd>
969 <table class="params">
970 <tr><td class="paramdir">[in,out]</td><td class="paramname">operation</td><td>Active AEAD operation. </td></tr>
971 <tr><td class="paramdir">[in]</td><td class="paramname">input</td><td>Buffer containing the fragment of additional data. </td></tr>
972 <tr><td class="paramdir"></td><td class="paramname">input_length</td><td>Size of the <code>input</code> buffer in bytes.</td></tr>
973 </table>
974 </dd>
975</dl>
976<dl class="retval"><dt>Return values</dt><dd>
977 <table class="retval">
978 <tr><td class="paramname"><a class="el" href="group__error.html#ga4cc859e2c66ca381c7418db3527a65e1">PSA_SUCCESS</a></td><td>Success. </td></tr>
979 <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, nonce not set, <a class="el" href="group__aead.html#ga3b105de2088cef7c3d9e2fd8048c841c">psa_aead_update()</a> already called, or operation already completed). </td></tr>
980 <tr><td class="paramname"><a class="el" href="group__error.html#ga798df25a505ebf931f7bec1f80f1f85f">PSA_ERROR_INVALID_ARGUMENT</a></td><td>The total input length overflows the additional data length that was previously specified with <a class="el" href="group__aead.html#gad3431e28d05002c2a7b0760610176050">psa_aead_set_lengths()</a>. </td></tr>
981 <tr><td class="paramname"><a class="el" href="group__error.html#ga91b2ad8a867517a2651f1b076c5216e5">PSA_ERROR_INSUFFICIENT_MEMORY</a></td><td></td></tr>
982 <tr><td class="paramname"><a class="el" href="group__error.html#ga5cdb6948371d49e916106249020ea3f7">PSA_ERROR_COMMUNICATION_FAILURE</a></td><td></td></tr>
983 <tr><td class="paramname"><a class="el" href="group__error.html#ga08b10e70fa5ff0b05c631d9f8f6b2c6b">PSA_ERROR_HARDWARE_FAILURE</a></td><td></td></tr>
984 <tr><td class="paramname"><a class="el" href="group__error.html#ga2c5dda1485cb54f2385cb9c1279a7004">PSA_ERROR_TAMPERING_DETECTED</a></td><td></td></tr>
985 </table>
986 </dd>
987</dl>
988
989</div>
990</div>
991<a class="anchor" id="gaaed211fc61977c859d6ff07f39f59219"></a>
992<div class="memitem">
993<div class="memproto">
994 <table class="memname">
995 <tr>
996 <td class="memname"><a class="el" href="group__error.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a> psa_aead_verify </td>
997 <td>(</td>
998 <td class="paramtype"><a class="el" href="group__aead.html#ga14f6a01afbaa8c5b3d8c5d345cbaa3ed">psa_aead_operation_t</a> *&#160;</td>
999 <td class="paramname"><em>operation</em>, </td>
1000 </tr>
1001 <tr>
1002 <td class="paramkey"></td>
1003 <td></td>
1004 <td class="paramtype">const uint8_t *&#160;</td>
1005 <td class="paramname"><em>tag</em>, </td>
1006 </tr>
1007 <tr>
1008 <td class="paramkey"></td>
1009 <td></td>
1010 <td class="paramtype">size_t&#160;</td>
1011 <td class="paramname"><em>tag_length</em>&#160;</td>
1012 </tr>
1013 <tr>
1014 <td></td>
1015 <td>)</td>
1016 <td></td><td></td>
1017 </tr>
1018 </table>
1019</div><div class="memdoc">
1020<p>Finish authenticating and decrypting a message in an AEAD operation.</p>
1021<p>The operation must have been set up with <a class="el" href="group__aead.html#ga439896519d4a367ec86b47f201884152">psa_aead_decrypt_setup()</a>.</p>
1022<p>This function finishes the authentication of the additional data formed by concatenating the inputs passed to preceding calls to <a class="el" href="group__aead.html#ga6d0eed03f832e5c9c91cb8adf2882569">psa_aead_update_ad()</a> with the ciphertext formed by concatenating the inputs passed to preceding calls to <a class="el" href="group__aead.html#ga3b105de2088cef7c3d9e2fd8048c841c">psa_aead_update()</a>.</p>
1023<p>When this function returns, the operation becomes inactive.</p>
1024<dl class="params"><dt>Parameters</dt><dd>
1025 <table class="params">
1026 <tr><td class="paramdir">[in,out]</td><td class="paramname">operation</td><td>Active AEAD operation. </td></tr>
1027 <tr><td class="paramdir">[in]</td><td class="paramname">tag</td><td>Buffer containing the authentication tag. </td></tr>
1028 <tr><td class="paramdir"></td><td class="paramname">tag_length</td><td>Size of the <code>tag</code> buffer in bytes.</td></tr>
1029 </table>
1030 </dd>
1031</dl>
1032<dl class="retval"><dt>Return values</dt><dd>
1033 <table class="retval">
1034 <tr><td class="paramname"><a class="el" href="group__error.html#ga4cc859e2c66ca381c7418db3527a65e1">PSA_SUCCESS</a></td><td>Success. </td></tr>
1035 <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, nonce not set, encryption, or already completed). </td></tr>
1036 <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>
1037 <tr><td class="paramname"><a class="el" href="group__error.html#ga798df25a505ebf931f7bec1f80f1f85f">PSA_ERROR_INVALID_ARGUMENT</a></td><td>The total length of input to <a class="el" href="group__aead.html#ga6d0eed03f832e5c9c91cb8adf2882569">psa_aead_update_ad()</a> so far is less than the additional data length that was previously specified with <a class="el" href="group__aead.html#gad3431e28d05002c2a7b0760610176050">psa_aead_set_lengths()</a>. </td></tr>
1038 <tr><td class="paramname"><a class="el" href="group__error.html#ga798df25a505ebf931f7bec1f80f1f85f">PSA_ERROR_INVALID_ARGUMENT</a></td><td>The total length of input to <a class="el" href="group__aead.html#ga3b105de2088cef7c3d9e2fd8048c841c">psa_aead_update()</a> so far is less than the plaintext length that was previously specified with <a class="el" href="group__aead.html#gad3431e28d05002c2a7b0760610176050">psa_aead_set_lengths()</a>. </td></tr>
1039 <tr><td class="paramname"><a class="el" href="group__error.html#ga91b2ad8a867517a2651f1b076c5216e5">PSA_ERROR_INSUFFICIENT_MEMORY</a></td><td></td></tr>
1040 <tr><td class="paramname"><a class="el" href="group__error.html#ga5cdb6948371d49e916106249020ea3f7">PSA_ERROR_COMMUNICATION_FAILURE</a></td><td></td></tr>
1041 <tr><td class="paramname"><a class="el" href="group__error.html#ga08b10e70fa5ff0b05c631d9f8f6b2c6b">PSA_ERROR_HARDWARE_FAILURE</a></td><td></td></tr>
1042 <tr><td class="paramname"><a class="el" href="group__error.html#ga2c5dda1485cb54f2385cb9c1279a7004">PSA_ERROR_TAMPERING_DETECTED</a></td><td></td></tr>
1043 </table>
1044 </dd>
1045</dl>
1046
1047</div>
1048</div>
1049</div><!-- contents -->
1050<!-- start footer part -->
1051<hr class="footer"/><address class="footer"><small>
1052Generated by &#160;<a href="http://www.doxygen.org/index.html">
1053<img class="footer" src="doxygen.png" alt="doxygen"/>
1054</a> 1.8.11
1055</small></address>
1056</body>
1057</html>