blob: ece8edadd80a911039421f5e818ac001fb8b222d [file] [log] [blame]
Gilles Peskinee59236f2018-01-27 23:32:46 +01001/**
2 * \file psa/crypto.h
3 * \brief Platform Security Architecture cryptography module
4 */
Jaeden Amerocab54942018-07-25 13:26:13 +01005/*
6 * Copyright (C) 2018, ARM Limited, All Rights Reserved
7 * SPDX-License-Identifier: Apache-2.0
8 *
9 * Licensed under the Apache License, Version 2.0 (the "License"); you may
10 * not use this file except in compliance with the License.
11 * You may obtain a copy of the License at
12 *
13 * http://www.apache.org/licenses/LICENSE-2.0
14 *
15 * Unless required by applicable law or agreed to in writing, software
16 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
17 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18 * See the License for the specific language governing permissions and
19 * limitations under the License.
20 */
Gilles Peskinee59236f2018-01-27 23:32:46 +010021
22#ifndef PSA_CRYPTO_H
23#define PSA_CRYPTO_H
24
25#include "crypto_platform.h"
26
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +010027#include <stddef.h>
28
Gilles Peskine62a7e7e2018-02-07 21:54:47 +010029#ifdef __DOXYGEN_ONLY__
Gilles Peskinef5b9fa12018-03-07 16:40:18 +010030/* This __DOXYGEN_ONLY__ block contains mock definitions for things that
31 * must be defined in the crypto_platform.h header. These mock definitions
32 * are present in this file as a convenience to generate pretty-printed
33 * documentation that includes those definitions. */
34
Gilles Peskine62a7e7e2018-02-07 21:54:47 +010035/** \defgroup platform Implementation-specific definitions
36 * @{
37 */
38
Gilles Peskineae32aac2018-11-30 14:39:32 +010039/** \brief Key handle.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +010040 *
Gilles Peskineae32aac2018-11-30 14:39:32 +010041 * This type represents open handles to keys. It must be an unsigned integral
Gilles Peskine308b91d2018-02-08 09:47:44 +010042 * type. The choice of type is implementation-dependent.
Gilles Peskineae32aac2018-11-30 14:39:32 +010043 *
Gilles Peskine23fd2bd2018-12-11 15:51:32 +010044 * 0 is not a valid key handle. How other handle values are assigned is
45 * implementation-dependent.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +010046 */
Gilles Peskineae32aac2018-11-30 14:39:32 +010047typedef _unsigned_integral_type_ psa_key_handle_t;
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +010048
Gilles Peskine62a7e7e2018-02-07 21:54:47 +010049/**@}*/
Gilles Peskinef5b9fa12018-03-07 16:40:18 +010050#endif /* __DOXYGEN_ONLY__ */
Gilles Peskine62a7e7e2018-02-07 21:54:47 +010051
Gilles Peskinee59236f2018-01-27 23:32:46 +010052#ifdef __cplusplus
53extern "C" {
54#endif
55
Gilles Peskinef3b731e2018-12-12 13:38:31 +010056/* The file "crypto_types.h" declares types that encode errors,
57 * algorithms, key types, policies, etc. */
58#include "crypto_types.h"
59
60/* The file "crypto_values.h" declares macros to build and analyze values
61 * of integral types defined in "crypto_types.h". */
62#include "crypto_values.h"
63
64/** \defgroup initialization Library initialization
Gilles Peskinee59236f2018-01-27 23:32:46 +010065 * @{
66 */
67
68/**
Gilles Peskinee59236f2018-01-27 23:32:46 +010069 * \brief Library initialization.
70 *
71 * Applications must call this function before calling any other
72 * function in this module.
73 *
74 * Applications may call this function more than once. Once a call
75 * succeeds, subsequent calls are guaranteed to succeed.
76 *
itayzafrir18617092018-09-16 12:22:41 +030077 * If the application calls other functions before calling psa_crypto_init(),
78 * the behavior is undefined. Implementations are encouraged to either perform
79 * the operation as if the library had been initialized or to return
80 * #PSA_ERROR_BAD_STATE or some other applicable error. In particular,
81 * implementations should not return a success status if the lack of
82 * initialization may have security implications, for example due to improper
83 * seeding of the random number generator.
84 *
Gilles Peskine28538492018-07-11 17:34:00 +020085 * \retval #PSA_SUCCESS
86 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
87 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
88 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +020089 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine28538492018-07-11 17:34:00 +020090 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
Gilles Peskinee59236f2018-01-27 23:32:46 +010091 */
92psa_status_t psa_crypto_init(void);
93
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +010094/**@}*/
95
Gilles Peskine105f67f2019-07-23 18:16:05 +020096/** \addtogroup attributes
Gilles Peskine87a5e562019-04-17 12:28:25 +020097 * @{
98 */
99
Gilles Peskinea0c06552019-05-21 15:54:54 +0200100/** \def PSA_KEY_ATTRIBUTES_INIT
101 *
102 * This macro returns a suitable initializer for a key attribute structure
103 * of type #psa_key_attributes_t.
104 */
105#ifdef __DOXYGEN_ONLY__
106/* This is an example definition for documentation purposes.
107 * Implementations should define a suitable value in `crypto_struct.h`.
108 */
109#define PSA_KEY_ATTRIBUTES_INIT {0}
110#endif
111
112/** Return an initial value for a key attributes structure.
113 */
114static psa_key_attributes_t psa_key_attributes_init(void);
115
Gilles Peskinedc8219a2019-05-15 16:11:15 +0200116/** Declare a key as persistent and set its key identifier.
Gilles Peskine20628592019-04-19 19:29:50 +0200117 *
Gilles Peskinef1b76942019-05-16 16:10:59 +0200118 * If the attribute structure currently declares the key as volatile (which
119 * is the default content of an attribute structure), this function sets
Gilles Peskinedc8219a2019-05-15 16:11:15 +0200120 * the lifetime attribute to #PSA_KEY_LIFETIME_PERSISTENT.
Gilles Peskine20628592019-04-19 19:29:50 +0200121 *
Gilles Peskinef1b76942019-05-16 16:10:59 +0200122 * This function does not access storage, it merely stores the given
123 * value in the structure.
124 * The persistent key will be written to storage when the attribute
125 * structure is passed to a key creation function such as
Gilles Peskine35ef36b2019-05-16 19:42:05 +0200126 * psa_import_key(), psa_generate_key(),
Gilles Peskinea99d3fb2019-05-16 15:28:51 +0200127 * psa_key_derivation_output_key() or psa_copy_key().
Gilles Peskine20628592019-04-19 19:29:50 +0200128 *
Gilles Peskine20628592019-04-19 19:29:50 +0200129 * This function may be declared as `static` (i.e. without external
130 * linkage). This function may be provided as a function-like macro,
131 * but in this case it must evaluate each of its arguments exactly once.
132 *
133 * \param[out] attributes The attribute structure to write to.
134 * \param id The persistent identifier for the key.
Gilles Peskinedc8219a2019-05-15 16:11:15 +0200135 */
136static void psa_set_key_id(psa_key_attributes_t *attributes,
137 psa_key_id_t id);
138
139/** Set the location of a persistent key.
140 *
141 * To make a key persistent, you must give it a persistent key identifier
Gilles Peskinef1b76942019-05-16 16:10:59 +0200142 * with psa_set_key_id(). By default, a key that has a persistent identifier
143 * is stored in the default storage area identifier by
144 * #PSA_KEY_LIFETIME_PERSISTENT. Call this function to choose a storage
145 * area, or to explicitly declare the key as volatile.
Gilles Peskinedc8219a2019-05-15 16:11:15 +0200146 *
Gilles Peskinef1b76942019-05-16 16:10:59 +0200147 * This function does not access storage, it merely stores the given
148 * value in the structure.
149 * The persistent key will be written to storage when the attribute
150 * structure is passed to a key creation function such as
Gilles Peskine35ef36b2019-05-16 19:42:05 +0200151 * psa_import_key(), psa_generate_key(),
Gilles Peskinea99d3fb2019-05-16 15:28:51 +0200152 * psa_key_derivation_output_key() or psa_copy_key().
Gilles Peskinedc8219a2019-05-15 16:11:15 +0200153 *
154 * This function may be declared as `static` (i.e. without external
155 * linkage). This function may be provided as a function-like macro,
156 * but in this case it must evaluate each of its arguments exactly once.
157 *
158 * \param[out] attributes The attribute structure to write to.
Gilles Peskine20628592019-04-19 19:29:50 +0200159 * \param lifetime The lifetime for the key.
160 * If this is #PSA_KEY_LIFETIME_VOLATILE, the
Gilles Peskinedc8219a2019-05-15 16:11:15 +0200161 * key will be volatile, and the key identifier
162 * attribute is reset to 0.
Gilles Peskine20628592019-04-19 19:29:50 +0200163 */
Gilles Peskinedc8219a2019-05-15 16:11:15 +0200164static void psa_set_key_lifetime(psa_key_attributes_t *attributes,
165 psa_key_lifetime_t lifetime);
Gilles Peskine4747d192019-04-17 15:05:45 +0200166
Gilles Peskine20628592019-04-19 19:29:50 +0200167/** Retrieve the key identifier from key attributes.
168 *
169 * This function may be declared as `static` (i.e. without external
170 * linkage). This function may be provided as a function-like macro,
171 * but in this case it must evaluate its argument exactly once.
172 *
173 * \param[in] attributes The key attribute structure to query.
174 *
175 * \return The persistent identifier stored in the attribute structure.
176 * This value is unspecified if the attribute structure declares
177 * the key as volatile.
178 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200179static psa_key_id_t psa_get_key_id(const psa_key_attributes_t *attributes);
180
Gilles Peskine20628592019-04-19 19:29:50 +0200181/** Retrieve the lifetime from key attributes.
182 *
183 * This function may be declared as `static` (i.e. without external
184 * linkage). This function may be provided as a function-like macro,
185 * but in this case it must evaluate its argument exactly once.
186 *
187 * \param[in] attributes The key attribute structure to query.
188 *
189 * \return The lifetime value stored in the attribute structure.
190 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200191static psa_key_lifetime_t psa_get_key_lifetime(
192 const psa_key_attributes_t *attributes);
193
Gilles Peskine20628592019-04-19 19:29:50 +0200194/** Declare usage flags for a key.
195 *
196 * Usage flags are part of a key's usage policy. They encode what
197 * kind of operations are permitted on the key. For more details,
198 * refer to the documentation of the type #psa_key_usage_t.
199 *
200 * This function overwrites any usage flags
201 * previously set in \p attributes.
202 *
203 * This function may be declared as `static` (i.e. without external
204 * linkage). This function may be provided as a function-like macro,
205 * but in this case it must evaluate each of its arguments exactly once.
206 *
207 * \param[out] attributes The attribute structure to write to.
208 * \param usage_flags The usage flags to write.
209 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200210static void psa_set_key_usage_flags(psa_key_attributes_t *attributes,
211 psa_key_usage_t usage_flags);
212
Gilles Peskine20628592019-04-19 19:29:50 +0200213/** Retrieve the usage flags from key attributes.
214 *
215 * This function may be declared as `static` (i.e. without external
216 * linkage). This function may be provided as a function-like macro,
217 * but in this case it must evaluate its argument exactly once.
218 *
219 * \param[in] attributes The key attribute structure to query.
220 *
221 * \return The usage flags stored in the attribute structure.
222 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200223static psa_key_usage_t psa_get_key_usage_flags(
224 const psa_key_attributes_t *attributes);
225
Gilles Peskine20628592019-04-19 19:29:50 +0200226/** Declare the permitted algorithm policy for a key.
227 *
228 * The permitted algorithm policy of a key encodes which algorithm or
229 * algorithms are permitted to be used with this key.
230 *
231 * This function overwrites any algorithm policy
232 * previously set in \p attributes.
233 *
234 * This function may be declared as `static` (i.e. without external
235 * linkage). This function may be provided as a function-like macro,
236 * but in this case it must evaluate each of its arguments exactly once.
237 *
238 * \param[out] attributes The attribute structure to write to.
239 * \param alg The permitted algorithm policy to write.
240 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200241static void psa_set_key_algorithm(psa_key_attributes_t *attributes,
242 psa_algorithm_t alg);
243
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100244
Gilles Peskine20628592019-04-19 19:29:50 +0200245/** Retrieve the algorithm policy from key attributes.
246 *
247 * This function may be declared as `static` (i.e. without external
248 * linkage). This function may be provided as a function-like macro,
249 * but in this case it must evaluate its argument exactly once.
250 *
251 * \param[in] attributes The key attribute structure to query.
252 *
253 * \return The algorithm stored in the attribute structure.
254 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200255static psa_algorithm_t psa_get_key_algorithm(
256 const psa_key_attributes_t *attributes);
257
Gilles Peskine20628592019-04-19 19:29:50 +0200258/** Declare the type of a key.
259 *
Gilles Peskine24f10f82019-05-16 12:18:32 +0200260 * This function overwrites any key type
Gilles Peskine20628592019-04-19 19:29:50 +0200261 * previously set in \p attributes.
262 *
263 * This function may be declared as `static` (i.e. without external
264 * linkage). This function may be provided as a function-like macro,
265 * but in this case it must evaluate each of its arguments exactly once.
266 *
267 * \param[out] attributes The attribute structure to write to.
268 * \param type The key type to write.
269 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200270static void psa_set_key_type(psa_key_attributes_t *attributes,
271 psa_key_type_t type);
272
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100273
Gilles Peskine3a4f1f82019-04-26 13:49:28 +0200274/** Declare the size of a key.
275 *
276 * This function overwrites any key size previously set in \p attributes.
277 *
278 * This function may be declared as `static` (i.e. without external
279 * linkage). This function may be provided as a function-like macro,
280 * but in this case it must evaluate each of its arguments exactly once.
281 *
282 * \param[out] attributes The attribute structure to write to.
283 * \param bits The key size in bits.
284 */
285static void psa_set_key_bits(psa_key_attributes_t *attributes,
286 size_t bits);
287
Gilles Peskine20628592019-04-19 19:29:50 +0200288/** Retrieve the key type from key attributes.
289 *
290 * This function may be declared as `static` (i.e. without external
291 * linkage). This function may be provided as a function-like macro,
292 * but in this case it must evaluate its argument exactly once.
293 *
294 * \param[in] attributes The key attribute structure to query.
295 *
296 * \return The key type stored in the attribute structure.
297 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200298static psa_key_type_t psa_get_key_type(const psa_key_attributes_t *attributes);
299
Gilles Peskine20628592019-04-19 19:29:50 +0200300/** Retrieve the key size from key attributes.
301 *
302 * This function may be declared as `static` (i.e. without external
303 * linkage). This function may be provided as a function-like macro,
304 * but in this case it must evaluate its argument exactly once.
305 *
306 * \param[in] attributes The key attribute structure to query.
307 *
308 * \return The key size stored in the attribute structure, in bits.
309 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200310static size_t psa_get_key_bits(const psa_key_attributes_t *attributes);
311
Gilles Peskine20628592019-04-19 19:29:50 +0200312/** Retrieve the attributes of a key.
313 *
314 * This function first resets the attribute structure as with
Gilles Peskine9c640f92019-04-28 11:36:21 +0200315 * psa_reset_key_attributes(). It then copies the attributes of
316 * the given key into the given attribute structure.
Gilles Peskine20628592019-04-19 19:29:50 +0200317 *
Gilles Peskine9c640f92019-04-28 11:36:21 +0200318 * \note This function may allocate memory or other resources.
319 * Once you have called this function on an attribute structure,
320 * you must call psa_reset_key_attributes() to free these resources.
Gilles Peskine20628592019-04-19 19:29:50 +0200321 *
Gilles Peskine20628592019-04-19 19:29:50 +0200322 * \param[in] handle Handle to the key to query.
323 * \param[in,out] attributes On success, the attributes of the key.
324 * On failure, equivalent to a
325 * freshly-initialized structure.
326 *
327 * \retval #PSA_SUCCESS
328 * \retval #PSA_ERROR_INVALID_HANDLE
329 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
330 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Adrian L. Shaw29b64072019-08-06 16:02:12 +0100331 * \retval #PSA_ERROR_CORRUPTION_DETECTED
332 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +0100333 * \retval #PSA_ERROR_BAD_STATE
334 * The library has not been previously initialized by psa_crypto_init().
335 * It is implementation-dependent whether a failure to initialize
336 * results in this error code.
Gilles Peskine20628592019-04-19 19:29:50 +0200337 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200338psa_status_t psa_get_key_attributes(psa_key_handle_t handle,
339 psa_key_attributes_t *attributes);
340
Gilles Peskine20628592019-04-19 19:29:50 +0200341/** Reset a key attribute structure to a freshly initialized state.
342 *
343 * You must initialize the attribute structure as described in the
344 * documentation of the type #psa_key_attributes_t before calling this
345 * function. Once the structure has been initialized, you may call this
346 * function at any time.
347 *
348 * This function frees any auxiliary resources that the structure
349 * may contain.
350 *
351 * \param[in,out] attributes The attribute structure to reset.
352 */
Gilles Peskine8c8f2ab2019-04-18 21:44:46 +0200353void psa_reset_key_attributes(psa_key_attributes_t *attributes);
Gilles Peskine4747d192019-04-17 15:05:45 +0200354
Gilles Peskine87a5e562019-04-17 12:28:25 +0200355/**@}*/
356
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100357/** \defgroup key_management Key management
358 * @{
359 */
360
Gilles Peskinef535eb22018-11-30 14:08:36 +0100361/** Open a handle to an existing persistent key.
362 *
Gilles Peskine4754cde2019-05-21 15:56:29 +0200363 * Open a handle to a persistent key. A key is persistent if it was created
364 * with a lifetime other than #PSA_KEY_LIFETIME_VOLATILE. A persistent key
365 * always has a nonzero key identifier, set with psa_set_key_id() when
366 * creating the key. Implementations may provide additional pre-provisioned
Andrew Thoelke203491c2019-08-21 17:55:30 +0100367 * keys that can be opened with psa_open_key(). Such keys have a key identifier
368 * in the vendor range, as documented in the description of #psa_key_id_t.
Gilles Peskine4754cde2019-05-21 15:56:29 +0200369 *
370 * The application must eventually close the handle with psa_close_key()
371 * to release associated resources. If the application dies without calling
372 * psa_close_key(), the implementation should perform the equivalent of a
373 * call to psa_close_key().
Gilles Peskinef535eb22018-11-30 14:08:36 +0100374 *
Andrew Thoelke9741b112019-08-21 18:20:41 +0100375 * Some implementations permit an application to open the same key multiple
376 * times. Applications that rely on this behavior will not be portable to
377 * implementations that only permit a single key handle to be opened. See
378 * also :ref:\`key-handles\`.
379 *
Gilles Peskinef535eb22018-11-30 14:08:36 +0100380 * \param id The persistent identifier of the key.
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100381 * \param[out] handle On success, a handle to the key.
Gilles Peskinef535eb22018-11-30 14:08:36 +0100382 *
383 * \retval #PSA_SUCCESS
384 * Success. The application can now use the value of `*handle`
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100385 * to access the key.
Gilles Peskinef535eb22018-11-30 14:08:36 +0100386 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
Andrew Thoelke9741b112019-08-21 18:20:41 +0100387 * The implementation does not have sufficient resources to open the
388 * key. This can be due to reaching an implementation limit on the
389 * number of open keys, the number of open key handles, or available
390 * memory.
David Saadab4ecc272019-02-14 13:48:10 +0200391 * \retval #PSA_ERROR_DOES_NOT_EXIST
Andrew Thoelke9741b112019-08-21 18:20:41 +0100392 * There is no persistent key with key identifier \p id.
Gilles Peskinef535eb22018-11-30 14:08:36 +0100393 * \retval #PSA_ERROR_INVALID_ARGUMENT
Andrew Thoelke9741b112019-08-21 18:20:41 +0100394 * \p id is not a valid persistent key identifier.
Gilles Peskinef535eb22018-11-30 14:08:36 +0100395 * \retval #PSA_ERROR_NOT_PERMITTED
396 * The specified key exists, but the application does not have the
397 * permission to access it. Note that this specification does not
398 * define any way to create such a key, but it may be possible
399 * through implementation-specific means.
Gilles Peskine225010f2019-05-06 18:44:55 +0200400 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Adrian L. Shawd789dc12019-08-12 15:06:48 +0100401 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine225010f2019-05-06 18:44:55 +0200402 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +0100403 * \retval #PSA_ERROR_BAD_STATE
404 * The library has not been previously initialized by psa_crypto_init().
405 * It is implementation-dependent whether a failure to initialize
406 * results in this error code.
Gilles Peskinef535eb22018-11-30 14:08:36 +0100407 */
Gilles Peskine225010f2019-05-06 18:44:55 +0200408psa_status_t psa_open_key(psa_key_id_t id,
Gilles Peskinef535eb22018-11-30 14:08:36 +0100409 psa_key_handle_t *handle);
410
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100411
Gilles Peskinef535eb22018-11-30 14:08:36 +0100412/** Close a key handle.
413 *
Andrew Thoelke3daba812019-08-21 22:46:56 +0100414 * If the handle designates a volatile key, this will destroy the key material
415 * and free all associated resources, just like psa_destroy_key().
Gilles Peskinef535eb22018-11-30 14:08:36 +0100416 *
Andrew Thoelke3daba812019-08-21 22:46:56 +0100417 * If this is the last open handle to a persistent key, then closing the handle
418 * will free all resources associated with the key in volatile memory. The key
419 * data in persistent storage is not affected and can be opened again later
420 * with a call to psa_open_key().
Gilles Peskinef535eb22018-11-30 14:08:36 +0100421 *
Andrew Thoelke3daba812019-08-21 22:46:56 +0100422 * Closing the key handle makes the handle invalid, and the key handle
Andrew Thoelke8824dae2019-08-22 15:04:48 +0100423 * must not be used again by the application.
Andrew Thoelke3daba812019-08-21 22:46:56 +0100424 *
425 * If the key is currently in use in a multipart operation, then closing the
Andrew Thoelke8824dae2019-08-22 15:04:48 +0100426 * last remaining handle to the key will abort the multipart operation.
Gilles Peskine5f25dd02019-01-14 18:24:53 +0100427 *
Gilles Peskinef535eb22018-11-30 14:08:36 +0100428 * \param handle The key handle to close.
429 *
430 * \retval #PSA_SUCCESS
431 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskineae32aac2018-11-30 14:39:32 +0100432 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +0100433 * \retval #PSA_ERROR_BAD_STATE
434 * The library has not been previously initialized by psa_crypto_init().
435 * It is implementation-dependent whether a failure to initialize
436 * results in this error code.
Gilles Peskinef535eb22018-11-30 14:08:36 +0100437 */
438psa_status_t psa_close_key(psa_key_handle_t handle);
439
Gilles Peskine3cac8c42018-11-30 14:07:45 +0100440/**@}*/
441
442/** \defgroup import_export Key import and export
443 * @{
444 */
445
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100446/**
447 * \brief Import a key in binary format.
448 *
Gilles Peskinef5b9fa12018-03-07 16:40:18 +0100449 * This function supports any output from psa_export_key(). Refer to the
Gilles Peskinef7933932018-10-31 14:07:52 +0100450 * documentation of psa_export_public_key() for the format of public keys
451 * and to the documentation of psa_export_key() for the format for
452 * other key types.
453 *
454 * This specification supports a single format for each key type.
455 * Implementations may support other formats as long as the standard
456 * format is supported. Implementations that support other formats
457 * should ensure that the formats are clearly unambiguous so as to
458 * minimize the risk that an invalid input is accidentally interpreted
459 * according to a different format.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100460 *
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100461
Gilles Peskine20628592019-04-19 19:29:50 +0200462 * \param[in] attributes The attributes for the new key.
Gilles Peskine4ce2a9d2019-05-03 16:57:15 +0200463 * The key size is always determined from the
464 * \p data buffer.
465 * If the key size in \p attributes is nonzero,
466 * it must be equal to the size from \p data.
Gilles Peskine20628592019-04-19 19:29:50 +0200467 * \param[out] handle On success, a handle to the newly created key.
468 * \c 0 on failure.
Gilles Peskinef7933932018-10-31 14:07:52 +0100469 * \param[in] data Buffer containing the key data. The content of this
Gilles Peskine24f10f82019-05-16 12:18:32 +0200470 * buffer is interpreted according to the type declared
471 * in \p attributes.
Gilles Peskine20628592019-04-19 19:29:50 +0200472 * All implementations must support at least the format
473 * described in the documentation
Gilles Peskinef7933932018-10-31 14:07:52 +0100474 * of psa_export_key() or psa_export_public_key() for
Gilles Peskine20628592019-04-19 19:29:50 +0200475 * the chosen type. Implementations may allow other
476 * formats, but should be conservative: implementations
477 * should err on the side of rejecting content if it
478 * may be erroneous (e.g. wrong type or truncated data).
Gilles Peskinefa4070c2018-07-12 19:23:03 +0200479 * \param data_length Size of the \p data buffer in bytes.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100480 *
Gilles Peskine28538492018-07-11 17:34:00 +0200481 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +0100482 * Success.
Gilles Peskine23fd2bd2018-12-11 15:51:32 +0100483 * If the key is persistent, the key material and the key's metadata
484 * have been saved to persistent storage.
Gilles Peskine20628592019-04-19 19:29:50 +0200485 * \retval #PSA_ERROR_ALREADY_EXISTS
486 * This is an attempt to create a persistent key, and there is
487 * already a persistent key with the given identifier.
Gilles Peskine28538492018-07-11 17:34:00 +0200488 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskine65eb8582018-04-19 08:28:58 +0200489 * The key type or key size is not supported, either by the
Gilles Peskine20628592019-04-19 19:29:50 +0200490 * implementation in general or in this particular persistent location.
Gilles Peskine28538492018-07-11 17:34:00 +0200491 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine4ce2a9d2019-05-03 16:57:15 +0200492 * The key attributes, as a whole, are invalid.
493 * \retval #PSA_ERROR_INVALID_ARGUMENT
494 * The key data is not correctly formatted.
495 * \retval #PSA_ERROR_INVALID_ARGUMENT
496 * The size in \p attributes is nonzero and does not match the size
497 * of the key data.
Gilles Peskine28538492018-07-11 17:34:00 +0200498 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
499 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
500 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Darryl Greend49a4992018-06-18 17:27:26 +0100501 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine28538492018-07-11 17:34:00 +0200502 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200503 * \retval #PSA_ERROR_CORRUPTION_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +0300504 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +0300505 * The library has not been previously initialized by psa_crypto_init().
506 * It is implementation-dependent whether a failure to initialize
507 * results in this error code.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100508 */
Gilles Peskine87a5e562019-04-17 12:28:25 +0200509psa_status_t psa_import_key(const psa_key_attributes_t *attributes,
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100510 const uint8_t *data,
Gilles Peskine73676cb2019-05-15 20:15:10 +0200511 size_t data_length,
512 psa_key_handle_t *handle);
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100513
514/**
Gilles Peskineae32aac2018-11-30 14:39:32 +0100515 * \brief Destroy a key.
Gilles Peskine154bd952018-04-19 08:38:16 +0200516 *
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100517 * This function destroys a key from both volatile
Gilles Peskine154bd952018-04-19 08:38:16 +0200518 * memory and, if applicable, non-volatile storage. Implementations shall
Adrian L. Shawd56456c2019-05-15 11:36:13 +0100519 * make a best effort to ensure that that the key material cannot be recovered.
Gilles Peskine154bd952018-04-19 08:38:16 +0200520 *
Gilles Peskineae32aac2018-11-30 14:39:32 +0100521 * This function also erases any metadata such as policies and frees all
522 * resources associated with the key.
Gilles Peskine154bd952018-04-19 08:38:16 +0200523 *
Andrew Thoelke07f16b72019-08-21 22:48:47 +0100524 * Destroying a key will invalidate all existing handles to the key.
525 *
526 * If the key is currently in use in a multipart operation, then destroying the
527 * key will abort the multipart operation.
528 *
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100529 * \param handle Handle to the key to erase.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100530 *
Gilles Peskine28538492018-07-11 17:34:00 +0200531 * \retval #PSA_SUCCESS
Adrian L. Shawd56456c2019-05-15 11:36:13 +0100532 * The key material has been erased.
Gilles Peskine28538492018-07-11 17:34:00 +0200533 * \retval #PSA_ERROR_NOT_PERMITTED
Adrian L. Shaw0a695bd2019-05-15 13:28:41 +0100534 * The key cannot be erased because it is
Gilles Peskine65eb8582018-04-19 08:28:58 +0200535 * read-only, either due to a policy or due to physical restrictions.
Gilles Peskineae32aac2018-11-30 14:39:32 +0100536 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +0200537 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Gilles Peskine65eb8582018-04-19 08:28:58 +0200538 * There was an failure in communication with the cryptoprocessor.
539 * The key material may still be present in the cryptoprocessor.
Gilles Peskine28538492018-07-11 17:34:00 +0200540 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine65eb8582018-04-19 08:28:58 +0200541 * The storage is corrupted. Implementations shall make a best effort
542 * to erase key material even in this stage, however applications
543 * should be aware that it may be impossible to guarantee that the
544 * key material is not recoverable in such cases.
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200545 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine65eb8582018-04-19 08:28:58 +0200546 * An unexpected condition which is not a storage corruption or
547 * a communication failure occurred. The cryptoprocessor may have
548 * been compromised.
itayzafrir90d8c7a2018-09-12 11:44:52 +0300549 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +0300550 * The library has not been previously initialized by psa_crypto_init().
551 * It is implementation-dependent whether a failure to initialize
552 * results in this error code.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100553 */
Gilles Peskineae32aac2018-11-30 14:39:32 +0100554psa_status_t psa_destroy_key(psa_key_handle_t handle);
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100555
556/**
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100557 * \brief Export a key in binary format.
558 *
559 * The output of this function can be passed to psa_import_key() to
560 * create an equivalent object.
561 *
Gilles Peskinef7933932018-10-31 14:07:52 +0100562 * If the implementation of psa_import_key() supports other formats
563 * beyond the format specified here, the output from psa_export_key()
564 * must use the representation specified here, not the original
565 * representation.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100566 *
Gilles Peskine308b91d2018-02-08 09:47:44 +0100567 * For standard key types, the output format is as follows:
568 *
569 * - For symmetric keys (including MAC keys), the format is the
570 * raw bytes of the key.
571 * - For DES, the key data consists of 8 bytes. The parity bits must be
572 * correct.
573 * - For Triple-DES, the format is the concatenation of the
574 * two or three DES keys.
Gilles Peskinec93b80c2019-05-16 19:39:54 +0200575 * - For RSA key pairs (#PSA_KEY_TYPE_RSA_KEY_PAIR), the format
Gilles Peskine4e1e9be2018-08-10 18:57:40 +0200576 * is the non-encrypted DER encoding of the representation defined by
577 * PKCS\#1 (RFC 8017) as `RSAPrivateKey`, version 0.
578 * ```
579 * RSAPrivateKey ::= SEQUENCE {
Gilles Peskine4f6c77b2018-08-11 01:17:53 +0200580 * version INTEGER, -- must be 0
Gilles Peskine4e1e9be2018-08-10 18:57:40 +0200581 * modulus INTEGER, -- n
582 * publicExponent INTEGER, -- e
583 * privateExponent INTEGER, -- d
584 * prime1 INTEGER, -- p
585 * prime2 INTEGER, -- q
586 * exponent1 INTEGER, -- d mod (p-1)
587 * exponent2 INTEGER, -- d mod (q-1)
588 * coefficient INTEGER, -- (inverse of q) mod p
589 * }
590 * ```
Gilles Peskine4e1e9be2018-08-10 18:57:40 +0200591 * - For elliptic curve key pairs (key types for which
Gilles Peskinec93b80c2019-05-16 19:39:54 +0200592 * #PSA_KEY_TYPE_IS_ECC_KEY_PAIR is true), the format is
Gilles Peskine6c6a0232018-11-15 17:44:43 +0100593 * a representation of the private value as a `ceiling(m/8)`-byte string
594 * where `m` is the bit size associated with the curve, i.e. the bit size
595 * of the order of the curve's coordinate field. This byte string is
596 * in little-endian order for Montgomery curves (curve types
597 * `PSA_ECC_CURVE_CURVEXXX`), and in big-endian order for Weierstrass
598 * curves (curve types `PSA_ECC_CURVE_SECTXXX`, `PSA_ECC_CURVE_SECPXXX`
599 * and `PSA_ECC_CURVE_BRAINPOOL_PXXX`).
Gilles Peskinef76aa772018-10-29 19:24:33 +0100600 * This is the content of the `privateKey` field of the `ECPrivateKey`
601 * format defined by RFC 5915.
Gilles Peskinedcaefae2019-05-16 12:55:35 +0200602 * - For Diffie-Hellman key exchange key pairs (key types for which
Gilles Peskinec93b80c2019-05-16 19:39:54 +0200603 * #PSA_KEY_TYPE_IS_DH_KEY_PAIR is true), the
Jaeden Amero8851c402019-01-11 14:20:03 +0000604 * format is the representation of the private key `x` as a big-endian byte
605 * string. The length of the byte string is the private key size in bytes
606 * (leading zeroes are not stripped).
Gilles Peskine4e1e9be2018-08-10 18:57:40 +0200607 * - For public keys (key types for which #PSA_KEY_TYPE_IS_PUBLIC_KEY is
608 * true), the format is the same as for psa_export_public_key().
Gilles Peskine308b91d2018-02-08 09:47:44 +0100609 *
Gilles Peskine4318dfc2019-05-14 14:23:32 +0200610 * The policy on the key must have the usage flag #PSA_KEY_USAGE_EXPORT set.
611 *
Gilles Peskineae32aac2018-11-30 14:39:32 +0100612 * \param handle Handle to the key to export.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200613 * \param[out] data Buffer where the key data is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +0200614 * \param data_size Size of the \p data buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200615 * \param[out] data_length On success, the number of bytes
616 * that make up the key data.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100617 *
Gilles Peskine28538492018-07-11 17:34:00 +0200618 * \retval #PSA_SUCCESS
Gilles Peskineae32aac2018-11-30 14:39:32 +0100619 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +0200620 * \retval #PSA_ERROR_NOT_PERMITTED
Gilles Peskine4318dfc2019-05-14 14:23:32 +0200621 * The key does not have the #PSA_KEY_USAGE_EXPORT flag.
Darryl Green9e2d7a02018-07-24 16:33:30 +0100622 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskine1be949b2018-08-10 19:06:59 +0200623 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
624 * The size of the \p data buffer is too small. You can determine a
625 * sufficient buffer size by calling
626 * #PSA_KEY_EXPORT_MAX_SIZE(\c type, \c bits)
627 * where \c type is the key type
628 * and \c bits is the key size in bits.
Gilles Peskine28538492018-07-11 17:34:00 +0200629 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
630 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200631 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw89b71522019-08-06 16:21:00 +0100632 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shaw0542d592019-08-06 16:34:44 +0100633 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
itayzafrir90d8c7a2018-09-12 11:44:52 +0300634 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +0300635 * The library has not been previously initialized by psa_crypto_init().
636 * It is implementation-dependent whether a failure to initialize
637 * results in this error code.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100638 */
Gilles Peskineae32aac2018-11-30 14:39:32 +0100639psa_status_t psa_export_key(psa_key_handle_t handle,
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100640 uint8_t *data,
641 size_t data_size,
642 size_t *data_length);
643
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100644/**
645 * \brief Export a public key or the public part of a key pair in binary format.
646 *
647 * The output of this function can be passed to psa_import_key() to
648 * create an object that is equivalent to the public key.
649 *
Jaeden Amerod3a0c2c2019-01-11 17:15:56 +0000650 * This specification supports a single format for each key type.
651 * Implementations may support other formats as long as the standard
652 * format is supported. Implementations that support other formats
653 * should ensure that the formats are clearly unambiguous so as to
654 * minimize the risk that an invalid input is accidentally interpreted
655 * according to a different format.
656 *
Jaeden Amero6b196002019-01-10 10:23:21 +0000657 * For standard key types, the output format is as follows:
658 * - For RSA public keys (#PSA_KEY_TYPE_RSA_PUBLIC_KEY), the DER encoding of
659 * the representation defined by RFC 3279 &sect;2.3.1 as `RSAPublicKey`.
660 * ```
661 * RSAPublicKey ::= SEQUENCE {
662 * modulus INTEGER, -- n
663 * publicExponent INTEGER } -- e
664 * ```
Jaeden Amero0ae445f2019-01-10 11:42:27 +0000665 * - For elliptic curve public keys (key types for which
666 * #PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY is true), the format is the uncompressed
667 * representation defined by SEC1 &sect;2.3.3 as the content of an ECPoint.
668 * Let `m` be the bit size associated with the curve, i.e. the bit size of
669 * `q` for a curve over `F_q`. The representation consists of:
670 * - The byte 0x04;
671 * - `x_P` as a `ceiling(m/8)`-byte string, big-endian;
672 * - `y_P` as a `ceiling(m/8)`-byte string, big-endian.
Gilles Peskinedcaefae2019-05-16 12:55:35 +0200673 * - For Diffie-Hellman key exchange public keys (key types for which
674 * #PSA_KEY_TYPE_IS_DH_PUBLIC_KEY is true),
Jaeden Amero8851c402019-01-11 14:20:03 +0000675 * the format is the representation of the public key `y = g^x mod p` as a
676 * big-endian byte string. The length of the byte string is the length of the
677 * base prime `p` in bytes.
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100678 *
Gilles Peskine4318dfc2019-05-14 14:23:32 +0200679 * Exporting a public key object or the public part of a key pair is
680 * always permitted, regardless of the key's usage flags.
681 *
Gilles Peskineae32aac2018-11-30 14:39:32 +0100682 * \param handle Handle to the key to export.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200683 * \param[out] data Buffer where the key data is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +0200684 * \param data_size Size of the \p data buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200685 * \param[out] data_length On success, the number of bytes
686 * that make up the key data.
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100687 *
Gilles Peskine28538492018-07-11 17:34:00 +0200688 * \retval #PSA_SUCCESS
Gilles Peskineae32aac2018-11-30 14:39:32 +0100689 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +0200690 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine1be949b2018-08-10 19:06:59 +0200691 * The key is neither a public key nor a key pair.
692 * \retval #PSA_ERROR_NOT_SUPPORTED
693 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
694 * The size of the \p data buffer is too small. You can determine a
695 * sufficient buffer size by calling
Gilles Peskinec93b80c2019-05-16 19:39:54 +0200696 * #PSA_KEY_EXPORT_MAX_SIZE(#PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(\c type), \c bits)
Gilles Peskine1be949b2018-08-10 19:06:59 +0200697 * where \c type is the key type
698 * and \c bits is the key size in bits.
Gilles Peskine28538492018-07-11 17:34:00 +0200699 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
700 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200701 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw398b3c22019-08-06 17:22:41 +0100702 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shaw88c51ad2019-08-06 17:09:33 +0100703 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
itayzafrir90d8c7a2018-09-12 11:44:52 +0300704 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +0300705 * The library has not been previously initialized by psa_crypto_init().
706 * It is implementation-dependent whether a failure to initialize
707 * results in this error code.
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100708 */
Gilles Peskineae32aac2018-11-30 14:39:32 +0100709psa_status_t psa_export_public_key(psa_key_handle_t handle,
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100710 uint8_t *data,
711 size_t data_size,
712 size_t *data_length);
713
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100714/** Make a copy of a key.
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100715 *
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100716 * Copy key material from one location to another.
Jaeden Amero70261c52019-01-04 11:47:20 +0000717 *
Gilles Peskineaec5a7f2019-02-05 20:26:09 +0100718 * This function is primarily useful to copy a key from one location
719 * to another, since it populates a key using the material from
720 * another key which may have a different lifetime.
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200721 *
Adrian L. Shaw0a695bd2019-05-15 13:28:41 +0100722 * This function may be used to share a key with a different party,
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100723 * subject to implementation-defined restrictions on key sharing.
Gilles Peskine7e198532018-03-08 07:50:30 +0100724 *
Gilles Peskine8e0206a2019-05-14 14:24:28 +0200725 * The policy on the source key must have the usage flag
726 * #PSA_KEY_USAGE_COPY set.
Gilles Peskined6a8f5f2019-05-14 16:25:50 +0200727 * This flag is sufficient to permit the copy if the key has the lifetime
728 * #PSA_KEY_LIFETIME_VOLATILE or #PSA_KEY_LIFETIME_PERSISTENT.
729 * Some secure elements do not provide a way to copy a key without
730 * making it extractable from the secure element. If a key is located
731 * in such a secure element, then the key must have both usage flags
732 * #PSA_KEY_USAGE_COPY and #PSA_KEY_USAGE_EXPORT in order to make
733 * a copy of the key outside the secure element.
Gilles Peskine8e0206a2019-05-14 14:24:28 +0200734 *
Gilles Peskine20628592019-04-19 19:29:50 +0200735 * The resulting key may only be used in a way that conforms to
736 * both the policy of the original key and the policy specified in
737 * the \p attributes parameter:
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100738 * - The usage flags on the resulting key are the bitwise-and of the
Gilles Peskine20628592019-04-19 19:29:50 +0200739 * usage flags on the source policy and the usage flags in \p attributes.
740 * - If both allow the same algorithm or wildcard-based
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100741 * algorithm policy, the resulting key has the same algorithm policy.
Gilles Peskine20628592019-04-19 19:29:50 +0200742 * - If either of the policies allows an algorithm and the other policy
743 * allows a wildcard-based algorithm policy that includes this algorithm,
744 * the resulting key allows the same algorithm.
745 * - If the policies do not allow any algorithm in common, this function
746 * fails with the status #PSA_ERROR_INVALID_ARGUMENT.
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200747 *
Gilles Peskine20628592019-04-19 19:29:50 +0200748 * The effect of this function on implementation-defined attributes is
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100749 * implementation-defined.
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200750 *
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100751 * \param source_handle The key to copy. It must be a valid key handle.
Gilles Peskine20628592019-04-19 19:29:50 +0200752 * \param[in] attributes The attributes for the new key.
753 * They are used as follows:
Gilles Peskine4ce2a9d2019-05-03 16:57:15 +0200754 * - The key type and size may be 0. If either is
755 * nonzero, it must match the corresponding
756 * attribute of the source key.
Gilles Peskine20628592019-04-19 19:29:50 +0200757 * - The key location (the lifetime and, for
758 * persistent keys, the key identifier) is
759 * used directly.
760 * - The policy constraints (usage flags and
761 * algorithm policy) are combined from
762 * the source key and \p attributes so that
763 * both sets of restrictions apply, as
764 * described in the documentation of this function.
765 * \param[out] target_handle On success, a handle to the newly created key.
766 * \c 0 on failure.
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200767 *
768 * \retval #PSA_SUCCESS
Gilles Peskineae32aac2018-11-30 14:39:32 +0100769 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine20628592019-04-19 19:29:50 +0200770 * \p source_handle is invalid.
David Saadab4ecc272019-02-14 13:48:10 +0200771 * \retval #PSA_ERROR_ALREADY_EXISTS
Gilles Peskine20628592019-04-19 19:29:50 +0200772 * This is an attempt to create a persistent key, and there is
773 * already a persistent key with the given identifier.
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200774 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine20628592019-04-19 19:29:50 +0200775 * The lifetime or identifier in \p attributes are invalid.
776 * \retval #PSA_ERROR_INVALID_ARGUMENT
777 * The policy constraints on the source and specified in
778 * \p attributes are incompatible.
Gilles Peskine4ce2a9d2019-05-03 16:57:15 +0200779 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine24f10f82019-05-16 12:18:32 +0200780 * \p attributes specifies a key type or key size
Gilles Peskine4ce2a9d2019-05-03 16:57:15 +0200781 * which does not match the attributes of the source key.
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100782 * \retval #PSA_ERROR_NOT_PERMITTED
Gilles Peskine8e0206a2019-05-14 14:24:28 +0200783 * The source key does not have the #PSA_KEY_USAGE_COPY usage flag.
784 * \retval #PSA_ERROR_NOT_PERMITTED
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100785 * The source key is not exportable and its lifetime does not
786 * allow copying it to the target's lifetime.
787 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
788 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200789 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
790 * \retval #PSA_ERROR_HARDWARE_FAILURE
Adrian L. Shaw60b03202019-08-06 17:26:16 +0100791 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200792 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +0100793 * \retval #PSA_ERROR_BAD_STATE
794 * The library has not been previously initialized by psa_crypto_init().
795 * It is implementation-dependent whether a failure to initialize
796 * results in this error code.
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100797 */
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100798psa_status_t psa_copy_key(psa_key_handle_t source_handle,
Gilles Peskine87a5e562019-04-17 12:28:25 +0200799 const psa_key_attributes_t *attributes,
800 psa_key_handle_t *target_handle);
Gilles Peskine20035e32018-02-03 22:44:14 +0100801
802/**@}*/
803
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100804/** \defgroup hash Message digests
805 * @{
806 */
807
Gilles Peskine69647a42019-01-14 20:18:12 +0100808/** Calculate the hash (digest) of a message.
809 *
810 * \note To verify the hash of a message against an
811 * expected value, use psa_hash_compare() instead.
812 *
813 * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value
814 * such that #PSA_ALG_IS_HASH(\p alg) is true).
815 * \param[in] input Buffer containing the message to hash.
816 * \param input_length Size of the \p input buffer in bytes.
817 * \param[out] hash Buffer where the hash is to be written.
818 * \param hash_size Size of the \p hash buffer in bytes.
819 * \param[out] hash_length On success, the number of bytes
820 * that make up the hash value. This is always
Gilles Peskined338b912019-02-15 13:01:41 +0100821 * #PSA_HASH_SIZE(\p alg).
Gilles Peskine69647a42019-01-14 20:18:12 +0100822 *
823 * \retval #PSA_SUCCESS
824 * Success.
825 * \retval #PSA_ERROR_NOT_SUPPORTED
826 * \p alg is not supported or is not a hash algorithm.
Adrian L. Shawf7d852a2019-08-06 17:50:26 +0100827 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
828 * \p hash_size is too small
Gilles Peskine69647a42019-01-14 20:18:12 +0100829 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
830 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
831 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200832 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +0100833 * \retval #PSA_ERROR_BAD_STATE
834 * The library has not been previously initialized by psa_crypto_init().
835 * It is implementation-dependent whether a failure to initialize
836 * results in this error code.
Gilles Peskine69647a42019-01-14 20:18:12 +0100837 */
838psa_status_t psa_hash_compute(psa_algorithm_t alg,
839 const uint8_t *input,
840 size_t input_length,
841 uint8_t *hash,
842 size_t hash_size,
843 size_t *hash_length);
844
845/** Calculate the hash (digest) of a message and compare it with a
846 * reference value.
847 *
848 * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value
849 * such that #PSA_ALG_IS_HASH(\p alg) is true).
850 * \param[in] input Buffer containing the message to hash.
851 * \param input_length Size of the \p input buffer in bytes.
852 * \param[out] hash Buffer containing the expected hash value.
Gilles Peskinea05602d2019-01-17 15:25:52 +0100853 * \param hash_length Size of the \p hash buffer in bytes.
Gilles Peskine69647a42019-01-14 20:18:12 +0100854 *
855 * \retval #PSA_SUCCESS
856 * The expected hash is identical to the actual hash of the input.
857 * \retval #PSA_ERROR_INVALID_SIGNATURE
858 * The hash of the message was calculated successfully, but it
859 * differs from the expected hash.
860 * \retval #PSA_ERROR_NOT_SUPPORTED
861 * \p alg is not supported or is not a hash algorithm.
Adrian L. Shaw8d0bcf22019-08-13 11:36:29 +0100862 * \retval #PSA_ERROR_INVALID_ARGUMENT
863 * \p input_length or \p hash_length do not match the hash size for \p alg
Gilles Peskine69647a42019-01-14 20:18:12 +0100864 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
865 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
866 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200867 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +0100868 * \retval #PSA_ERROR_BAD_STATE
869 * The library has not been previously initialized by psa_crypto_init().
870 * It is implementation-dependent whether a failure to initialize
871 * results in this error code.
Gilles Peskine69647a42019-01-14 20:18:12 +0100872 */
873psa_status_t psa_hash_compare(psa_algorithm_t alg,
874 const uint8_t *input,
875 size_t input_length,
876 const uint8_t *hash,
877 const size_t hash_length);
878
Gilles Peskine308b91d2018-02-08 09:47:44 +0100879/** The type of the state data structure for multipart hash operations.
880 *
Jaeden Amero6a25b412019-01-04 11:47:44 +0000881 * Before calling any function on a hash operation object, the application must
882 * initialize it by any of the following means:
883 * - Set the structure to all-bits-zero, for example:
884 * \code
885 * psa_hash_operation_t operation;
886 * memset(&operation, 0, sizeof(operation));
887 * \endcode
888 * - Initialize the structure to logical zero values, for example:
889 * \code
890 * psa_hash_operation_t operation = {0};
891 * \endcode
892 * - Initialize the structure to the initializer #PSA_HASH_OPERATION_INIT,
893 * for example:
894 * \code
895 * psa_hash_operation_t operation = PSA_HASH_OPERATION_INIT;
896 * \endcode
897 * - Assign the result of the function psa_hash_operation_init()
898 * to the structure, for example:
899 * \code
900 * psa_hash_operation_t operation;
901 * operation = psa_hash_operation_init();
902 * \endcode
903 *
Gilles Peskine92b30732018-03-03 21:29:30 +0100904 * This is an implementation-defined \c struct. Applications should not
Gilles Peskine308b91d2018-02-08 09:47:44 +0100905 * make any assumptions about the content of this structure except
906 * as directed by the documentation of a specific implementation. */
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100907typedef struct psa_hash_operation_s psa_hash_operation_t;
908
Jaeden Amero6a25b412019-01-04 11:47:44 +0000909/** \def PSA_HASH_OPERATION_INIT
910 *
911 * This macro returns a suitable initializer for a hash operation object
912 * of type #psa_hash_operation_t.
913 */
914#ifdef __DOXYGEN_ONLY__
915/* This is an example definition for documentation purposes.
916 * Implementations should define a suitable value in `crypto_struct.h`.
917 */
918#define PSA_HASH_OPERATION_INIT {0}
919#endif
920
921/** Return an initial value for a hash operation object.
922 */
923static psa_hash_operation_t psa_hash_operation_init(void);
924
Gilles Peskinef45adda2019-01-14 18:29:18 +0100925/** Set up a multipart hash operation.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100926 *
927 * The sequence of operations to calculate a hash (message digest)
928 * is as follows:
929 * -# Allocate an operation object which will be passed to all the functions
930 * listed here.
Jaeden Amero6a25b412019-01-04 11:47:44 +0000931 * -# Initialize the operation object with one of the methods described in the
932 * documentation for #psa_hash_operation_t, e.g. PSA_HASH_OPERATION_INIT.
Gilles Peskineda8191d1c2018-07-08 19:46:38 +0200933 * -# Call psa_hash_setup() to specify the algorithm.
Gilles Peskine7e4acc52018-02-16 21:24:11 +0100934 * -# Call psa_hash_update() zero, one or more times, passing a fragment
Gilles Peskine308b91d2018-02-08 09:47:44 +0100935 * of the message each time. The hash that is calculated is the hash
936 * of the concatenation of these messages in order.
937 * -# To calculate the hash, call psa_hash_finish().
938 * To compare the hash with an expected value, call psa_hash_verify().
939 *
940 * The application may call psa_hash_abort() at any time after the operation
Jaeden Amero6a25b412019-01-04 11:47:44 +0000941 * has been initialized.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100942 *
Gilles Peskineda8191d1c2018-07-08 19:46:38 +0200943 * After a successful call to psa_hash_setup(), the application must
Gilles Peskineed522972018-03-20 17:54:15 +0100944 * eventually terminate the operation. The following events terminate an
945 * operation:
Gilles Peskine308b91d2018-02-08 09:47:44 +0100946 * - A failed call to psa_hash_update().
Gilles Peskine19067982018-03-20 17:54:53 +0100947 * - A call to psa_hash_finish(), psa_hash_verify() or psa_hash_abort().
Gilles Peskine308b91d2018-02-08 09:47:44 +0100948 *
Jaeden Amero6a25b412019-01-04 11:47:44 +0000949 * \param[in,out] operation The operation object to set up. It must have
950 * been initialized as per the documentation for
951 * #psa_hash_operation_t and not yet in use.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200952 * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value
953 * such that #PSA_ALG_IS_HASH(\p alg) is true).
Gilles Peskine308b91d2018-02-08 09:47:44 +0100954 *
Gilles Peskine28538492018-07-11 17:34:00 +0200955 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +0100956 * Success.
Gilles Peskine28538492018-07-11 17:34:00 +0200957 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +0200958 * \p alg is not supported or is not a hash algorithm.
Gilles Peskine8e1addc2019-01-10 11:51:17 +0100959 * \retval #PSA_ERROR_BAD_STATE
960 * The operation state is not valid (already set up and not
961 * subsequently completed).
Gilles Peskine28538492018-07-11 17:34:00 +0200962 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
963 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
964 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200965 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +0100966 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shawe970d652019-08-08 14:40:04 +0100967 * \p operation is either not initialized or is in use
968 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shawdec47b62019-08-07 14:25:38 +0100969 * The library has not been previously initialized by psa_crypto_init().
970 * It is implementation-dependent whether a failure to initialize
971 * results in this error code.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100972 */
Gilles Peskineda8191d1c2018-07-08 19:46:38 +0200973psa_status_t psa_hash_setup(psa_hash_operation_t *operation,
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100974 psa_algorithm_t alg);
975
Gilles Peskine308b91d2018-02-08 09:47:44 +0100976/** Add a message fragment to a multipart hash operation.
977 *
Gilles Peskineda8191d1c2018-07-08 19:46:38 +0200978 * The application must call psa_hash_setup() before calling this function.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100979 *
980 * If this function returns an error status, the operation becomes inactive.
981 *
Gilles Peskineedd11a12018-07-12 01:08:58 +0200982 * \param[in,out] operation Active hash operation.
983 * \param[in] input Buffer containing the message fragment to hash.
Gilles Peskinefa4070c2018-07-12 19:23:03 +0200984 * \param input_length Size of the \p input buffer in bytes.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100985 *
Gilles Peskine28538492018-07-11 17:34:00 +0200986 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +0100987 * Success.
Gilles Peskine28538492018-07-11 17:34:00 +0200988 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +0100989 * The operation state is not valid (not set up, or already completed).
Gilles Peskine28538492018-07-11 17:34:00 +0200990 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
991 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
992 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200993 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +0100994 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shaw320659b2019-08-08 14:49:01 +0100995 * The operation state is not valid.
996 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shawdec47b62019-08-07 14:25:38 +0100997 * The library has not been previously initialized by psa_crypto_init().
998 * It is implementation-dependent whether a failure to initialize
999 * results in this error code.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001000 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +01001001psa_status_t psa_hash_update(psa_hash_operation_t *operation,
1002 const uint8_t *input,
1003 size_t input_length);
1004
Gilles Peskine308b91d2018-02-08 09:47:44 +01001005/** Finish the calculation of the hash of a message.
1006 *
Gilles Peskineda8191d1c2018-07-08 19:46:38 +02001007 * The application must call psa_hash_setup() before calling this function.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001008 * This function calculates the hash of the message formed by concatenating
1009 * the inputs passed to preceding calls to psa_hash_update().
1010 *
1011 * When this function returns, the operation becomes inactive.
1012 *
1013 * \warning Applications should not call this function if they expect
1014 * a specific value for the hash. Call psa_hash_verify() instead.
1015 * Beware that comparing integrity or authenticity data such as
1016 * hash values with a function such as \c memcmp is risky
1017 * because the time taken by the comparison may leak information
1018 * about the hashed data which could allow an attacker to guess
1019 * a valid hash and thereby bypass security controls.
1020 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001021 * \param[in,out] operation Active hash operation.
1022 * \param[out] hash Buffer where the hash is to be written.
1023 * \param hash_size Size of the \p hash buffer in bytes.
1024 * \param[out] hash_length On success, the number of bytes
1025 * that make up the hash value. This is always
Gilles Peskinebe42f312018-07-13 14:38:15 +02001026 * #PSA_HASH_SIZE(\c alg) where \c alg is the
Gilles Peskineedd11a12018-07-12 01:08:58 +02001027 * hash algorithm that is calculated.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001028 *
Gilles Peskine28538492018-07-11 17:34:00 +02001029 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +01001030 * Success.
Gilles Peskine28538492018-07-11 17:34:00 +02001031 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001032 * The operation state is not valid (not set up, or already completed).
Gilles Peskine28538492018-07-11 17:34:00 +02001033 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001034 * The size of the \p hash buffer is too small. You can determine a
Gilles Peskine7256e6c2018-07-12 00:34:26 +02001035 * sufficient buffer size by calling #PSA_HASH_SIZE(\c alg)
Gilles Peskine308b91d2018-02-08 09:47:44 +01001036 * where \c alg is the hash algorithm that is calculated.
Gilles Peskine28538492018-07-11 17:34:00 +02001037 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1038 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1039 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001040 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001041 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shaw320659b2019-08-08 14:49:01 +01001042 * The operation state is not valid.
1043 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001044 * The library has not been previously initialized by psa_crypto_init().
1045 * It is implementation-dependent whether a failure to initialize
1046 * results in this error code.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001047 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +01001048psa_status_t psa_hash_finish(psa_hash_operation_t *operation,
1049 uint8_t *hash,
1050 size_t hash_size,
1051 size_t *hash_length);
1052
Gilles Peskine308b91d2018-02-08 09:47:44 +01001053/** Finish the calculation of the hash of a message and compare it with
1054 * an expected value.
1055 *
Gilles Peskineda8191d1c2018-07-08 19:46:38 +02001056 * The application must call psa_hash_setup() before calling this function.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001057 * This function calculates the hash of the message formed by concatenating
1058 * the inputs passed to preceding calls to psa_hash_update(). It then
1059 * compares the calculated hash with the expected hash passed as a
1060 * parameter to this function.
1061 *
1062 * When this function returns, the operation becomes inactive.
1063 *
Gilles Peskine19067982018-03-20 17:54:53 +01001064 * \note Implementations shall make the best effort to ensure that the
Gilles Peskine308b91d2018-02-08 09:47:44 +01001065 * comparison between the actual hash and the expected hash is performed
1066 * in constant time.
1067 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001068 * \param[in,out] operation Active hash operation.
1069 * \param[in] hash Buffer containing the expected hash value.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001070 * \param hash_length Size of the \p hash buffer in bytes.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001071 *
Gilles Peskine28538492018-07-11 17:34:00 +02001072 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +01001073 * The expected hash is identical to the actual hash of the message.
Gilles Peskine28538492018-07-11 17:34:00 +02001074 * \retval #PSA_ERROR_INVALID_SIGNATURE
Gilles Peskine308b91d2018-02-08 09:47:44 +01001075 * The hash of the message was calculated successfully, but it
1076 * differs from the expected hash.
Gilles Peskine28538492018-07-11 17:34:00 +02001077 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001078 * The operation state is not valid (not set up, or already completed).
Gilles Peskine28538492018-07-11 17:34:00 +02001079 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1080 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1081 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001082 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001083 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shaw320659b2019-08-08 14:49:01 +01001084 * The operation state is not valid.
1085 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001086 * The library has not been previously initialized by psa_crypto_init().
1087 * It is implementation-dependent whether a failure to initialize
1088 * results in this error code.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001089 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +01001090psa_status_t psa_hash_verify(psa_hash_operation_t *operation,
1091 const uint8_t *hash,
1092 size_t hash_length);
1093
Gilles Peskine308b91d2018-02-08 09:47:44 +01001094/** Abort a hash operation.
1095 *
Gilles Peskine308b91d2018-02-08 09:47:44 +01001096 * Aborting an operation frees all associated resources except for the
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001097 * \p operation structure itself. Once aborted, the operation object
1098 * can be reused for another operation by calling
1099 * psa_hash_setup() again.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001100 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001101 * You may call this function any time after the operation object has
1102 * been initialized by any of the following methods:
1103 * - A call to psa_hash_setup(), whether it succeeds or not.
1104 * - Initializing the \c struct to all-bits-zero.
1105 * - Initializing the \c struct to logical zeros, e.g.
1106 * `psa_hash_operation_t operation = {0}`.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001107 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001108 * In particular, calling psa_hash_abort() after the operation has been
1109 * terminated by a call to psa_hash_abort(), psa_hash_finish() or
1110 * psa_hash_verify() is safe and has no effect.
1111 *
1112 * \param[in,out] operation Initialized hash operation.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001113 *
Gilles Peskine28538492018-07-11 17:34:00 +02001114 * \retval #PSA_SUCCESS
1115 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001116 * \p operation is not an active hash operation.
Gilles Peskine28538492018-07-11 17:34:00 +02001117 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1118 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001119 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001120 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shaw320659b2019-08-08 14:49:01 +01001121 * The operation state is not valid.
1122 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001123 * The library has not been previously initialized by psa_crypto_init().
1124 * It is implementation-dependent whether a failure to initialize
1125 * results in this error code.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001126 */
1127psa_status_t psa_hash_abort(psa_hash_operation_t *operation);
Gilles Peskine9ef733f2018-02-07 21:05:37 +01001128
Gilles Peskineebb2c3e2019-01-19 12:03:41 +01001129/** Clone a hash operation.
1130 *
Gilles Peskinee43aa392019-01-21 14:50:37 +01001131 * This function copies the state of an ongoing hash operation to
1132 * a new operation object. In other words, this function is equivalent
1133 * to calling psa_hash_setup() on \p target_operation with the same
1134 * algorithm that \p source_operation was set up for, then
1135 * psa_hash_update() on \p target_operation with the same input that
1136 * that was passed to \p source_operation. After this function returns, the
1137 * two objects are independent, i.e. subsequent calls involving one of
1138 * the objects do not affect the other object.
1139 *
Gilles Peskineebb2c3e2019-01-19 12:03:41 +01001140 * \param[in] source_operation The active hash operation to clone.
1141 * \param[in,out] target_operation The operation object to set up.
1142 * It must be initialized but not active.
1143 *
1144 * \retval #PSA_SUCCESS
1145 * \retval #PSA_ERROR_BAD_STATE
1146 * \p source_operation is not an active hash operation.
1147 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinee43aa392019-01-21 14:50:37 +01001148 * \p target_operation is active.
Gilles Peskineebb2c3e2019-01-19 12:03:41 +01001149 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1150 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001151 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawd789dc12019-08-12 15:06:48 +01001152 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001153 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shaw320659b2019-08-08 14:49:01 +01001154 * The operation state is either not initialized or has already been setup.
1155 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001156 * The library has not been previously initialized by psa_crypto_init().
1157 * It is implementation-dependent whether a failure to initialize
1158 * results in this error code.
Gilles Peskineebb2c3e2019-01-19 12:03:41 +01001159 */
1160psa_status_t psa_hash_clone(const psa_hash_operation_t *source_operation,
1161 psa_hash_operation_t *target_operation);
1162
Gilles Peskine9ef733f2018-02-07 21:05:37 +01001163/**@}*/
1164
Gilles Peskine8c9def32018-02-08 10:02:12 +01001165/** \defgroup MAC Message authentication codes
1166 * @{
1167 */
1168
Gilles Peskine69647a42019-01-14 20:18:12 +01001169/** Calculate the MAC (message authentication code) of a message.
1170 *
1171 * \note To verify the MAC of a message against an
1172 * expected value, use psa_mac_verify() instead.
1173 * Beware that comparing integrity or authenticity data such as
1174 * MAC values with a function such as \c memcmp is risky
1175 * because the time taken by the comparison may leak information
1176 * about the MAC value which could allow an attacker to guess
1177 * a valid MAC and thereby bypass security controls.
1178 *
1179 * \param handle Handle to the key to use for the operation.
1180 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
Gilles Peskine63f79302019-02-15 13:01:17 +01001181 * such that #PSA_ALG_IS_MAC(\p alg) is true).
Gilles Peskine69647a42019-01-14 20:18:12 +01001182 * \param[in] input Buffer containing the input message.
1183 * \param input_length Size of the \p input buffer in bytes.
1184 * \param[out] mac Buffer where the MAC value is to be written.
1185 * \param mac_size Size of the \p mac buffer in bytes.
1186 * \param[out] mac_length On success, the number of bytes
Gilles Peskined338b912019-02-15 13:01:41 +01001187 * that make up the MAC value.
Gilles Peskine69647a42019-01-14 20:18:12 +01001188 *
1189 * \retval #PSA_SUCCESS
1190 * Success.
1191 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine69647a42019-01-14 20:18:12 +01001192 * \retval #PSA_ERROR_NOT_PERMITTED
1193 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001194 * \p handle is not compatible with \p alg.
Gilles Peskine69647a42019-01-14 20:18:12 +01001195 * \retval #PSA_ERROR_NOT_SUPPORTED
1196 * \p alg is not supported or is not a MAC algorithm.
Adrian L. Shawd5ae06b2019-08-07 15:59:33 +01001197 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1198 * \p mac_size is too small
Gilles Peskine69647a42019-01-14 20:18:12 +01001199 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1200 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1201 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001202 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawfa591c42019-08-07 10:47:47 +01001203 * \retval #PSA_ERROR_STORAGE_FAILURE
1204 * The key could not be retrieved from storage.
Gilles Peskine69647a42019-01-14 20:18:12 +01001205 * \retval #PSA_ERROR_BAD_STATE
1206 * The library has not been previously initialized by psa_crypto_init().
1207 * It is implementation-dependent whether a failure to initialize
1208 * results in this error code.
1209 */
1210psa_status_t psa_mac_compute(psa_key_handle_t handle,
1211 psa_algorithm_t alg,
1212 const uint8_t *input,
1213 size_t input_length,
1214 uint8_t *mac,
1215 size_t mac_size,
1216 size_t *mac_length);
1217
1218/** Calculate the MAC of a message and compare it with a reference value.
1219 *
1220 * \param handle Handle to the key to use for the operation.
1221 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
Gilles Peskine63f79302019-02-15 13:01:17 +01001222 * such that #PSA_ALG_IS_MAC(\p alg) is true).
Gilles Peskine69647a42019-01-14 20:18:12 +01001223 * \param[in] input Buffer containing the input message.
1224 * \param input_length Size of the \p input buffer in bytes.
1225 * \param[out] mac Buffer containing the expected MAC value.
1226 * \param mac_length Size of the \p mac buffer in bytes.
1227 *
1228 * \retval #PSA_SUCCESS
1229 * The expected MAC is identical to the actual MAC of the input.
1230 * \retval #PSA_ERROR_INVALID_SIGNATURE
1231 * The MAC of the message was calculated successfully, but it
1232 * differs from the expected value.
1233 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine69647a42019-01-14 20:18:12 +01001234 * \retval #PSA_ERROR_NOT_PERMITTED
1235 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001236 * \p handle is not compatible with \p alg.
Gilles Peskine69647a42019-01-14 20:18:12 +01001237 * \retval #PSA_ERROR_NOT_SUPPORTED
1238 * \p alg is not supported or is not a MAC algorithm.
1239 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1240 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1241 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001242 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001243 * \retval #PSA_ERROR_STORAGE_FAILURE
1244 * The key could not be retrieved from storage.
1245 * \retval #PSA_ERROR_BAD_STATE
1246 * The library has not been previously initialized by psa_crypto_init().
1247 * It is implementation-dependent whether a failure to initialize
1248 * results in this error code.
Gilles Peskine69647a42019-01-14 20:18:12 +01001249 */
Gilles Peskinea05602d2019-01-17 15:25:52 +01001250psa_status_t psa_mac_verify(psa_key_handle_t handle,
1251 psa_algorithm_t alg,
Gilles Peskine69647a42019-01-14 20:18:12 +01001252 const uint8_t *input,
1253 size_t input_length,
1254 const uint8_t *mac,
1255 const size_t mac_length);
1256
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001257/** The type of the state data structure for multipart MAC operations.
1258 *
Jaeden Amero769ce272019-01-04 11:48:03 +00001259 * Before calling any function on a MAC operation object, the application must
1260 * initialize it by any of the following means:
1261 * - Set the structure to all-bits-zero, for example:
1262 * \code
1263 * psa_mac_operation_t operation;
1264 * memset(&operation, 0, sizeof(operation));
1265 * \endcode
1266 * - Initialize the structure to logical zero values, for example:
1267 * \code
1268 * psa_mac_operation_t operation = {0};
1269 * \endcode
1270 * - Initialize the structure to the initializer #PSA_MAC_OPERATION_INIT,
1271 * for example:
1272 * \code
1273 * psa_mac_operation_t operation = PSA_MAC_OPERATION_INIT;
1274 * \endcode
1275 * - Assign the result of the function psa_mac_operation_init()
1276 * to the structure, for example:
1277 * \code
1278 * psa_mac_operation_t operation;
1279 * operation = psa_mac_operation_init();
1280 * \endcode
1281 *
Gilles Peskine92b30732018-03-03 21:29:30 +01001282 * This is an implementation-defined \c struct. Applications should not
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001283 * make any assumptions about the content of this structure except
1284 * as directed by the documentation of a specific implementation. */
Gilles Peskine8c9def32018-02-08 10:02:12 +01001285typedef struct psa_mac_operation_s psa_mac_operation_t;
1286
Jaeden Amero769ce272019-01-04 11:48:03 +00001287/** \def PSA_MAC_OPERATION_INIT
1288 *
1289 * This macro returns a suitable initializer for a MAC operation object of type
1290 * #psa_mac_operation_t.
1291 */
1292#ifdef __DOXYGEN_ONLY__
1293/* This is an example definition for documentation purposes.
1294 * Implementations should define a suitable value in `crypto_struct.h`.
1295 */
1296#define PSA_MAC_OPERATION_INIT {0}
1297#endif
1298
1299/** Return an initial value for a MAC operation object.
1300 */
1301static psa_mac_operation_t psa_mac_operation_init(void);
1302
Gilles Peskinef45adda2019-01-14 18:29:18 +01001303/** Set up a multipart MAC calculation operation.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001304 *
Gilles Peskine89167cb2018-07-08 20:12:23 +02001305 * This function sets up the calculation of the MAC
1306 * (message authentication code) of a byte string.
1307 * To verify the MAC of a message against an
1308 * expected value, use psa_mac_verify_setup() instead.
1309 *
1310 * The sequence of operations to calculate a MAC is as follows:
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001311 * -# Allocate an operation object which will be passed to all the functions
1312 * listed here.
Jaeden Amero769ce272019-01-04 11:48:03 +00001313 * -# Initialize the operation object with one of the methods described in the
1314 * documentation for #psa_mac_operation_t, e.g. PSA_MAC_OPERATION_INIT.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001315 * -# Call psa_mac_sign_setup() to specify the algorithm and key.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001316 * -# Call psa_mac_update() zero, one or more times, passing a fragment
1317 * of the message each time. The MAC that is calculated is the MAC
1318 * of the concatenation of these messages in order.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001319 * -# At the end of the message, call psa_mac_sign_finish() to finish
1320 * calculating the MAC value and retrieve it.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001321 *
1322 * The application may call psa_mac_abort() at any time after the operation
Jaeden Amero769ce272019-01-04 11:48:03 +00001323 * has been initialized.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001324 *
Gilles Peskine89167cb2018-07-08 20:12:23 +02001325 * After a successful call to psa_mac_sign_setup(), the application must
1326 * eventually terminate the operation through one of the following methods:
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001327 * - A failed call to psa_mac_update().
Gilles Peskine89167cb2018-07-08 20:12:23 +02001328 * - A call to psa_mac_sign_finish() or psa_mac_abort().
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001329 *
Jaeden Amero769ce272019-01-04 11:48:03 +00001330 * \param[in,out] operation The operation object to set up. It must have
1331 * been initialized as per the documentation for
1332 * #psa_mac_operation_t and not yet in use.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001333 * \param handle Handle to the key to use for the operation.
Gilles Peskine5f25dd02019-01-14 18:24:53 +01001334 * It must remain valid until the operation
1335 * terminates.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001336 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
Gilles Peskine63f79302019-02-15 13:01:17 +01001337 * such that #PSA_ALG_IS_MAC(\p alg) is true).
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001338 *
Gilles Peskine28538492018-07-11 17:34:00 +02001339 * \retval #PSA_SUCCESS
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001340 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001341 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +02001342 * \retval #PSA_ERROR_NOT_PERMITTED
1343 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001344 * \p handle is not compatible with \p alg.
Gilles Peskine28538492018-07-11 17:34:00 +02001345 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001346 * \p alg is not supported or is not a MAC algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02001347 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1348 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1349 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001350 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw2409ba02019-08-07 16:05:06 +01001351 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdf3c7ac2019-08-12 16:43:30 +01001352 * The key could not be retrieved from storage.
itayzafrir90d8c7a2018-09-12 11:44:52 +03001353 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskine8e1addc2019-01-10 11:51:17 +01001354 * The operation state is not valid (already set up and not
1355 * subsequently completed).
1356 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03001357 * The library has not been previously initialized by psa_crypto_init().
1358 * It is implementation-dependent whether a failure to initialize
1359 * results in this error code.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001360 */
Gilles Peskine89167cb2018-07-08 20:12:23 +02001361psa_status_t psa_mac_sign_setup(psa_mac_operation_t *operation,
Gilles Peskineae32aac2018-11-30 14:39:32 +01001362 psa_key_handle_t handle,
Gilles Peskine89167cb2018-07-08 20:12:23 +02001363 psa_algorithm_t alg);
1364
Gilles Peskinef45adda2019-01-14 18:29:18 +01001365/** Set up a multipart MAC verification operation.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001366 *
1367 * This function sets up the verification of the MAC
1368 * (message authentication code) of a byte string against an expected value.
1369 *
1370 * The sequence of operations to verify a MAC is as follows:
1371 * -# Allocate an operation object which will be passed to all the functions
1372 * listed here.
Jaeden Amero769ce272019-01-04 11:48:03 +00001373 * -# Initialize the operation object with one of the methods described in the
1374 * documentation for #psa_mac_operation_t, e.g. PSA_MAC_OPERATION_INIT.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001375 * -# Call psa_mac_verify_setup() to specify the algorithm and key.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001376 * -# Call psa_mac_update() zero, one or more times, passing a fragment
1377 * of the message each time. The MAC that is calculated is the MAC
1378 * of the concatenation of these messages in order.
1379 * -# At the end of the message, call psa_mac_verify_finish() to finish
1380 * calculating the actual MAC of the message and verify it against
1381 * the expected value.
1382 *
1383 * The application may call psa_mac_abort() at any time after the operation
Jaeden Amero769ce272019-01-04 11:48:03 +00001384 * has been initialized.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001385 *
1386 * After a successful call to psa_mac_verify_setup(), the application must
1387 * eventually terminate the operation through one of the following methods:
1388 * - A failed call to psa_mac_update().
1389 * - A call to psa_mac_verify_finish() or psa_mac_abort().
1390 *
Jaeden Amero769ce272019-01-04 11:48:03 +00001391 * \param[in,out] operation The operation object to set up. It must have
1392 * been initialized as per the documentation for
1393 * #psa_mac_operation_t and not yet in use.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001394 * \param handle Handle to the key to use for the operation.
Gilles Peskine5f25dd02019-01-14 18:24:53 +01001395 * It must remain valid until the operation
1396 * terminates.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001397 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
1398 * such that #PSA_ALG_IS_MAC(\p alg) is true).
Gilles Peskine89167cb2018-07-08 20:12:23 +02001399 *
Gilles Peskine28538492018-07-11 17:34:00 +02001400 * \retval #PSA_SUCCESS
Gilles Peskine89167cb2018-07-08 20:12:23 +02001401 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001402 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +02001403 * \retval #PSA_ERROR_NOT_PERMITTED
1404 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine89167cb2018-07-08 20:12:23 +02001405 * \c key is not compatible with \c alg.
Gilles Peskine28538492018-07-11 17:34:00 +02001406 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskine89167cb2018-07-08 20:12:23 +02001407 * \c alg is not supported or is not a MAC algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02001408 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1409 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1410 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001411 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw9770d0e2019-08-07 16:18:18 +01001412 * \retval #PSA_ERROR_STORAGE_FAILURE
1413 * The key could not be retrieved from storage
itayzafrir90d8c7a2018-09-12 11:44:52 +03001414 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskine8e1addc2019-01-10 11:51:17 +01001415 * The operation state is not valid (already set up and not
1416 * subsequently completed).
1417 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03001418 * The library has not been previously initialized by psa_crypto_init().
1419 * It is implementation-dependent whether a failure to initialize
1420 * results in this error code.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001421 */
1422psa_status_t psa_mac_verify_setup(psa_mac_operation_t *operation,
Gilles Peskineae32aac2018-11-30 14:39:32 +01001423 psa_key_handle_t handle,
Gilles Peskine89167cb2018-07-08 20:12:23 +02001424 psa_algorithm_t alg);
Gilles Peskine8c9def32018-02-08 10:02:12 +01001425
Gilles Peskinedcd14942018-07-12 00:30:52 +02001426/** Add a message fragment to a multipart MAC operation.
1427 *
1428 * The application must call psa_mac_sign_setup() or psa_mac_verify_setup()
1429 * before calling this function.
1430 *
1431 * If this function returns an error status, the operation becomes inactive.
1432 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001433 * \param[in,out] operation Active MAC operation.
1434 * \param[in] input Buffer containing the message fragment to add to
1435 * the MAC calculation.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001436 * \param input_length Size of the \p input buffer in bytes.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001437 *
1438 * \retval #PSA_SUCCESS
1439 * Success.
1440 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001441 * The operation state is not valid (not set up, or already completed).
Gilles Peskinedcd14942018-07-12 00:30:52 +02001442 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1443 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1444 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001445 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawd789dc12019-08-12 15:06:48 +01001446 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001447 * \retval #PSA_ERROR_BAD_STATE
1448 * The library has not been previously initialized by psa_crypto_init().
1449 * It is implementation-dependent whether a failure to initialize
1450 * results in this error code.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001451 */
Gilles Peskine8c9def32018-02-08 10:02:12 +01001452psa_status_t psa_mac_update(psa_mac_operation_t *operation,
1453 const uint8_t *input,
1454 size_t input_length);
1455
Gilles Peskinedcd14942018-07-12 00:30:52 +02001456/** Finish the calculation of the MAC of a message.
1457 *
1458 * The application must call psa_mac_sign_setup() before calling this function.
1459 * This function calculates the MAC of the message formed by concatenating
1460 * the inputs passed to preceding calls to psa_mac_update().
1461 *
1462 * When this function returns, the operation becomes inactive.
1463 *
1464 * \warning Applications should not call this function if they expect
1465 * a specific value for the MAC. Call psa_mac_verify_finish() instead.
1466 * Beware that comparing integrity or authenticity data such as
1467 * MAC values with a function such as \c memcmp is risky
1468 * because the time taken by the comparison may leak information
1469 * about the MAC value which could allow an attacker to guess
1470 * a valid MAC and thereby bypass security controls.
1471 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001472 * \param[in,out] operation Active MAC operation.
1473 * \param[out] mac Buffer where the MAC value is to be written.
1474 * \param mac_size Size of the \p mac buffer in bytes.
1475 * \param[out] mac_length On success, the number of bytes
1476 * that make up the MAC value. This is always
Gilles Peskinedda3bd32018-07-12 19:40:46 +02001477 * #PSA_MAC_FINAL_SIZE(\c key_type, \c key_bits, \c alg)
Gilles Peskineedd11a12018-07-12 01:08:58 +02001478 * where \c key_type and \c key_bits are the type and
Gilles Peskinedda3bd32018-07-12 19:40:46 +02001479 * bit-size respectively of the key and \c alg is the
Gilles Peskineedd11a12018-07-12 01:08:58 +02001480 * MAC algorithm that is calculated.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001481 *
1482 * \retval #PSA_SUCCESS
1483 * Success.
1484 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001485 * The operation state is not valid (not set up, or already completed).
Gilles Peskinedcd14942018-07-12 00:30:52 +02001486 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001487 * The size of the \p mac buffer is too small. You can determine a
Gilles Peskinedcd14942018-07-12 00:30:52 +02001488 * sufficient buffer size by calling PSA_MAC_FINAL_SIZE().
1489 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1490 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1491 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001492 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw26322362019-08-13 11:43:40 +01001493 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001494 * \retval #PSA_ERROR_BAD_STATE
1495 * The library has not been previously initialized by psa_crypto_init().
1496 * It is implementation-dependent whether a failure to initialize
1497 * results in this error code.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001498 */
Gilles Peskineacd4be32018-07-08 19:56:25 +02001499psa_status_t psa_mac_sign_finish(psa_mac_operation_t *operation,
1500 uint8_t *mac,
1501 size_t mac_size,
1502 size_t *mac_length);
Gilles Peskine8c9def32018-02-08 10:02:12 +01001503
Gilles Peskinedcd14942018-07-12 00:30:52 +02001504/** Finish the calculation of the MAC of a message and compare it with
1505 * an expected value.
1506 *
1507 * The application must call psa_mac_verify_setup() before calling this function.
1508 * This function calculates the MAC of the message formed by concatenating
1509 * the inputs passed to preceding calls to psa_mac_update(). It then
1510 * compares the calculated MAC with the expected MAC passed as a
1511 * parameter to this function.
1512 *
1513 * When this function returns, the operation becomes inactive.
1514 *
1515 * \note Implementations shall make the best effort to ensure that the
1516 * comparison between the actual MAC and the expected MAC is performed
1517 * in constant time.
1518 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001519 * \param[in,out] operation Active MAC operation.
1520 * \param[in] mac Buffer containing the expected MAC value.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001521 * \param mac_length Size of the \p mac buffer in bytes.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001522 *
1523 * \retval #PSA_SUCCESS
1524 * The expected MAC is identical to the actual MAC of the message.
1525 * \retval #PSA_ERROR_INVALID_SIGNATURE
1526 * The MAC of the message was calculated successfully, but it
1527 * differs from the expected MAC.
1528 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001529 * The operation state is not valid (not set up, or already completed).
Gilles Peskinedcd14942018-07-12 00:30:52 +02001530 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1531 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1532 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001533 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawd9e90242019-08-13 11:44:30 +01001534 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001535 * \retval #PSA_ERROR_BAD_STATE
1536 * The library has not been previously initialized by psa_crypto_init().
1537 * It is implementation-dependent whether a failure to initialize
1538 * results in this error code.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001539 */
Gilles Peskineacd4be32018-07-08 19:56:25 +02001540psa_status_t psa_mac_verify_finish(psa_mac_operation_t *operation,
1541 const uint8_t *mac,
1542 size_t mac_length);
Gilles Peskine8c9def32018-02-08 10:02:12 +01001543
Gilles Peskinedcd14942018-07-12 00:30:52 +02001544/** Abort a MAC operation.
1545 *
Gilles Peskinedcd14942018-07-12 00:30:52 +02001546 * Aborting an operation frees all associated resources except for the
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001547 * \p operation structure itself. Once aborted, the operation object
1548 * can be reused for another operation by calling
1549 * psa_mac_sign_setup() or psa_mac_verify_setup() again.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001550 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001551 * You may call this function any time after the operation object has
1552 * been initialized by any of the following methods:
1553 * - A call to psa_mac_sign_setup() or psa_mac_verify_setup(), whether
1554 * it succeeds or not.
1555 * - Initializing the \c struct to all-bits-zero.
1556 * - Initializing the \c struct to logical zeros, e.g.
1557 * `psa_mac_operation_t operation = {0}`.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001558 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001559 * In particular, calling psa_mac_abort() after the operation has been
1560 * terminated by a call to psa_mac_abort(), psa_mac_sign_finish() or
1561 * psa_mac_verify_finish() is safe and has no effect.
1562 *
1563 * \param[in,out] operation Initialized MAC operation.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001564 *
1565 * \retval #PSA_SUCCESS
1566 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001567 * \p operation is not an active MAC operation.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001568 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1569 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001570 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001571 * \retval #PSA_ERROR_BAD_STATE
1572 * The library has not been previously initialized by psa_crypto_init().
1573 * It is implementation-dependent whether a failure to initialize
1574 * results in this error code.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001575 */
Gilles Peskine8c9def32018-02-08 10:02:12 +01001576psa_status_t psa_mac_abort(psa_mac_operation_t *operation);
1577
1578/**@}*/
1579
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001580/** \defgroup cipher Symmetric ciphers
1581 * @{
1582 */
1583
Gilles Peskine69647a42019-01-14 20:18:12 +01001584/** Encrypt a message using a symmetric cipher.
1585 *
1586 * This function encrypts a message with a random IV (initialization
1587 * vector).
1588 *
1589 * \param handle Handle to the key to use for the operation.
1590 * It must remain valid until the operation
1591 * terminates.
1592 * \param alg The cipher algorithm to compute
1593 * (\c PSA_ALG_XXX value such that
1594 * #PSA_ALG_IS_CIPHER(\p alg) is true).
1595 * \param[in] input Buffer containing the message to encrypt.
1596 * \param input_length Size of the \p input buffer in bytes.
1597 * \param[out] output Buffer where the output is to be written.
1598 * The output contains the IV followed by
1599 * the ciphertext proper.
1600 * \param output_size Size of the \p output buffer in bytes.
1601 * \param[out] output_length On success, the number of bytes
1602 * that make up the output.
1603 *
1604 * \retval #PSA_SUCCESS
1605 * Success.
1606 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine69647a42019-01-14 20:18:12 +01001607 * \retval #PSA_ERROR_NOT_PERMITTED
1608 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001609 * \p handle is not compatible with \p alg.
Gilles Peskine69647a42019-01-14 20:18:12 +01001610 * \retval #PSA_ERROR_NOT_SUPPORTED
1611 * \p alg is not supported or is not a cipher algorithm.
1612 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1613 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1614 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1615 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001616 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawa3f6ba52019-08-08 14:51:49 +01001617 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001618 * \retval #PSA_ERROR_BAD_STATE
1619 * The library has not been previously initialized by psa_crypto_init().
1620 * It is implementation-dependent whether a failure to initialize
1621 * results in this error code.
Gilles Peskine69647a42019-01-14 20:18:12 +01001622 */
1623psa_status_t psa_cipher_encrypt(psa_key_handle_t handle,
1624 psa_algorithm_t alg,
1625 const uint8_t *input,
1626 size_t input_length,
1627 uint8_t *output,
1628 size_t output_size,
1629 size_t *output_length);
1630
1631/** Decrypt a message using a symmetric cipher.
1632 *
1633 * This function decrypts a message encrypted with a symmetric cipher.
1634 *
1635 * \param handle Handle to the key to use for the operation.
1636 * It must remain valid until the operation
1637 * terminates.
1638 * \param alg The cipher algorithm to compute
1639 * (\c PSA_ALG_XXX value such that
1640 * #PSA_ALG_IS_CIPHER(\p alg) is true).
1641 * \param[in] input Buffer containing the message to decrypt.
1642 * This consists of the IV followed by the
1643 * ciphertext proper.
1644 * \param input_length Size of the \p input buffer in bytes.
1645 * \param[out] output Buffer where the plaintext is to be written.
1646 * \param output_size Size of the \p output buffer in bytes.
1647 * \param[out] output_length On success, the number of bytes
1648 * that make up the output.
1649 *
1650 * \retval #PSA_SUCCESS
1651 * Success.
1652 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine69647a42019-01-14 20:18:12 +01001653 * \retval #PSA_ERROR_NOT_PERMITTED
1654 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001655 * \p handle is not compatible with \p alg.
Gilles Peskine69647a42019-01-14 20:18:12 +01001656 * \retval #PSA_ERROR_NOT_SUPPORTED
1657 * \p alg is not supported or is not a cipher algorithm.
1658 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1659 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1660 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1661 * \retval #PSA_ERROR_HARDWARE_FAILURE
Adrian L. Shawa3f6ba52019-08-08 14:51:49 +01001662 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001663 * \retval #PSA_ERROR_BAD_STATE
1664 * The library has not been previously initialized by psa_crypto_init().
1665 * It is implementation-dependent whether a failure to initialize
1666 * results in this error code. * \retval #PSA_ERROR_CORRUPTION_DETECTED
1667
Gilles Peskine69647a42019-01-14 20:18:12 +01001668 */
1669psa_status_t psa_cipher_decrypt(psa_key_handle_t handle,
1670 psa_algorithm_t alg,
1671 const uint8_t *input,
1672 size_t input_length,
1673 uint8_t *output,
1674 size_t output_size,
1675 size_t *output_length);
1676
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001677/** The type of the state data structure for multipart cipher operations.
1678 *
Jaeden Amero5bae2272019-01-04 11:48:27 +00001679 * Before calling any function on a cipher operation object, the application
1680 * must initialize it by any of the following means:
1681 * - Set the structure to all-bits-zero, for example:
1682 * \code
1683 * psa_cipher_operation_t operation;
1684 * memset(&operation, 0, sizeof(operation));
1685 * \endcode
1686 * - Initialize the structure to logical zero values, for example:
1687 * \code
1688 * psa_cipher_operation_t operation = {0};
1689 * \endcode
1690 * - Initialize the structure to the initializer #PSA_CIPHER_OPERATION_INIT,
1691 * for example:
1692 * \code
1693 * psa_cipher_operation_t operation = PSA_CIPHER_OPERATION_INIT;
1694 * \endcode
1695 * - Assign the result of the function psa_cipher_operation_init()
1696 * to the structure, for example:
1697 * \code
1698 * psa_cipher_operation_t operation;
1699 * operation = psa_cipher_operation_init();
1700 * \endcode
1701 *
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001702 * This is an implementation-defined \c struct. Applications should not
1703 * make any assumptions about the content of this structure except
1704 * as directed by the documentation of a specific implementation. */
1705typedef struct psa_cipher_operation_s psa_cipher_operation_t;
1706
Jaeden Amero5bae2272019-01-04 11:48:27 +00001707/** \def PSA_CIPHER_OPERATION_INIT
1708 *
1709 * This macro returns a suitable initializer for a cipher operation object of
1710 * type #psa_cipher_operation_t.
1711 */
1712#ifdef __DOXYGEN_ONLY__
1713/* This is an example definition for documentation purposes.
1714 * Implementations should define a suitable value in `crypto_struct.h`.
1715 */
1716#define PSA_CIPHER_OPERATION_INIT {0}
1717#endif
1718
1719/** Return an initial value for a cipher operation object.
1720 */
1721static psa_cipher_operation_t psa_cipher_operation_init(void);
1722
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001723/** Set the key for a multipart symmetric encryption operation.
1724 *
1725 * The sequence of operations to encrypt a message with a symmetric cipher
1726 * is as follows:
1727 * -# Allocate an operation object which will be passed to all the functions
1728 * listed here.
Jaeden Amero5bae2272019-01-04 11:48:27 +00001729 * -# Initialize the operation object with one of the methods described in the
1730 * documentation for #psa_cipher_operation_t, e.g.
1731 * PSA_CIPHER_OPERATION_INIT.
Gilles Peskinefe119512018-07-08 21:39:34 +02001732 * -# Call psa_cipher_encrypt_setup() to specify the algorithm and key.
itayzafrired7382f2018-08-02 14:19:33 +03001733 * -# Call either psa_cipher_generate_iv() or psa_cipher_set_iv() to
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001734 * generate or set the IV (initialization vector). You should use
itayzafrired7382f2018-08-02 14:19:33 +03001735 * psa_cipher_generate_iv() unless the protocol you are implementing
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001736 * requires a specific IV value.
1737 * -# Call psa_cipher_update() zero, one or more times, passing a fragment
1738 * of the message each time.
1739 * -# Call psa_cipher_finish().
1740 *
1741 * The application may call psa_cipher_abort() at any time after the operation
Jaeden Amero5bae2272019-01-04 11:48:27 +00001742 * has been initialized.
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001743 *
Gilles Peskinefe119512018-07-08 21:39:34 +02001744 * After a successful call to psa_cipher_encrypt_setup(), the application must
Gilles Peskineed522972018-03-20 17:54:15 +01001745 * eventually terminate the operation. The following events terminate an
1746 * operation:
Gilles Peskinef45adda2019-01-14 18:29:18 +01001747 * - A failed call to any of the \c psa_cipher_xxx functions.
Gilles Peskine19067982018-03-20 17:54:53 +01001748 * - A call to psa_cipher_finish() or psa_cipher_abort().
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001749 *
Jaeden Amero5bae2272019-01-04 11:48:27 +00001750 * \param[in,out] operation The operation object to set up. It must have
1751 * been initialized as per the documentation for
1752 * #psa_cipher_operation_t and not yet in use.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001753 * \param handle Handle to the key to use for the operation.
Gilles Peskine5f25dd02019-01-14 18:24:53 +01001754 * It must remain valid until the operation
1755 * terminates.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001756 * \param alg The cipher algorithm to compute
1757 * (\c PSA_ALG_XXX value such that
1758 * #PSA_ALG_IS_CIPHER(\p alg) is true).
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001759 *
Gilles Peskine28538492018-07-11 17:34:00 +02001760 * \retval #PSA_SUCCESS
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001761 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001762 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +02001763 * \retval #PSA_ERROR_NOT_PERMITTED
1764 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001765 * \p handle is not compatible with \p alg.
Gilles Peskine28538492018-07-11 17:34:00 +02001766 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001767 * \p alg is not supported or is not a cipher algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02001768 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1769 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1770 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001771 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdc5bf5c2019-08-13 11:46:09 +01001772 * \retval #PSA_ERROR_STORAGE_FAILURE
itayzafrir90d8c7a2018-09-12 11:44:52 +03001773 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskine8e1addc2019-01-10 11:51:17 +01001774 * The operation state is not valid (already set up and not
1775 * subsequently completed).
1776 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03001777 * The library has not been previously initialized by psa_crypto_init().
1778 * It is implementation-dependent whether a failure to initialize
1779 * results in this error code.
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001780 */
Gilles Peskinefe119512018-07-08 21:39:34 +02001781psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation,
Gilles Peskineae32aac2018-11-30 14:39:32 +01001782 psa_key_handle_t handle,
Gilles Peskinefe119512018-07-08 21:39:34 +02001783 psa_algorithm_t alg);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001784
1785/** Set the key for a multipart symmetric decryption operation.
1786 *
1787 * The sequence of operations to decrypt a message with a symmetric cipher
1788 * is as follows:
1789 * -# Allocate an operation object which will be passed to all the functions
1790 * listed here.
Jaeden Amero5bae2272019-01-04 11:48:27 +00001791 * -# Initialize the operation object with one of the methods described in the
1792 * documentation for #psa_cipher_operation_t, e.g.
1793 * PSA_CIPHER_OPERATION_INIT.
Gilles Peskinefe119512018-07-08 21:39:34 +02001794 * -# Call psa_cipher_decrypt_setup() to specify the algorithm and key.
Gilles Peskinef45adda2019-01-14 18:29:18 +01001795 * -# Call psa_cipher_set_iv() with the IV (initialization vector) for the
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001796 * decryption. If the IV is prepended to the ciphertext, you can call
1797 * psa_cipher_update() on a buffer containing the IV followed by the
1798 * beginning of the message.
1799 * -# Call psa_cipher_update() zero, one or more times, passing a fragment
1800 * of the message each time.
1801 * -# Call psa_cipher_finish().
1802 *
1803 * The application may call psa_cipher_abort() at any time after the operation
Jaeden Amero5bae2272019-01-04 11:48:27 +00001804 * has been initialized.
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001805 *
Gilles Peskinefe119512018-07-08 21:39:34 +02001806 * After a successful call to psa_cipher_decrypt_setup(), the application must
Gilles Peskineed522972018-03-20 17:54:15 +01001807 * eventually terminate the operation. The following events terminate an
1808 * operation:
Gilles Peskinef45adda2019-01-14 18:29:18 +01001809 * - A failed call to any of the \c psa_cipher_xxx functions.
Gilles Peskine19067982018-03-20 17:54:53 +01001810 * - A call to psa_cipher_finish() or psa_cipher_abort().
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001811 *
Jaeden Amero5bae2272019-01-04 11:48:27 +00001812 * \param[in,out] operation The operation object to set up. It must have
1813 * been initialized as per the documentation for
1814 * #psa_cipher_operation_t and not yet in use.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001815 * \param handle Handle to the key to use for the operation.
Gilles Peskine5f25dd02019-01-14 18:24:53 +01001816 * It must remain valid until the operation
1817 * terminates.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001818 * \param alg The cipher algorithm to compute
1819 * (\c PSA_ALG_XXX value such that
1820 * #PSA_ALG_IS_CIPHER(\p alg) is true).
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001821 *
Gilles Peskine28538492018-07-11 17:34:00 +02001822 * \retval #PSA_SUCCESS
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001823 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001824 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +02001825 * \retval #PSA_ERROR_NOT_PERMITTED
1826 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001827 * \p handle is not compatible with \p alg.
Gilles Peskine28538492018-07-11 17:34:00 +02001828 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001829 * \p alg is not supported or is not a cipher algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02001830 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1831 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1832 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001833 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdc5bf5c2019-08-13 11:46:09 +01001834 * \retval #PSA_ERROR_STORAGE_FAILURE
itayzafrir90d8c7a2018-09-12 11:44:52 +03001835 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskine8e1addc2019-01-10 11:51:17 +01001836 * The operation state is not valid (already set up and not
1837 * subsequently completed).
1838 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03001839 * The library has not been previously initialized by psa_crypto_init().
1840 * It is implementation-dependent whether a failure to initialize
1841 * results in this error code.
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001842 */
Gilles Peskinefe119512018-07-08 21:39:34 +02001843psa_status_t psa_cipher_decrypt_setup(psa_cipher_operation_t *operation,
Gilles Peskineae32aac2018-11-30 14:39:32 +01001844 psa_key_handle_t handle,
Gilles Peskinefe119512018-07-08 21:39:34 +02001845 psa_algorithm_t alg);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001846
Gilles Peskinedcd14942018-07-12 00:30:52 +02001847/** Generate an IV for a symmetric encryption operation.
1848 *
1849 * This function generates a random IV (initialization vector), nonce
1850 * or initial counter value for the encryption operation as appropriate
1851 * for the chosen algorithm, key type and key size.
1852 *
1853 * The application must call psa_cipher_encrypt_setup() before
1854 * calling this function.
1855 *
1856 * If this function returns an error status, the operation becomes inactive.
1857 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001858 * \param[in,out] operation Active cipher operation.
1859 * \param[out] iv Buffer where the generated IV is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001860 * \param iv_size Size of the \p iv buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001861 * \param[out] iv_length On success, the number of bytes of the
1862 * generated IV.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001863 *
1864 * \retval #PSA_SUCCESS
1865 * Success.
1866 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001867 * The operation state is not valid (not set up, or IV already set).
Gilles Peskinedcd14942018-07-12 00:30:52 +02001868 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinedda3bd32018-07-12 19:40:46 +02001869 * The size of the \p iv buffer is too small.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001870 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1871 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1872 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001873 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001874 * \retval #PSA_ERROR_BAD_STATE
1875 * The library has not been previously initialized by psa_crypto_init().
1876 * It is implementation-dependent whether a failure to initialize
1877 * results in this error code.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001878 */
Gilles Peskinefe119512018-07-08 21:39:34 +02001879psa_status_t psa_cipher_generate_iv(psa_cipher_operation_t *operation,
Andrew Thoelke47629d02019-03-22 11:24:17 +00001880 uint8_t *iv,
Gilles Peskinefe119512018-07-08 21:39:34 +02001881 size_t iv_size,
1882 size_t *iv_length);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001883
Gilles Peskinedcd14942018-07-12 00:30:52 +02001884/** Set the IV for a symmetric encryption or decryption operation.
1885 *
Gilles Peskinef45adda2019-01-14 18:29:18 +01001886 * This function sets the IV (initialization vector), nonce
Gilles Peskinedcd14942018-07-12 00:30:52 +02001887 * or initial counter value for the encryption or decryption operation.
1888 *
1889 * The application must call psa_cipher_encrypt_setup() before
1890 * calling this function.
1891 *
1892 * If this function returns an error status, the operation becomes inactive.
1893 *
1894 * \note When encrypting, applications should use psa_cipher_generate_iv()
1895 * instead of this function, unless implementing a protocol that requires
1896 * a non-random IV.
1897 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001898 * \param[in,out] operation Active cipher operation.
1899 * \param[in] iv Buffer containing the IV to use.
1900 * \param iv_length Size of the IV in bytes.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001901 *
1902 * \retval #PSA_SUCCESS
1903 * Success.
1904 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001905 * The operation state is not valid (not set up, or IV already set).
Gilles Peskinedcd14942018-07-12 00:30:52 +02001906 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001907 * The size of \p iv is not acceptable for the chosen algorithm,
Gilles Peskinedcd14942018-07-12 00:30:52 +02001908 * or the chosen algorithm does not use an IV.
1909 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1910 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1911 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001912 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001913 * \retval #PSA_ERROR_BAD_STATE
1914 * The library has not been previously initialized by psa_crypto_init().
1915 * It is implementation-dependent whether a failure to initialize
1916 * results in this error code.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001917 */
Gilles Peskinefe119512018-07-08 21:39:34 +02001918psa_status_t psa_cipher_set_iv(psa_cipher_operation_t *operation,
Andrew Thoelke47629d02019-03-22 11:24:17 +00001919 const uint8_t *iv,
Gilles Peskinefe119512018-07-08 21:39:34 +02001920 size_t iv_length);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001921
Gilles Peskinedcd14942018-07-12 00:30:52 +02001922/** Encrypt or decrypt a message fragment in an active cipher operation.
1923 *
Gilles Peskine9ac94262018-07-12 20:15:32 +02001924 * Before calling this function, you must:
1925 * 1. Call either psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup().
1926 * The choice of setup function determines whether this function
1927 * encrypts or decrypts its input.
1928 * 2. If the algorithm requires an IV, call psa_cipher_generate_iv()
1929 * (recommended when encrypting) or psa_cipher_set_iv().
Gilles Peskinedcd14942018-07-12 00:30:52 +02001930 *
1931 * If this function returns an error status, the operation becomes inactive.
1932 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001933 * \param[in,out] operation Active cipher operation.
1934 * \param[in] input Buffer containing the message fragment to
1935 * encrypt or decrypt.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001936 * \param input_length Size of the \p input buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001937 * \param[out] output Buffer where the output is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001938 * \param output_size Size of the \p output buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001939 * \param[out] output_length On success, the number of bytes
1940 * that make up the returned output.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001941 *
1942 * \retval #PSA_SUCCESS
1943 * Success.
1944 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001945 * The operation state is not valid (not set up, IV required but
Gilles Peskinedcd14942018-07-12 00:30:52 +02001946 * not set, or already completed).
1947 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1948 * The size of the \p output buffer is too small.
1949 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1950 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1951 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001952 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001953 * \retval #PSA_ERROR_BAD_STATE
1954 * The library has not been previously initialized by psa_crypto_init().
1955 * It is implementation-dependent whether a failure to initialize
1956 * results in this error code.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001957 */
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001958psa_status_t psa_cipher_update(psa_cipher_operation_t *operation,
1959 const uint8_t *input,
mohammad1603503973b2018-03-12 15:59:30 +02001960 size_t input_length,
Andrew Thoelke47629d02019-03-22 11:24:17 +00001961 uint8_t *output,
Gilles Peskine2d277862018-06-18 15:41:12 +02001962 size_t output_size,
mohammad1603503973b2018-03-12 15:59:30 +02001963 size_t *output_length);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001964
Gilles Peskinedcd14942018-07-12 00:30:52 +02001965/** Finish encrypting or decrypting a message in a cipher operation.
1966 *
1967 * The application must call psa_cipher_encrypt_setup() or
1968 * psa_cipher_decrypt_setup() before calling this function. The choice
1969 * of setup function determines whether this function encrypts or
1970 * decrypts its input.
1971 *
1972 * This function finishes the encryption or decryption of the message
1973 * formed by concatenating the inputs passed to preceding calls to
1974 * psa_cipher_update().
1975 *
1976 * When this function returns, the operation becomes inactive.
1977 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001978 * \param[in,out] operation Active cipher operation.
1979 * \param[out] output Buffer where the output is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001980 * \param output_size Size of the \p output buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001981 * \param[out] output_length On success, the number of bytes
1982 * that make up the returned output.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001983 *
1984 * \retval #PSA_SUCCESS
1985 * Success.
1986 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001987 * The operation state is not valid (not set up, IV required but
Gilles Peskinedcd14942018-07-12 00:30:52 +02001988 * not set, or already completed).
1989 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1990 * The size of the \p output buffer is too small.
1991 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1992 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1993 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001994 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001995 * \retval #PSA_ERROR_BAD_STATE
1996 * The library has not been previously initialized by psa_crypto_init().
1997 * It is implementation-dependent whether a failure to initialize
1998 * results in this error code.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001999 */
Gilles Peskine428dc5a2018-03-03 21:27:18 +01002000psa_status_t psa_cipher_finish(psa_cipher_operation_t *operation,
mohammad1603503973b2018-03-12 15:59:30 +02002001 uint8_t *output,
Moran Peker0071b872018-04-22 20:16:58 +03002002 size_t output_size,
mohammad1603503973b2018-03-12 15:59:30 +02002003 size_t *output_length);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01002004
Gilles Peskinedcd14942018-07-12 00:30:52 +02002005/** Abort a cipher operation.
2006 *
Gilles Peskinedcd14942018-07-12 00:30:52 +02002007 * Aborting an operation frees all associated resources except for the
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02002008 * \p operation structure itself. Once aborted, the operation object
2009 * can be reused for another operation by calling
2010 * psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup() again.
Gilles Peskinedcd14942018-07-12 00:30:52 +02002011 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02002012 * You may call this function any time after the operation object has
2013 * been initialized by any of the following methods:
2014 * - A call to psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup(),
2015 * whether it succeeds or not.
2016 * - Initializing the \c struct to all-bits-zero.
2017 * - Initializing the \c struct to logical zeros, e.g.
2018 * `psa_cipher_operation_t operation = {0}`.
Gilles Peskinedcd14942018-07-12 00:30:52 +02002019 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02002020 * In particular, calling psa_cipher_abort() after the operation has been
2021 * terminated by a call to psa_cipher_abort() or psa_cipher_finish()
2022 * is safe and has no effect.
2023 *
2024 * \param[in,out] operation Initialized cipher operation.
Gilles Peskinedcd14942018-07-12 00:30:52 +02002025 *
2026 * \retval #PSA_SUCCESS
2027 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002028 * \p operation is not an active cipher operation.
Gilles Peskinedcd14942018-07-12 00:30:52 +02002029 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2030 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002031 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01002032 * \retval #PSA_ERROR_BAD_STATE
2033 * The library has not been previously initialized by psa_crypto_init().
2034 * It is implementation-dependent whether a failure to initialize
2035 * results in this error code.
Gilles Peskinedcd14942018-07-12 00:30:52 +02002036 */
Gilles Peskine428dc5a2018-03-03 21:27:18 +01002037psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation);
2038
2039/**@}*/
2040
Gilles Peskine3b555712018-03-03 21:27:57 +01002041/** \defgroup aead Authenticated encryption with associated data (AEAD)
2042 * @{
2043 */
2044
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002045/** Process an authenticated encryption operation.
Gilles Peskine3b555712018-03-03 21:27:57 +01002046 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002047 * \param handle Handle to the key to use for the operation.
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002048 * \param alg The AEAD algorithm to compute
2049 * (\c PSA_ALG_XXX value such that
Gilles Peskine7256e6c2018-07-12 00:34:26 +02002050 * #PSA_ALG_IS_AEAD(\p alg) is true).
Gilles Peskineedd11a12018-07-12 01:08:58 +02002051 * \param[in] nonce Nonce or IV to use.
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002052 * \param nonce_length Size of the \p nonce buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002053 * \param[in] additional_data Additional data that will be authenticated
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002054 * but not encrypted.
2055 * \param additional_data_length Size of \p additional_data in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002056 * \param[in] plaintext Data that will be authenticated and
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002057 * encrypted.
2058 * \param plaintext_length Size of \p plaintext in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002059 * \param[out] ciphertext Output buffer for the authenticated and
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002060 * encrypted data. The additional data is not
2061 * part of this output. For algorithms where the
2062 * encrypted data and the authentication tag
2063 * are defined as separate outputs, the
2064 * authentication tag is appended to the
2065 * encrypted data.
2066 * \param ciphertext_size Size of the \p ciphertext buffer in bytes.
2067 * This must be at least
2068 * #PSA_AEAD_ENCRYPT_OUTPUT_SIZE(\p alg,
2069 * \p plaintext_length).
Gilles Peskineedd11a12018-07-12 01:08:58 +02002070 * \param[out] ciphertext_length On success, the size of the output
Gilles Peskine4c6fdbb2019-02-08 11:22:39 +01002071 * in the \p ciphertext buffer.
Gilles Peskine3b555712018-03-03 21:27:57 +01002072 *
Gilles Peskine28538492018-07-11 17:34:00 +02002073 * \retval #PSA_SUCCESS
Gilles Peskine3b555712018-03-03 21:27:57 +01002074 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01002075 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +02002076 * \retval #PSA_ERROR_NOT_PERMITTED
2077 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002078 * \p handle is not compatible with \p alg.
Gilles Peskine28538492018-07-11 17:34:00 +02002079 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002080 * \p alg is not supported or is not an AEAD algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02002081 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2082 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2083 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002084 * \retval #PSA_ERROR_CORRUPTION_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03002085 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002086 * The library has not been previously initialized by psa_crypto_init().
2087 * It is implementation-dependent whether a failure to initialize
2088 * results in this error code.
Gilles Peskine3b555712018-03-03 21:27:57 +01002089 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002090psa_status_t psa_aead_encrypt(psa_key_handle_t handle,
Gilles Peskine9fb0e012018-07-19 15:51:49 +02002091 psa_algorithm_t alg,
2092 const uint8_t *nonce,
2093 size_t nonce_length,
2094 const uint8_t *additional_data,
2095 size_t additional_data_length,
2096 const uint8_t *plaintext,
2097 size_t plaintext_length,
2098 uint8_t *ciphertext,
2099 size_t ciphertext_size,
2100 size_t *ciphertext_length);
Gilles Peskine3b555712018-03-03 21:27:57 +01002101
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002102/** Process an authenticated decryption operation.
Gilles Peskine3b555712018-03-03 21:27:57 +01002103 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002104 * \param handle Handle to the key to use for the operation.
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002105 * \param alg The AEAD algorithm to compute
2106 * (\c PSA_ALG_XXX value such that
Gilles Peskine7256e6c2018-07-12 00:34:26 +02002107 * #PSA_ALG_IS_AEAD(\p alg) is true).
Gilles Peskineedd11a12018-07-12 01:08:58 +02002108 * \param[in] nonce Nonce or IV to use.
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002109 * \param nonce_length Size of the \p nonce buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002110 * \param[in] additional_data Additional data that has been authenticated
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002111 * but not encrypted.
2112 * \param additional_data_length Size of \p additional_data in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002113 * \param[in] ciphertext Data that has been authenticated and
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002114 * encrypted. For algorithms where the
2115 * encrypted data and the authentication tag
2116 * are defined as separate inputs, the buffer
2117 * must contain the encrypted data followed
2118 * by the authentication tag.
2119 * \param ciphertext_length Size of \p ciphertext in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002120 * \param[out] plaintext Output buffer for the decrypted data.
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002121 * \param plaintext_size Size of the \p plaintext buffer in bytes.
2122 * This must be at least
2123 * #PSA_AEAD_DECRYPT_OUTPUT_SIZE(\p alg,
2124 * \p ciphertext_length).
Gilles Peskineedd11a12018-07-12 01:08:58 +02002125 * \param[out] plaintext_length On success, the size of the output
Gilles Peskine4c6fdbb2019-02-08 11:22:39 +01002126 * in the \p plaintext buffer.
Gilles Peskine3b555712018-03-03 21:27:57 +01002127 *
Gilles Peskine28538492018-07-11 17:34:00 +02002128 * \retval #PSA_SUCCESS
Gilles Peskine3b555712018-03-03 21:27:57 +01002129 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01002130 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +02002131 * \retval #PSA_ERROR_INVALID_SIGNATURE
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002132 * The ciphertext is not authentic.
Gilles Peskine28538492018-07-11 17:34:00 +02002133 * \retval #PSA_ERROR_NOT_PERMITTED
2134 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002135 * \p handle is not compatible with \p alg.
Gilles Peskine28538492018-07-11 17:34:00 +02002136 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002137 * \p alg is not supported or is not an AEAD algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02002138 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
Adrian L. Shawc207ba32019-08-08 10:55:38 +01002139 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2140 * \p plaintext_size or \p nonce_length is too small
Gilles Peskine28538492018-07-11 17:34:00 +02002141 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2142 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002143 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawc207ba32019-08-08 10:55:38 +01002144 * \retval #PSA_ERROR_STORAGE_FAILURE
itayzafrir90d8c7a2018-09-12 11:44:52 +03002145 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002146 * The library has not been previously initialized by psa_crypto_init().
2147 * It is implementation-dependent whether a failure to initialize
2148 * results in this error code.
Gilles Peskine3b555712018-03-03 21:27:57 +01002149 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002150psa_status_t psa_aead_decrypt(psa_key_handle_t handle,
Gilles Peskine9fb0e012018-07-19 15:51:49 +02002151 psa_algorithm_t alg,
2152 const uint8_t *nonce,
2153 size_t nonce_length,
2154 const uint8_t *additional_data,
2155 size_t additional_data_length,
2156 const uint8_t *ciphertext,
2157 size_t ciphertext_length,
2158 uint8_t *plaintext,
2159 size_t plaintext_size,
2160 size_t *plaintext_length);
Gilles Peskine3b555712018-03-03 21:27:57 +01002161
Gilles Peskine30a9e412019-01-14 18:36:12 +01002162/** The type of the state data structure for multipart AEAD operations.
2163 *
2164 * Before calling any function on an AEAD operation object, the application
2165 * must initialize it by any of the following means:
2166 * - Set the structure to all-bits-zero, for example:
2167 * \code
2168 * psa_aead_operation_t operation;
2169 * memset(&operation, 0, sizeof(operation));
2170 * \endcode
2171 * - Initialize the structure to logical zero values, for example:
2172 * \code
2173 * psa_aead_operation_t operation = {0};
2174 * \endcode
2175 * - Initialize the structure to the initializer #PSA_AEAD_OPERATION_INIT,
2176 * for example:
2177 * \code
2178 * psa_aead_operation_t operation = PSA_AEAD_OPERATION_INIT;
2179 * \endcode
2180 * - Assign the result of the function psa_aead_operation_init()
2181 * to the structure, for example:
2182 * \code
2183 * psa_aead_operation_t operation;
2184 * operation = psa_aead_operation_init();
2185 * \endcode
2186 *
2187 * This is an implementation-defined \c struct. Applications should not
2188 * make any assumptions about the content of this structure except
2189 * as directed by the documentation of a specific implementation. */
2190typedef struct psa_aead_operation_s psa_aead_operation_t;
2191
2192/** \def PSA_AEAD_OPERATION_INIT
2193 *
2194 * This macro returns a suitable initializer for an AEAD operation object of
2195 * type #psa_aead_operation_t.
2196 */
2197#ifdef __DOXYGEN_ONLY__
2198/* This is an example definition for documentation purposes.
2199 * Implementations should define a suitable value in `crypto_struct.h`.
2200 */
2201#define PSA_AEAD_OPERATION_INIT {0}
2202#endif
2203
2204/** Return an initial value for an AEAD operation object.
2205 */
2206static psa_aead_operation_t psa_aead_operation_init(void);
2207
2208/** Set the key for a multipart authenticated encryption operation.
2209 *
2210 * The sequence of operations to encrypt a message with authentication
2211 * is as follows:
2212 * -# Allocate an operation object which will be passed to all the functions
2213 * listed here.
2214 * -# Initialize the operation object with one of the methods described in the
2215 * documentation for #psa_aead_operation_t, e.g.
2216 * PSA_AEAD_OPERATION_INIT.
2217 * -# Call psa_aead_encrypt_setup() to specify the algorithm and key.
Gilles Peskinebc59c852019-01-17 15:26:08 +01002218 * -# If needed, call psa_aead_set_lengths() to specify the length of the
2219 * inputs to the subsequent calls to psa_aead_update_ad() and
2220 * psa_aead_update(). See the documentation of psa_aead_set_lengths()
2221 * for details.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002222 * -# Call either psa_aead_generate_nonce() or psa_aead_set_nonce() to
2223 * generate or set the nonce. You should use
2224 * psa_aead_generate_nonce() unless the protocol you are implementing
2225 * requires a specific nonce value.
2226 * -# Call psa_aead_update_ad() zero, one or more times, passing a fragment
2227 * of the non-encrypted additional authenticated data each time.
2228 * -# Call psa_aead_update() zero, one or more times, passing a fragment
Gilles Peskinea05602d2019-01-17 15:25:52 +01002229 * of the message to encrypt each time.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002230 * -# Call psa_aead_finish().
2231 *
2232 * The application may call psa_aead_abort() at any time after the operation
2233 * has been initialized.
2234 *
2235 * After a successful call to psa_aead_encrypt_setup(), the application must
2236 * eventually terminate the operation. The following events terminate an
2237 * operation:
2238 * - A failed call to any of the \c psa_aead_xxx functions.
2239 * - A call to psa_aead_finish(), psa_aead_verify() or psa_aead_abort().
2240 *
2241 * \param[in,out] operation The operation object to set up. It must have
2242 * been initialized as per the documentation for
2243 * #psa_aead_operation_t and not yet in use.
2244 * \param handle Handle to the key to use for the operation.
2245 * It must remain valid until the operation
2246 * terminates.
2247 * \param alg The AEAD algorithm to compute
2248 * (\c PSA_ALG_XXX value such that
2249 * #PSA_ALG_IS_AEAD(\p alg) is true).
2250 *
2251 * \retval #PSA_SUCCESS
2252 * Success.
2253 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine30a9e412019-01-14 18:36:12 +01002254 * \retval #PSA_ERROR_NOT_PERMITTED
2255 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002256 * \p handle is not compatible with \p alg.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002257 * \retval #PSA_ERROR_NOT_SUPPORTED
2258 * \p alg is not supported or is not an AEAD algorithm.
2259 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2260 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2261 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002262 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw3e412492019-08-08 15:10:33 +01002263 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine30a9e412019-01-14 18:36:12 +01002264 * \retval #PSA_ERROR_BAD_STATE
2265 * The library has not been previously initialized by psa_crypto_init().
2266 * It is implementation-dependent whether a failure to initialize
2267 * results in this error code.
2268 */
2269psa_status_t psa_aead_encrypt_setup(psa_aead_operation_t *operation,
2270 psa_key_handle_t handle,
2271 psa_algorithm_t alg);
2272
2273/** Set the key for a multipart authenticated decryption operation.
2274 *
2275 * The sequence of operations to decrypt a message with authentication
2276 * is as follows:
2277 * -# Allocate an operation object which will be passed to all the functions
2278 * listed here.
2279 * -# Initialize the operation object with one of the methods described in the
2280 * documentation for #psa_aead_operation_t, e.g.
2281 * PSA_AEAD_OPERATION_INIT.
2282 * -# Call psa_aead_decrypt_setup() to specify the algorithm and key.
Gilles Peskinebc59c852019-01-17 15:26:08 +01002283 * -# If needed, call psa_aead_set_lengths() to specify the length of the
2284 * inputs to the subsequent calls to psa_aead_update_ad() and
2285 * psa_aead_update(). See the documentation of psa_aead_set_lengths()
2286 * for details.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002287 * -# Call psa_aead_set_nonce() with the nonce for the decryption.
2288 * -# Call psa_aead_update_ad() zero, one or more times, passing a fragment
2289 * of the non-encrypted additional authenticated data each time.
2290 * -# Call psa_aead_update() zero, one or more times, passing a fragment
Gilles Peskinea05602d2019-01-17 15:25:52 +01002291 * of the ciphertext to decrypt each time.
2292 * -# Call psa_aead_verify().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002293 *
2294 * The application may call psa_aead_abort() at any time after the operation
2295 * has been initialized.
2296 *
2297 * After a successful call to psa_aead_decrypt_setup(), the application must
2298 * eventually terminate the operation. The following events terminate an
2299 * operation:
2300 * - A failed call to any of the \c psa_aead_xxx functions.
2301 * - A call to psa_aead_finish(), psa_aead_verify() or psa_aead_abort().
2302 *
2303 * \param[in,out] operation The operation object to set up. It must have
2304 * been initialized as per the documentation for
2305 * #psa_aead_operation_t and not yet in use.
2306 * \param handle Handle to the key to use for the operation.
2307 * It must remain valid until the operation
2308 * terminates.
2309 * \param alg The AEAD algorithm to compute
2310 * (\c PSA_ALG_XXX value such that
2311 * #PSA_ALG_IS_AEAD(\p alg) is true).
2312 *
2313 * \retval #PSA_SUCCESS
2314 * Success.
2315 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine30a9e412019-01-14 18:36:12 +01002316 * \retval #PSA_ERROR_NOT_PERMITTED
2317 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002318 * \p handle is not compatible with \p alg.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002319 * \retval #PSA_ERROR_NOT_SUPPORTED
2320 * \p alg is not supported or is not an AEAD algorithm.
2321 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2322 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2323 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002324 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw3e412492019-08-08 15:10:33 +01002325 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine30a9e412019-01-14 18:36:12 +01002326 * \retval #PSA_ERROR_BAD_STATE
2327 * The library has not been previously initialized by psa_crypto_init().
2328 * It is implementation-dependent whether a failure to initialize
2329 * results in this error code.
2330 */
2331psa_status_t psa_aead_decrypt_setup(psa_aead_operation_t *operation,
2332 psa_key_handle_t handle,
2333 psa_algorithm_t alg);
2334
2335/** Generate a random nonce for an authenticated encryption operation.
2336 *
2337 * This function generates a random nonce for the authenticated encryption
2338 * operation with an appropriate size for the chosen algorithm, key type
2339 * and key size.
2340 *
2341 * The application must call psa_aead_encrypt_setup() before
2342 * calling this function.
2343 *
2344 * If this function returns an error status, the operation becomes inactive.
2345 *
2346 * \param[in,out] operation Active AEAD operation.
2347 * \param[out] nonce Buffer where the generated nonce is to be
2348 * written.
2349 * \param nonce_size Size of the \p nonce buffer in bytes.
2350 * \param[out] nonce_length On success, the number of bytes of the
2351 * generated nonce.
2352 *
2353 * \retval #PSA_SUCCESS
2354 * Success.
2355 * \retval #PSA_ERROR_BAD_STATE
2356 * The operation state is not valid (not set up, or nonce already set).
2357 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2358 * The size of the \p nonce buffer is too small.
2359 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2360 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2361 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002362 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01002363 * \retval #PSA_ERROR_BAD_STATE
2364 * The library has not been previously initialized by psa_crypto_init().
2365 * It is implementation-dependent whether a failure to initialize
2366 * results in this error code.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002367 */
2368psa_status_t psa_aead_generate_nonce(psa_aead_operation_t *operation,
Andrew Thoelked16bdac2019-05-15 12:34:01 +01002369 uint8_t *nonce,
Gilles Peskine30a9e412019-01-14 18:36:12 +01002370 size_t nonce_size,
2371 size_t *nonce_length);
2372
2373/** Set the nonce for an authenticated encryption or decryption operation.
2374 *
2375 * This function sets the nonce for the authenticated
2376 * encryption or decryption operation.
2377 *
2378 * The application must call psa_aead_encrypt_setup() before
2379 * calling this function.
2380 *
2381 * If this function returns an error status, the operation becomes inactive.
2382 *
Gilles Peskinea05602d2019-01-17 15:25:52 +01002383 * \note When encrypting, applications should use psa_aead_generate_nonce()
Gilles Peskine30a9e412019-01-14 18:36:12 +01002384 * instead of this function, unless implementing a protocol that requires
2385 * a non-random IV.
2386 *
2387 * \param[in,out] operation Active AEAD operation.
Gilles Peskinea05602d2019-01-17 15:25:52 +01002388 * \param[in] nonce Buffer containing the nonce to use.
2389 * \param nonce_length Size of the nonce in bytes.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002390 *
2391 * \retval #PSA_SUCCESS
2392 * Success.
2393 * \retval #PSA_ERROR_BAD_STATE
2394 * The operation state is not valid (not set up, or nonce already set).
2395 * \retval #PSA_ERROR_INVALID_ARGUMENT
2396 * The size of \p nonce is not acceptable for the chosen algorithm.
2397 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2398 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2399 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002400 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01002401 * \retval #PSA_ERROR_BAD_STATE
2402 * The library has not been previously initialized by psa_crypto_init().
2403 * It is implementation-dependent whether a failure to initialize
2404 * results in this error code.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002405 */
2406psa_status_t psa_aead_set_nonce(psa_aead_operation_t *operation,
Andrew Thoelked16bdac2019-05-15 12:34:01 +01002407 const uint8_t *nonce,
Gilles Peskine30a9e412019-01-14 18:36:12 +01002408 size_t nonce_length);
2409
Gilles Peskinebc59c852019-01-17 15:26:08 +01002410/** Declare the lengths of the message and additional data for AEAD.
2411 *
2412 * The application must call this function before calling
2413 * psa_aead_update_ad() or psa_aead_update() if the algorithm for
2414 * the operation requires it. If the algorithm does not require it,
2415 * calling this function is optional, but if this function is called
2416 * then the implementation must enforce the lengths.
2417 *
2418 * You may call this function before or after setting the nonce with
2419 * psa_aead_set_nonce() or psa_aead_generate_nonce().
2420 *
2421 * - For #PSA_ALG_CCM, calling this function is required.
2422 * - For the other AEAD algorithms defined in this specification, calling
2423 * this function is not required.
2424 * - For vendor-defined algorithm, refer to the vendor documentation.
2425 *
2426 * \param[in,out] operation Active AEAD operation.
2427 * \param ad_length Size of the non-encrypted additional
2428 * authenticated data in bytes.
2429 * \param plaintext_length Size of the plaintext to encrypt in bytes.
2430 *
2431 * \retval #PSA_SUCCESS
2432 * Success.
2433 * \retval #PSA_ERROR_BAD_STATE
2434 * The operation state is not valid (not set up, already completed,
2435 * or psa_aead_update_ad() or psa_aead_update() already called).
2436 * \retval #PSA_ERROR_INVALID_ARGUMENT
2437 * At least one of the lengths is not acceptable for the chosen
2438 * algorithm.
2439 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2440 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2441 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002442 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01002443 * \retval #PSA_ERROR_BAD_STATE
2444 * The library has not been previously initialized by psa_crypto_init().
2445 * It is implementation-dependent whether a failure to initialize
2446 * results in this error code.
Gilles Peskinebc59c852019-01-17 15:26:08 +01002447 */
2448psa_status_t psa_aead_set_lengths(psa_aead_operation_t *operation,
2449 size_t ad_length,
2450 size_t plaintext_length);
2451
Gilles Peskine30a9e412019-01-14 18:36:12 +01002452/** Pass additional data to an active AEAD operation.
2453 *
2454 * Additional data is authenticated, but not encrypted.
2455 *
2456 * You may call this function multiple times to pass successive fragments
2457 * of the additional data. You may not call this function after passing
2458 * data to encrypt or decrypt with psa_aead_update().
2459 *
2460 * Before calling this function, you must:
2461 * 1. Call either psa_aead_encrypt_setup() or psa_aead_decrypt_setup().
2462 * 2. Set the nonce with psa_aead_generate_nonce() or psa_aead_set_nonce().
2463 *
2464 * If this function returns an error status, the operation becomes inactive.
2465 *
2466 * \warning When decrypting, until psa_aead_verify() has returned #PSA_SUCCESS,
2467 * there is no guarantee that the input is valid. Therefore, until
2468 * you have called psa_aead_verify() and it has returned #PSA_SUCCESS,
2469 * treat the input as untrusted and prepare to undo any action that
2470 * depends on the input if psa_aead_verify() returns an error status.
2471 *
2472 * \param[in,out] operation Active AEAD operation.
2473 * \param[in] input Buffer containing the fragment of
2474 * additional data.
2475 * \param input_length Size of the \p input buffer in bytes.
2476 *
2477 * \retval #PSA_SUCCESS
2478 * Success.
2479 * \retval #PSA_ERROR_BAD_STATE
2480 * The operation state is not valid (not set up, nonce not set,
2481 * psa_aead_update() already called, or operation already completed).
Gilles Peskinebc59c852019-01-17 15:26:08 +01002482 * \retval #PSA_ERROR_INVALID_ARGUMENT
2483 * The total input length overflows the additional data length that
2484 * was previously specified with psa_aead_set_lengths().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002485 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2486 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2487 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002488 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01002489 * \retval #PSA_ERROR_BAD_STATE
2490 * The library has not been previously initialized by psa_crypto_init().
2491 * It is implementation-dependent whether a failure to initialize
2492 * results in this error code.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002493 */
2494psa_status_t psa_aead_update_ad(psa_aead_operation_t *operation,
2495 const uint8_t *input,
2496 size_t input_length);
2497
2498/** Encrypt or decrypt a message fragment in an active AEAD operation.
2499 *
2500 * Before calling this function, you must:
2501 * 1. Call either psa_aead_encrypt_setup() or psa_aead_decrypt_setup().
2502 * The choice of setup function determines whether this function
2503 * encrypts or decrypts its input.
2504 * 2. Set the nonce with psa_aead_generate_nonce() or psa_aead_set_nonce().
2505 * 3. Call psa_aead_update_ad() to pass all the additional data.
2506 *
2507 * If this function returns an error status, the operation becomes inactive.
2508 *
2509 * \warning When decrypting, until psa_aead_verify() has returned #PSA_SUCCESS,
2510 * there is no guarantee that the input is valid. Therefore, until
2511 * you have called psa_aead_verify() and it has returned #PSA_SUCCESS:
2512 * - Do not use the output in any way other than storing it in a
2513 * confidential location. If you take any action that depends
2514 * on the tentative decrypted data, this action will need to be
2515 * undone if the input turns out not to be valid. Furthermore,
2516 * if an adversary can observe that this action took place
2517 * (for example through timing), they may be able to use this
2518 * fact as an oracle to decrypt any message encrypted with the
2519 * same key.
2520 * - In particular, do not copy the output anywhere but to a
2521 * memory or storage space that you have exclusive access to.
2522 *
Gilles Peskinef02aec92019-05-06 15:42:54 +02002523 * This function does not require the input to be aligned to any
2524 * particular block boundary. If the implementation can only process
Gilles Peskineac99e322019-05-14 16:10:53 +02002525 * a whole block at a time, it must consume all the input provided, but
2526 * it may delay the end of the corresponding output until a subsequent
2527 * call to psa_aead_update(), psa_aead_finish() or psa_aead_verify()
2528 * provides sufficient input. The amount of data that can be delayed
2529 * in this way is bounded by #PSA_AEAD_UPDATE_OUTPUT_SIZE.
Gilles Peskinef02aec92019-05-06 15:42:54 +02002530 *
Gilles Peskine30a9e412019-01-14 18:36:12 +01002531 * \param[in,out] operation Active AEAD operation.
2532 * \param[in] input Buffer containing the message fragment to
2533 * encrypt or decrypt.
2534 * \param input_length Size of the \p input buffer in bytes.
2535 * \param[out] output Buffer where the output is to be written.
2536 * \param output_size Size of the \p output buffer in bytes.
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002537 * This must be at least
2538 * #PSA_AEAD_UPDATE_OUTPUT_SIZE(\c alg,
2539 * \p input_length) where \c alg is the
2540 * algorithm that is being calculated.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002541 * \param[out] output_length On success, the number of bytes
2542 * that make up the returned output.
2543 *
2544 * \retval #PSA_SUCCESS
2545 * Success.
2546 * \retval #PSA_ERROR_BAD_STATE
2547 * The operation state is not valid (not set up, nonce not set
2548 * or already completed).
2549 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2550 * The size of the \p output buffer is too small.
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002551 * You can determine a sufficient buffer size by calling
2552 * #PSA_AEAD_UPDATE_OUTPUT_SIZE(\c alg, \p input_length)
2553 * where \c alg is the algorithm that is being calculated.
Gilles Peskinebc59c852019-01-17 15:26:08 +01002554 * \retval #PSA_ERROR_INVALID_ARGUMENT
2555 * The total length of input to psa_aead_update_ad() so far is
2556 * less than the additional data length that was previously
2557 * specified with psa_aead_set_lengths().
2558 * \retval #PSA_ERROR_INVALID_ARGUMENT
2559 * The total input length overflows the plaintext length that
2560 * was previously specified with psa_aead_set_lengths().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002561 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2562 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2563 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002564 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01002565 * \retval #PSA_ERROR_BAD_STATE
2566 * The library has not been previously initialized by psa_crypto_init().
2567 * It is implementation-dependent whether a failure to initialize
2568 * results in this error code.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002569 */
2570psa_status_t psa_aead_update(psa_aead_operation_t *operation,
2571 const uint8_t *input,
2572 size_t input_length,
Andrew Thoelked16bdac2019-05-15 12:34:01 +01002573 uint8_t *output,
Gilles Peskine30a9e412019-01-14 18:36:12 +01002574 size_t output_size,
2575 size_t *output_length);
2576
2577/** Finish encrypting a message in an AEAD operation.
2578 *
2579 * The operation must have been set up with psa_aead_encrypt_setup().
2580 *
2581 * This function finishes the authentication of the additional data
2582 * formed by concatenating the inputs passed to preceding calls to
2583 * psa_aead_update_ad() with the plaintext formed by concatenating the
2584 * inputs passed to preceding calls to psa_aead_update().
2585 *
2586 * This function has two output buffers:
2587 * - \p ciphertext contains trailing ciphertext that was buffered from
Gilles Peskinef02aec92019-05-06 15:42:54 +02002588 * preceding calls to psa_aead_update().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002589 * - \p tag contains the authentication tag. Its length is always
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002590 * #PSA_AEAD_TAG_LENGTH(\c alg) where \c alg is the AEAD algorithm
Gilles Peskine30a9e412019-01-14 18:36:12 +01002591 * that the operation performs.
2592 *
2593 * When this function returns, the operation becomes inactive.
2594 *
2595 * \param[in,out] operation Active AEAD operation.
2596 * \param[out] ciphertext Buffer where the last part of the ciphertext
2597 * is to be written.
2598 * \param ciphertext_size Size of the \p ciphertext buffer in bytes.
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002599 * This must be at least
2600 * #PSA_AEAD_FINISH_OUTPUT_SIZE(\c alg) where
2601 * \c alg is the algorithm that is being
2602 * calculated.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002603 * \param[out] ciphertext_length On success, the number of bytes of
2604 * returned ciphertext.
2605 * \param[out] tag Buffer where the authentication tag is
2606 * to be written.
2607 * \param tag_size Size of the \p tag buffer in bytes.
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002608 * This must be at least
2609 * #PSA_AEAD_TAG_LENGTH(\c alg) where \c alg is
2610 * the algorithm that is being calculated.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002611 * \param[out] tag_length On success, the number of bytes
2612 * that make up the returned tag.
2613 *
2614 * \retval #PSA_SUCCESS
2615 * Success.
2616 * \retval #PSA_ERROR_BAD_STATE
2617 * The operation state is not valid (not set up, nonce not set,
2618 * decryption, or already completed).
2619 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002620 * The size of the \p ciphertext or \p tag buffer is too small.
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002621 * You can determine a sufficient buffer size for \p ciphertext by
2622 * calling #PSA_AEAD_FINISH_OUTPUT_SIZE(\c alg)
2623 * where \c alg is the algorithm that is being calculated.
2624 * You can determine a sufficient buffer size for \p tag by
2625 * calling #PSA_AEAD_TAG_LENGTH(\c alg).
Gilles Peskinebc59c852019-01-17 15:26:08 +01002626 * \retval #PSA_ERROR_INVALID_ARGUMENT
2627 * The total length of input to psa_aead_update_ad() so far is
2628 * less than the additional data length that was previously
2629 * specified with psa_aead_set_lengths().
2630 * \retval #PSA_ERROR_INVALID_ARGUMENT
2631 * The total length of input to psa_aead_update() so far is
2632 * less than the plaintext length that was previously
2633 * specified with psa_aead_set_lengths().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002634 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2635 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2636 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002637 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01002638 * \retval #PSA_ERROR_BAD_STATE
2639 * The library has not been previously initialized by psa_crypto_init().
2640 * It is implementation-dependent whether a failure to initialize
2641 * results in this error code.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002642 */
2643psa_status_t psa_aead_finish(psa_aead_operation_t *operation,
Gilles Peskinea05602d2019-01-17 15:25:52 +01002644 uint8_t *ciphertext,
2645 size_t ciphertext_size,
2646 size_t *ciphertext_length,
Gilles Peskine30a9e412019-01-14 18:36:12 +01002647 uint8_t *tag,
2648 size_t tag_size,
2649 size_t *tag_length);
2650
2651/** Finish authenticating and decrypting a message in an AEAD operation.
2652 *
2653 * The operation must have been set up with psa_aead_decrypt_setup().
2654 *
2655 * This function finishes the authentication of the additional data
2656 * formed by concatenating the inputs passed to preceding calls to
2657 * psa_aead_update_ad() with the ciphertext formed by concatenating the
2658 * inputs passed to preceding calls to psa_aead_update().
2659 *
2660 * When this function returns, the operation becomes inactive.
2661 *
2662 * \param[in,out] operation Active AEAD operation.
Gilles Peskine5211efb2019-05-06 15:56:05 +02002663 * \param[out] plaintext Buffer where the last part of the plaintext
Gilles Peskineac99e322019-05-14 16:10:53 +02002664 * is to be written. This is the remaining data
Gilles Peskine5211efb2019-05-06 15:56:05 +02002665 * from previous calls to psa_aead_update()
2666 * that could not be processed until the end
2667 * of the input.
2668 * \param plaintext_size Size of the \p plaintext buffer in bytes.
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002669 * This must be at least
2670 * #PSA_AEAD_VERIFY_OUTPUT_SIZE(\c alg) where
2671 * \c alg is the algorithm that is being
2672 * calculated.
Gilles Peskine5211efb2019-05-06 15:56:05 +02002673 * \param[out] plaintext_length On success, the number of bytes of
2674 * returned plaintext.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002675 * \param[in] tag Buffer containing the authentication tag.
2676 * \param tag_length Size of the \p tag buffer in bytes.
2677 *
2678 * \retval #PSA_SUCCESS
2679 * Success.
2680 * \retval #PSA_ERROR_BAD_STATE
2681 * The operation state is not valid (not set up, nonce not set,
2682 * encryption, or already completed).
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002683 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2684 * The size of the \p plaintext buffer is too small.
2685 * You can determine a sufficient buffer size for \p plaintext by
2686 * calling #PSA_AEAD_VERIFY_OUTPUT_SIZE(\c alg)
2687 * where \c alg is the algorithm that is being calculated.
Gilles Peskinebc59c852019-01-17 15:26:08 +01002688 * \retval #PSA_ERROR_INVALID_ARGUMENT
2689 * The total length of input to psa_aead_update_ad() so far is
2690 * less than the additional data length that was previously
2691 * specified with psa_aead_set_lengths().
2692 * \retval #PSA_ERROR_INVALID_ARGUMENT
2693 * The total length of input to psa_aead_update() so far is
2694 * less than the plaintext length that was previously
2695 * specified with psa_aead_set_lengths().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002696 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2697 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2698 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002699 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01002700 * \retval #PSA_ERROR_BAD_STATE
2701 * The library has not been previously initialized by psa_crypto_init().
2702 * It is implementation-dependent whether a failure to initialize
2703 * results in this error code.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002704 */
2705psa_status_t psa_aead_verify(psa_aead_operation_t *operation,
Gilles Peskine5211efb2019-05-06 15:56:05 +02002706 uint8_t *plaintext,
2707 size_t plaintext_size,
2708 size_t *plaintext_length,
Gilles Peskine30a9e412019-01-14 18:36:12 +01002709 const uint8_t *tag,
2710 size_t tag_length);
2711
2712/** Abort an AEAD operation.
2713 *
2714 * Aborting an operation frees all associated resources except for the
2715 * \p operation structure itself. Once aborted, the operation object
2716 * can be reused for another operation by calling
2717 * psa_aead_encrypt_setup() or psa_aead_decrypt_setup() again.
2718 *
2719 * You may call this function any time after the operation object has
2720 * been initialized by any of the following methods:
2721 * - A call to psa_aead_encrypt_setup() or psa_aead_decrypt_setup(),
2722 * whether it succeeds or not.
2723 * - Initializing the \c struct to all-bits-zero.
2724 * - Initializing the \c struct to logical zeros, e.g.
2725 * `psa_aead_operation_t operation = {0}`.
2726 *
2727 * In particular, calling psa_aead_abort() after the operation has been
2728 * terminated by a call to psa_aead_abort() or psa_aead_finish()
2729 * is safe and has no effect.
2730 *
2731 * \param[in,out] operation Initialized AEAD operation.
2732 *
2733 * \retval #PSA_SUCCESS
2734 * \retval #PSA_ERROR_BAD_STATE
2735 * \p operation is not an active AEAD operation.
2736 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2737 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002738 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01002739 * \retval #PSA_ERROR_BAD_STATE
2740 * The library has not been previously initialized by psa_crypto_init().
2741 * It is implementation-dependent whether a failure to initialize
2742 * results in this error code.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002743 */
2744psa_status_t psa_aead_abort(psa_aead_operation_t *operation);
2745
Gilles Peskine3b555712018-03-03 21:27:57 +01002746/**@}*/
2747
Gilles Peskine20035e32018-02-03 22:44:14 +01002748/** \defgroup asymmetric Asymmetric cryptography
2749 * @{
2750 */
2751
2752/**
2753 * \brief Sign a hash or short message with a private key.
2754 *
Gilles Peskine08bac712018-06-26 16:14:46 +02002755 * Note that to perform a hash-and-sign signature algorithm, you must
Gilles Peskineda8191d1c2018-07-08 19:46:38 +02002756 * first calculate the hash by calling psa_hash_setup(), psa_hash_update()
Gilles Peskine08bac712018-06-26 16:14:46 +02002757 * and psa_hash_finish(). Then pass the resulting hash as the \p hash
2758 * parameter to this function. You can use #PSA_ALG_SIGN_GET_HASH(\p alg)
2759 * to determine the hash algorithm to use.
2760 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002761 * \param handle Handle to the key to use for the operation.
2762 * It must be an asymmetric key pair.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002763 * \param alg A signature algorithm that is compatible with
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002764 * the type of \p handle.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002765 * \param[in] hash The hash or message to sign.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002766 * \param hash_length Size of the \p hash buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002767 * \param[out] signature Buffer where the signature is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002768 * \param signature_size Size of the \p signature buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002769 * \param[out] signature_length On success, the number of bytes
2770 * that make up the returned signature value.
Gilles Peskine308b91d2018-02-08 09:47:44 +01002771 *
Gilles Peskine28538492018-07-11 17:34:00 +02002772 * \retval #PSA_SUCCESS
Adrian L. Shaw27c12152019-08-08 11:10:32 +01002773 * \retval #PSA_ERROR_INVALID_HANDLE
2774 * \retval #PSA_ERROR_NOT_PERMITTED
Gilles Peskine28538492018-07-11 17:34:00 +02002775 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002776 * The size of the \p signature buffer is too small. You can
Gilles Peskine308b91d2018-02-08 09:47:44 +01002777 * determine a sufficient buffer size by calling
Gilles Peskine7256e6c2018-07-12 00:34:26 +02002778 * #PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
Gilles Peskine308b91d2018-02-08 09:47:44 +01002779 * where \c key_type and \c key_bits are the type and bit-size
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002780 * respectively of \p handle.
Gilles Peskine28538492018-07-11 17:34:00 +02002781 * \retval #PSA_ERROR_NOT_SUPPORTED
2782 * \retval #PSA_ERROR_INVALID_ARGUMENT
2783 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2784 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2785 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002786 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw27c12152019-08-08 11:10:32 +01002787 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine28538492018-07-11 17:34:00 +02002788 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
itayzafrir90d8c7a2018-09-12 11:44:52 +03002789 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002790 * The library has not been previously initialized by psa_crypto_init().
2791 * It is implementation-dependent whether a failure to initialize
2792 * results in this error code.
Gilles Peskine20035e32018-02-03 22:44:14 +01002793 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002794psa_status_t psa_asymmetric_sign(psa_key_handle_t handle,
Gilles Peskine20035e32018-02-03 22:44:14 +01002795 psa_algorithm_t alg,
2796 const uint8_t *hash,
2797 size_t hash_length,
Gilles Peskine20035e32018-02-03 22:44:14 +01002798 uint8_t *signature,
2799 size_t signature_size,
2800 size_t *signature_length);
2801
2802/**
2803 * \brief Verify the signature a hash or short message using a public key.
2804 *
Gilles Peskine08bac712018-06-26 16:14:46 +02002805 * Note that to perform a hash-and-sign signature algorithm, you must
Gilles Peskineda8191d1c2018-07-08 19:46:38 +02002806 * first calculate the hash by calling psa_hash_setup(), psa_hash_update()
Gilles Peskine08bac712018-06-26 16:14:46 +02002807 * and psa_hash_finish(). Then pass the resulting hash as the \p hash
2808 * parameter to this function. You can use #PSA_ALG_SIGN_GET_HASH(\p alg)
2809 * to determine the hash algorithm to use.
2810 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002811 * \param handle Handle to the key to use for the operation.
2812 * It must be a public key or an asymmetric key pair.
Gilles Peskine308b91d2018-02-08 09:47:44 +01002813 * \param alg A signature algorithm that is compatible with
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002814 * the type of \p handle.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002815 * \param[in] hash The hash or message whose signature is to be
Gilles Peskine08bac712018-06-26 16:14:46 +02002816 * verified.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002817 * \param hash_length Size of the \p hash buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002818 * \param[in] signature Buffer containing the signature to verify.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002819 * \param signature_length Size of the \p signature buffer in bytes.
Gilles Peskine308b91d2018-02-08 09:47:44 +01002820 *
Gilles Peskine28538492018-07-11 17:34:00 +02002821 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +01002822 * The signature is valid.
Adrian L. Shaw6e758c92019-08-08 11:11:43 +01002823 * \retval #PSA_ERROR_INVALID_HANDLE
2824 * \retval #PSA_ERROR_NOT_PERMITTED
Gilles Peskine28538492018-07-11 17:34:00 +02002825 * \retval #PSA_ERROR_INVALID_SIGNATURE
Gilles Peskine308b91d2018-02-08 09:47:44 +01002826 * The calculation was perfomed successfully, but the passed
2827 * signature is not a valid signature.
Gilles Peskine28538492018-07-11 17:34:00 +02002828 * \retval #PSA_ERROR_NOT_SUPPORTED
2829 * \retval #PSA_ERROR_INVALID_ARGUMENT
2830 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2831 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2832 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002833 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw6e758c92019-08-08 11:11:43 +01002834 * \retval #PSA_ERROR_STORAGE_FAILURE
itayzafrir90d8c7a2018-09-12 11:44:52 +03002835 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002836 * The library has not been previously initialized by psa_crypto_init().
2837 * It is implementation-dependent whether a failure to initialize
2838 * results in this error code.
Gilles Peskine20035e32018-02-03 22:44:14 +01002839 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002840psa_status_t psa_asymmetric_verify(psa_key_handle_t handle,
Gilles Peskine20035e32018-02-03 22:44:14 +01002841 psa_algorithm_t alg,
2842 const uint8_t *hash,
2843 size_t hash_length,
Gilles Peskinee9191ff2018-06-27 14:58:41 +02002844 const uint8_t *signature,
Gilles Peskine526fab02018-06-27 18:19:40 +02002845 size_t signature_length);
Gilles Peskine20035e32018-02-03 22:44:14 +01002846
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002847/**
2848 * \brief Encrypt a short message with a public key.
2849 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002850 * \param handle Handle to the key to use for the operation.
2851 * It must be a public key or an asymmetric
2852 * key pair.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002853 * \param alg An asymmetric encryption algorithm that is
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002854 * compatible with the type of \p handle.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002855 * \param[in] input The message to encrypt.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002856 * \param input_length Size of the \p input buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002857 * \param[in] salt A salt or label, if supported by the
2858 * encryption algorithm.
2859 * If the algorithm does not support a
2860 * salt, pass \c NULL.
2861 * If the algorithm supports an optional
2862 * salt and you do not want to pass a salt,
2863 * pass \c NULL.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002864 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02002865 * - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is
2866 * supported.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002867 * \param salt_length Size of the \p salt buffer in bytes.
2868 * If \p salt is \c NULL, pass 0.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002869 * \param[out] output Buffer where the encrypted message is to
2870 * be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002871 * \param output_size Size of the \p output buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002872 * \param[out] output_length On success, the number of bytes
2873 * that make up the returned output.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002874 *
Gilles Peskine28538492018-07-11 17:34:00 +02002875 * \retval #PSA_SUCCESS
Adrian L. Shawf961d5c2019-08-08 10:27:50 +01002876 * \retval #PSA_ERROR_INVALID_HANDLE
2877 * \retval #PSA_ERROR_NOT_PERMITTED
Gilles Peskine28538492018-07-11 17:34:00 +02002878 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002879 * The size of the \p output buffer is too small. You can
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002880 * determine a sufficient buffer size by calling
Gilles Peskine7256e6c2018-07-12 00:34:26 +02002881 * #PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002882 * where \c key_type and \c key_bits are the type and bit-size
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002883 * respectively of \p handle.
Gilles Peskine28538492018-07-11 17:34:00 +02002884 * \retval #PSA_ERROR_NOT_SUPPORTED
2885 * \retval #PSA_ERROR_INVALID_ARGUMENT
2886 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2887 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2888 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002889 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawf961d5c2019-08-08 10:27:50 +01002890 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine28538492018-07-11 17:34:00 +02002891 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
itayzafrir90d8c7a2018-09-12 11:44:52 +03002892 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002893 * The library has not been previously initialized by psa_crypto_init().
2894 * It is implementation-dependent whether a failure to initialize
2895 * results in this error code.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002896 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002897psa_status_t psa_asymmetric_encrypt(psa_key_handle_t handle,
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002898 psa_algorithm_t alg,
2899 const uint8_t *input,
2900 size_t input_length,
2901 const uint8_t *salt,
2902 size_t salt_length,
2903 uint8_t *output,
2904 size_t output_size,
2905 size_t *output_length);
2906
2907/**
2908 * \brief Decrypt a short message with a private key.
2909 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002910 * \param handle Handle to the key to use for the operation.
2911 * It must be an asymmetric key pair.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002912 * \param alg An asymmetric encryption algorithm that is
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002913 * compatible with the type of \p handle.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002914 * \param[in] input The message to decrypt.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002915 * \param input_length Size of the \p input buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002916 * \param[in] salt A salt or label, if supported by the
2917 * encryption algorithm.
2918 * If the algorithm does not support a
2919 * salt, pass \c NULL.
2920 * If the algorithm supports an optional
2921 * salt and you do not want to pass a salt,
2922 * pass \c NULL.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002923 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02002924 * - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is
2925 * supported.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002926 * \param salt_length Size of the \p salt buffer in bytes.
2927 * If \p salt is \c NULL, pass 0.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002928 * \param[out] output Buffer where the decrypted message is to
2929 * be written.
2930 * \param output_size Size of the \c output buffer in bytes.
2931 * \param[out] output_length On success, the number of bytes
2932 * that make up the returned output.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002933 *
Gilles Peskine28538492018-07-11 17:34:00 +02002934 * \retval #PSA_SUCCESS
Adrian L. Shaw96f31ad2019-08-08 10:30:58 +01002935 * \retval #PSA_ERROR_INVALID_HANDLE
2936 * \retval #PSA_ERROR_NOT_PERMITTED
Gilles Peskine28538492018-07-11 17:34:00 +02002937 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002938 * The size of the \p output buffer is too small. You can
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002939 * determine a sufficient buffer size by calling
Gilles Peskinedda3bd32018-07-12 19:40:46 +02002940 * #PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002941 * where \c key_type and \c key_bits are the type and bit-size
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002942 * respectively of \p handle.
Gilles Peskine28538492018-07-11 17:34:00 +02002943 * \retval #PSA_ERROR_NOT_SUPPORTED
2944 * \retval #PSA_ERROR_INVALID_ARGUMENT
2945 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2946 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2947 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002948 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw96f31ad2019-08-08 10:30:58 +01002949 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine28538492018-07-11 17:34:00 +02002950 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
2951 * \retval #PSA_ERROR_INVALID_PADDING
itayzafrir90d8c7a2018-09-12 11:44:52 +03002952 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002953 * The library has not been previously initialized by psa_crypto_init().
2954 * It is implementation-dependent whether a failure to initialize
2955 * results in this error code.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002956 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002957psa_status_t psa_asymmetric_decrypt(psa_key_handle_t handle,
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002958 psa_algorithm_t alg,
2959 const uint8_t *input,
2960 size_t input_length,
2961 const uint8_t *salt,
2962 size_t salt_length,
2963 uint8_t *output,
2964 size_t output_size,
2965 size_t *output_length);
2966
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +01002967/**@}*/
2968
Gilles Peskine35675b62019-05-16 17:26:11 +02002969/** \defgroup key_derivation Key derivation and pseudorandom generation
Gilles Peskineeab56e42018-07-12 17:12:33 +02002970 * @{
2971 */
2972
Gilles Peskine35675b62019-05-16 17:26:11 +02002973/** The type of the state data structure for key derivation operations.
Gilles Peskineeab56e42018-07-12 17:12:33 +02002974 *
Gilles Peskine35675b62019-05-16 17:26:11 +02002975 * Before calling any function on a key derivation operation object, the
2976 * application must initialize it by any of the following means:
Gilles Peskineeab56e42018-07-12 17:12:33 +02002977 * - Set the structure to all-bits-zero, for example:
2978 * \code
Gilles Peskine35675b62019-05-16 17:26:11 +02002979 * psa_key_derivation_operation_t operation;
2980 * memset(&operation, 0, sizeof(operation));
Gilles Peskineeab56e42018-07-12 17:12:33 +02002981 * \endcode
2982 * - Initialize the structure to logical zero values, for example:
2983 * \code
Gilles Peskine35675b62019-05-16 17:26:11 +02002984 * psa_key_derivation_operation_t operation = {0};
Gilles Peskineeab56e42018-07-12 17:12:33 +02002985 * \endcode
Gilles Peskinea99d3fb2019-05-16 15:28:51 +02002986 * - Initialize the structure to the initializer #PSA_KEY_DERIVATION_OPERATION_INIT,
Gilles Peskineeab56e42018-07-12 17:12:33 +02002987 * for example:
2988 * \code
Gilles Peskine35675b62019-05-16 17:26:11 +02002989 * psa_key_derivation_operation_t operation = PSA_KEY_DERIVATION_OPERATION_INIT;
Gilles Peskineeab56e42018-07-12 17:12:33 +02002990 * \endcode
Gilles Peskinea99d3fb2019-05-16 15:28:51 +02002991 * - Assign the result of the function psa_key_derivation_operation_init()
Gilles Peskineeab56e42018-07-12 17:12:33 +02002992 * to the structure, for example:
2993 * \code
Gilles Peskine35675b62019-05-16 17:26:11 +02002994 * psa_key_derivation_operation_t operation;
2995 * operation = psa_key_derivation_operation_init();
Gilles Peskineeab56e42018-07-12 17:12:33 +02002996 * \endcode
2997 *
2998 * This is an implementation-defined \c struct. Applications should not
2999 * make any assumptions about the content of this structure except
3000 * as directed by the documentation of a specific implementation.
3001 */
Gilles Peskinecbe66502019-05-16 16:59:18 +02003002typedef struct psa_key_derivation_s psa_key_derivation_operation_t;
Gilles Peskineeab56e42018-07-12 17:12:33 +02003003
Gilles Peskinea99d3fb2019-05-16 15:28:51 +02003004/** \def PSA_KEY_DERIVATION_OPERATION_INIT
Gilles Peskineeab56e42018-07-12 17:12:33 +02003005 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003006 * This macro returns a suitable initializer for a key derivation operation
3007 * object of type #psa_key_derivation_operation_t.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003008 */
3009#ifdef __DOXYGEN_ONLY__
3010/* This is an example definition for documentation purposes.
3011 * Implementations should define a suitable value in `crypto_struct.h`.
3012 */
Gilles Peskinea99d3fb2019-05-16 15:28:51 +02003013#define PSA_KEY_DERIVATION_OPERATION_INIT {0}
Gilles Peskineeab56e42018-07-12 17:12:33 +02003014#endif
3015
Gilles Peskine35675b62019-05-16 17:26:11 +02003016/** Return an initial value for a key derivation operation object.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003017 */
Gilles Peskinea99d3fb2019-05-16 15:28:51 +02003018static psa_key_derivation_operation_t psa_key_derivation_operation_init(void);
Gilles Peskineeab56e42018-07-12 17:12:33 +02003019
Gilles Peskine1cb9a082019-05-16 17:56:47 +02003020/** Set up a key derivation operation.
3021 *
3022 * A key derivation algorithm takes some inputs and uses them to generate
3023 * a byte stream in a deterministic way.
3024 * This byte stream can be used to produce keys and other
3025 * cryptographic material.
3026 *
3027 * To derive a key:
3028 * - Start with an initialized object of type #psa_key_derivation_operation_t.
3029 * - Call psa_key_derivation_setup() to select the algorithm.
3030 * - Provide the inputs for the key derivation by calling
3031 * psa_key_derivation_input_bytes() or psa_key_derivation_input_key()
3032 * as appropriate. Which inputs are needed, in what order, and whether
3033 * they may be keys and if so of what type depends on the algorithm.
3034 * - Optionally set the operation's maximum capacity with
3035 * psa_key_derivation_set_capacity(). You may do this before, in the middle
3036 * of or after providing inputs. For some algorithms, this step is mandatory
3037 * because the output depends on the maximum capacity.
3038 * - To derive a key, call psa_key_derivation_output_key().
3039 * To derive a byte string for a different purpose, call
3040 * - psa_key_derivation_output_bytes().
3041 * Successive calls to these functions use successive output bytes
3042 * calculated by the key derivation algorithm.
3043 * - Clean up the key derivation operation object with
3044 * psa_key_derivation_abort().
3045 *
3046 * \param[in,out] operation The key derivation operation object
3047 * to set up. It must
3048 * have been initialized but not set up yet.
3049 * \param alg The key derivation algorithm to compute
3050 * (\c PSA_ALG_XXX value such that
3051 * #PSA_ALG_IS_KEY_DERIVATION(\p alg) is true).
3052 *
3053 * \retval #PSA_SUCCESS
3054 * Success.
3055 * \retval #PSA_ERROR_INVALID_ARGUMENT
3056 * \c alg is not a key derivation algorithm.
3057 * \retval #PSA_ERROR_NOT_SUPPORTED
3058 * \c alg is not supported or is not a key derivation algorithm.
3059 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3060 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3061 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003062 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine1cb9a082019-05-16 17:56:47 +02003063 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shaw320659b2019-08-08 14:49:01 +01003064 * The operation state is either not initialized or has already been setup.
Adrian L. Shawdec47b62019-08-07 14:25:38 +01003065 * \retval #PSA_ERROR_BAD_STATE
3066 * The library has not been previously initialized by psa_crypto_init().
3067 * It is implementation-dependent whether a failure to initialize
3068 * results in this error code.
Gilles Peskine1cb9a082019-05-16 17:56:47 +02003069 */
3070psa_status_t psa_key_derivation_setup(
3071 psa_key_derivation_operation_t *operation,
3072 psa_algorithm_t alg);
3073
Gilles Peskine35675b62019-05-16 17:26:11 +02003074/** Retrieve the current capacity of a key derivation operation.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003075 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003076 * The capacity of a key derivation is the maximum number of bytes that it can
3077 * return. When you get *N* bytes of output from a key derivation operation,
3078 * this reduces its capacity by *N*.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003079 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003080 * \param[in] operation The operation to query.
3081 * \param[out] capacity On success, the capacity of the operation.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003082 *
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003083 * \retval #PSA_SUCCESS
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003084 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01003085 * \retval #PSA_ERROR_BAD_STATE
3086 * The operation state is not valid.
3087 * \retval #PSA_ERROR_BAD_STATE
3088 * The library has not been previously initialized by psa_crypto_init().
3089 * It is implementation-dependent whether a failure to initialize
3090 * results in this error code.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003091 */
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003092psa_status_t psa_key_derivation_get_capacity(
3093 const psa_key_derivation_operation_t *operation,
3094 size_t *capacity);
Gilles Peskineeab56e42018-07-12 17:12:33 +02003095
Gilles Peskine35675b62019-05-16 17:26:11 +02003096/** Set the maximum capacity of a key derivation operation.
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003097 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003098 * The capacity of a key derivation operation is the maximum number of bytes
3099 * that the key derivation operation can return from this point onwards.
3100 *
3101 * \param[in,out] operation The key derivation operation object to modify.
3102 * \param capacity The new capacity of the operation.
3103 * It must be less or equal to the operation's
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003104 * current capacity.
3105 *
3106 * \retval #PSA_SUCCESS
3107 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine35675b62019-05-16 17:26:11 +02003108 * \p capacity is larger than the operation's current capacity.
3109 * In this case, the operation object remains valid and its capacity
3110 * remains unchanged.
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003111 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01003112 * The operation state is not valid.
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003113 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01003114 * \retval #PSA_ERROR_BAD_STATE
3115 * The library has not been previously initialized by psa_crypto_init().
3116 * It is implementation-dependent whether a failure to initialize
3117 * results in this error code.
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003118 */
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003119psa_status_t psa_key_derivation_set_capacity(
3120 psa_key_derivation_operation_t *operation,
3121 size_t capacity);
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003122
Gilles Peskine1cb9a082019-05-16 17:56:47 +02003123/** Use the maximum possible capacity for a key derivation operation.
3124 *
3125 * Use this value as the capacity argument when setting up a key derivation
3126 * to indicate that the operation should have the maximum possible capacity.
3127 * The value of the maximum possible capacity depends on the key derivation
3128 * algorithm.
3129 */
3130#define PSA_KEY_DERIVATION_UNLIMITED_CAPACITY ((size_t)(-1))
3131
3132/** Provide an input for key derivation or key agreement.
3133 *
3134 * Which inputs are required and in what order depends on the algorithm.
3135 * Refer to the documentation of each key derivation or key agreement
3136 * algorithm for information.
3137 *
3138 * This function passes direct inputs. Some inputs must be passed as keys
3139 * using psa_key_derivation_input_key() instead of this function. Refer to
3140 * the documentation of individual step types for information.
3141 *
3142 * \param[in,out] operation The key derivation operation object to use.
3143 * It must have been set up with
3144 * psa_key_derivation_setup() and must not
3145 * have produced any output yet.
3146 * \param step Which step the input data is for.
3147 * \param[in] data Input data to use.
3148 * \param data_length Size of the \p data buffer in bytes.
3149 *
3150 * \retval #PSA_SUCCESS
3151 * Success.
3152 * \retval #PSA_ERROR_INVALID_ARGUMENT
3153 * \c step is not compatible with the operation's algorithm.
3154 * \retval #PSA_ERROR_INVALID_ARGUMENT
3155 * \c step does not allow direct inputs.
3156 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3157 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3158 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003159 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine1cb9a082019-05-16 17:56:47 +02003160 * \retval #PSA_ERROR_BAD_STATE
3161 * The value of \p step is not valid given the state of \p operation.
3162 * \retval #PSA_ERROR_BAD_STATE
3163 * The library has not been previously initialized by psa_crypto_init().
3164 * It is implementation-dependent whether a failure to initialize
3165 * results in this error code.
3166 */
3167psa_status_t psa_key_derivation_input_bytes(
3168 psa_key_derivation_operation_t *operation,
3169 psa_key_derivation_step_t step,
3170 const uint8_t *data,
3171 size_t data_length);
3172
3173/** Provide an input for key derivation in the form of a key.
3174 *
3175 * Which inputs are required and in what order depends on the algorithm.
3176 * Refer to the documentation of each key derivation or key agreement
3177 * algorithm for information.
3178 *
3179 * This function passes key inputs. Some inputs must be passed as keys
3180 * of the appropriate type using this function, while others must be
3181 * passed as direct inputs using psa_key_derivation_input_bytes(). Refer to
3182 * the documentation of individual step types for information.
3183 *
3184 * \param[in,out] operation The key derivation operation object to use.
3185 * It must have been set up with
3186 * psa_key_derivation_setup() and must not
3187 * have produced any output yet.
3188 * \param step Which step the input data is for.
3189 * \param handle Handle to the key. It must have an
3190 * appropriate type for \p step and must
3191 * allow the usage #PSA_KEY_USAGE_DERIVE.
3192 *
3193 * \retval #PSA_SUCCESS
3194 * Success.
3195 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine1cb9a082019-05-16 17:56:47 +02003196 * \retval #PSA_ERROR_NOT_PERMITTED
3197 * \retval #PSA_ERROR_INVALID_ARGUMENT
3198 * \c step is not compatible with the operation's algorithm.
3199 * \retval #PSA_ERROR_INVALID_ARGUMENT
3200 * \c step does not allow key inputs.
3201 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3202 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3203 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003204 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine1cb9a082019-05-16 17:56:47 +02003205 * \retval #PSA_ERROR_BAD_STATE
3206 * The value of \p step is not valid given the state of \p operation.
3207 * \retval #PSA_ERROR_BAD_STATE
3208 * The library has not been previously initialized by psa_crypto_init().
3209 * It is implementation-dependent whether a failure to initialize
3210 * results in this error code.
3211 */
3212psa_status_t psa_key_derivation_input_key(
3213 psa_key_derivation_operation_t *operation,
3214 psa_key_derivation_step_t step,
3215 psa_key_handle_t handle);
3216
3217/** Perform a key agreement and use the shared secret as input to a key
3218 * derivation.
3219 *
3220 * A key agreement algorithm takes two inputs: a private key \p private_key
3221 * a public key \p peer_key.
3222 * The result of this function is passed as input to a key derivation.
3223 * The output of this key derivation can be extracted by reading from the
3224 * resulting operation to produce keys and other cryptographic material.
3225 *
3226 * \param[in,out] operation The key derivation operation object to use.
3227 * It must have been set up with
3228 * psa_key_derivation_setup() with a
3229 * key agreement and derivation algorithm
3230 * \c alg (\c PSA_ALG_XXX value such that
3231 * #PSA_ALG_IS_KEY_AGREEMENT(\c alg) is true
3232 * and #PSA_ALG_IS_RAW_KEY_AGREEMENT(\c alg)
3233 * is false).
3234 * The operation must be ready for an
3235 * input of the type given by \p step.
3236 * \param step Which step the input data is for.
3237 * \param private_key Handle to the private key to use.
3238 * \param[in] peer_key Public key of the peer. The peer key must be in the
3239 * same format that psa_import_key() accepts for the
3240 * public key type corresponding to the type of
3241 * private_key. That is, this function performs the
3242 * equivalent of
3243 * #psa_import_key(...,
3244 * `peer_key`, `peer_key_length`) where
3245 * with key attributes indicating the public key
3246 * type corresponding to the type of `private_key`.
3247 * For example, for EC keys, this means that peer_key
3248 * is interpreted as a point on the curve that the
3249 * private key is on. The standard formats for public
3250 * keys are documented in the documentation of
3251 * psa_export_public_key().
3252 * \param peer_key_length Size of \p peer_key in bytes.
3253 *
3254 * \retval #PSA_SUCCESS
3255 * Success.
3256 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine1cb9a082019-05-16 17:56:47 +02003257 * \retval #PSA_ERROR_NOT_PERMITTED
3258 * \retval #PSA_ERROR_INVALID_ARGUMENT
3259 * \c private_key is not compatible with \c alg,
3260 * or \p peer_key is not valid for \c alg or not compatible with
3261 * \c private_key.
3262 * \retval #PSA_ERROR_NOT_SUPPORTED
3263 * \c alg is not supported or is not a key derivation algorithm.
3264 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3265 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3266 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003267 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01003268 * \retval #PSA_ERROR_BAD_STATE
3269 * The library has not been previously initialized by psa_crypto_init().
3270 * It is implementation-dependent whether a failure to initialize
3271 * results in this error code.
Gilles Peskine1cb9a082019-05-16 17:56:47 +02003272 */
3273psa_status_t psa_key_derivation_key_agreement(
3274 psa_key_derivation_operation_t *operation,
3275 psa_key_derivation_step_t step,
3276 psa_key_handle_t private_key,
3277 const uint8_t *peer_key,
3278 size_t peer_key_length);
3279
Gilles Peskine35675b62019-05-16 17:26:11 +02003280/** Read some data from a key derivation operation.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003281 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003282 * This function calculates output bytes from a key derivation algorithm and
3283 * return those bytes.
3284 * If you view the key derivation's output as a stream of bytes, this
3285 * function destructively reads the requested number of bytes from the
3286 * stream.
3287 * The operation's capacity decreases by the number of bytes read.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003288 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003289 * \param[in,out] operation The key derivation operation object to read from.
3290 * \param[out] output Buffer where the output will be written.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003291 * \param output_length Number of bytes to output.
3292 *
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003293 * \retval #PSA_SUCCESS
David Saadab4ecc272019-02-14 13:48:10 +02003294 * \retval #PSA_ERROR_INSUFFICIENT_DATA
Gilles Peskine35675b62019-05-16 17:26:11 +02003295 * The operation's capacity was less than
3296 * \p output_length bytes. Note that in this case,
3297 * no output is written to the output buffer.
3298 * The operation's capacity is set to 0, thus
Gilles Peskineeab56e42018-07-12 17:12:33 +02003299 * subsequent calls to this function will not
3300 * succeed, even with a smaller output buffer.
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003301 * \retval #PSA_ERROR_BAD_STATE
3302 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3303 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3304 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003305 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01003306 * \retval #PSA_ERROR_BAD_STATE
3307 * The library has not been previously initialized by psa_crypto_init().
3308 * It is implementation-dependent whether a failure to initialize
3309 * results in this error code.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003310 */
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003311psa_status_t psa_key_derivation_output_bytes(
3312 psa_key_derivation_operation_t *operation,
3313 uint8_t *output,
3314 size_t output_length);
Gilles Peskineeab56e42018-07-12 17:12:33 +02003315
Gilles Peskine35675b62019-05-16 17:26:11 +02003316/** Derive a key from an ongoing key derivation operation.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003317 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003318 * This function calculates output bytes from a key derivation algorithm
3319 * and uses those bytes to generate a key deterministically.
3320 * If you view the key derivation's output as a stream of bytes, this
3321 * function destructively reads as many bytes as required from the
3322 * stream.
3323 * The operation's capacity decreases by the number of bytes read.
3324 *
3325 * How much output is produced and consumed from the operation, and how
3326 * the key is derived, depends on the key type:
Gilles Peskineeab56e42018-07-12 17:12:33 +02003327 *
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003328 * - For key types for which the key is an arbitrary sequence of bytes
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003329 * of a given size, this function is functionally equivalent to
3330 * calling #psa_key_derivation_output_bytes
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003331 * and passing the resulting output to #psa_import_key.
3332 * However, this function has a security benefit:
3333 * if the implementation provides an isolation boundary then
3334 * the key material is not exposed outside the isolation boundary.
3335 * As a consequence, for these key types, this function always consumes
Gilles Peskine35675b62019-05-16 17:26:11 +02003336 * exactly (\p bits / 8) bytes from the operation.
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003337 * The following key types defined in this specification follow this scheme:
3338 *
3339 * - #PSA_KEY_TYPE_AES;
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003340 * - #PSA_KEY_TYPE_ARC4;
3341 * - #PSA_KEY_TYPE_CAMELLIA;
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003342 * - #PSA_KEY_TYPE_DERIVE;
3343 * - #PSA_KEY_TYPE_HMAC.
3344 *
3345 * - For ECC keys on a Montgomery elliptic curve
Gilles Peskinec93b80c2019-05-16 19:39:54 +02003346 * (#PSA_KEY_TYPE_ECC_KEY_PAIR(\c curve) where \c curve designates a
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003347 * Montgomery curve), this function always draws a byte string whose
3348 * length is determined by the curve, and sets the mandatory bits
3349 * accordingly. That is:
3350 *
3351 * - #PSA_ECC_CURVE_CURVE25519: draw a 32-byte string
3352 * and process it as specified in RFC 7748 &sect;5.
3353 * - #PSA_ECC_CURVE_CURVE448: draw a 56-byte string
3354 * and process it as specified in RFC 7748 &sect;5.
3355 *
3356 * - For key types for which the key is represented by a single sequence of
3357 * \p bits bits with constraints as to which bit sequences are acceptable,
3358 * this function draws a byte string of length (\p bits / 8) bytes rounded
3359 * up to the nearest whole number of bytes. If the resulting byte string
3360 * is acceptable, it becomes the key, otherwise the drawn bytes are discarded.
3361 * This process is repeated until an acceptable byte string is drawn.
Gilles Peskine35675b62019-05-16 17:26:11 +02003362 * The byte string drawn from the operation is interpreted as specified
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003363 * for the output produced by psa_export_key().
3364 * The following key types defined in this specification follow this scheme:
3365 *
Gilles Peskine2de2c0d2019-03-11 17:59:16 +01003366 * - #PSA_KEY_TYPE_DES.
3367 * Force-set the parity bits, but discard forbidden weak keys.
3368 * For 2-key and 3-key triple-DES, the three keys are generated
3369 * successively (for example, for 3-key triple-DES,
3370 * if the first 8 bytes specify a weak key and the next 8 bytes do not,
3371 * discard the first 8 bytes, use the next 8 bytes as the first key,
Gilles Peskine35675b62019-05-16 17:26:11 +02003372 * and continue reading output from the operation to derive the other
Gilles Peskine2de2c0d2019-03-11 17:59:16 +01003373 * two keys).
Gilles Peskinec93b80c2019-05-16 19:39:54 +02003374 * - Finite-field Diffie-Hellman keys (#PSA_KEY_TYPE_DH_KEY_PAIR(\c group)
Gilles Peskinea1302192019-05-16 13:58:24 +02003375 * where \c group designates any Diffie-Hellman group) and
Gilles Peskine2de2c0d2019-03-11 17:59:16 +01003376 * ECC keys on a Weierstrass elliptic curve
Gilles Peskinec93b80c2019-05-16 19:39:54 +02003377 * (#PSA_KEY_TYPE_ECC_KEY_PAIR(\c curve) where \c curve designates a
Gilles Peskine2de2c0d2019-03-11 17:59:16 +01003378 * Weierstrass curve).
3379 * For these key types, interpret the byte string as integer
3380 * in big-endian order. Discard it if it is not in the range
3381 * [0, *N* - 2] where *N* is the boundary of the private key domain
3382 * (the prime *p* for Diffie-Hellman, the subprime *q* for DSA,
Gilles Peskine55799712019-03-12 11:50:26 +01003383 * or the order of the curve's base point for ECC).
Gilles Peskine2de2c0d2019-03-11 17:59:16 +01003384 * Add 1 to the resulting integer and use this as the private key *x*.
Gilles Peskine55799712019-03-12 11:50:26 +01003385 * This method allows compliance to NIST standards, specifically
3386 * the methods titled "key-pair generation by testing candidates"
Gilles Peskine2de2c0d2019-03-11 17:59:16 +01003387 * in NIST SP 800-56A &sect;5.6.1.1.4 for Diffie-Hellman,
3388 * in FIPS 186-4 &sect;B.1.2 for DSA, and
3389 * in NIST SP 800-56A &sect;5.6.1.2.2 or
3390 * FIPS 186-4 &sect;B.4.2 for elliptic curve keys.
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003391 *
Gilles Peskinec93b80c2019-05-16 19:39:54 +02003392 * - For other key types, including #PSA_KEY_TYPE_RSA_KEY_PAIR,
Gilles Peskine35675b62019-05-16 17:26:11 +02003393 * the way in which the operation output is consumed is
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003394 * implementation-defined.
3395 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003396 * In all cases, the data that is read is discarded from the operation.
3397 * The operation's capacity is decreased by the number of bytes read.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003398 *
Gilles Peskine20628592019-04-19 19:29:50 +02003399 * \param[in] attributes The attributes for the new key.
Gilles Peskine35675b62019-05-16 17:26:11 +02003400 * \param[in,out] operation The key derivation operation object to read from.
Gilles Peskine20628592019-04-19 19:29:50 +02003401 * \param[out] handle On success, a handle to the newly created key.
3402 * \c 0 on failure.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003403 *
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003404 * \retval #PSA_SUCCESS
Gilles Peskineeab56e42018-07-12 17:12:33 +02003405 * Success.
Gilles Peskine23fd2bd2018-12-11 15:51:32 +01003406 * If the key is persistent, the key material and the key's metadata
3407 * have been saved to persistent storage.
Gilles Peskine20628592019-04-19 19:29:50 +02003408 * \retval #PSA_ERROR_ALREADY_EXISTS
3409 * This is an attempt to create a persistent key, and there is
3410 * already a persistent key with the given identifier.
David Saadab4ecc272019-02-14 13:48:10 +02003411 * \retval #PSA_ERROR_INSUFFICIENT_DATA
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003412 * There was not enough data to create the desired key.
3413 * Note that in this case, no output is written to the output buffer.
Gilles Peskine35675b62019-05-16 17:26:11 +02003414 * The operation's capacity is set to 0, thus subsequent calls to
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003415 * this function will not succeed, even with a smaller output buffer.
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003416 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskineeab56e42018-07-12 17:12:33 +02003417 * The key type or key size is not supported, either by the
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +01003418 * implementation in general or in this particular location.
k-stachowiakb9b4f092019-08-15 19:01:59 +02003419 * \retval #PSA_ERROR_INVALID_ARGUMENT
3420 * The provided key attributes are not valid for the operation.
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003421 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003422 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3423 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
3424 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3425 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003426 * \retval #PSA_ERROR_CORRUPTION_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03003427 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03003428 * The library has not been previously initialized by psa_crypto_init().
3429 * It is implementation-dependent whether a failure to initialize
3430 * results in this error code.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003431 */
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003432psa_status_t psa_key_derivation_output_key(
3433 const psa_key_attributes_t *attributes,
3434 psa_key_derivation_operation_t *operation,
3435 psa_key_handle_t *handle);
Gilles Peskineeab56e42018-07-12 17:12:33 +02003436
Gilles Peskine35675b62019-05-16 17:26:11 +02003437/** Abort a key derivation operation.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003438 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003439 * Once a key derivation operation has been aborted, its capacity is zero.
3440 * Aborting an operation frees all associated resources except for the
3441 * \c operation structure itself.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003442 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003443 * This function may be called at any time as long as the operation
Gilles Peskinea99d3fb2019-05-16 15:28:51 +02003444 * object has been initialized to #PSA_KEY_DERIVATION_OPERATION_INIT, to
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003445 * psa_key_derivation_operation_init() or a zero value. In particular,
3446 * it is valid to call psa_key_derivation_abort() twice, or to call
3447 * psa_key_derivation_abort() on an operation that has not been set up.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003448 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003449 * Once aborted, the key derivation operation object may be called.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003450 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003451 * \param[in,out] operation The operation to abort.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003452 *
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003453 * \retval #PSA_SUCCESS
3454 * \retval #PSA_ERROR_BAD_STATE
3455 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3456 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003457 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01003458 * \retval #PSA_ERROR_BAD_STATE
3459 * The library has not been previously initialized by psa_crypto_init().
3460 * It is implementation-dependent whether a failure to initialize
3461 * results in this error code.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003462 */
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003463psa_status_t psa_key_derivation_abort(
3464 psa_key_derivation_operation_t *operation);
Gilles Peskineeab56e42018-07-12 17:12:33 +02003465
Gilles Peskine58fe9e82019-05-16 18:01:45 +02003466/** Perform a key agreement and return the raw shared secret.
Gilles Peskine769c7a62019-01-18 16:42:29 +01003467 *
3468 * \warning The raw result of a key agreement algorithm such as finite-field
3469 * Diffie-Hellman or elliptic curve Diffie-Hellman has biases and should
3470 * not be used directly as key material. It should instead be passed as
3471 * input to a key derivation algorithm. To chain a key agreement with
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003472 * a key derivation, use psa_key_derivation_key_agreement() and other
3473 * functions from the key derivation interface.
Gilles Peskine769c7a62019-01-18 16:42:29 +01003474 *
Gilles Peskine47e79fb2019-02-08 11:24:59 +01003475 * \param alg The key agreement algorithm to compute
3476 * (\c PSA_ALG_XXX value such that
3477 * #PSA_ALG_IS_RAW_KEY_AGREEMENT(\p alg)
3478 * is true).
Gilles Peskine769c7a62019-01-18 16:42:29 +01003479 * \param private_key Handle to the private key to use.
3480 * \param[in] peer_key Public key of the peer. It must be
3481 * in the same format that psa_import_key()
3482 * accepts. The standard formats for public
3483 * keys are documented in the documentation
3484 * of psa_export_public_key().
3485 * \param peer_key_length Size of \p peer_key in bytes.
3486 * \param[out] output Buffer where the decrypted message is to
3487 * be written.
3488 * \param output_size Size of the \c output buffer in bytes.
3489 * \param[out] output_length On success, the number of bytes
3490 * that make up the returned output.
3491 *
3492 * \retval #PSA_SUCCESS
3493 * Success.
3494 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine769c7a62019-01-18 16:42:29 +01003495 * \retval #PSA_ERROR_NOT_PERMITTED
3496 * \retval #PSA_ERROR_INVALID_ARGUMENT
3497 * \p alg is not a key agreement algorithm
3498 * \retval #PSA_ERROR_INVALID_ARGUMENT
3499 * \p private_key is not compatible with \p alg,
3500 * or \p peer_key is not valid for \p alg or not compatible with
3501 * \p private_key.
Adrian L. Shaw0d280b92019-08-08 15:07:07 +01003502 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
3503 * \p output_size is too small
Gilles Peskine769c7a62019-01-18 16:42:29 +01003504 * \retval #PSA_ERROR_NOT_SUPPORTED
3505 * \p alg is not a supported key agreement algorithm.
3506 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3507 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3508 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003509 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw0d280b92019-08-08 15:07:07 +01003510 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01003511 * \retval #PSA_ERROR_BAD_STATE
3512 * The library has not been previously initialized by psa_crypto_init().
3513 * It is implementation-dependent whether a failure to initialize
3514 * results in this error code.
Gilles Peskine769c7a62019-01-18 16:42:29 +01003515 */
Gilles Peskinebe697d82019-05-16 18:00:41 +02003516psa_status_t psa_raw_key_agreement(psa_algorithm_t alg,
3517 psa_key_handle_t private_key,
3518 const uint8_t *peer_key,
3519 size_t peer_key_length,
3520 uint8_t *output,
3521 size_t output_size,
3522 size_t *output_length);
Gilles Peskine01d718c2018-09-18 12:01:02 +02003523
Gilles Peskineea0fb492018-07-12 17:17:20 +02003524/**@}*/
3525
Gilles Peskineedd76872018-07-20 17:42:05 +02003526/** \defgroup random Random generation
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003527 * @{
3528 */
3529
3530/**
3531 * \brief Generate random bytes.
3532 *
3533 * \warning This function **can** fail! Callers MUST check the return status
3534 * and MUST NOT use the content of the output buffer if the return
3535 * status is not #PSA_SUCCESS.
3536 *
Gilles Peskine35ef36b2019-05-16 19:42:05 +02003537 * \note To generate a key, use psa_generate_key() instead.
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003538 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02003539 * \param[out] output Output buffer for the generated data.
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003540 * \param output_size Number of bytes to generate and output.
3541 *
Gilles Peskine28538492018-07-11 17:34:00 +02003542 * \retval #PSA_SUCCESS
3543 * \retval #PSA_ERROR_NOT_SUPPORTED
3544 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
Adrian L. Shaw71b33ff2019-08-08 15:07:57 +01003545 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
Gilles Peskine28538492018-07-11 17:34:00 +02003546 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3547 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003548 * \retval #PSA_ERROR_CORRUPTION_DETECTED
itayzafrir0adf0fc2018-09-06 16:24:41 +03003549 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03003550 * The library has not been previously initialized by psa_crypto_init().
3551 * It is implementation-dependent whether a failure to initialize
3552 * results in this error code.
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003553 */
3554psa_status_t psa_generate_random(uint8_t *output,
3555 size_t output_size);
3556
3557/**
3558 * \brief Generate a key or key pair.
3559 *
Gilles Peskinee56e8782019-04-26 17:34:02 +02003560 * The key is generated randomly.
3561 * Its location, policy, type and size are taken from \p attributes.
3562 *
Gilles Peskine20a77ae2019-05-16 14:05:56 +02003563 * The following type-specific considerations apply:
Gilles Peskinec93b80c2019-05-16 19:39:54 +02003564 * - For RSA keys (#PSA_KEY_TYPE_RSA_KEY_PAIR),
Gilles Peskine20a77ae2019-05-16 14:05:56 +02003565 * the public exponent is 65537.
3566 * The modulus is a product of two probabilistic primes
3567 * between 2^{n-1} and 2^n where n is the bit size specified in the
3568 * attributes.
3569 *
Gilles Peskine20628592019-04-19 19:29:50 +02003570 * \param[in] attributes The attributes for the new key.
Gilles Peskine20628592019-04-19 19:29:50 +02003571 * \param[out] handle On success, a handle to the newly created key.
3572 * \c 0 on failure.
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003573 *
Gilles Peskine28538492018-07-11 17:34:00 +02003574 * \retval #PSA_SUCCESS
Gilles Peskine23fd2bd2018-12-11 15:51:32 +01003575 * Success.
3576 * If the key is persistent, the key material and the key's metadata
3577 * have been saved to persistent storage.
David Saadab4ecc272019-02-14 13:48:10 +02003578 * \retval #PSA_ERROR_ALREADY_EXISTS
Gilles Peskine20628592019-04-19 19:29:50 +02003579 * This is an attempt to create a persistent key, and there is
3580 * already a persistent key with the given identifier.
Gilles Peskine28538492018-07-11 17:34:00 +02003581 * \retval #PSA_ERROR_NOT_SUPPORTED
3582 * \retval #PSA_ERROR_INVALID_ARGUMENT
3583 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3584 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
3585 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3586 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003587 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawd21c6e62019-08-08 10:58:08 +01003588 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
3589 * \retval #PSA_ERROR_STORAGE_FAILURE
itayzafrir90d8c7a2018-09-12 11:44:52 +03003590 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03003591 * The library has not been previously initialized by psa_crypto_init().
3592 * It is implementation-dependent whether a failure to initialize
3593 * results in this error code.
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003594 */
Gilles Peskine35ef36b2019-05-16 19:42:05 +02003595psa_status_t psa_generate_key(const psa_key_attributes_t *attributes,
Gilles Peskinee56e8782019-04-26 17:34:02 +02003596 psa_key_handle_t *handle);
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003597
3598/**@}*/
3599
Gilles Peskinee59236f2018-01-27 23:32:46 +01003600#ifdef __cplusplus
3601}
3602#endif
3603
Gilles Peskine0cad07c2018-06-27 19:49:02 +02003604/* The file "crypto_sizes.h" contains definitions for size calculation
3605 * macros whose definitions are implementation-specific. */
3606#include "crypto_sizes.h"
3607
Gilles Peskine9ef733f2018-02-07 21:05:37 +01003608/* The file "crypto_struct.h" contains definitions for
3609 * implementation-specific structs that are declared above. */
3610#include "crypto_struct.h"
3611
3612/* The file "crypto_extra.h" contains vendor-specific definitions. This
3613 * can include vendor-defined algorithms, extra functions, etc. */
Gilles Peskinee59236f2018-01-27 23:32:46 +01003614#include "crypto_extra.h"
3615
3616#endif /* PSA_CRYPTO_H */