Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
TARGET_TFM/TARGET_TFM_LATEST/include/psa/crypto.h
1 /*
2  * Copyright (c) 2018-2020, Arm Limited. All rights reserved.
3  *
4  * SPDX-License-Identifier: BSD-3-Clause
5  *
6  */
7 /**
8  * \file psa/crypto.h
9  * \brief Platform Security Architecture cryptography module
10  */
11 
12 #ifndef PSA_CRYPTO_H
13 #define PSA_CRYPTO_H
14 
15 #include <stddef.h>
16 
17 #ifdef __DOXYGEN_ONLY__
18 /* This __DOXYGEN_ONLY__ block contains mock definitions for things that
19  * must be defined in the crypto_platform.h header. These mock definitions
20  * are present in this file as a convenience to generate pretty-printed
21  * documentation that includes those definitions. */
22 
23 /** \defgroup platform Implementation-specific definitions
24  * @{
25  */
26 
27 /** \brief Key handle.
28  *
29  * This type represents open handles to keys. It must be an unsigned integral
30  * type. The choice of type is implementation-dependent.
31  *
32  * 0 is not a valid key handle. How other handle values are assigned is
33  * implementation-dependent.
34  */
35 typedef _unsigned_integral_type_ psa_key_handle_t;
36 
37 /**@}*/
38 #endif /* __DOXYGEN_ONLY__ */
39 
40 #ifdef __cplusplus
41 extern "C" {
42 #endif
43 
44 /* The file "crypto_types.h" declares types that encode errors,
45  * algorithms, key types, policies, etc. */
46 #include "psa/crypto_types.h"
47 
48 /** \defgroup version API version
49  * @{
50  */
51 
52 /**
53  * The major version of this implementation of the PSA Crypto API
54  */
55 #define PSA_CRYPTO_API_VERSION_MAJOR 1
56 
57 /**
58  * The minor version of this implementation of the PSA Crypto API
59  */
60 #define PSA_CRYPTO_API_VERSION_MINOR 0
61 
62 /**@}*/
63 
64 /* The file "crypto_values.h" declares macros to build and analyze values
65  * of integral types defined in "crypto_types.h". */
66 #include "psa/crypto_values.h"
67 
68 /** \defgroup initialization Library initialization
69  * @{
70  */
71 
72 /**
73  * \brief Library initialization.
74  *
75  * Applications must call this function before calling any other
76  * function in this module.
77  *
78  * Applications may call this function more than once. Once a call
79  * succeeds, subsequent calls are guaranteed to succeed.
80  *
81  * If the application calls other functions before calling psa_crypto_init(),
82  * the behavior is undefined. Implementations are encouraged to either perform
83  * the operation as if the library had been initialized or to return
84  * #PSA_ERROR_BAD_STATE or some other applicable error. In particular,
85  * implementations should not return a success status if the lack of
86  * initialization may have security implications, for example due to improper
87  * seeding of the random number generator.
88  *
89  * \retval #PSA_SUCCESS
90  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
91  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
92  * \retval #PSA_ERROR_HARDWARE_FAILURE
93  * \retval #PSA_ERROR_CORRUPTION_DETECTED
94  * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
95  */
96 psa_status_t psa_crypto_init(void);
97 
98 /**@}*/
99 
100 /** \addtogroup attributes
101  * @{
102  */
103 
104 /** \def PSA_KEY_ATTRIBUTES_INIT
105  *
106  * This macro returns a suitable initializer for a key attribute structure
107  * of type #psa_key_attributes_t.
108  */
109 #ifdef __DOXYGEN_ONLY__
110 /* This is an example definition for documentation purposes.
111  * Implementations should define a suitable value in `crypto_struct.h`.
112  */
113 #define PSA_KEY_ATTRIBUTES_INIT {0}
114 #endif
115 
116 /** Return an initial value for a key attributes structure.
117  */
118 static psa_key_attributes_t psa_key_attributes_init(void);
119 
120 /** Declare a key as persistent and set its key identifier.
121  *
122  * If the attribute structure currently declares the key as volatile (which
123  * is the default content of an attribute structure), this function sets
124  * the lifetime attribute to #PSA_KEY_LIFETIME_PERSISTENT.
125  *
126  * This function does not access storage, it merely stores the given
127  * value in the structure.
128  * The persistent key will be written to storage when the attribute
129  * structure is passed to a key creation function such as
130  * psa_import_key(), psa_generate_key(),
131  * psa_key_derivation_output_key() or psa_copy_key().
132  *
133  * This function may be declared as `static` (i.e. without external
134  * linkage). This function may be provided as a function-like macro,
135  * but in this case it must evaluate each of its arguments exactly once.
136  *
137  * \param[out] attributes The attribute structure to write to.
138  * \param id The persistent identifier for the key.
139  */
140 static void psa_set_key_id(psa_key_attributes_t *attributes,
141  psa_key_id_t id);
142 
143 /** Set the location of a persistent key.
144  *
145  * To make a key persistent, you must give it a persistent key identifier
146  * with psa_set_key_id(). By default, a key that has a persistent identifier
147  * is stored in the default storage area identifier by
148  * #PSA_KEY_LIFETIME_PERSISTENT. Call this function to choose a storage
149  * area, or to explicitly declare the key as volatile.
150  *
151  * This function does not access storage, it merely stores the given
152  * value in the structure.
153  * The persistent key will be written to storage when the attribute
154  * structure is passed to a key creation function such as
155  * psa_import_key(), psa_generate_key(),
156  * psa_key_derivation_output_key() or psa_copy_key().
157  *
158  * This function may be declared as `static` (i.e. without external
159  * linkage). This function may be provided as a function-like macro,
160  * but in this case it must evaluate each of its arguments exactly once.
161  *
162  * \param[out] attributes The attribute structure to write to.
163  * \param lifetime The lifetime for the key.
164  * If this is #PSA_KEY_LIFETIME_VOLATILE, the
165  * key will be volatile, and the key identifier
166  * attribute is reset to 0.
167  */
168 static void psa_set_key_lifetime(psa_key_attributes_t *attributes,
169  psa_key_lifetime_t lifetime);
170 
171 /** Retrieve the key identifier from key attributes.
172  *
173  * This function may be declared as `static` (i.e. without external
174  * linkage). This function may be provided as a function-like macro,
175  * but in this case it must evaluate its argument exactly once.
176  *
177  * \param[in] attributes The key attribute structure to query.
178  *
179  * \return The persistent identifier stored in the attribute structure.
180  * This value is unspecified if the attribute structure declares
181  * the key as volatile.
182  */
183 static psa_key_id_t psa_get_key_id(const psa_key_attributes_t *attributes);
184 
185 /** Retrieve the lifetime from key attributes.
186  *
187  * This function may be declared as `static` (i.e. without external
188  * linkage). This function may be provided as a function-like macro,
189  * but in this case it must evaluate its argument exactly once.
190  *
191  * \param[in] attributes The key attribute structure to query.
192  *
193  * \return The lifetime value stored in the attribute structure.
194  */
195 static psa_key_lifetime_t psa_get_key_lifetime(
196  const psa_key_attributes_t *attributes);
197 
198 /** Declare usage flags for a key.
199  *
200  * Usage flags are part of a key's usage policy. They encode what
201  * kind of operations are permitted on the key. For more details,
202  * refer to the documentation of the type #psa_key_usage_t.
203  *
204  * This function overwrites any usage flags
205  * previously set in \p attributes.
206  *
207  * This function may be declared as `static` (i.e. without external
208  * linkage). This function may be provided as a function-like macro,
209  * but in this case it must evaluate each of its arguments exactly once.
210  *
211  * \param[out] attributes The attribute structure to write to.
212  * \param usage_flags The usage flags to write.
213  */
214 static void psa_set_key_usage_flags(psa_key_attributes_t *attributes,
215  psa_key_usage_t usage_flags);
216 
217 /** Retrieve the usage flags from key attributes.
218  *
219  * This function may be declared as `static` (i.e. without external
220  * linkage). This function may be provided as a function-like macro,
221  * but in this case it must evaluate its argument exactly once.
222  *
223  * \param[in] attributes The key attribute structure to query.
224  *
225  * \return The usage flags stored in the attribute structure.
226  */
227 static psa_key_usage_t psa_get_key_usage_flags(
228  const psa_key_attributes_t *attributes);
229 
230 /** Declare the permitted algorithm policy for a key.
231  *
232  * The permitted algorithm policy of a key encodes which algorithm or
233  * algorithms are permitted to be used with this key. The following
234  * algorithm policies are supported:
235  * - 0 does not allow any cryptographic operation with the key. The key
236  * may be used for non-cryptographic actions such as exporting (if
237  * permitted by the usage flags).
238  * - An algorithm value permits this particular algorithm.
239  * - An algorithm wildcard built from #PSA_ALG_ANY_HASH allows the specified
240  * signature scheme with any hash algorithm.
241  *
242  * This function overwrites any algorithm policy
243  * previously set in \p attributes.
244  *
245  * This function may be declared as `static` (i.e. without external
246  * linkage). This function may be provided as a function-like macro,
247  * but in this case it must evaluate each of its arguments exactly once.
248  *
249  * \param[out] attributes The attribute structure to write to.
250  * \param alg The permitted algorithm policy to write.
251  */
252 static void psa_set_key_algorithm(psa_key_attributes_t *attributes,
253  psa_algorithm_t alg);
254 
255 
256 /** Retrieve the algorithm policy from key attributes.
257  *
258  * This function may be declared as `static` (i.e. without external
259  * linkage). This function may be provided as a function-like macro,
260  * but in this case it must evaluate its argument exactly once.
261  *
262  * \param[in] attributes The key attribute structure to query.
263  *
264  * \return The algorithm stored in the attribute structure.
265  */
266 static psa_algorithm_t psa_get_key_algorithm(
267  const psa_key_attributes_t *attributes);
268 
269 /** Declare the type of a key.
270  *
271  * This function overwrites any key type
272  * previously set in \p attributes.
273  *
274  * This function may be declared as `static` (i.e. without external
275  * linkage). This function may be provided as a function-like macro,
276  * but in this case it must evaluate each of its arguments exactly once.
277  *
278  * \param[out] attributes The attribute structure to write to.
279  * \param type The key type to write.
280  * If this is 0, the key type in \p attributes
281  * becomes unspecified.
282  */
283 static void psa_set_key_type(psa_key_attributes_t *attributes,
284  psa_key_type_t type);
285 
286 
287 /** Declare the size of a key.
288  *
289  * This function overwrites any key size previously set in \p attributes.
290  *
291  * This function may be declared as `static` (i.e. without external
292  * linkage). This function may be provided as a function-like macro,
293  * but in this case it must evaluate each of its arguments exactly once.
294  *
295  * \param[out] attributes The attribute structure to write to.
296  * \param bits The key size in bits.
297  * If this is 0, the key size in \p attributes
298  * becomes unspecified. Keys of size 0 are
299  * not supported.
300  */
301 static void psa_set_key_bits(psa_key_attributes_t *attributes,
302  size_t bits);
303 
304 /** Retrieve the key type from key attributes.
305  *
306  * This function may be declared as `static` (i.e. without external
307  * linkage). This function may be provided as a function-like macro,
308  * but in this case it must evaluate its argument exactly once.
309  *
310  * \param[in] attributes The key attribute structure to query.
311  *
312  * \return The key type stored in the attribute structure.
313  */
314 static psa_key_type_t psa_get_key_type(const psa_key_attributes_t *attributes);
315 
316 /** Retrieve the key size from key attributes.
317  *
318  * This function may be declared as `static` (i.e. without external
319  * linkage). This function may be provided as a function-like macro,
320  * but in this case it must evaluate its argument exactly once.
321  *
322  * \param[in] attributes The key attribute structure to query.
323  *
324  * \return The key size stored in the attribute structure, in bits.
325  */
326 static size_t psa_get_key_bits(const psa_key_attributes_t *attributes);
327 
328 /** Retrieve the attributes of a key.
329  *
330  * This function first resets the attribute structure as with
331  * psa_reset_key_attributes(). It then copies the attributes of
332  * the given key into the given attribute structure.
333  *
334  * \note This function may allocate memory or other resources.
335  * Once you have called this function on an attribute structure,
336  * you must call psa_reset_key_attributes() to free these resources.
337  *
338  * \param[in] handle Handle to the key to query.
339  * \param[in,out] attributes On success, the attributes of the key.
340  * On failure, equivalent to a
341  * freshly-initialized structure.
342  *
343  * \retval #PSA_SUCCESS
344  * \retval #PSA_ERROR_INVALID_HANDLE
345  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
346  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
347  * \retval #PSA_ERROR_CORRUPTION_DETECTED
348  * \retval #PSA_ERROR_STORAGE_FAILURE
349  * \retval #PSA_ERROR_BAD_STATE
350  * The library has not been previously initialized by psa_crypto_init().
351  * It is implementation-dependent whether a failure to initialize
352  * results in this error code.
353  */
354 psa_status_t psa_get_key_attributes(psa_key_handle_t handle,
355  psa_key_attributes_t *attributes);
356 
357 /** Reset a key attribute structure to a freshly initialized state.
358  *
359  * You must initialize the attribute structure as described in the
360  * documentation of the type #psa_key_attributes_t before calling this
361  * function. Once the structure has been initialized, you may call this
362  * function at any time.
363  *
364  * This function frees any auxiliary resources that the structure
365  * may contain.
366  *
367  * \param[in,out] attributes The attribute structure to reset.
368  */
369 void psa_reset_key_attributes(psa_key_attributes_t *attributes);
370 
371 /**@}*/
372 
373 /** \defgroup key_management Key management
374  * @{
375  */
376 
377 /** Open a handle to an existing persistent key.
378  *
379  * Open a handle to a persistent key. A key is persistent if it was created
380  * with a lifetime other than #PSA_KEY_LIFETIME_VOLATILE. A persistent key
381  * always has a nonzero key identifier, set with psa_set_key_id() when
382  * creating the key. Implementations may provide additional pre-provisioned
383  * keys that can be opened with psa_open_key(). Such keys have a key identifier
384  * in the vendor range, as documented in the description of #psa_key_id_t.
385  *
386  * The application must eventually close the handle with psa_close_key() or
387  * psa_destroy_key() to release associated resources. If the application dies
388  * without calling one of these functions, the implementation should perform
389  * the equivalent of a call to psa_close_key().
390  *
391  * Some implementations permit an application to open the same key multiple
392  * times. If this is successful, each call to psa_open_key() will return a
393  * different key handle.
394  *
395  * \note Applications that rely on opening a key multiple times will not be
396  * portable to implementations that only permit a single key handle to be
397  * opened. See also :ref:\`key-handles\`.
398  *
399  * \param id The persistent identifier of the key.
400  * \param[out] handle On success, a handle to the key.
401  *
402  * \retval #PSA_SUCCESS
403  * Success. The application can now use the value of `*handle`
404  * to access the key.
405  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
406  * The implementation does not have sufficient resources to open the
407  * key. This can be due to reaching an implementation limit on the
408  * number of open keys, the number of open key handles, or available
409  * memory.
410  * \retval #PSA_ERROR_DOES_NOT_EXIST
411  * There is no persistent key with key identifier \p id.
412  * \retval #PSA_ERROR_INVALID_ARGUMENT
413  * \p id is not a valid persistent key identifier.
414  * \retval #PSA_ERROR_NOT_PERMITTED
415  * The specified key exists, but the application does not have the
416  * permission to access it. Note that this specification does not
417  * define any way to create such a key, but it may be possible
418  * through implementation-specific means.
419  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
420  * \retval #PSA_ERROR_CORRUPTION_DETECTED
421  * \retval #PSA_ERROR_STORAGE_FAILURE
422  * \retval #PSA_ERROR_BAD_STATE
423  * The library has not been previously initialized by psa_crypto_init().
424  * It is implementation-dependent whether a failure to initialize
425  * results in this error code.
426  */
427 psa_status_t psa_open_key(psa_key_id_t id,
428  psa_key_handle_t *handle);
429 
430 
431 /** Close a key handle.
432  *
433  * If the handle designates a volatile key, this will destroy the key material
434  * and free all associated resources, just like psa_destroy_key().
435  *
436  * If this is the last open handle to a persistent key, then closing the handle
437  * will free all resources associated with the key in volatile memory. The key
438  * data in persistent storage is not affected and can be opened again later
439  * with a call to psa_open_key().
440  *
441  * Closing the key handle makes the handle invalid, and the key handle
442  * must not be used again by the application.
443  *
444  * \note If the key handle was used to set up an active
445  * :ref:\`multipart operation <multipart-operations>\`, then closing the
446  * key handle can cause the multipart operation to fail. Applications should
447  * maintain the key handle until after the multipart operation has finished.
448  *
449  * \param handle The key handle to close.
450  * If this is \c 0, do nothing and return \c PSA_SUCCESS.
451  *
452  * \retval #PSA_SUCCESS
453  * \p handle was a valid handle or \c 0. It is now closed.
454  * \retval #PSA_ERROR_INVALID_HANDLE
455  * \p handle is not a valid handle nor \c 0.
456  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
457  * \retval #PSA_ERROR_CORRUPTION_DETECTED
458  * \retval #PSA_ERROR_BAD_STATE
459  * The library has not been previously initialized by psa_crypto_init().
460  * It is implementation-dependent whether a failure to initialize
461  * results in this error code.
462  */
463 psa_status_t psa_close_key(psa_key_handle_t handle);
464 
465 /** Make a copy of a key.
466  *
467  * Copy key material from one location to another.
468  *
469  * This function is primarily useful to copy a key from one location
470  * to another, since it populates a key using the material from
471  * another key which may have a different lifetime.
472  *
473  * This function may be used to share a key with a different party,
474  * subject to implementation-defined restrictions on key sharing.
475  *
476  * The policy on the source key must have the usage flag
477  * #PSA_KEY_USAGE_COPY set.
478  * This flag is sufficient to permit the copy if the key has the lifetime
479  * #PSA_KEY_LIFETIME_VOLATILE or #PSA_KEY_LIFETIME_PERSISTENT.
480  * Some secure elements do not provide a way to copy a key without
481  * making it extractable from the secure element. If a key is located
482  * in such a secure element, then the key must have both usage flags
483  * #PSA_KEY_USAGE_COPY and #PSA_KEY_USAGE_EXPORT in order to make
484  * a copy of the key outside the secure element.
485  *
486  * The resulting key may only be used in a way that conforms to
487  * both the policy of the original key and the policy specified in
488  * the \p attributes parameter:
489  * - The usage flags on the resulting key are the bitwise-and of the
490  * usage flags on the source policy and the usage flags in \p attributes.
491  * - If both allow the same algorithm or wildcard-based
492  * algorithm policy, the resulting key has the same algorithm policy.
493  * - If either of the policies allows an algorithm and the other policy
494  * allows a wildcard-based algorithm policy that includes this algorithm,
495  * the resulting key allows the same algorithm.
496  * - If the policies do not allow any algorithm in common, this function
497  * fails with the status #PSA_ERROR_INVALID_ARGUMENT.
498  *
499  * The effect of this function on implementation-defined attributes is
500  * implementation-defined.
501  *
502  * \param source_handle The key to copy. It must be a valid key handle.
503  * \param[in] attributes The attributes for the new key.
504  * They are used as follows:
505  * - The key type and size may be 0. If either is
506  * nonzero, it must match the corresponding
507  * attribute of the source key.
508  * - The key location (the lifetime and, for
509  * persistent keys, the key identifier) is
510  * used directly.
511  * - The policy constraints (usage flags and
512  * algorithm policy) are combined from
513  * the source key and \p attributes so that
514  * both sets of restrictions apply, as
515  * described in the documentation of this function.
516  * \param[out] target_handle On success, a handle to the newly created key.
517  * \c 0 on failure.
518  *
519  * \retval #PSA_SUCCESS
520  * \retval #PSA_ERROR_INVALID_HANDLE
521  * \p source_handle is invalid.
522  * \retval #PSA_ERROR_ALREADY_EXISTS
523  * This is an attempt to create a persistent key, and there is
524  * already a persistent key with the given identifier.
525  * \retval #PSA_ERROR_INVALID_ARGUMENT
526  * The lifetime or identifier in \p attributes are invalid.
527  * \retval #PSA_ERROR_INVALID_ARGUMENT
528  * The policy constraints on the source and specified in
529  * \p attributes are incompatible.
530  * \retval #PSA_ERROR_INVALID_ARGUMENT
531  * \p attributes specifies a key type or key size
532  * which does not match the attributes of the source key.
533  * \retval #PSA_ERROR_NOT_PERMITTED
534  * The source key does not have the #PSA_KEY_USAGE_COPY usage flag.
535  * \retval #PSA_ERROR_NOT_PERMITTED
536  * The source key is not exportable and its lifetime does not
537  * allow copying it to the target's lifetime.
538  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
539  * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
540  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
541  * \retval #PSA_ERROR_HARDWARE_FAILURE
542  * \retval #PSA_ERROR_STORAGE_FAILURE
543  * \retval #PSA_ERROR_CORRUPTION_DETECTED
544  * \retval #PSA_ERROR_BAD_STATE
545  * The library has not been previously initialized by psa_crypto_init().
546  * It is implementation-dependent whether a failure to initialize
547  * results in this error code.
548  */
549 psa_status_t psa_copy_key(psa_key_handle_t source_handle,
550  const psa_key_attributes_t *attributes,
551  psa_key_handle_t *target_handle);
552 
553 
554 /**
555  * \brief Destroy a key.
556  *
557  * This function destroys a key from both volatile
558  * memory and, if applicable, non-volatile storage. Implementations shall
559  * make a best effort to ensure that that the key material cannot be recovered.
560  *
561  * This function also erases any metadata such as policies and frees
562  * resources associated with the key. To free all resources associated with
563  * the key, all handles to the key must be closed or destroyed.
564  *
565  * Destroying the key makes the handle invalid, and the key handle
566  * must not be used again by the application. Using other open handles to the
567  * destroyed key in a cryptographic operation will result in an error.
568  *
569  * If a key is currently in use in a multipart operation, then destroying the
570  * key will cause the multipart operation to fail.
571  *
572  * \param handle Handle to the key to erase.
573  * If this is \c 0, do nothing and return \c PSA_SUCCESS.
574  *
575  * \retval #PSA_SUCCESS
576  * \p handle was a valid handle and the key material that it
577  * referred to has been erased.
578  * Alternatively, \p handle is \c 0.
579  * \retval #PSA_ERROR_NOT_PERMITTED
580  * The key cannot be erased because it is
581  * read-only, either due to a policy or due to physical restrictions.
582  * \retval #PSA_ERROR_INVALID_HANDLE
583  * \p handle is not a valid handle nor \c 0.
584  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
585  * There was an failure in communication with the cryptoprocessor.
586  * The key material may still be present in the cryptoprocessor.
587  * \retval #PSA_ERROR_STORAGE_FAILURE
588  * The storage is corrupted. Implementations shall make a best effort
589  * to erase key material even in this stage, however applications
590  * should be aware that it may be impossible to guarantee that the
591  * key material is not recoverable in such cases.
592  * \retval #PSA_ERROR_CORRUPTION_DETECTED
593  * An unexpected condition which is not a storage corruption or
594  * a communication failure occurred. The cryptoprocessor may have
595  * been compromised.
596  * \retval #PSA_ERROR_BAD_STATE
597  * The library has not been previously initialized by psa_crypto_init().
598  * It is implementation-dependent whether a failure to initialize
599  * results in this error code.
600  */
601 psa_status_t psa_destroy_key(psa_key_handle_t handle);
602 
603 /**@}*/
604 
605 /** \defgroup import_export Key import and export
606  * @{
607  */
608 
609 /**
610  * \brief Import a key in binary format.
611  *
612  * This function supports any output from psa_export_key(). Refer to the
613  * documentation of psa_export_public_key() for the format of public keys
614  * and to the documentation of psa_export_key() for the format for
615  * other key types.
616  *
617  * The key data determines the key size. The attributes may optionally
618  * specify a key size; in this case it must match the size determined
619  * from the key data. A key size of 0 in \p attributes indicates that
620  * the key size is solely determined by the key data.
621  *
622  * Implementations must reject an attempt to import a key of size 0.
623  *
624  * This specification supports a single format for each key type.
625  * Implementations may support other formats as long as the standard
626  * format is supported. Implementations that support other formats
627  * should ensure that the formats are clearly unambiguous so as to
628  * minimize the risk that an invalid input is accidentally interpreted
629  * according to a different format.
630  *
631  * \param[in] attributes The attributes for the new key.
632  * The key size is always determined from the
633  * \p data buffer.
634  * If the key size in \p attributes is nonzero,
635  * it must be equal to the size from \p data.
636  * \param[out] handle On success, a handle to the newly created key.
637  * \c 0 on failure.
638  * \param[in] data Buffer containing the key data. The content of this
639  * buffer is interpreted according to the type declared
640  * in \p attributes.
641  * All implementations must support at least the format
642  * described in the documentation
643  * of psa_export_key() or psa_export_public_key() for
644  * the chosen type. Implementations may allow other
645  * formats, but should be conservative: implementations
646  * should err on the side of rejecting content if it
647  * may be erroneous (e.g. wrong type or truncated data).
648  * \param data_length Size of the \p data buffer in bytes.
649  *
650  * \retval #PSA_SUCCESS
651  * Success.
652  * If the key is persistent, the key material and the key's metadata
653  * have been saved to persistent storage.
654  * \retval #PSA_ERROR_ALREADY_EXISTS
655  * This is an attempt to create a persistent key, and there is
656  * already a persistent key with the given identifier.
657  * \retval #PSA_ERROR_NOT_SUPPORTED
658  * The key type or key size is not supported, either by the
659  * implementation in general or in this particular persistent location.
660  * \retval #PSA_ERROR_INVALID_ARGUMENT
661  * The key attributes, as a whole, are invalid.
662  * \retval #PSA_ERROR_INVALID_ARGUMENT
663  * The key data is not correctly formatted.
664  * \retval #PSA_ERROR_INVALID_ARGUMENT
665  * The size in \p attributes is nonzero and does not match the size
666  * of the key data.
667  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
668  * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
669  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
670  * \retval #PSA_ERROR_STORAGE_FAILURE
671  * \retval #PSA_ERROR_HARDWARE_FAILURE
672  * \retval #PSA_ERROR_CORRUPTION_DETECTED
673  * \retval #PSA_ERROR_BAD_STATE
674  * The library has not been previously initialized by psa_crypto_init().
675  * It is implementation-dependent whether a failure to initialize
676  * results in this error code.
677  */
678 psa_status_t psa_import_key(const psa_key_attributes_t *attributes,
679  const uint8_t *data,
680  size_t data_length,
681  psa_key_handle_t *handle);
682 
683 
684 
685 /**
686  * \brief Export a key in binary format.
687  *
688  * The output of this function can be passed to psa_import_key() to
689  * create an equivalent object.
690  *
691  * If the implementation of psa_import_key() supports other formats
692  * beyond the format specified here, the output from psa_export_key()
693  * must use the representation specified here, not the original
694  * representation.
695  *
696  * For standard key types, the output format is as follows:
697  *
698  * - For symmetric keys (including MAC keys), the format is the
699  * raw bytes of the key.
700  * - For DES, the key data consists of 8 bytes. The parity bits must be
701  * correct.
702  * - For Triple-DES, the format is the concatenation of the
703  * two or three DES keys.
704  * - For RSA key pairs (#PSA_KEY_TYPE_RSA_KEY_PAIR), the format
705  * is the non-encrypted DER encoding of the representation defined by
706  * PKCS\#1 (RFC 8017) as `RSAPrivateKey`, version 0.
707  * ```
708  * RSAPrivateKey ::= SEQUENCE {
709  * version INTEGER, -- must be 0
710  * modulus INTEGER, -- n
711  * publicExponent INTEGER, -- e
712  * privateExponent INTEGER, -- d
713  * prime1 INTEGER, -- p
714  * prime2 INTEGER, -- q
715  * exponent1 INTEGER, -- d mod (p-1)
716  * exponent2 INTEGER, -- d mod (q-1)
717  * coefficient INTEGER, -- (inverse of q) mod p
718  * }
719  * ```
720  * - For elliptic curve key pairs (key types for which
721  * #PSA_KEY_TYPE_IS_ECC_KEY_PAIR is true), the format is
722  * a representation of the private value as a `ceiling(m/8)`-byte string
723  * where `m` is the bit size associated with the curve, i.e. the bit size
724  * of the order of the curve's coordinate field. This byte string is
725  * in little-endian order for Montgomery curves (curve types
726  * `PSA_ECC_FAMILY_CURVEXXX`), and in big-endian order for Weierstrass
727  * curves (curve types `PSA_ECC_FAMILY_SECTXXX`, `PSA_ECC_FAMILY_SECPXXX`
728  * and `PSA_ECC_FAMILY_BRAINPOOL_PXXX`).
729  * For Weierstrass curves, this is the content of the `privateKey` field of
730  * the `ECPrivateKey` format defined by RFC 5915. For Montgomery curves,
731  * the format is defined by RFC 7748, and output is masked according to §5.
732  * - For Diffie-Hellman key exchange key pairs (key types for which
733  * #PSA_KEY_TYPE_IS_DH_KEY_PAIR is true), the
734  * format is the representation of the private key `x` as a big-endian byte
735  * string. The length of the byte string is the private key size in bytes
736  * (leading zeroes are not stripped).
737  * - For public keys (key types for which #PSA_KEY_TYPE_IS_PUBLIC_KEY is
738  * true), the format is the same as for psa_export_public_key().
739  *
740  * The policy on the key must have the usage flag #PSA_KEY_USAGE_EXPORT set.
741  *
742  * \param handle Handle to the key to export.
743  * \param[out] data Buffer where the key data is to be written.
744  * \param data_size Size of the \p data buffer in bytes.
745  * \param[out] data_length On success, the number of bytes
746  * that make up the key data.
747  *
748  * \retval #PSA_SUCCESS
749  * \retval #PSA_ERROR_INVALID_HANDLE
750  * \retval #PSA_ERROR_NOT_PERMITTED
751  * The key does not have the #PSA_KEY_USAGE_EXPORT flag.
752  * \retval #PSA_ERROR_NOT_SUPPORTED
753  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
754  * The size of the \p data buffer is too small. You can determine a
755  * sufficient buffer size by calling
756  * #PSA_KEY_EXPORT_MAX_SIZE(\c type, \c bits)
757  * where \c type is the key type
758  * and \c bits is the key size in bits.
759  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
760  * \retval #PSA_ERROR_HARDWARE_FAILURE
761  * \retval #PSA_ERROR_CORRUPTION_DETECTED
762  * \retval #PSA_ERROR_STORAGE_FAILURE
763  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
764  * \retval #PSA_ERROR_BAD_STATE
765  * The library has not been previously initialized by psa_crypto_init().
766  * It is implementation-dependent whether a failure to initialize
767  * results in this error code.
768  */
769 psa_status_t psa_export_key(psa_key_handle_t handle,
770  uint8_t *data,
771  size_t data_size,
772  size_t *data_length);
773 
774 /**
775  * \brief Export a public key or the public part of a key pair in binary format.
776  *
777  * The output of this function can be passed to psa_import_key() to
778  * create an object that is equivalent to the public key.
779  *
780  * This specification supports a single format for each key type.
781  * Implementations may support other formats as long as the standard
782  * format is supported. Implementations that support other formats
783  * should ensure that the formats are clearly unambiguous so as to
784  * minimize the risk that an invalid input is accidentally interpreted
785  * according to a different format.
786  *
787  * For standard key types, the output format is as follows:
788  * - For RSA public keys (#PSA_KEY_TYPE_RSA_PUBLIC_KEY), the DER encoding of
789  * the representation defined by RFC 3279 &sect;2.3.1 as `RSAPublicKey`.
790  * ```
791  * RSAPublicKey ::= SEQUENCE {
792  * modulus INTEGER, -- n
793  * publicExponent INTEGER } -- e
794  * ```
795  * - For elliptic curve public keys (key types for which
796  * #PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY is true), the format is the uncompressed
797  * representation defined by SEC1 &sect;2.3.3 as the content of an ECPoint.
798  * Let `m` be the bit size associated with the curve, i.e. the bit size of
799  * `q` for a curve over `F_q`. The representation consists of:
800  * - The byte 0x04;
801  * - `x_P` as a `ceiling(m/8)`-byte string, big-endian;
802  * - `y_P` as a `ceiling(m/8)`-byte string, big-endian.
803  * - For Diffie-Hellman key exchange public keys (key types for which
804  * #PSA_KEY_TYPE_IS_DH_PUBLIC_KEY is true),
805  * the format is the representation of the public key `y = g^x mod p` as a
806  * big-endian byte string. The length of the byte string is the length of the
807  * base prime `p` in bytes.
808  *
809  * Exporting a public key object or the public part of a key pair is
810  * always permitted, regardless of the key's usage flags.
811  *
812  * \param handle Handle to the key to export.
813  * \param[out] data Buffer where the key data is to be written.
814  * \param data_size Size of the \p data buffer in bytes.
815  * \param[out] data_length On success, the number of bytes
816  * that make up the key data.
817  *
818  * \retval #PSA_SUCCESS
819  * \retval #PSA_ERROR_INVALID_HANDLE
820  * \retval #PSA_ERROR_INVALID_ARGUMENT
821  * The key is neither a public key nor a key pair.
822  * \retval #PSA_ERROR_NOT_SUPPORTED
823  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
824  * The size of the \p data buffer is too small. You can determine a
825  * sufficient buffer size by calling
826  * #PSA_KEY_EXPORT_MAX_SIZE(#PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(\c type), \c bits)
827  * where \c type is the key type
828  * and \c bits is the key size in bits.
829  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
830  * \retval #PSA_ERROR_HARDWARE_FAILURE
831  * \retval #PSA_ERROR_CORRUPTION_DETECTED
832  * \retval #PSA_ERROR_STORAGE_FAILURE
833  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
834  * \retval #PSA_ERROR_BAD_STATE
835  * The library has not been previously initialized by psa_crypto_init().
836  * It is implementation-dependent whether a failure to initialize
837  * results in this error code.
838  */
839 psa_status_t psa_export_public_key(psa_key_handle_t handle,
840  uint8_t *data,
841  size_t data_size,
842  size_t *data_length);
843 
844 
845 
846 /**@}*/
847 
848 /** \defgroup hash Message digests
849  * @{
850  */
851 
852 /** Calculate the hash (digest) of a message.
853  *
854  * \note To verify the hash of a message against an
855  * expected value, use psa_hash_compare() instead.
856  *
857  * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value
858  * such that #PSA_ALG_IS_HASH(\p alg) is true).
859  * \param[in] input Buffer containing the message to hash.
860  * \param input_length Size of the \p input buffer in bytes.
861  * \param[out] hash Buffer where the hash is to be written.
862  * \param hash_size Size of the \p hash buffer in bytes.
863  * \param[out] hash_length On success, the number of bytes
864  * that make up the hash value. This is always
865  * #PSA_HASH_SIZE(\p alg).
866  *
867  * \retval #PSA_SUCCESS
868  * Success.
869  * \retval #PSA_ERROR_NOT_SUPPORTED
870  * \p alg is not supported or is not a hash algorithm.
871  * \retval #PSA_ERROR_INVALID_ARGUMENT
872  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
873  * \p hash_size is too small
874  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
875  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
876  * \retval #PSA_ERROR_HARDWARE_FAILURE
877  * \retval #PSA_ERROR_CORRUPTION_DETECTED
878  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
879  * \retval #PSA_ERROR_BAD_STATE
880  * The library has not been previously initialized by psa_crypto_init().
881  * It is implementation-dependent whether a failure to initialize
882  * results in this error code.
883  */
884 psa_status_t psa_hash_compute(psa_algorithm_t alg,
885  const uint8_t *input,
886  size_t input_length,
887  uint8_t *hash,
888  size_t hash_size,
889  size_t *hash_length);
890 
891 /** Calculate the hash (digest) of a message and compare it with a
892  * reference value.
893  *
894  * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value
895  * such that #PSA_ALG_IS_HASH(\p alg) is true).
896  * \param[in] input Buffer containing the message to hash.
897  * \param input_length Size of the \p input buffer in bytes.
898  * \param[out] hash Buffer containing the expected hash value.
899  * \param hash_length Size of the \p hash buffer in bytes.
900  *
901  * \retval #PSA_SUCCESS
902  * The expected hash is identical to the actual hash of the input.
903  * \retval #PSA_ERROR_INVALID_SIGNATURE
904  * The hash of the message was calculated successfully, but it
905  * differs from the expected hash.
906  * \retval #PSA_ERROR_NOT_SUPPORTED
907  * \p alg is not supported or is not a hash algorithm.
908  * \retval #PSA_ERROR_INVALID_ARGUMENT
909  * \p input_length or \p hash_length do not match the hash size for \p alg
910  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
911  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
912  * \retval #PSA_ERROR_HARDWARE_FAILURE
913  * \retval #PSA_ERROR_CORRUPTION_DETECTED
914  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
915  * \retval #PSA_ERROR_BAD_STATE
916  * The library has not been previously initialized by psa_crypto_init().
917  * It is implementation-dependent whether a failure to initialize
918  * results in this error code.
919  */
920 psa_status_t psa_hash_compare(psa_algorithm_t alg,
921  const uint8_t *input,
922  size_t input_length,
923  const uint8_t *hash,
924  size_t hash_length);
925 
926 /** The type of the state data structure for multipart hash operations.
927  *
928  * Before calling any function on a hash operation object, the application must
929  * initialize it by any of the following means:
930  * - Set the structure to all-bits-zero, for example:
931  * \code
932  * psa_hash_operation_t operation;
933  * memset(&operation, 0, sizeof(operation));
934  * \endcode
935  * - Initialize the structure to logical zero values, for example:
936  * \code
937  * psa_hash_operation_t operation = {0};
938  * \endcode
939  * - Initialize the structure to the initializer #PSA_HASH_OPERATION_INIT,
940  * for example:
941  * \code
942  * psa_hash_operation_t operation = PSA_HASH_OPERATION_INIT;
943  * \endcode
944  * - Assign the result of the function psa_hash_operation_init()
945  * to the structure, for example:
946  * \code
947  * psa_hash_operation_t operation;
948  * operation = psa_hash_operation_init();
949  * \endcode
950  *
951  * This is an implementation-defined \c struct. Applications should not
952  * make any assumptions about the content of this structure except
953  * as directed by the documentation of a specific implementation. */
954 typedef struct psa_hash_operation_s psa_hash_operation_t;
955 
956 /** \def PSA_HASH_OPERATION_INIT
957  *
958  * This macro returns a suitable initializer for a hash operation object
959  * of type #psa_hash_operation_t.
960  */
961 #ifdef __DOXYGEN_ONLY__
962 /* This is an example definition for documentation purposes.
963  * Implementations should define a suitable value in `crypto_struct.h`.
964  */
965 #define PSA_HASH_OPERATION_INIT {0}
966 #endif
967 
968 /** Return an initial value for a hash operation object.
969  */
970 static psa_hash_operation_t psa_hash_operation_init(void);
971 
972 /** Set up a multipart hash operation.
973  *
974  * The sequence of operations to calculate a hash (message digest)
975  * is as follows:
976  * -# Allocate an operation object which will be passed to all the functions
977  * listed here.
978  * -# Initialize the operation object with one of the methods described in the
979  * documentation for #psa_hash_operation_t, e.g. #PSA_HASH_OPERATION_INIT.
980  * -# Call psa_hash_setup() to specify the algorithm.
981  * -# Call psa_hash_update() zero, one or more times, passing a fragment
982  * of the message each time. The hash that is calculated is the hash
983  * of the concatenation of these messages in order.
984  * -# To calculate the hash, call psa_hash_finish().
985  * To compare the hash with an expected value, call psa_hash_verify().
986  *
987  * If an error occurs at any step after a call to psa_hash_setup(), the
988  * operation will need to be reset by a call to psa_hash_abort(). The
989  * application may call psa_hash_abort() at any time after the operation
990  * has been initialized.
991  *
992  * After a successful call to psa_hash_setup(), the application must
993  * eventually terminate the operation. The following events terminate an
994  * operation:
995  * - A successful call to psa_hash_finish() or psa_hash_verify().
996  * - A call to psa_hash_abort().
997  *
998  * \param[in,out] operation The operation object to set up. It must have
999  * been initialized as per the documentation for
1000  * #psa_hash_operation_t and not yet in use.
1001  * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value
1002  * such that #PSA_ALG_IS_HASH(\p alg) is true).
1003  *
1004  * \retval #PSA_SUCCESS
1005  * Success.
1006  * \retval #PSA_ERROR_NOT_SUPPORTED
1007  * \p alg is not a supported hash algorithm.
1008  * \retval #PSA_ERROR_INVALID_ARGUMENT
1009  * \p alg is not a hash algorithm.
1010  * \retval #PSA_ERROR_BAD_STATE
1011  * The operation state is not valid (it must be inactive).
1012  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1013  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1014  * \retval #PSA_ERROR_HARDWARE_FAILURE
1015  * \retval #PSA_ERROR_CORRUPTION_DETECTED
1016  * \retval #PSA_ERROR_BAD_STATE
1017  * The library has not been previously initialized by psa_crypto_init().
1018  * It is implementation-dependent whether a failure to initialize
1019  * results in this error code.
1020  */
1021 psa_status_t psa_hash_setup(psa_hash_operation_t *operation,
1022  psa_algorithm_t alg);
1023 
1024 /** Add a message fragment to a multipart hash operation.
1025  *
1026  * The application must call psa_hash_setup() before calling this function.
1027  *
1028  * If this function returns an error status, the operation enters an error
1029  * state and must be aborted by calling psa_hash_abort().
1030  *
1031  * \param[in,out] operation Active hash operation.
1032  * \param[in] input Buffer containing the message fragment to hash.
1033  * \param input_length Size of the \p input buffer in bytes.
1034  *
1035  * \retval #PSA_SUCCESS
1036  * Success.
1037  * \retval #PSA_ERROR_BAD_STATE
1038  * The operation state is not valid (it muct be active).
1039  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1040  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1041  * \retval #PSA_ERROR_HARDWARE_FAILURE
1042  * \retval #PSA_ERROR_CORRUPTION_DETECTED
1043  * \retval #PSA_ERROR_BAD_STATE
1044  * 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.
1047  */
1048 psa_status_t psa_hash_update(psa_hash_operation_t *operation,
1049  const uint8_t *input,
1050  size_t input_length);
1051 
1052 /** Finish the calculation of the hash of a message.
1053  *
1054  * The application must call psa_hash_setup() before calling this function.
1055  * This function calculates the hash of the message formed by concatenating
1056  * the inputs passed to preceding calls to psa_hash_update().
1057  *
1058  * When this function returns successfuly, the operation becomes inactive.
1059  * If this function returns an error status, the operation enters an error
1060  * state and must be aborted by calling psa_hash_abort().
1061  *
1062  * \warning Applications should not call this function if they expect
1063  * a specific value for the hash. Call psa_hash_verify() instead.
1064  * Beware that comparing integrity or authenticity data such as
1065  * hash values with a function such as \c memcmp is risky
1066  * because the time taken by the comparison may leak information
1067  * about the hashed data which could allow an attacker to guess
1068  * a valid hash and thereby bypass security controls.
1069  *
1070  * \param[in,out] operation Active hash operation.
1071  * \param[out] hash Buffer where the hash is to be written.
1072  * \param hash_size Size of the \p hash buffer in bytes.
1073  * \param[out] hash_length On success, the number of bytes
1074  * that make up the hash value. This is always
1075  * #PSA_HASH_SIZE(\c alg) where \c alg is the
1076  * hash algorithm that is calculated.
1077  *
1078  * \retval #PSA_SUCCESS
1079  * Success.
1080  * \retval #PSA_ERROR_BAD_STATE
1081  * The operation state is not valid (it must be active).
1082  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1083  * The size of the \p hash buffer is too small. You can determine a
1084  * sufficient buffer size by calling #PSA_HASH_SIZE(\c alg)
1085  * where \c alg is the hash algorithm that is calculated.
1086  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1087  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1088  * \retval #PSA_ERROR_HARDWARE_FAILURE
1089  * \retval #PSA_ERROR_CORRUPTION_DETECTED
1090  * \retval #PSA_ERROR_BAD_STATE
1091  * The library has not been previously initialized by psa_crypto_init().
1092  * It is implementation-dependent whether a failure to initialize
1093  * results in this error code.
1094  */
1095 psa_status_t psa_hash_finish(psa_hash_operation_t *operation,
1096  uint8_t *hash,
1097  size_t hash_size,
1098  size_t *hash_length);
1099 
1100 /** Finish the calculation of the hash of a message and compare it with
1101  * an expected value.
1102  *
1103  * The application must call psa_hash_setup() before calling this function.
1104  * This function calculates the hash of the message formed by concatenating
1105  * the inputs passed to preceding calls to psa_hash_update(). It then
1106  * compares the calculated hash with the expected hash passed as a
1107  * parameter to this function.
1108  *
1109  * When this function returns successfuly, the operation becomes inactive.
1110  * If this function returns an error status, the operation enters an error
1111  * state and must be aborted by calling psa_hash_abort().
1112  *
1113  * \note Implementations shall make the best effort to ensure that the
1114  * comparison between the actual hash and the expected hash is performed
1115  * in constant time.
1116  *
1117  * \param[in,out] operation Active hash operation.
1118  * \param[in] hash Buffer containing the expected hash value.
1119  * \param hash_length Size of the \p hash buffer in bytes.
1120  *
1121  * \retval #PSA_SUCCESS
1122  * The expected hash is identical to the actual hash of the message.
1123  * \retval #PSA_ERROR_INVALID_SIGNATURE
1124  * The hash of the message was calculated successfully, but it
1125  * differs from the expected hash.
1126  * \retval #PSA_ERROR_BAD_STATE
1127  * The operation state is not valid (it must be active).
1128  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1129  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1130  * \retval #PSA_ERROR_HARDWARE_FAILURE
1131  * \retval #PSA_ERROR_CORRUPTION_DETECTED
1132  * \retval #PSA_ERROR_BAD_STATE
1133  * The library has not been previously initialized by psa_crypto_init().
1134  * It is implementation-dependent whether a failure to initialize
1135  * results in this error code.
1136  */
1137 psa_status_t psa_hash_verify(psa_hash_operation_t *operation,
1138  const uint8_t *hash,
1139  size_t hash_length);
1140 
1141 /** Abort a hash operation.
1142  *
1143  * Aborting an operation frees all associated resources except for the
1144  * \p operation structure itself. Once aborted, the operation object
1145  * can be reused for another operation by calling
1146  * psa_hash_setup() again.
1147  *
1148  * You may call this function any time after the operation object has
1149  * been initialized by one of the methods described in #psa_hash_operation_t.
1150  *
1151  * In particular, calling psa_hash_abort() after the operation has been
1152  * terminated by a call to psa_hash_abort(), psa_hash_finish() or
1153  * psa_hash_verify() is safe and has no effect.
1154  *
1155  * \param[in,out] operation Initialized hash operation.
1156  *
1157  * \retval #PSA_SUCCESS
1158  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1159  * \retval #PSA_ERROR_HARDWARE_FAILURE
1160  * \retval #PSA_ERROR_CORRUPTION_DETECTED
1161  * \retval #PSA_ERROR_BAD_STATE
1162  * The library has not been previously initialized by psa_crypto_init().
1163  * It is implementation-dependent whether a failure to initialize
1164  * results in this error code.
1165  */
1166 psa_status_t psa_hash_abort(psa_hash_operation_t *operation);
1167 
1168 /** Clone a hash operation.
1169  *
1170  * This function copies the state of an ongoing hash operation to
1171  * a new operation object. In other words, this function is equivalent
1172  * to calling psa_hash_setup() on \p target_operation with the same
1173  * algorithm that \p source_operation was set up for, then
1174  * psa_hash_update() on \p target_operation with the same input that
1175  * that was passed to \p source_operation. After this function returns, the
1176  * two objects are independent, i.e. subsequent calls involving one of
1177  * the objects do not affect the other object.
1178  *
1179  * \param[in] source_operation The active hash operation to clone.
1180  * \param[in,out] target_operation The operation object to set up.
1181  * It must be initialized but not active.
1182  *
1183  * \retval #PSA_SUCCESS
1184  * \retval #PSA_ERROR_BAD_STATE
1185  * The \p source_operation state is not valid (it must be active).
1186  * \retval #PSA_ERROR_BAD_STATE
1187  * The \p target_operation state is not valid (it must be inactive).
1188  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1189  * \retval #PSA_ERROR_HARDWARE_FAILURE
1190  * \retval #PSA_ERROR_CORRUPTION_DETECTED
1191  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1192  * \retval #PSA_ERROR_BAD_STATE
1193  * The library has not been previously initialized by psa_crypto_init().
1194  * It is implementation-dependent whether a failure to initialize
1195  * results in this error code.
1196  */
1197 psa_status_t psa_hash_clone(const psa_hash_operation_t *source_operation,
1198  psa_hash_operation_t *target_operation);
1199 
1200 /**@}*/
1201 
1202 /** \defgroup MAC Message authentication codes
1203  * @{
1204  */
1205 
1206 /** Calculate the MAC (message authentication code) of a message.
1207  *
1208  * \note To verify the MAC of a message against an
1209  * expected value, use psa_mac_verify() instead.
1210  * Beware that comparing integrity or authenticity data such as
1211  * MAC values with a function such as \c memcmp is risky
1212  * because the time taken by the comparison may leak information
1213  * about the MAC value which could allow an attacker to guess
1214  * a valid MAC and thereby bypass security controls.
1215  *
1216  * \param handle Handle to the key to use for the operation.
1217  * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
1218  * such that #PSA_ALG_IS_MAC(\p alg) is true).
1219  * \param[in] input Buffer containing the input message.
1220  * \param input_length Size of the \p input buffer in bytes.
1221  * \param[out] mac Buffer where the MAC value is to be written.
1222  * \param mac_size Size of the \p mac buffer in bytes.
1223  * \param[out] mac_length On success, the number of bytes
1224  * that make up the MAC value.
1225  *
1226  * \retval #PSA_SUCCESS
1227  * Success.
1228  * \retval #PSA_ERROR_INVALID_HANDLE
1229  * \retval #PSA_ERROR_NOT_PERMITTED
1230  * \retval #PSA_ERROR_INVALID_ARGUMENT
1231  * \p handle is not compatible with \p alg.
1232  * \retval #PSA_ERROR_NOT_SUPPORTED
1233  * \p alg is not supported or is not a MAC algorithm.
1234  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1235  * \p mac_size is too small
1236  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1237  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1238  * \retval #PSA_ERROR_HARDWARE_FAILURE
1239  * \retval #PSA_ERROR_CORRUPTION_DETECTED
1240  * \retval #PSA_ERROR_STORAGE_FAILURE
1241  * The key could not be retrieved from storage.
1242  * \retval #PSA_ERROR_BAD_STATE
1243  * The library has not been previously initialized by psa_crypto_init().
1244  * It is implementation-dependent whether a failure to initialize
1245  * results in this error code.
1246  */
1247 psa_status_t psa_mac_compute(psa_key_handle_t handle,
1248  psa_algorithm_t alg,
1249  const uint8_t *input,
1250  size_t input_length,
1251  uint8_t *mac,
1252  size_t mac_size,
1253  size_t *mac_length);
1254 
1255 /** Calculate the MAC of a message and compare it with a reference value.
1256  *
1257  * \param handle Handle to the key to use for the operation.
1258  * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
1259  * such that #PSA_ALG_IS_MAC(\p alg) is true).
1260  * \param[in] input Buffer containing the input message.
1261  * \param input_length Size of the \p input buffer in bytes.
1262  * \param[out] mac Buffer containing the expected MAC value.
1263  * \param mac_length Size of the \p mac buffer in bytes.
1264  *
1265  * \retval #PSA_SUCCESS
1266  * The expected MAC is identical to the actual MAC of the input.
1267  * \retval #PSA_ERROR_INVALID_SIGNATURE
1268  * The MAC of the message was calculated successfully, but it
1269  * differs from the expected value.
1270  * \retval #PSA_ERROR_INVALID_HANDLE
1271  * \retval #PSA_ERROR_NOT_PERMITTED
1272  * \retval #PSA_ERROR_INVALID_ARGUMENT
1273  * \p handle is not compatible with \p alg.
1274  * \retval #PSA_ERROR_NOT_SUPPORTED
1275  * \p alg is not supported or is not a MAC algorithm.
1276  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1277  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1278  * \retval #PSA_ERROR_HARDWARE_FAILURE
1279  * \retval #PSA_ERROR_CORRUPTION_DETECTED
1280  * \retval #PSA_ERROR_STORAGE_FAILURE
1281  * The key could not be retrieved from storage.
1282  * \retval #PSA_ERROR_BAD_STATE
1283  * The library has not been previously initialized by psa_crypto_init().
1284  * It is implementation-dependent whether a failure to initialize
1285  * results in this error code.
1286  */
1287 psa_status_t psa_mac_verify(psa_key_handle_t handle,
1288  psa_algorithm_t alg,
1289  const uint8_t *input,
1290  size_t input_length,
1291  const uint8_t *mac,
1292  size_t mac_length);
1293 
1294 /** The type of the state data structure for multipart MAC operations.
1295  *
1296  * Before calling any function on a MAC operation object, the application must
1297  * initialize it by any of the following means:
1298  * - Set the structure to all-bits-zero, for example:
1299  * \code
1300  * psa_mac_operation_t operation;
1301  * memset(&operation, 0, sizeof(operation));
1302  * \endcode
1303  * - Initialize the structure to logical zero values, for example:
1304  * \code
1305  * psa_mac_operation_t operation = {0};
1306  * \endcode
1307  * - Initialize the structure to the initializer #PSA_MAC_OPERATION_INIT,
1308  * for example:
1309  * \code
1310  * psa_mac_operation_t operation = PSA_MAC_OPERATION_INIT;
1311  * \endcode
1312  * - Assign the result of the function psa_mac_operation_init()
1313  * to the structure, for example:
1314  * \code
1315  * psa_mac_operation_t operation;
1316  * operation = psa_mac_operation_init();
1317  * \endcode
1318  *
1319  * This is an implementation-defined \c struct. Applications should not
1320  * make any assumptions about the content of this structure except
1321  * as directed by the documentation of a specific implementation. */
1322 typedef struct psa_mac_operation_s psa_mac_operation_t;
1323 
1324 /** \def PSA_MAC_OPERATION_INIT
1325  *
1326  * This macro returns a suitable initializer for a MAC operation object of type
1327  * #psa_mac_operation_t.
1328  */
1329 #ifdef __DOXYGEN_ONLY__
1330 /* This is an example definition for documentation purposes.
1331  * Implementations should define a suitable value in `crypto_struct.h`.
1332  */
1333 #define PSA_MAC_OPERATION_INIT {0}
1334 #endif
1335 
1336 /** Return an initial value for a MAC operation object.
1337  */
1338 static psa_mac_operation_t psa_mac_operation_init(void);
1339 
1340 /** Set up a multipart MAC calculation operation.
1341  *
1342  * This function sets up the calculation of the MAC
1343  * (message authentication code) of a byte string.
1344  * To verify the MAC of a message against an
1345  * expected value, use psa_mac_verify_setup() instead.
1346  *
1347  * The sequence of operations to calculate a MAC is as follows:
1348  * -# Allocate an operation object which will be passed to all the functions
1349  * listed here.
1350  * -# Initialize the operation object with one of the methods described in the
1351  * documentation for #psa_mac_operation_t, e.g. #PSA_MAC_OPERATION_INIT.
1352  * -# Call psa_mac_sign_setup() to specify the algorithm and key.
1353  * -# Call psa_mac_update() zero, one or more times, passing a fragment
1354  * of the message each time. The MAC that is calculated is the MAC
1355  * of the concatenation of these messages in order.
1356  * -# At the end of the message, call psa_mac_sign_finish() to finish
1357  * calculating the MAC value and retrieve it.
1358  *
1359  * If an error occurs at any step after a call to psa_mac_sign_setup(), the
1360  * operation will need to be reset by a call to psa_mac_abort(). The
1361  * application may call psa_mac_abort() at any time after the operation
1362  * has been initialized.
1363  *
1364  * After a successful call to psa_mac_sign_setup(), the application must
1365  * eventually terminate the operation through one of the following methods:
1366  * - A successful call to psa_mac_sign_finish().
1367  * - A call to psa_mac_abort().
1368  *
1369  * \param[in,out] operation The operation object to set up. It must have
1370  * been initialized as per the documentation for
1371  * #psa_mac_operation_t and not yet in use.
1372  * \param handle Handle to the key to use for the operation.
1373  * It must remain valid until the operation
1374  * terminates.
1375  * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
1376  * such that #PSA_ALG_IS_MAC(\p alg) is true).
1377  *
1378  * \retval #PSA_SUCCESS
1379  * Success.
1380  * \retval #PSA_ERROR_INVALID_HANDLE
1381  * \retval #PSA_ERROR_NOT_PERMITTED
1382  * \retval #PSA_ERROR_INVALID_ARGUMENT
1383  * \p handle is not compatible with \p alg.
1384  * \retval #PSA_ERROR_NOT_SUPPORTED
1385  * \p alg is not supported or is not a MAC algorithm.
1386  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1387  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1388  * \retval #PSA_ERROR_HARDWARE_FAILURE
1389  * \retval #PSA_ERROR_CORRUPTION_DETECTED
1390  * \retval #PSA_ERROR_STORAGE_FAILURE
1391  * The key could not be retrieved from storage.
1392  * \retval #PSA_ERROR_BAD_STATE
1393  * The operation state is not valid (it must be inactive).
1394  * \retval #PSA_ERROR_BAD_STATE
1395  * The library has not been previously initialized by psa_crypto_init().
1396  * It is implementation-dependent whether a failure to initialize
1397  * results in this error code.
1398  */
1399 psa_status_t psa_mac_sign_setup(psa_mac_operation_t *operation,
1400  psa_key_handle_t handle,
1401  psa_algorithm_t alg);
1402 
1403 /** Set up a multipart MAC verification operation.
1404  *
1405  * This function sets up the verification of the MAC
1406  * (message authentication code) of a byte string against an expected value.
1407  *
1408  * The sequence of operations to verify a MAC is as follows:
1409  * -# Allocate an operation object which will be passed to all the functions
1410  * listed here.
1411  * -# Initialize the operation object with one of the methods described in the
1412  * documentation for #psa_mac_operation_t, e.g. #PSA_MAC_OPERATION_INIT.
1413  * -# Call psa_mac_verify_setup() to specify the algorithm and key.
1414  * -# Call psa_mac_update() zero, one or more times, passing a fragment
1415  * of the message each time. The MAC that is calculated is the MAC
1416  * of the concatenation of these messages in order.
1417  * -# At the end of the message, call psa_mac_verify_finish() to finish
1418  * calculating the actual MAC of the message and verify it against
1419  * the expected value.
1420  *
1421  * If an error occurs at any step after a call to psa_mac_verify_setup(), the
1422  * operation will need to be reset by a call to psa_mac_abort(). The
1423  * application may call psa_mac_abort() at any time after the operation
1424  * has been initialized.
1425  *
1426  * After a successful call to psa_mac_verify_setup(), the application must
1427  * eventually terminate the operation through one of the following methods:
1428  * - A successful call to psa_mac_verify_finish().
1429  * - A call to psa_mac_abort().
1430  *
1431  * \param[in,out] operation The operation object to set up. It must have
1432  * been initialized as per the documentation for
1433  * #psa_mac_operation_t and not yet in use.
1434  * \param handle Handle to the key to use for the operation.
1435  * It must remain valid until the operation
1436  * terminates.
1437  * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
1438  * such that #PSA_ALG_IS_MAC(\p alg) is true).
1439  *
1440  * \retval #PSA_SUCCESS
1441  * Success.
1442  * \retval #PSA_ERROR_INVALID_HANDLE
1443  * \retval #PSA_ERROR_NOT_PERMITTED
1444  * \retval #PSA_ERROR_INVALID_ARGUMENT
1445  * \c key is not compatible with \c alg.
1446  * \retval #PSA_ERROR_NOT_SUPPORTED
1447  * \c alg is not supported or is not a MAC algorithm.
1448  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1449  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1450  * \retval #PSA_ERROR_HARDWARE_FAILURE
1451  * \retval #PSA_ERROR_CORRUPTION_DETECTED
1452  * \retval #PSA_ERROR_STORAGE_FAILURE
1453  * The key could not be retrieved from storage
1454  * \retval #PSA_ERROR_BAD_STATE
1455  * The operation state is not valid (it must be inactive).
1456  * \retval #PSA_ERROR_BAD_STATE
1457  * The library has not been previously initialized by psa_crypto_init().
1458  * It is implementation-dependent whether a failure to initialize
1459  * results in this error code.
1460  */
1461 psa_status_t psa_mac_verify_setup(psa_mac_operation_t *operation,
1462  psa_key_handle_t handle,
1463  psa_algorithm_t alg);
1464 
1465 /** Add a message fragment to a multipart MAC operation.
1466  *
1467  * The application must call psa_mac_sign_setup() or psa_mac_verify_setup()
1468  * before calling this function.
1469  *
1470  * If this function returns an error status, the operation enters an error
1471  * state and must be aborted by calling psa_mac_abort().
1472  *
1473  * \param[in,out] operation Active MAC operation.
1474  * \param[in] input Buffer containing the message fragment to add to
1475  * the MAC calculation.
1476  * \param input_length Size of the \p input buffer in bytes.
1477  *
1478  * \retval #PSA_SUCCESS
1479  * Success.
1480  * \retval #PSA_ERROR_BAD_STATE
1481  * The operation state is not valid (it must be active).
1482  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1483  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1484  * \retval #PSA_ERROR_HARDWARE_FAILURE
1485  * \retval #PSA_ERROR_CORRUPTION_DETECTED
1486  * \retval #PSA_ERROR_STORAGE_FAILURE
1487  * \retval #PSA_ERROR_BAD_STATE
1488  * The library has not been previously initialized by psa_crypto_init().
1489  * It is implementation-dependent whether a failure to initialize
1490  * results in this error code.
1491  */
1492 psa_status_t psa_mac_update(psa_mac_operation_t *operation,
1493  const uint8_t *input,
1494  size_t input_length);
1495 
1496 /** Finish the calculation of the MAC of a message.
1497  *
1498  * The application must call psa_mac_sign_setup() before calling this function.
1499  * This function calculates the MAC of the message formed by concatenating
1500  * the inputs passed to preceding calls to psa_mac_update().
1501  *
1502  * When this function returns successfuly, the operation becomes inactive.
1503  * If this function returns an error status, the operation enters an error
1504  * state and must be aborted by calling psa_mac_abort().
1505  *
1506  * \warning Applications should not call this function if they expect
1507  * a specific value for the MAC. Call psa_mac_verify_finish() instead.
1508  * Beware that comparing integrity or authenticity data such as
1509  * MAC values with a function such as \c memcmp is risky
1510  * because the time taken by the comparison may leak information
1511  * about the MAC value which could allow an attacker to guess
1512  * a valid MAC and thereby bypass security controls.
1513  *
1514  * \param[in,out] operation Active MAC operation.
1515  * \param[out] mac Buffer where the MAC value is to be written.
1516  * \param mac_size Size of the \p mac buffer in bytes.
1517  * \param[out] mac_length On success, the number of bytes
1518  * that make up the MAC value. This is always
1519  * #PSA_MAC_FINAL_SIZE(\c key_type, \c key_bits, \c alg)
1520  * where \c key_type and \c key_bits are the type and
1521  * bit-size respectively of the key and \c alg is the
1522  * MAC algorithm that is calculated.
1523  *
1524  * \retval #PSA_SUCCESS
1525  * Success.
1526  * \retval #PSA_ERROR_BAD_STATE
1527  * The operation state is not valid (it must be an active mac sign
1528  * operation).
1529  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1530  * The size of the \p mac buffer is too small. You can determine a
1531  * sufficient buffer size by calling PSA_MAC_FINAL_SIZE().
1532  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1533  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1534  * \retval #PSA_ERROR_HARDWARE_FAILURE
1535  * \retval #PSA_ERROR_CORRUPTION_DETECTED
1536  * \retval #PSA_ERROR_STORAGE_FAILURE
1537  * \retval #PSA_ERROR_BAD_STATE
1538  * The library has not been previously initialized by psa_crypto_init().
1539  * It is implementation-dependent whether a failure to initialize
1540  * results in this error code.
1541  */
1542 psa_status_t psa_mac_sign_finish(psa_mac_operation_t *operation,
1543  uint8_t *mac,
1544  size_t mac_size,
1545  size_t *mac_length);
1546 
1547 /** Finish the calculation of the MAC of a message and compare it with
1548  * an expected value.
1549  *
1550  * The application must call psa_mac_verify_setup() before calling this function.
1551  * This function calculates the MAC of the message formed by concatenating
1552  * the inputs passed to preceding calls to psa_mac_update(). It then
1553  * compares the calculated MAC with the expected MAC passed as a
1554  * parameter to this function.
1555  *
1556  * When this function returns successfuly, the operation becomes inactive.
1557  * If this function returns an error status, the operation enters an error
1558  * state and must be aborted by calling psa_mac_abort().
1559  *
1560  * \note Implementations shall make the best effort to ensure that the
1561  * comparison between the actual MAC and the expected MAC is performed
1562  * in constant time.
1563  *
1564  * \param[in,out] operation Active MAC operation.
1565  * \param[in] mac Buffer containing the expected MAC value.
1566  * \param mac_length Size of the \p mac buffer in bytes.
1567  *
1568  * \retval #PSA_SUCCESS
1569  * The expected MAC is identical to the actual MAC of the message.
1570  * \retval #PSA_ERROR_INVALID_SIGNATURE
1571  * The MAC of the message was calculated successfully, but it
1572  * differs from the expected MAC.
1573  * \retval #PSA_ERROR_BAD_STATE
1574  * The operation state is not valid (it must be an active mac verify
1575  * operation).
1576  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1577  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1578  * \retval #PSA_ERROR_HARDWARE_FAILURE
1579  * \retval #PSA_ERROR_CORRUPTION_DETECTED
1580  * \retval #PSA_ERROR_STORAGE_FAILURE
1581  * \retval #PSA_ERROR_BAD_STATE
1582  * The library has not been previously initialized by psa_crypto_init().
1583  * It is implementation-dependent whether a failure to initialize
1584  * results in this error code.
1585  */
1586 psa_status_t psa_mac_verify_finish(psa_mac_operation_t *operation,
1587  const uint8_t *mac,
1588  size_t mac_length);
1589 
1590 /** Abort a MAC operation.
1591  *
1592  * Aborting an operation frees all associated resources except for the
1593  * \p operation structure itself. Once aborted, the operation object
1594  * can be reused for another operation by calling
1595  * psa_mac_sign_setup() or psa_mac_verify_setup() again.
1596  *
1597  * You may call this function any time after the operation object has
1598  * been initialized by one of the methods described in #psa_mac_operation_t.
1599  *
1600  * In particular, calling psa_mac_abort() after the operation has been
1601  * terminated by a call to psa_mac_abort(), psa_mac_sign_finish() or
1602  * psa_mac_verify_finish() is safe and has no effect.
1603  *
1604  * \param[in,out] operation Initialized MAC operation.
1605  *
1606  * \retval #PSA_SUCCESS
1607  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1608  * \retval #PSA_ERROR_HARDWARE_FAILURE
1609  * \retval #PSA_ERROR_CORRUPTION_DETECTED
1610  * \retval #PSA_ERROR_BAD_STATE
1611  * The library has not been previously initialized by psa_crypto_init().
1612  * It is implementation-dependent whether a failure to initialize
1613  * results in this error code.
1614  */
1615 psa_status_t psa_mac_abort(psa_mac_operation_t *operation);
1616 
1617 /**@}*/
1618 
1619 /** \defgroup cipher Symmetric ciphers
1620  * @{
1621  */
1622 
1623 /** Encrypt a message using a symmetric cipher.
1624  *
1625  * This function encrypts a message with a random IV (initialization
1626  * vector). Use the multipart operation interface with a
1627  * #psa_cipher_operation_t object to provide other forms of IV.
1628  *
1629  * \param handle Handle to the key to use for the operation.
1630  * It must remain valid until the operation
1631  * terminates.
1632  * \param alg The cipher algorithm to compute
1633  * (\c PSA_ALG_XXX value such that
1634  * #PSA_ALG_IS_CIPHER(\p alg) is true).
1635  * \param[in] input Buffer containing the message to encrypt.
1636  * \param input_length Size of the \p input buffer in bytes.
1637  * \param[out] output Buffer where the output is to be written.
1638  * The output contains the IV followed by
1639  * the ciphertext proper.
1640  * \param output_size Size of the \p output buffer in bytes.
1641  * \param[out] output_length On success, the number of bytes
1642  * that make up the output.
1643  *
1644  * \retval #PSA_SUCCESS
1645  * Success.
1646  * \retval #PSA_ERROR_INVALID_HANDLE
1647  * \retval #PSA_ERROR_NOT_PERMITTED
1648  * \retval #PSA_ERROR_INVALID_ARGUMENT
1649  * \p handle is not compatible with \p alg.
1650  * \retval #PSA_ERROR_NOT_SUPPORTED
1651  * \p alg is not supported or is not a cipher algorithm.
1652  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1653  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1654  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1655  * \retval #PSA_ERROR_HARDWARE_FAILURE
1656  * \retval #PSA_ERROR_CORRUPTION_DETECTED
1657  * \retval #PSA_ERROR_STORAGE_FAILURE
1658  * \retval #PSA_ERROR_BAD_STATE
1659  * The library has not been previously initialized by psa_crypto_init().
1660  * It is implementation-dependent whether a failure to initialize
1661  * results in this error code.
1662  */
1663 psa_status_t psa_cipher_encrypt(psa_key_handle_t handle,
1664  psa_algorithm_t alg,
1665  const uint8_t *input,
1666  size_t input_length,
1667  uint8_t *output,
1668  size_t output_size,
1669  size_t *output_length);
1670 
1671 /** Decrypt a message using a symmetric cipher.
1672  *
1673  * This function decrypts a message encrypted with a symmetric cipher.
1674  *
1675  * \param handle Handle to the key to use for the operation.
1676  * It must remain valid until the operation
1677  * terminates.
1678  * \param alg The cipher algorithm to compute
1679  * (\c PSA_ALG_XXX value such that
1680  * #PSA_ALG_IS_CIPHER(\p alg) is true).
1681  * \param[in] input Buffer containing the message to decrypt.
1682  * This consists of the IV followed by the
1683  * ciphertext proper.
1684  * \param input_length Size of the \p input buffer in bytes.
1685  * \param[out] output Buffer where the plaintext is to be written.
1686  * \param output_size Size of the \p output buffer in bytes.
1687  * \param[out] output_length On success, the number of bytes
1688  * that make up the output.
1689  *
1690  * \retval #PSA_SUCCESS
1691  * Success.
1692  * \retval #PSA_ERROR_INVALID_HANDLE
1693  * \retval #PSA_ERROR_NOT_PERMITTED
1694  * \retval #PSA_ERROR_INVALID_ARGUMENT
1695  * \p handle is not compatible with \p alg.
1696  * \retval #PSA_ERROR_NOT_SUPPORTED
1697  * \p alg is not supported or is not a cipher algorithm.
1698  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1699  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1700  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1701  * \retval #PSA_ERROR_HARDWARE_FAILURE
1702  * \retval #PSA_ERROR_STORAGE_FAILURE
1703  * \retval #PSA_ERROR_CORRUPTION_DETECTED
1704  * \retval #PSA_ERROR_BAD_STATE
1705  * The library has not been previously initialized by psa_crypto_init().
1706  * It is implementation-dependent whether a failure to initialize
1707  * results in this error code.
1708  */
1709 psa_status_t psa_cipher_decrypt(psa_key_handle_t handle,
1710  psa_algorithm_t alg,
1711  const uint8_t *input,
1712  size_t input_length,
1713  uint8_t *output,
1714  size_t output_size,
1715  size_t *output_length);
1716 
1717 /** The type of the state data structure for multipart cipher operations.
1718  *
1719  * Before calling any function on a cipher operation object, the application
1720  * must initialize it by any of the following means:
1721  * - Set the structure to all-bits-zero, for example:
1722  * \code
1723  * psa_cipher_operation_t operation;
1724  * memset(&operation, 0, sizeof(operation));
1725  * \endcode
1726  * - Initialize the structure to logical zero values, for example:
1727  * \code
1728  * psa_cipher_operation_t operation = {0};
1729  * \endcode
1730  * - Initialize the structure to the initializer #PSA_CIPHER_OPERATION_INIT,
1731  * for example:
1732  * \code
1733  * psa_cipher_operation_t operation = PSA_CIPHER_OPERATION_INIT;
1734  * \endcode
1735  * - Assign the result of the function psa_cipher_operation_init()
1736  * to the structure, for example:
1737  * \code
1738  * psa_cipher_operation_t operation;
1739  * operation = psa_cipher_operation_init();
1740  * \endcode
1741  *
1742  * This is an implementation-defined \c struct. Applications should not
1743  * make any assumptions about the content of this structure except
1744  * as directed by the documentation of a specific implementation. */
1745 typedef struct psa_cipher_operation_s psa_cipher_operation_t;
1746 
1747 /** \def PSA_CIPHER_OPERATION_INIT
1748  *
1749  * This macro returns a suitable initializer for a cipher operation object of
1750  * type #psa_cipher_operation_t.
1751  */
1752 #ifdef __DOXYGEN_ONLY__
1753 /* This is an example definition for documentation purposes.
1754  * Implementations should define a suitable value in `crypto_struct.h`.
1755  */
1756 #define PSA_CIPHER_OPERATION_INIT {0}
1757 #endif
1758 
1759 /** Return an initial value for a cipher operation object.
1760  */
1761 static psa_cipher_operation_t psa_cipher_operation_init(void);
1762 
1763 /** Set the key for a multipart symmetric encryption operation.
1764  *
1765  * The sequence of operations to encrypt a message with a symmetric cipher
1766  * is as follows:
1767  * -# Allocate an operation object which will be passed to all the functions
1768  * listed here.
1769  * -# Initialize the operation object with one of the methods described in the
1770  * documentation for #psa_cipher_operation_t, e.g.
1771  * #PSA_CIPHER_OPERATION_INIT.
1772  * -# Call psa_cipher_encrypt_setup() to specify the algorithm and key.
1773  * -# Call either psa_cipher_generate_iv() or psa_cipher_set_iv() to
1774  * generate or set the IV (initialization vector). You should use
1775  * psa_cipher_generate_iv() unless the protocol you are implementing
1776  * requires a specific IV value.
1777  * -# Call psa_cipher_update() zero, one or more times, passing a fragment
1778  * of the message each time.
1779  * -# Call psa_cipher_finish().
1780  *
1781  * If an error occurs at any step after a call to psa_cipher_encrypt_setup(),
1782  * the operation will need to be reset by a call to psa_cipher_abort(). The
1783  * application may call psa_cipher_abort() at any time after the operation
1784  * has been initialized.
1785  *
1786  * After a successful call to psa_cipher_encrypt_setup(), the application must
1787  * eventually terminate the operation. The following events terminate an
1788  * operation:
1789  * - A successful call to psa_cipher_finish().
1790  * - A call to psa_cipher_abort().
1791  *
1792  * \param[in,out] operation The operation object to set up. It must have
1793  * been initialized as per the documentation for
1794  * #psa_cipher_operation_t and not yet in use.
1795  * \param handle Handle to the key to use for the operation.
1796  * It must remain valid until the operation
1797  * terminates.
1798  * \param alg The cipher algorithm to compute
1799  * (\c PSA_ALG_XXX value such that
1800  * #PSA_ALG_IS_CIPHER(\p alg) is true).
1801  *
1802  * \retval #PSA_SUCCESS
1803  * Success.
1804  * \retval #PSA_ERROR_INVALID_HANDLE
1805  * \retval #PSA_ERROR_NOT_PERMITTED
1806  * \retval #PSA_ERROR_INVALID_ARGUMENT
1807  * \p handle is not compatible with \p alg.
1808  * \retval #PSA_ERROR_NOT_SUPPORTED
1809  * \p alg is not supported or is not a cipher algorithm.
1810  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1811  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1812  * \retval #PSA_ERROR_HARDWARE_FAILURE
1813  * \retval #PSA_ERROR_CORRUPTION_DETECTED
1814  * \retval #PSA_ERROR_STORAGE_FAILURE
1815  * \retval #PSA_ERROR_BAD_STATE
1816  * The operation state is not valid (it must be inactive).
1817  * \retval #PSA_ERROR_BAD_STATE
1818  * The library has not been previously initialized by psa_crypto_init().
1819  * It is implementation-dependent whether a failure to initialize
1820  * results in this error code.
1821  */
1822 psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation,
1823  psa_key_handle_t handle,
1824  psa_algorithm_t alg);
1825 
1826 /** Set the key for a multipart symmetric decryption operation.
1827  *
1828  * The sequence of operations to decrypt a message with a symmetric cipher
1829  * is as follows:
1830  * -# Allocate an operation object which will be passed to all the functions
1831  * listed here.
1832  * -# Initialize the operation object with one of the methods described in the
1833  * documentation for #psa_cipher_operation_t, e.g.
1834  * #PSA_CIPHER_OPERATION_INIT.
1835  * -# Call psa_cipher_decrypt_setup() to specify the algorithm and key.
1836  * -# Call psa_cipher_set_iv() with the IV (initialization vector) for the
1837  * decryption. If the IV is prepended to the ciphertext, you can call
1838  * psa_cipher_update() on a buffer containing the IV followed by the
1839  * beginning of the message.
1840  * -# Call psa_cipher_update() zero, one or more times, passing a fragment
1841  * of the message each time.
1842  * -# Call psa_cipher_finish().
1843  *
1844  * If an error occurs at any step after a call to psa_cipher_decrypt_setup(),
1845  * the operation will need to be reset by a call to psa_cipher_abort(). The
1846  * application may call psa_cipher_abort() at any time after the operation
1847  * has been initialized.
1848  *
1849  * After a successful call to psa_cipher_decrypt_setup(), the application must
1850  * eventually terminate the operation. The following events terminate an
1851  * operation:
1852  * - A successful call to psa_cipher_finish().
1853  * - A call to psa_cipher_abort().
1854  *
1855  * \param[in,out] operation The operation object to set up. It must have
1856  * been initialized as per the documentation for
1857  * #psa_cipher_operation_t and not yet in use.
1858  * \param handle Handle to the key to use for the operation.
1859  * It must remain valid until the operation
1860  * terminates.
1861  * \param alg The cipher algorithm to compute
1862  * (\c PSA_ALG_XXX value such that
1863  * #PSA_ALG_IS_CIPHER(\p alg) is true).
1864  *
1865  * \retval #PSA_SUCCESS
1866  * Success.
1867  * \retval #PSA_ERROR_INVALID_HANDLE
1868  * \retval #PSA_ERROR_NOT_PERMITTED
1869  * \retval #PSA_ERROR_INVALID_ARGUMENT
1870  * \p handle is not compatible with \p alg.
1871  * \retval #PSA_ERROR_NOT_SUPPORTED
1872  * \p alg is not supported or is not a cipher algorithm.
1873  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1874  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1875  * \retval #PSA_ERROR_HARDWARE_FAILURE
1876  * \retval #PSA_ERROR_CORRUPTION_DETECTED
1877  * \retval #PSA_ERROR_STORAGE_FAILURE
1878  * \retval #PSA_ERROR_BAD_STATE
1879  * The operation state is not valid (it must be inactive).
1880  * \retval #PSA_ERROR_BAD_STATE
1881  * The library has not been previously initialized by psa_crypto_init().
1882  * It is implementation-dependent whether a failure to initialize
1883  * results in this error code.
1884  */
1885 psa_status_t psa_cipher_decrypt_setup(psa_cipher_operation_t *operation,
1886  psa_key_handle_t handle,
1887  psa_algorithm_t alg);
1888 
1889 /** Generate an IV for a symmetric encryption operation.
1890  *
1891  * This function generates a random IV (initialization vector), nonce
1892  * or initial counter value for the encryption operation as appropriate
1893  * for the chosen algorithm, key type and key size.
1894  *
1895  * The application must call psa_cipher_encrypt_setup() before
1896  * calling this function.
1897  *
1898  * If this function returns an error status, the operation enters an error
1899  * state and must be aborted by calling psa_cipher_abort().
1900  *
1901  * \param[in,out] operation Active cipher operation.
1902  * \param[out] iv Buffer where the generated IV is to be written.
1903  * \param iv_size Size of the \p iv buffer in bytes.
1904  * \param[out] iv_length On success, the number of bytes of the
1905  * generated IV.
1906  *
1907  * \retval #PSA_SUCCESS
1908  * Success.
1909  * \retval #PSA_ERROR_BAD_STATE
1910  * The operation state is not valid (it must be active, with no IV set).
1911  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1912  * The size of the \p iv buffer is too small.
1913  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1914  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1915  * \retval #PSA_ERROR_HARDWARE_FAILURE
1916  * \retval #PSA_ERROR_CORRUPTION_DETECTED
1917  * \retval #PSA_ERROR_STORAGE_FAILURE
1918  * \retval #PSA_ERROR_BAD_STATE
1919  * The library has not been previously initialized by psa_crypto_init().
1920  * It is implementation-dependent whether a failure to initialize
1921  * results in this error code.
1922  */
1923 psa_status_t psa_cipher_generate_iv(psa_cipher_operation_t *operation,
1924  uint8_t *iv,
1925  size_t iv_size,
1926  size_t *iv_length);
1927 
1928 /** Set the IV for a symmetric encryption or decryption operation.
1929  *
1930  * This function sets the IV (initialization vector), nonce
1931  * or initial counter value for the encryption or decryption operation.
1932  *
1933  * The application must call psa_cipher_encrypt_setup() before
1934  * calling this function.
1935  *
1936  * If this function returns an error status, the operation enters an error
1937  * state and must be aborted by calling psa_cipher_abort().
1938  *
1939  * \note When encrypting, applications should use psa_cipher_generate_iv()
1940  * instead of this function, unless implementing a protocol that requires
1941  * a non-random IV.
1942  *
1943  * \param[in,out] operation Active cipher operation.
1944  * \param[in] iv Buffer containing the IV to use.
1945  * \param iv_length Size of the IV in bytes.
1946  *
1947  * \retval #PSA_SUCCESS
1948  * Success.
1949  * \retval #PSA_ERROR_BAD_STATE
1950  * The operation state is not valid (it must be an active cipher
1951  * encrypt operation, with no IV set).
1952  * \retval #PSA_ERROR_INVALID_ARGUMENT
1953  * The size of \p iv is not acceptable for the chosen algorithm,
1954  * or the chosen algorithm does not use an IV.
1955  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1956  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1957  * \retval #PSA_ERROR_HARDWARE_FAILURE
1958  * \retval #PSA_ERROR_CORRUPTION_DETECTED
1959  * \retval #PSA_ERROR_STORAGE_FAILURE
1960  * \retval #PSA_ERROR_BAD_STATE
1961  * The library has not been previously initialized by psa_crypto_init().
1962  * It is implementation-dependent whether a failure to initialize
1963  * results in this error code.
1964  */
1965 psa_status_t psa_cipher_set_iv(psa_cipher_operation_t *operation,
1966  const uint8_t *iv,
1967  size_t iv_length);
1968 
1969 /** Encrypt or decrypt a message fragment in an active cipher operation.
1970  *
1971  * Before calling this function, you must:
1972  * 1. Call either psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup().
1973  * The choice of setup function determines whether this function
1974  * encrypts or decrypts its input.
1975  * 2. If the algorithm requires an IV, call psa_cipher_generate_iv()
1976  * (recommended when encrypting) or psa_cipher_set_iv().
1977  *
1978  * If this function returns an error status, the operation enters an error
1979  * state and must be aborted by calling psa_cipher_abort().
1980  *
1981  * \param[in,out] operation Active cipher operation.
1982  * \param[in] input Buffer containing the message fragment to
1983  * encrypt or decrypt.
1984  * \param input_length Size of the \p input buffer in bytes.
1985  * \param[out] output Buffer where the output is to be written.
1986  * \param output_size Size of the \p output buffer in bytes.
1987  * \param[out] output_length On success, the number of bytes
1988  * that make up the returned output.
1989  *
1990  * \retval #PSA_SUCCESS
1991  * Success.
1992  * \retval #PSA_ERROR_BAD_STATE
1993  * The operation state is not valid (it must be active, with an IV set
1994  * if required for the algorithm).
1995  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1996  * The size of the \p output buffer is too small.
1997  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1998  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1999  * \retval #PSA_ERROR_HARDWARE_FAILURE
2000  * \retval #PSA_ERROR_CORRUPTION_DETECTED
2001  * \retval #PSA_ERROR_STORAGE_FAILURE
2002  * \retval #PSA_ERROR_BAD_STATE
2003  * The library has not been previously initialized by psa_crypto_init().
2004  * It is implementation-dependent whether a failure to initialize
2005  * results in this error code.
2006  */
2007 psa_status_t psa_cipher_update(psa_cipher_operation_t *operation,
2008  const uint8_t *input,
2009  size_t input_length,
2010  uint8_t *output,
2011  size_t output_size,
2012  size_t *output_length);
2013 
2014 /** Finish encrypting or decrypting a message in a cipher operation.
2015  *
2016  * The application must call psa_cipher_encrypt_setup() or
2017  * psa_cipher_decrypt_setup() before calling this function. The choice
2018  * of setup function determines whether this function encrypts or
2019  * decrypts its input.
2020  *
2021  * This function finishes the encryption or decryption of the message
2022  * formed by concatenating the inputs passed to preceding calls to
2023  * psa_cipher_update().
2024  *
2025  * When this function returns successfuly, the operation becomes inactive.
2026  * If this function returns an error status, the operation enters an error
2027  * state and must be aborted by calling psa_cipher_abort().
2028  *
2029  * \param[in,out] operation Active cipher operation.
2030  * \param[out] output Buffer where the output is to be written.
2031  * \param output_size Size of the \p output buffer in bytes.
2032  * \param[out] output_length On success, the number of bytes
2033  * that make up the returned output.
2034  *
2035  * \retval #PSA_SUCCESS
2036  * Success.
2037  * \retval #PSA_ERROR_INVALID_ARGUMENT
2038  * The total input size passed to this operation is not valid for
2039  * this particular algorithm. For example, the algorithm is a based
2040  * on block cipher and requires a whole number of blocks, but the
2041  * total input size is not a multiple of the block size.
2042  * \retval #PSA_ERROR_INVALID_PADDING
2043  * This is a decryption operation for an algorithm that includes
2044  * padding, and the ciphertext does not contain valid padding.
2045  * \retval #PSA_ERROR_BAD_STATE
2046  * The operation state is not valid (it must be active, with an IV set
2047  * if required for the algorithm).
2048  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2049  * The size of the \p output buffer is too small.
2050  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2051  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2052  * \retval #PSA_ERROR_HARDWARE_FAILURE
2053  * \retval #PSA_ERROR_CORRUPTION_DETECTED
2054  * \retval #PSA_ERROR_STORAGE_FAILURE
2055  * \retval #PSA_ERROR_BAD_STATE
2056  * The library has not been previously initialized by psa_crypto_init().
2057  * It is implementation-dependent whether a failure to initialize
2058  * results in this error code.
2059  */
2060 psa_status_t psa_cipher_finish(psa_cipher_operation_t *operation,
2061  uint8_t *output,
2062  size_t output_size,
2063  size_t *output_length);
2064 
2065 /** Abort a cipher operation.
2066  *
2067  * Aborting an operation frees all associated resources except for the
2068  * \p operation structure itself. Once aborted, the operation object
2069  * can be reused for another operation by calling
2070  * psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup() again.
2071  *
2072  * You may call this function any time after the operation object has
2073  * been initialized as described in #psa_cipher_operation_t.
2074  *
2075  * In particular, calling psa_cipher_abort() after the operation has been
2076  * terminated by a call to psa_cipher_abort() or psa_cipher_finish()
2077  * is safe and has no effect.
2078  *
2079  * \param[in,out] operation Initialized cipher operation.
2080  *
2081  * \retval #PSA_SUCCESS
2082  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2083  * \retval #PSA_ERROR_HARDWARE_FAILURE
2084  * \retval #PSA_ERROR_CORRUPTION_DETECTED
2085  * \retval #PSA_ERROR_BAD_STATE
2086  * 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.
2089  */
2090 psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation);
2091 
2092 /**@}*/
2093 
2094 /** \defgroup aead Authenticated encryption with associated data (AEAD)
2095  * @{
2096  */
2097 
2098 /** Process an authenticated encryption operation.
2099  *
2100  * \param handle Handle to the key to use for the operation.
2101  * \param alg The AEAD algorithm to compute
2102  * (\c PSA_ALG_XXX value such that
2103  * #PSA_ALG_IS_AEAD(\p alg) is true).
2104  * \param[in] nonce Nonce or IV to use.
2105  * \param nonce_length Size of the \p nonce buffer in bytes.
2106  * \param[in] additional_data Additional data that will be authenticated
2107  * but not encrypted.
2108  * \param additional_data_length Size of \p additional_data in bytes.
2109  * \param[in] plaintext Data that will be authenticated and
2110  * encrypted.
2111  * \param plaintext_length Size of \p plaintext in bytes.
2112  * \param[out] ciphertext Output buffer for the authenticated and
2113  * encrypted data. The additional data is not
2114  * part of this output. For algorithms where the
2115  * encrypted data and the authentication tag
2116  * are defined as separate outputs, the
2117  * authentication tag is appended to the
2118  * encrypted data.
2119  * \param ciphertext_size Size of the \p ciphertext buffer in bytes.
2120  * This must be at least
2121  * #PSA_AEAD_ENCRYPT_OUTPUT_SIZE(\p alg,
2122  * \p plaintext_length).
2123  * \param[out] ciphertext_length On success, the size of the output
2124  * in the \p ciphertext buffer.
2125  *
2126  * \retval #PSA_SUCCESS
2127  * Success.
2128  * \retval #PSA_ERROR_INVALID_HANDLE
2129  * \retval #PSA_ERROR_NOT_PERMITTED
2130  * \retval #PSA_ERROR_INVALID_ARGUMENT
2131  * \p handle is not compatible with \p alg.
2132  * \retval #PSA_ERROR_NOT_SUPPORTED
2133  * \p alg is not supported or is not an AEAD algorithm.
2134  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2135  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2136  * \p ciphertext_size is too small
2137  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2138  * \retval #PSA_ERROR_HARDWARE_FAILURE
2139  * \retval #PSA_ERROR_CORRUPTION_DETECTED
2140  * \retval #PSA_ERROR_STORAGE_FAILURE
2141  * \retval #PSA_ERROR_BAD_STATE
2142  * The library has not been previously initialized by psa_crypto_init().
2143  * It is implementation-dependent whether a failure to initialize
2144  * results in this error code.
2145  */
2146 psa_status_t psa_aead_encrypt(psa_key_handle_t handle,
2147  psa_algorithm_t alg,
2148  const uint8_t *nonce,
2149  size_t nonce_length,
2150  const uint8_t *additional_data,
2151  size_t additional_data_length,
2152  const uint8_t *plaintext,
2153  size_t plaintext_length,
2154  uint8_t *ciphertext,
2155  size_t ciphertext_size,
2156  size_t *ciphertext_length);
2157 
2158 /** Process an authenticated decryption operation.
2159  *
2160  * \param handle Handle to the key to use for the operation.
2161  * \param alg The AEAD algorithm to compute
2162  * (\c PSA_ALG_XXX value such that
2163  * #PSA_ALG_IS_AEAD(\p alg) is true).
2164  * \param[in] nonce Nonce or IV to use.
2165  * \param nonce_length Size of the \p nonce buffer in bytes.
2166  * \param[in] additional_data Additional data that has been authenticated
2167  * but not encrypted.
2168  * \param additional_data_length Size of \p additional_data in bytes.
2169  * \param[in] ciphertext Data that has been authenticated and
2170  * encrypted. For algorithms where the
2171  * encrypted data and the authentication tag
2172  * are defined as separate inputs, the buffer
2173  * must contain the encrypted data followed
2174  * by the authentication tag.
2175  * \param ciphertext_length Size of \p ciphertext in bytes.
2176  * \param[out] plaintext Output buffer for the decrypted data.
2177  * \param plaintext_size Size of the \p plaintext buffer in bytes.
2178  * This must be at least
2179  * #PSA_AEAD_DECRYPT_OUTPUT_SIZE(\p alg,
2180  * \p ciphertext_length).
2181  * \param[out] plaintext_length On success, the size of the output
2182  * in the \p plaintext buffer.
2183  *
2184  * \retval #PSA_SUCCESS
2185  * Success.
2186  * \retval #PSA_ERROR_INVALID_HANDLE
2187  * \retval #PSA_ERROR_INVALID_SIGNATURE
2188  * The ciphertext is not authentic.
2189  * \retval #PSA_ERROR_NOT_PERMITTED
2190  * \retval #PSA_ERROR_INVALID_ARGUMENT
2191  * \p handle is not compatible with \p alg.
2192  * \retval #PSA_ERROR_NOT_SUPPORTED
2193  * \p alg is not supported or is not an AEAD algorithm.
2194  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2195  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2196  * \p plaintext_size or \p nonce_length is too small
2197  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2198  * \retval #PSA_ERROR_HARDWARE_FAILURE
2199  * \retval #PSA_ERROR_CORRUPTION_DETECTED
2200  * \retval #PSA_ERROR_STORAGE_FAILURE
2201  * \retval #PSA_ERROR_BAD_STATE
2202  * The library has not been previously initialized by psa_crypto_init().
2203  * It is implementation-dependent whether a failure to initialize
2204  * results in this error code.
2205  */
2206 psa_status_t psa_aead_decrypt(psa_key_handle_t handle,
2207  psa_algorithm_t alg,
2208  const uint8_t *nonce,
2209  size_t nonce_length,
2210  const uint8_t *additional_data,
2211  size_t additional_data_length,
2212  const uint8_t *ciphertext,
2213  size_t ciphertext_length,
2214  uint8_t *plaintext,
2215  size_t plaintext_size,
2216  size_t *plaintext_length);
2217 
2218 /** The type of the state data structure for multipart AEAD operations.
2219  *
2220  * Before calling any function on an AEAD operation object, the application
2221  * must initialize it by any of the following means:
2222  * - Set the structure to all-bits-zero, for example:
2223  * \code
2224  * psa_aead_operation_t operation;
2225  * memset(&operation, 0, sizeof(operation));
2226  * \endcode
2227  * - Initialize the structure to logical zero values, for example:
2228  * \code
2229  * psa_aead_operation_t operation = {0};
2230  * \endcode
2231  * - Initialize the structure to the initializer #PSA_AEAD_OPERATION_INIT,
2232  * for example:
2233  * \code
2234  * psa_aead_operation_t operation = PSA_AEAD_OPERATION_INIT;
2235  * \endcode
2236  * - Assign the result of the function psa_aead_operation_init()
2237  * to the structure, for example:
2238  * \code
2239  * psa_aead_operation_t operation;
2240  * operation = psa_aead_operation_init();
2241  * \endcode
2242  *
2243  * This is an implementation-defined \c struct. Applications should not
2244  * make any assumptions about the content of this structure except
2245  * as directed by the documentation of a specific implementation. */
2246 typedef struct psa_aead_operation_s psa_aead_operation_t;
2247 
2248 /** \def PSA_AEAD_OPERATION_INIT
2249  *
2250  * This macro returns a suitable initializer for an AEAD operation object of
2251  * type #psa_aead_operation_t.
2252  */
2253 #ifdef __DOXYGEN_ONLY__
2254 /* This is an example definition for documentation purposes.
2255  * Implementations should define a suitable value in `crypto_struct.h`.
2256  */
2257 #define PSA_AEAD_OPERATION_INIT {0}
2258 #endif
2259 
2260 /** Return an initial value for an AEAD operation object.
2261  */
2262 static psa_aead_operation_t psa_aead_operation_init(void);
2263 
2264 /** Set the key for a multipart authenticated encryption operation.
2265  *
2266  * The sequence of operations to encrypt a message with authentication
2267  * is as follows:
2268  * -# Allocate an operation object which will be passed to all the functions
2269  * listed here.
2270  * -# Initialize the operation object with one of the methods described in the
2271  * documentation for #psa_aead_operation_t, e.g.
2272  * #PSA_AEAD_OPERATION_INIT.
2273  * -# Call psa_aead_encrypt_setup() to specify the algorithm and key.
2274  * -# If needed, call psa_aead_set_lengths() to specify the length of the
2275  * inputs to the subsequent calls to psa_aead_update_ad() and
2276  * psa_aead_update(). See the documentation of psa_aead_set_lengths()
2277  * for details.
2278  * -# Call either psa_aead_generate_nonce() or psa_aead_set_nonce() to
2279  * generate or set the nonce. You should use
2280  * psa_aead_generate_nonce() unless the protocol you are implementing
2281  * requires a specific nonce value.
2282  * -# Call psa_aead_update_ad() zero, one or more times, passing a fragment
2283  * of the non-encrypted additional authenticated data each time.
2284  * -# Call psa_aead_update() zero, one or more times, passing a fragment
2285  * of the message to encrypt each time.
2286  * -# Call psa_aead_finish().
2287  *
2288  * If an error occurs at any step after a call to psa_aead_encrypt_setup(),
2289  * the operation will need to be reset by a call to psa_aead_abort(). The
2290  * application may call psa_aead_abort() at any time after the operation
2291  * has been initialized.
2292  *
2293  * After a successful call to psa_aead_encrypt_setup(), the application must
2294  * eventually terminate the operation. The following events terminate an
2295  * operation:
2296  * - A successful call to psa_aead_finish().
2297  * - A call to psa_aead_abort().
2298  *
2299  * \param[in,out] operation The operation object to set up. It must have
2300  * been initialized as per the documentation for
2301  * #psa_aead_operation_t and not yet in use.
2302  * \param handle Handle to the key to use for the operation.
2303  * It must remain valid until the operation
2304  * terminates.
2305  * \param alg The AEAD algorithm to compute
2306  * (\c PSA_ALG_XXX value such that
2307  * #PSA_ALG_IS_AEAD(\p alg) is true).
2308  *
2309  * \retval #PSA_SUCCESS
2310  * Success.
2311  * \retval #PSA_ERROR_BAD_STATE
2312  * The operation state is not valid (it must be inactive).
2313  * \retval #PSA_ERROR_INVALID_HANDLE
2314  * \retval #PSA_ERROR_NOT_PERMITTED
2315  * \retval #PSA_ERROR_INVALID_ARGUMENT
2316  * \p handle is not compatible with \p alg.
2317  * \retval #PSA_ERROR_NOT_SUPPORTED
2318  * \p alg is not supported or is not an AEAD algorithm.
2319  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2320  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2321  * \retval #PSA_ERROR_HARDWARE_FAILURE
2322  * \retval #PSA_ERROR_CORRUPTION_DETECTED
2323  * \retval #PSA_ERROR_STORAGE_FAILURE
2324  * \retval #PSA_ERROR_BAD_STATE
2325  * The library has not been previously initialized by psa_crypto_init().
2326  * It is implementation-dependent whether a failure to initialize
2327  * results in this error code.
2328  */
2329 psa_status_t psa_aead_encrypt_setup(psa_aead_operation_t *operation,
2330  psa_key_handle_t handle,
2331  psa_algorithm_t alg);
2332 
2333 /** Set the key for a multipart authenticated decryption operation.
2334  *
2335  * The sequence of operations to decrypt a message with authentication
2336  * is as follows:
2337  * -# Allocate an operation object which will be passed to all the functions
2338  * listed here.
2339  * -# Initialize the operation object with one of the methods described in the
2340  * documentation for #psa_aead_operation_t, e.g.
2341  * #PSA_AEAD_OPERATION_INIT.
2342  * -# Call psa_aead_decrypt_setup() to specify the algorithm and key.
2343  * -# If needed, call psa_aead_set_lengths() to specify the length of the
2344  * inputs to the subsequent calls to psa_aead_update_ad() and
2345  * psa_aead_update(). See the documentation of psa_aead_set_lengths()
2346  * for details.
2347  * -# Call psa_aead_set_nonce() with the nonce for the decryption.
2348  * -# Call psa_aead_update_ad() zero, one or more times, passing a fragment
2349  * of the non-encrypted additional authenticated data each time.
2350  * -# Call psa_aead_update() zero, one or more times, passing a fragment
2351  * of the ciphertext to decrypt each time.
2352  * -# Call psa_aead_verify().
2353  *
2354  * If an error occurs at any step after a call to psa_aead_decrypt_setup(),
2355  * the operation will need to be reset by a call to psa_aead_abort(). The
2356  * application may call psa_aead_abort() at any time after the operation
2357  * has been initialized.
2358  *
2359  * After a successful call to psa_aead_decrypt_setup(), the application must
2360  * eventually terminate the operation. The following events terminate an
2361  * operation:
2362  * - A successful call to psa_aead_verify().
2363  * - A call to psa_aead_abort().
2364  *
2365  * \param[in,out] operation The operation object to set up. It must have
2366  * been initialized as per the documentation for
2367  * #psa_aead_operation_t and not yet in use.
2368  * \param handle Handle to the key to use for the operation.
2369  * It must remain valid until the operation
2370  * terminates.
2371  * \param alg The AEAD algorithm to compute
2372  * (\c PSA_ALG_XXX value such that
2373  * #PSA_ALG_IS_AEAD(\p alg) is true).
2374  *
2375  * \retval #PSA_SUCCESS
2376  * Success.
2377  * \retval #PSA_ERROR_BAD_STATE
2378  * The operation state is not valid (it must be inactive).
2379  * \retval #PSA_ERROR_INVALID_HANDLE
2380  * \retval #PSA_ERROR_NOT_PERMITTED
2381  * \retval #PSA_ERROR_INVALID_ARGUMENT
2382  * \p handle is not compatible with \p alg.
2383  * \retval #PSA_ERROR_NOT_SUPPORTED
2384  * \p alg is not supported or is not an AEAD algorithm.
2385  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2386  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2387  * \retval #PSA_ERROR_HARDWARE_FAILURE
2388  * \retval #PSA_ERROR_CORRUPTION_DETECTED
2389  * \retval #PSA_ERROR_STORAGE_FAILURE
2390  * \retval #PSA_ERROR_BAD_STATE
2391  * The library has not been previously initialized by psa_crypto_init().
2392  * It is implementation-dependent whether a failure to initialize
2393  * results in this error code.
2394  */
2395 psa_status_t psa_aead_decrypt_setup(psa_aead_operation_t *operation,
2396  psa_key_handle_t handle,
2397  psa_algorithm_t alg);
2398 
2399 /** Generate a random nonce for an authenticated encryption operation.
2400  *
2401  * This function generates a random nonce for the authenticated encryption
2402  * operation with an appropriate size for the chosen algorithm, key type
2403  * and key size.
2404  *
2405  * The application must call psa_aead_encrypt_setup() before
2406  * calling this function.
2407  *
2408  * If this function returns an error status, the operation enters an error
2409  * state and must be aborted by calling psa_aead_abort().
2410  *
2411  * \param[in,out] operation Active AEAD operation.
2412  * \param[out] nonce Buffer where the generated nonce is to be
2413  * written.
2414  * \param nonce_size Size of the \p nonce buffer in bytes.
2415  * \param[out] nonce_length On success, the number of bytes of the
2416  * generated nonce.
2417  *
2418  * \retval #PSA_SUCCESS
2419  * Success.
2420  * \retval #PSA_ERROR_BAD_STATE
2421  * The operation state is not valid (it must be an active aead encrypt
2422  operation, with no nonce set).
2423  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2424  * The size of the \p nonce buffer is too small.
2425  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2426  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2427  * \retval #PSA_ERROR_HARDWARE_FAILURE
2428  * \retval #PSA_ERROR_CORRUPTION_DETECTED
2429  * \retval #PSA_ERROR_STORAGE_FAILURE
2430  * \retval #PSA_ERROR_BAD_STATE
2431  * The library has not been previously initialized by psa_crypto_init().
2432  * It is implementation-dependent whether a failure to initialize
2433  * results in this error code.
2434  */
2435 psa_status_t psa_aead_generate_nonce(psa_aead_operation_t *operation,
2436  uint8_t *nonce,
2437  size_t nonce_size,
2438  size_t *nonce_length);
2439 
2440 /** Set the nonce for an authenticated encryption or decryption operation.
2441  *
2442  * This function sets the nonce for the authenticated
2443  * encryption or decryption operation.
2444  *
2445  * The application must call psa_aead_encrypt_setup() or
2446  * psa_aead_decrypt_setup() before calling this function.
2447  *
2448  * If this function returns an error status, the operation enters an error
2449  * state and must be aborted by calling psa_aead_abort().
2450  *
2451  * \note When encrypting, applications should use psa_aead_generate_nonce()
2452  * instead of this function, unless implementing a protocol that requires
2453  * a non-random IV.
2454  *
2455  * \param[in,out] operation Active AEAD operation.
2456  * \param[in] nonce Buffer containing the nonce to use.
2457  * \param nonce_length Size of the nonce in bytes.
2458  *
2459  * \retval #PSA_SUCCESS
2460  * Success.
2461  * \retval #PSA_ERROR_BAD_STATE
2462  * The operation state is not valid (it must be active, with no nonce
2463  * set).
2464  * \retval #PSA_ERROR_INVALID_ARGUMENT
2465  * The size of \p nonce is not acceptable for the chosen algorithm.
2466  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2467  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2468  * \retval #PSA_ERROR_HARDWARE_FAILURE
2469  * \retval #PSA_ERROR_CORRUPTION_DETECTED
2470  * \retval #PSA_ERROR_STORAGE_FAILURE
2471  * \retval #PSA_ERROR_BAD_STATE
2472  * The library has not been previously initialized by psa_crypto_init().
2473  * It is implementation-dependent whether a failure to initialize
2474  * results in this error code.
2475  */
2476 psa_status_t psa_aead_set_nonce(psa_aead_operation_t *operation,
2477  const uint8_t *nonce,
2478  size_t nonce_length);
2479 
2480 /** Declare the lengths of the message and additional data for AEAD.
2481  *
2482  * The application must call this function before calling
2483  * psa_aead_update_ad() or psa_aead_update() if the algorithm for
2484  * the operation requires it. If the algorithm does not require it,
2485  * calling this function is optional, but if this function is called
2486  * then the implementation must enforce the lengths.
2487  *
2488  * You may call this function before or after setting the nonce with
2489  * psa_aead_set_nonce() or psa_aead_generate_nonce().
2490  *
2491  * - For #PSA_ALG_CCM, calling this function is required.
2492  * - For the other AEAD algorithms defined in this specification, calling
2493  * this function is not required.
2494  * - For vendor-defined algorithm, refer to the vendor documentation.
2495  *
2496  * If this function returns an error status, the operation enters an error
2497  * state and must be aborted by calling psa_aead_abort().
2498  *
2499  * \param[in,out] operation Active AEAD operation.
2500  * \param ad_length Size of the non-encrypted additional
2501  * authenticated data in bytes.
2502  * \param plaintext_length Size of the plaintext to encrypt in bytes.
2503  *
2504  * \retval #PSA_SUCCESS
2505  * Success.
2506  * \retval #PSA_ERROR_BAD_STATE
2507  * The operation state is not valid (it must be active, and
2508  * psa_aead_update_ad() and psa_aead_update() must not have been
2509  * called yet).
2510  * \retval #PSA_ERROR_INVALID_ARGUMENT
2511  * At least one of the lengths is not acceptable for the chosen
2512  * algorithm.
2513  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2514  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2515  * \retval #PSA_ERROR_HARDWARE_FAILURE
2516  * \retval #PSA_ERROR_CORRUPTION_DETECTED
2517  * \retval #PSA_ERROR_BAD_STATE
2518  * The library has not been previously initialized by psa_crypto_init().
2519  * It is implementation-dependent whether a failure to initialize
2520  * results in this error code.
2521  */
2522 psa_status_t psa_aead_set_lengths(psa_aead_operation_t *operation,
2523  size_t ad_length,
2524  size_t plaintext_length);
2525 
2526 /** Pass additional data to an active AEAD operation.
2527  *
2528  * Additional data is authenticated, but not encrypted.
2529  *
2530  * You may call this function multiple times to pass successive fragments
2531  * of the additional data. You may not call this function after passing
2532  * data to encrypt or decrypt with psa_aead_update().
2533  *
2534  * Before calling this function, you must:
2535  * 1. Call either psa_aead_encrypt_setup() or psa_aead_decrypt_setup().
2536  * 2. Set the nonce with psa_aead_generate_nonce() or psa_aead_set_nonce().
2537  *
2538  * If this function returns an error status, the operation enters an error
2539  * state and must be aborted by calling psa_aead_abort().
2540  *
2541  * \warning When decrypting, until psa_aead_verify() has returned #PSA_SUCCESS,
2542  * there is no guarantee that the input is valid. Therefore, until
2543  * you have called psa_aead_verify() and it has returned #PSA_SUCCESS,
2544  * treat the input as untrusted and prepare to undo any action that
2545  * depends on the input if psa_aead_verify() returns an error status.
2546  *
2547  * \param[in,out] operation Active AEAD operation.
2548  * \param[in] input Buffer containing the fragment of
2549  * additional data.
2550  * \param input_length Size of the \p input buffer in bytes.
2551  *
2552  * \retval #PSA_SUCCESS
2553  * Success.
2554  * \retval #PSA_ERROR_BAD_STATE
2555  * The operation state is not valid (it must be active, have a nonce
2556  * set, have lengths set if required by the algorithm, and
2557  * psa_aead_update() must not have been called yet).
2558  * \retval #PSA_ERROR_INVALID_ARGUMENT
2559  * The total input length overflows the additional data length that
2560  * was previously specified with psa_aead_set_lengths().
2561  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2562  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2563  * \retval #PSA_ERROR_HARDWARE_FAILURE
2564  * \retval #PSA_ERROR_CORRUPTION_DETECTED
2565  * \retval #PSA_ERROR_STORAGE_FAILURE
2566  * \retval #PSA_ERROR_BAD_STATE
2567  * The library has not been previously initialized by psa_crypto_init().
2568  * It is implementation-dependent whether a failure to initialize
2569  * results in this error code.
2570  */
2571 psa_status_t psa_aead_update_ad(psa_aead_operation_t *operation,
2572  const uint8_t *input,
2573  size_t input_length);
2574 
2575 /** Encrypt or decrypt a message fragment in an active AEAD operation.
2576  *
2577  * Before calling this function, you must:
2578  * 1. Call either psa_aead_encrypt_setup() or psa_aead_decrypt_setup().
2579  * The choice of setup function determines whether this function
2580  * encrypts or decrypts its input.
2581  * 2. Set the nonce with psa_aead_generate_nonce() or psa_aead_set_nonce().
2582  * 3. Call psa_aead_update_ad() to pass all the additional data.
2583  *
2584  * If this function returns an error status, the operation enters an error
2585  * state and must be aborted by calling psa_aead_abort().
2586  *
2587  * \warning When decrypting, until psa_aead_verify() has returned #PSA_SUCCESS,
2588  * there is no guarantee that the input is valid. Therefore, until
2589  * you have called psa_aead_verify() and it has returned #PSA_SUCCESS:
2590  * - Do not use the output in any way other than storing it in a
2591  * confidential location. If you take any action that depends
2592  * on the tentative decrypted data, this action will need to be
2593  * undone if the input turns out not to be valid. Furthermore,
2594  * if an adversary can observe that this action took place
2595  * (for example through timing), they may be able to use this
2596  * fact as an oracle to decrypt any message encrypted with the
2597  * same key.
2598  * - In particular, do not copy the output anywhere but to a
2599  * memory or storage space that you have exclusive access to.
2600  *
2601  * This function does not require the input to be aligned to any
2602  * particular block boundary. If the implementation can only process
2603  * a whole block at a time, it must consume all the input provided, but
2604  * it may delay the end of the corresponding output until a subsequent
2605  * call to psa_aead_update(), psa_aead_finish() or psa_aead_verify()
2606  * provides sufficient input. The amount of data that can be delayed
2607  * in this way is bounded by #PSA_AEAD_UPDATE_OUTPUT_SIZE.
2608  *
2609  * \param[in,out] operation Active AEAD operation.
2610  * \param[in] input Buffer containing the message fragment to
2611  * encrypt or decrypt.
2612  * \param input_length Size of the \p input buffer in bytes.
2613  * \param[out] output Buffer where the output is to be written.
2614  * \param output_size Size of the \p output buffer in bytes.
2615  * This must be at least
2616  * #PSA_AEAD_UPDATE_OUTPUT_SIZE(\c alg,
2617  * \p input_length) where \c alg is the
2618  * algorithm that is being calculated.
2619  * \param[out] output_length On success, the number of bytes
2620  * that make up the returned output.
2621  *
2622  * \retval #PSA_SUCCESS
2623  * Success.
2624  * \retval #PSA_ERROR_BAD_STATE
2625  * The operation state is not valid (it must be active, have a nonce
2626  * set, and have lengths set if required by the algorithm).
2627  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2628  * The size of the \p output buffer is too small.
2629  * You can determine a sufficient buffer size by calling
2630  * #PSA_AEAD_UPDATE_OUTPUT_SIZE(\c alg, \p input_length)
2631  * where \c alg is the algorithm that is being calculated.
2632  * \retval #PSA_ERROR_INVALID_ARGUMENT
2633  * The total length of input to psa_aead_update_ad() so far is
2634  * less than the additional data length that was previously
2635  * specified with psa_aead_set_lengths().
2636  * \retval #PSA_ERROR_INVALID_ARGUMENT
2637  * The total input length overflows the plaintext length that
2638  * was previously specified with psa_aead_set_lengths().
2639  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2640  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2641  * \retval #PSA_ERROR_HARDWARE_FAILURE
2642  * \retval #PSA_ERROR_CORRUPTION_DETECTED
2643  * \retval #PSA_ERROR_STORAGE_FAILURE
2644  * \retval #PSA_ERROR_BAD_STATE
2645  * The library has not been previously initialized by psa_crypto_init().
2646  * It is implementation-dependent whether a failure to initialize
2647  * results in this error code.
2648  */
2649 psa_status_t psa_aead_update(psa_aead_operation_t *operation,
2650  const uint8_t *input,
2651  size_t input_length,
2652  uint8_t *output,
2653  size_t output_size,
2654  size_t *output_length);
2655 
2656 /** Finish encrypting a message in an AEAD operation.
2657  *
2658  * The operation must have been set up with psa_aead_encrypt_setup().
2659  *
2660  * This function finishes the authentication of the additional data
2661  * formed by concatenating the inputs passed to preceding calls to
2662  * psa_aead_update_ad() with the plaintext formed by concatenating the
2663  * inputs passed to preceding calls to psa_aead_update().
2664  *
2665  * This function has two output buffers:
2666  * - \p ciphertext contains trailing ciphertext that was buffered from
2667  * preceding calls to psa_aead_update().
2668  * - \p tag contains the authentication tag. Its length is always
2669  * #PSA_AEAD_TAG_LENGTH(\c alg) where \c alg is the AEAD algorithm
2670  * that the operation performs.
2671  *
2672  * When this function returns successfuly, the operation becomes inactive.
2673  * If this function returns an error status, the operation enters an error
2674  * state and must be aborted by calling psa_aead_abort().
2675  *
2676  * \param[in,out] operation Active AEAD operation.
2677  * \param[out] ciphertext Buffer where the last part of the ciphertext
2678  * is to be written.
2679  * \param ciphertext_size Size of the \p ciphertext buffer in bytes.
2680  * This must be at least
2681  * #PSA_AEAD_FINISH_OUTPUT_SIZE(\c alg) where
2682  * \c alg is the algorithm that is being
2683  * calculated.
2684  * \param[out] ciphertext_length On success, the number of bytes of
2685  * returned ciphertext.
2686  * \param[out] tag Buffer where the authentication tag is
2687  * to be written.
2688  * \param tag_size Size of the \p tag buffer in bytes.
2689  * This must be at least
2690  * #PSA_AEAD_TAG_LENGTH(\c alg) where \c alg is
2691  * the algorithm that is being calculated.
2692  * \param[out] tag_length On success, the number of bytes
2693  * that make up the returned tag.
2694  *
2695  * \retval #PSA_SUCCESS
2696  * Success.
2697  * \retval #PSA_ERROR_BAD_STATE
2698  * The operation state is not valid (it must be an active encryption
2699  * operation with a nonce set).
2700  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2701  * The size of the \p ciphertext or \p tag buffer is too small.
2702  * You can determine a sufficient buffer size for \p ciphertext by
2703  * calling #PSA_AEAD_FINISH_OUTPUT_SIZE(\c alg)
2704  * where \c alg is the algorithm that is being calculated.
2705  * You can determine a sufficient buffer size for \p tag by
2706  * calling #PSA_AEAD_TAG_LENGTH(\c alg).
2707  * \retval #PSA_ERROR_INVALID_ARGUMENT
2708  * The total length of input to psa_aead_update_ad() so far is
2709  * less than the additional data length that was previously
2710  * specified with psa_aead_set_lengths().
2711  * \retval #PSA_ERROR_INVALID_ARGUMENT
2712  * The total length of input to psa_aead_update() so far is
2713  * less than the plaintext length that was previously
2714  * specified with psa_aead_set_lengths().
2715  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2716  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2717  * \retval #PSA_ERROR_HARDWARE_FAILURE
2718  * \retval #PSA_ERROR_CORRUPTION_DETECTED
2719  * \retval #PSA_ERROR_STORAGE_FAILURE
2720  * \retval #PSA_ERROR_BAD_STATE
2721  * The library has not been previously initialized by psa_crypto_init().
2722  * It is implementation-dependent whether a failure to initialize
2723  * results in this error code.
2724  */
2725 psa_status_t psa_aead_finish(psa_aead_operation_t *operation,
2726  uint8_t *ciphertext,
2727  size_t ciphertext_size,
2728  size_t *ciphertext_length,
2729  uint8_t *tag,
2730  size_t tag_size,
2731  size_t *tag_length);
2732 
2733 /** Finish authenticating and decrypting a message in an AEAD operation.
2734  *
2735  * The operation must have been set up with psa_aead_decrypt_setup().
2736  *
2737  * This function finishes the authenticated decryption of the message
2738  * components:
2739  *
2740  * - The additional data consisting of the concatenation of the inputs
2741  * passed to preceding calls to psa_aead_update_ad().
2742  * - The ciphertext consisting of the concatenation of the inputs passed to
2743  * preceding calls to psa_aead_update().
2744  * - The tag passed to this function call.
2745  *
2746  * If the authentication tag is correct, this function outputs any remaining
2747  * plaintext and reports success. If the authentication tag is not correct,
2748  * this function returns #PSA_ERROR_INVALID_SIGNATURE.
2749  *
2750  * When this function returns successfuly, the operation becomes inactive.
2751  * If this function returns an error status, the operation enters an error
2752  * state and must be aborted by calling psa_aead_abort().
2753  *
2754  * \note Implementations shall make the best effort to ensure that the
2755  * comparison between the actual tag and the expected tag is performed
2756  * in constant time.
2757  *
2758  * \param[in,out] operation Active AEAD operation.
2759  * \param[out] plaintext Buffer where the last part of the plaintext
2760  * is to be written. This is the remaining data
2761  * from previous calls to psa_aead_update()
2762  * that could not be processed until the end
2763  * of the input.
2764  * \param plaintext_size Size of the \p plaintext buffer in bytes.
2765  * This must be at least
2766  * #PSA_AEAD_VERIFY_OUTPUT_SIZE(\c alg) where
2767  * \c alg is the algorithm that is being
2768  * calculated.
2769  * \param[out] plaintext_length On success, the number of bytes of
2770  * returned plaintext.
2771  * \param[in] tag Buffer containing the authentication tag.
2772  * \param tag_length Size of the \p tag buffer in bytes.
2773  *
2774  * \retval #PSA_SUCCESS
2775  * Success.
2776  * \retval #PSA_ERROR_INVALID_SIGNATURE
2777  * The calculations were successful, but the authentication tag is
2778  * not correct.
2779  * \retval #PSA_ERROR_BAD_STATE
2780  * The operation state is not valid (it must be an active decryption
2781  * operation with a nonce set).
2782  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2783  * The size of the \p plaintext buffer is too small.
2784  * You can determine a sufficient buffer size for \p plaintext by
2785  * calling #PSA_AEAD_VERIFY_OUTPUT_SIZE(\c alg)
2786  * where \c alg is the algorithm that is being calculated.
2787  * \retval #PSA_ERROR_INVALID_ARGUMENT
2788  * The total length of input to psa_aead_update_ad() so far is
2789  * less than the additional data length that was previously
2790  * specified with psa_aead_set_lengths().
2791  * \retval #PSA_ERROR_INVALID_ARGUMENT
2792  * The total length of input to psa_aead_update() so far is
2793  * less than the plaintext length that was previously
2794  * specified with psa_aead_set_lengths().
2795  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2796  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2797  * \retval #PSA_ERROR_HARDWARE_FAILURE
2798  * \retval #PSA_ERROR_CORRUPTION_DETECTED
2799  * \retval #PSA_ERROR_STORAGE_FAILURE
2800  * \retval #PSA_ERROR_BAD_STATE
2801  * The library has not been previously initialized by psa_crypto_init().
2802  * It is implementation-dependent whether a failure to initialize
2803  * results in this error code.
2804  */
2805 psa_status_t psa_aead_verify(psa_aead_operation_t *operation,
2806  uint8_t *plaintext,
2807  size_t plaintext_size,
2808  size_t *plaintext_length,
2809  const uint8_t *tag,
2810  size_t tag_length);
2811 
2812 /** Abort an AEAD operation.
2813  *
2814  * Aborting an operation frees all associated resources except for the
2815  * \p operation structure itself. Once aborted, the operation object
2816  * can be reused for another operation by calling
2817  * psa_aead_encrypt_setup() or psa_aead_decrypt_setup() again.
2818  *
2819  * You may call this function any time after the operation object has
2820  * been initialized as described in #psa_aead_operation_t.
2821  *
2822  * In particular, calling psa_aead_abort() after the operation has been
2823  * terminated by a call to psa_aead_abort(), psa_aead_finish() or
2824  * psa_aead_verify() is safe and has no effect.
2825  *
2826  * \param[in,out] operation Initialized AEAD operation.
2827  *
2828  * \retval #PSA_SUCCESS
2829  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2830  * \retval #PSA_ERROR_HARDWARE_FAILURE
2831  * \retval #PSA_ERROR_CORRUPTION_DETECTED
2832  * \retval #PSA_ERROR_BAD_STATE
2833  * The library has not been previously initialized by psa_crypto_init().
2834  * It is implementation-dependent whether a failure to initialize
2835  * results in this error code.
2836  */
2837 psa_status_t psa_aead_abort(psa_aead_operation_t *operation);
2838 
2839 /**@}*/
2840 
2841 /** \defgroup asymmetric Asymmetric cryptography
2842  * @{
2843  */
2844 
2845 /**
2846  * \brief Sign a hash or short message with a private key.
2847  *
2848  * Note that to perform a hash-and-sign signature algorithm, you must
2849  * first calculate the hash by calling psa_hash_setup(), psa_hash_update()
2850  * and psa_hash_finish(). Then pass the resulting hash as the \p hash
2851  * parameter to this function. You can use #PSA_ALG_SIGN_GET_HASH(\p alg)
2852  * to determine the hash algorithm to use.
2853  *
2854  * \param handle Handle to the key to use for the operation.
2855  * It must be an asymmetric key pair.
2856  * \param alg A signature algorithm that is compatible with
2857  * the type of \p handle.
2858  * \param[in] hash The hash or message to sign.
2859  * \param hash_length Size of the \p hash buffer in bytes.
2860  * \param[out] signature Buffer where the signature is to be written.
2861  * \param signature_size Size of the \p signature buffer in bytes.
2862  * \param[out] signature_length On success, the number of bytes
2863  * that make up the returned signature value.
2864  *
2865  * \retval #PSA_SUCCESS
2866  * \retval #PSA_ERROR_INVALID_HANDLE
2867  * \retval #PSA_ERROR_NOT_PERMITTED
2868  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2869  * The size of the \p signature buffer is too small. You can
2870  * determine a sufficient buffer size by calling
2871  * #PSA_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
2872  * where \c key_type and \c key_bits are the type and bit-size
2873  * respectively of \p handle.
2874  * \retval #PSA_ERROR_NOT_SUPPORTED
2875  * \retval #PSA_ERROR_INVALID_ARGUMENT
2876  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2877  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2878  * \retval #PSA_ERROR_HARDWARE_FAILURE
2879  * \retval #PSA_ERROR_CORRUPTION_DETECTED
2880  * \retval #PSA_ERROR_STORAGE_FAILURE
2881  * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
2882  * \retval #PSA_ERROR_BAD_STATE
2883  * The library has not been previously initialized by psa_crypto_init().
2884  * It is implementation-dependent whether a failure to initialize
2885  * results in this error code.
2886  */
2887 psa_status_t psa_sign_hash(psa_key_handle_t handle,
2888  psa_algorithm_t alg,
2889  const uint8_t *hash,
2890  size_t hash_length,
2891  uint8_t *signature,
2892  size_t signature_size,
2893  size_t *signature_length);
2894 
2895 /**
2896  * \brief Verify the signature a hash or short message using a public key.
2897  *
2898  * Note that to perform a hash-and-sign signature algorithm, you must
2899  * first calculate the hash by calling psa_hash_setup(), psa_hash_update()
2900  * and psa_hash_finish(). Then pass the resulting hash as the \p hash
2901  * parameter to this function. You can use #PSA_ALG_SIGN_GET_HASH(\p alg)
2902  * to determine the hash algorithm to use.
2903  *
2904  * \param handle Handle to the key to use for the operation.
2905  * It must be a public key or an asymmetric key pair.
2906  * \param alg A signature algorithm that is compatible with
2907  * the type of \p handle.
2908  * \param[in] hash The hash or message whose signature is to be
2909  * verified.
2910  * \param hash_length Size of the \p hash buffer in bytes.
2911  * \param[in] signature Buffer containing the signature to verify.
2912  * \param signature_length Size of the \p signature buffer in bytes.
2913  *
2914  * \retval #PSA_SUCCESS
2915  * The signature is valid.
2916  * \retval #PSA_ERROR_INVALID_HANDLE
2917  * \retval #PSA_ERROR_NOT_PERMITTED
2918  * \retval #PSA_ERROR_INVALID_SIGNATURE
2919  * The calculation was perfomed successfully, but the passed
2920  * signature is not a valid signature.
2921  * \retval #PSA_ERROR_NOT_SUPPORTED
2922  * \retval #PSA_ERROR_INVALID_ARGUMENT
2923  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2924  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2925  * \retval #PSA_ERROR_HARDWARE_FAILURE
2926  * \retval #PSA_ERROR_CORRUPTION_DETECTED
2927  * \retval #PSA_ERROR_STORAGE_FAILURE
2928  * \retval #PSA_ERROR_BAD_STATE
2929  * The library has not been previously initialized by psa_crypto_init().
2930  * It is implementation-dependent whether a failure to initialize
2931  * results in this error code.
2932  */
2933 psa_status_t psa_verify_hash(psa_key_handle_t handle,
2934  psa_algorithm_t alg,
2935  const uint8_t *hash,
2936  size_t hash_length,
2937  const uint8_t *signature,
2938  size_t signature_length);
2939 
2940 /**
2941  * \brief Encrypt a short message with a public key.
2942  *
2943  * \param handle Handle to the key to use for the operation.
2944  * It must be a public key or an asymmetric
2945  * key pair.
2946  * \param alg An asymmetric encryption algorithm that is
2947  * compatible with the type of \p handle.
2948  * \param[in] input The message to encrypt.
2949  * \param input_length Size of the \p input buffer in bytes.
2950  * \param[in] salt A salt or label, if supported by the
2951  * encryption algorithm.
2952  * If the algorithm does not support a
2953  * salt, pass \c NULL.
2954  * If the algorithm supports an optional
2955  * salt and you do not want to pass a salt,
2956  * pass \c NULL.
2957  *
2958  * - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is
2959  * supported.
2960  * \param salt_length Size of the \p salt buffer in bytes.
2961  * If \p salt is \c NULL, pass 0.
2962  * \param[out] output Buffer where the encrypted message is to
2963  * be written.
2964  * \param output_size Size of the \p output buffer in bytes.
2965  * \param[out] output_length On success, the number of bytes
2966  * that make up the returned output.
2967  *
2968  * \retval #PSA_SUCCESS
2969  * \retval #PSA_ERROR_INVALID_HANDLE
2970  * \retval #PSA_ERROR_NOT_PERMITTED
2971  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2972  * The size of the \p output buffer is too small. You can
2973  * determine a sufficient buffer size by calling
2974  * #PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
2975  * where \c key_type and \c key_bits are the type and bit-size
2976  * respectively of \p handle.
2977  * \retval #PSA_ERROR_NOT_SUPPORTED
2978  * \retval #PSA_ERROR_INVALID_ARGUMENT
2979  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2980  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2981  * \retval #PSA_ERROR_HARDWARE_FAILURE
2982  * \retval #PSA_ERROR_CORRUPTION_DETECTED
2983  * \retval #PSA_ERROR_STORAGE_FAILURE
2984  * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
2985  * \retval #PSA_ERROR_BAD_STATE
2986  * The library has not been previously initialized by psa_crypto_init().
2987  * It is implementation-dependent whether a failure to initialize
2988  * results in this error code.
2989  */
2990 psa_status_t psa_asymmetric_encrypt(psa_key_handle_t handle,
2991  psa_algorithm_t alg,
2992  const uint8_t *input,
2993  size_t input_length,
2994  const uint8_t *salt,
2995  size_t salt_length,
2996  uint8_t *output,
2997  size_t output_size,
2998  size_t *output_length);
2999 
3000 /**
3001  * \brief Decrypt a short message with a private key.
3002  *
3003  * \param handle Handle to the key to use for the operation.
3004  * It must be an asymmetric key pair.
3005  * \param alg An asymmetric encryption algorithm that is
3006  * compatible with the type of \p handle.
3007  * \param[in] input The message to decrypt.
3008  * \param input_length Size of the \p input buffer in bytes.
3009  * \param[in] salt A salt or label, if supported by the
3010  * encryption algorithm.
3011  * If the algorithm does not support a
3012  * salt, pass \c NULL.
3013  * If the algorithm supports an optional
3014  * salt and you do not want to pass a salt,
3015  * pass \c NULL.
3016  *
3017  * - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is
3018  * supported.
3019  * \param salt_length Size of the \p salt buffer in bytes.
3020  * If \p salt is \c NULL, pass 0.
3021  * \param[out] output Buffer where the decrypted message is to
3022  * be written.
3023  * \param output_size Size of the \c output buffer in bytes.
3024  * \param[out] output_length On success, the number of bytes
3025  * that make up the returned output.
3026  *
3027  * \retval #PSA_SUCCESS
3028  * \retval #PSA_ERROR_INVALID_HANDLE
3029  * \retval #PSA_ERROR_NOT_PERMITTED
3030  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
3031  * The size of the \p output buffer is too small. You can
3032  * determine a sufficient buffer size by calling
3033  * #PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
3034  * where \c key_type and \c key_bits are the type and bit-size
3035  * respectively of \p handle.
3036  * \retval #PSA_ERROR_NOT_SUPPORTED
3037  * \retval #PSA_ERROR_INVALID_ARGUMENT
3038  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3039  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3040  * \retval #PSA_ERROR_HARDWARE_FAILURE
3041  * \retval #PSA_ERROR_CORRUPTION_DETECTED
3042  * \retval #PSA_ERROR_STORAGE_FAILURE
3043  * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
3044  * \retval #PSA_ERROR_INVALID_PADDING
3045  * \retval #PSA_ERROR_BAD_STATE
3046  * The library has not been previously initialized by psa_crypto_init().
3047  * It is implementation-dependent whether a failure to initialize
3048  * results in this error code.
3049  */
3050 psa_status_t psa_asymmetric_decrypt(psa_key_handle_t handle,
3051  psa_algorithm_t alg,
3052  const uint8_t *input,
3053  size_t input_length,
3054  const uint8_t *salt,
3055  size_t salt_length,
3056  uint8_t *output,
3057  size_t output_size,
3058  size_t *output_length);
3059 
3060 /**@}*/
3061 
3062 /** \defgroup key_derivation Key derivation and pseudorandom generation
3063  * @{
3064  */
3065 
3066 /** The type of the state data structure for key derivation operations.
3067  *
3068  * Before calling any function on a key derivation operation object, the
3069  * application must initialize it by any of the following means:
3070  * - Set the structure to all-bits-zero, for example:
3071  * \code
3072  * psa_key_derivation_operation_t operation;
3073  * memset(&operation, 0, sizeof(operation));
3074  * \endcode
3075  * - Initialize the structure to logical zero values, for example:
3076  * \code
3077  * psa_key_derivation_operation_t operation = {0};
3078  * \endcode
3079  * - Initialize the structure to the initializer #PSA_KEY_DERIVATION_OPERATION_INIT,
3080  * for example:
3081  * \code
3082  * psa_key_derivation_operation_t operation = PSA_KEY_DERIVATION_OPERATION_INIT;
3083  * \endcode
3084  * - Assign the result of the function psa_key_derivation_operation_init()
3085  * to the structure, for example:
3086  * \code
3087  * psa_key_derivation_operation_t operation;
3088  * operation = psa_key_derivation_operation_init();
3089  * \endcode
3090  *
3091  * This is an implementation-defined \c struct. Applications should not
3092  * make any assumptions about the content of this structure except
3093  * as directed by the documentation of a specific implementation.
3094  */
3095 typedef struct psa_key_derivation_s psa_key_derivation_operation_t;
3096 
3097 /** \def PSA_KEY_DERIVATION_OPERATION_INIT
3098  *
3099  * This macro returns a suitable initializer for a key derivation operation
3100  * object of type #psa_key_derivation_operation_t.
3101  */
3102 #ifdef __DOXYGEN_ONLY__
3103 /* This is an example definition for documentation purposes.
3104  * Implementations should define a suitable value in `crypto_struct.h`.
3105  */
3106 #define PSA_KEY_DERIVATION_OPERATION_INIT {0}
3107 #endif
3108 
3109 /** Return an initial value for a key derivation operation object.
3110  */
3111 static psa_key_derivation_operation_t psa_key_derivation_operation_init(void);
3112 
3113 /** Set up a key derivation operation.
3114  *
3115  * A key derivation algorithm takes some inputs and uses them to generate
3116  * a byte stream in a deterministic way.
3117  * This byte stream can be used to produce keys and other
3118  * cryptographic material.
3119  *
3120  * To derive a key:
3121  * -# Start with an initialized object of type #psa_key_derivation_operation_t.
3122  * -# Call psa_key_derivation_setup() to select the algorithm.
3123  * -# Provide the inputs for the key derivation by calling
3124  * psa_key_derivation_input_bytes() or psa_key_derivation_input_key()
3125  * as appropriate. Which inputs are needed, in what order, and whether
3126  * they may be keys and if so of what type depends on the algorithm.
3127  * -# Optionally set the operation's maximum capacity with
3128  * psa_key_derivation_set_capacity(). You may do this before, in the middle
3129  * of or after providing inputs. For some algorithms, this step is mandatory
3130  * because the output depends on the maximum capacity.
3131  * -# To derive a key, call psa_key_derivation_output_key().
3132  * To derive a byte string for a different purpose, call
3133  * psa_key_derivation_output_bytes().
3134  * Successive calls to these functions use successive output bytes
3135  * calculated by the key derivation algorithm.
3136  * -# Clean up the key derivation operation object with
3137  * psa_key_derivation_abort().
3138  *
3139  * If this function returns an error, the key derivation operation object is
3140  * not changed.
3141  *
3142  * If an error occurs at any step after a call to psa_key_derivation_setup(),
3143  * the operation will need to be reset by a call to psa_key_derivation_abort().
3144  *
3145  * Implementations must reject an attempt to derive a key of size 0.
3146  *
3147  * \param[in,out] operation The key derivation operation object
3148  * to set up. It must
3149  * have been initialized but not set up yet.
3150  * \param alg The key derivation algorithm to compute
3151  * (\c PSA_ALG_XXX value such that
3152  * #PSA_ALG_IS_KEY_DERIVATION(\p alg) is true).
3153  *
3154  * \retval #PSA_SUCCESS
3155  * Success.
3156  * \retval #PSA_ERROR_INVALID_ARGUMENT
3157  * \c alg is not a key derivation algorithm.
3158  * \retval #PSA_ERROR_NOT_SUPPORTED
3159  * \c alg is not supported or is not a key derivation algorithm.
3160  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3161  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3162  * \retval #PSA_ERROR_HARDWARE_FAILURE
3163  * \retval #PSA_ERROR_CORRUPTION_DETECTED
3164  * \retval #PSA_ERROR_STORAGE_FAILURE
3165  * \retval #PSA_ERROR_BAD_STATE
3166  * The operation state is not valid (it must be inactive).
3167  * \retval #PSA_ERROR_BAD_STATE
3168  * The library has not been previously initialized by psa_crypto_init().
3169  * It is implementation-dependent whether a failure to initialize
3170  * results in this error code.
3171  */
3172 psa_status_t psa_key_derivation_setup(
3173  psa_key_derivation_operation_t *operation,
3174  psa_algorithm_t alg);
3175 
3176 /** Retrieve the current capacity of a key derivation operation.
3177  *
3178  * The capacity of a key derivation is the maximum number of bytes that it can
3179  * return. When you get *N* bytes of output from a key derivation operation,
3180  * this reduces its capacity by *N*.
3181  *
3182  * \param[in] operation The operation to query.
3183  * \param[out] capacity On success, the capacity of the operation.
3184  *
3185  * \retval #PSA_SUCCESS
3186  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3187  * \retval #PSA_ERROR_BAD_STATE
3188  * The operation state is not valid (it must be active).
3189  * \retval #PSA_ERROR_HARDWARE_FAILURE
3190  * \retval #PSA_ERROR_CORRUPTION_DETECTED
3191  * \retval #PSA_ERROR_BAD_STATE
3192  * The library has not been previously initialized by psa_crypto_init().
3193  * It is implementation-dependent whether a failure to initialize
3194  * results in this error code.
3195  */
3196 psa_status_t psa_key_derivation_get_capacity(
3197  const psa_key_derivation_operation_t *operation,
3198  size_t *capacity);
3199 
3200 /** Set the maximum capacity of a key derivation operation.
3201  *
3202  * The capacity of a key derivation operation is the maximum number of bytes
3203  * that the key derivation operation can return from this point onwards.
3204  *
3205  * \param[in,out] operation The key derivation operation object to modify.
3206  * \param capacity The new capacity of the operation.
3207  * It must be less or equal to the operation's
3208  * current capacity.
3209  *
3210  * \retval #PSA_SUCCESS
3211  * \retval #PSA_ERROR_INVALID_ARGUMENT
3212  * \p capacity is larger than the operation's current capacity.
3213  * In this case, the operation object remains valid and its capacity
3214  * remains unchanged.
3215  * \retval #PSA_ERROR_BAD_STATE
3216  * The operation state is not valid (it must be active).
3217  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3218  * \retval #PSA_ERROR_HARDWARE_FAILURE
3219  * \retval #PSA_ERROR_CORRUPTION_DETECTED
3220  * \retval #PSA_ERROR_BAD_STATE
3221  * The library has not been previously initialized by psa_crypto_init().
3222  * It is implementation-dependent whether a failure to initialize
3223  * results in this error code.
3224  */
3225 psa_status_t psa_key_derivation_set_capacity(
3226  psa_key_derivation_operation_t *operation,
3227  size_t capacity);
3228 
3229 /** Use the maximum possible capacity for a key derivation operation.
3230  *
3231  * Use this value as the capacity argument when setting up a key derivation
3232  * to indicate that the operation should have the maximum possible capacity.
3233  * The value of the maximum possible capacity depends on the key derivation
3234  * algorithm.
3235  */
3236 #define PSA_KEY_DERIVATION_UNLIMITED_CAPACITY ((size_t)(-1))
3237 
3238 /** Provide an input for key derivation or key agreement.
3239  *
3240  * Which inputs are required and in what order depends on the algorithm.
3241  * Refer to the documentation of each key derivation or key agreement
3242  * algorithm for information.
3243  *
3244  * This function passes direct inputs, which is usually correct for
3245  * non-secret inputs. To pass a secret input, which should be in a key
3246  * object, call psa_key_derivation_input_key() instead of this function.
3247  * Refer to the documentation of individual step types
3248  * (`PSA_KEY_DERIVATION_INPUT_xxx` values of type ::psa_key_derivation_step_t)
3249  * for more information.
3250  *
3251  * If this function returns an error status, the operation enters an error
3252  * state and must be aborted by calling psa_key_derivation_abort().
3253  *
3254  * \param[in,out] operation The key derivation operation object to use.
3255  * It must have been set up with
3256  * psa_key_derivation_setup() and must not
3257  * have produced any output yet.
3258  * \param step Which step the input data is for.
3259  * \param[in] data Input data to use.
3260  * \param data_length Size of the \p data buffer in bytes.
3261  *
3262  * \retval #PSA_SUCCESS
3263  * Success.
3264  * \retval #PSA_ERROR_INVALID_ARGUMENT
3265  * \c step is not compatible with the operation's algorithm.
3266  * \retval #PSA_ERROR_INVALID_ARGUMENT
3267  * \c step does not allow direct inputs.
3268  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3269  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3270  * \retval #PSA_ERROR_HARDWARE_FAILURE
3271  * \retval #PSA_ERROR_CORRUPTION_DETECTED
3272  * \retval #PSA_ERROR_STORAGE_FAILURE
3273  * \retval #PSA_ERROR_BAD_STATE
3274  * The operation state is not valid for this input \p step.
3275  * \retval #PSA_ERROR_BAD_STATE
3276  * The library has not been previously initialized by psa_crypto_init().
3277  * It is implementation-dependent whether a failure to initialize
3278  * results in this error code.
3279  */
3280 psa_status_t psa_key_derivation_input_bytes(
3281  psa_key_derivation_operation_t *operation,
3282  psa_key_derivation_step_t step,
3283  const uint8_t *data,
3284  size_t data_length);
3285 
3286 /** Provide an input for key derivation in the form of a key.
3287  *
3288  * Which inputs are required and in what order depends on the algorithm.
3289  * Refer to the documentation of each key derivation or key agreement
3290  * algorithm for information.
3291  *
3292  * This function obtains input from a key object, which is usually correct for
3293  * secret inputs or for non-secret personalization strings kept in the key
3294  * store. To pass a non-secret parameter which is not in the key store,
3295  * call psa_key_derivation_input_bytes() instead of this function.
3296  * Refer to the documentation of individual step types
3297  * (`PSA_KEY_DERIVATION_INPUT_xxx` values of type ::psa_key_derivation_step_t)
3298  * for more information.
3299  *
3300  * If this function returns an error status, the operation enters an error
3301  * state and must be aborted by calling psa_key_derivation_abort().
3302  *
3303  * \param[in,out] operation The key derivation operation object to use.
3304  * It must have been set up with
3305  * psa_key_derivation_setup() and must not
3306  * have produced any output yet.
3307  * \param step Which step the input data is for.
3308  * \param handle Handle to the key. It must have an
3309  * appropriate type for \p step and must
3310  * allow the usage #PSA_KEY_USAGE_DERIVE.
3311  *
3312  * \retval #PSA_SUCCESS
3313  * Success.
3314  * \retval #PSA_ERROR_INVALID_HANDLE
3315  * \retval #PSA_ERROR_NOT_PERMITTED
3316  * \retval #PSA_ERROR_INVALID_ARGUMENT
3317  * \c step is not compatible with the operation's algorithm.
3318  * \retval #PSA_ERROR_INVALID_ARGUMENT
3319  * \c step does not allow key inputs of the given type
3320  * or does not allow key inputs at all.
3321  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3322  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3323  * \retval #PSA_ERROR_HARDWARE_FAILURE
3324  * \retval #PSA_ERROR_CORRUPTION_DETECTED
3325  * \retval #PSA_ERROR_STORAGE_FAILURE
3326  * \retval #PSA_ERROR_BAD_STATE
3327  * The operation state is not valid for this input \p step.
3328  * \retval #PSA_ERROR_BAD_STATE
3329  * The library has not been previously initialized by psa_crypto_init().
3330  * It is implementation-dependent whether a failure to initialize
3331  * results in this error code.
3332  */
3333 psa_status_t psa_key_derivation_input_key(
3334  psa_key_derivation_operation_t *operation,
3335  psa_key_derivation_step_t step,
3336  psa_key_handle_t handle);
3337 
3338 /** Perform a key agreement and use the shared secret as input to a key
3339  * derivation.
3340  *
3341  * A key agreement algorithm takes two inputs: a private key \p private_key
3342  * a public key \p peer_key.
3343  * The result of this function is passed as input to a key derivation.
3344  * The output of this key derivation can be extracted by reading from the
3345  * resulting operation to produce keys and other cryptographic material.
3346  *
3347  * If this function returns an error status, the operation enters an error
3348  * state and must be aborted by calling psa_key_derivation_abort().
3349  *
3350  * \param[in,out] operation The key derivation operation object to use.
3351  * It must have been set up with
3352  * psa_key_derivation_setup() with a
3353  * key agreement and derivation algorithm
3354  * \c alg (\c PSA_ALG_XXX value such that
3355  * #PSA_ALG_IS_KEY_AGREEMENT(\c alg) is true
3356  * and #PSA_ALG_IS_RAW_KEY_AGREEMENT(\c alg)
3357  * is false).
3358  * The operation must be ready for an
3359  * input of the type given by \p step.
3360  * \param step Which step the input data is for.
3361  * \param private_key Handle to the private key to use.
3362  * \param[in] peer_key Public key of the peer. The peer key must be in the
3363  * same format that psa_import_key() accepts for the
3364  * public key type corresponding to the type of
3365  * private_key. That is, this function performs the
3366  * equivalent of
3367  * #psa_import_key(...,
3368  * `peer_key`, `peer_key_length`) where
3369  * with key attributes indicating the public key
3370  * type corresponding to the type of `private_key`.
3371  * For example, for EC keys, this means that peer_key
3372  * is interpreted as a point on the curve that the
3373  * private key is on. The standard formats for public
3374  * keys are documented in the documentation of
3375  * psa_export_public_key().
3376  * \param peer_key_length Size of \p peer_key in bytes.
3377  *
3378  * \retval #PSA_SUCCESS
3379  * Success.
3380  * \retval #PSA_ERROR_BAD_STATE
3381  * The operation state is not valid for this key agreement \p step.
3382  * \retval #PSA_ERROR_INVALID_HANDLE
3383  * \retval #PSA_ERROR_NOT_PERMITTED
3384  * \retval #PSA_ERROR_INVALID_ARGUMENT
3385  * \c private_key is not compatible with \c alg,
3386  * or \p peer_key is not valid for \c alg or not compatible with
3387  * \c private_key.
3388  * \retval #PSA_ERROR_NOT_SUPPORTED
3389  * \c alg is not supported or is not a key derivation algorithm.
3390  * \retval #PSA_ERROR_INVALID_ARGUMENT
3391  * \c step does not allow an input resulting from a key agreement.
3392  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3393  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3394  * \retval #PSA_ERROR_HARDWARE_FAILURE
3395  * \retval #PSA_ERROR_CORRUPTION_DETECTED
3396  * \retval #PSA_ERROR_STORAGE_FAILURE
3397  * \retval #PSA_ERROR_BAD_STATE
3398  * The library has not been previously initialized by psa_crypto_init().
3399  * It is implementation-dependent whether a failure to initialize
3400  * results in this error code.
3401  */
3402 psa_status_t psa_key_derivation_key_agreement(
3403  psa_key_derivation_operation_t *operation,
3404  psa_key_derivation_step_t step,
3405  psa_key_handle_t private_key,
3406  const uint8_t *peer_key,
3407  size_t peer_key_length);
3408 
3409 /** Read some data from a key derivation operation.
3410  *
3411  * This function calculates output bytes from a key derivation algorithm and
3412  * return those bytes.
3413  * If you view the key derivation's output as a stream of bytes, this
3414  * function destructively reads the requested number of bytes from the
3415  * stream.
3416  * The operation's capacity decreases by the number of bytes read.
3417  *
3418  * If this function returns an error status other than
3419  * #PSA_ERROR_INSUFFICIENT_DATA, the operation enters an error
3420  * state and must be aborted by calling psa_key_derivation_abort().
3421  *
3422  * \param[in,out] operation The key derivation operation object to read from.
3423  * \param[out] output Buffer where the output will be written.
3424  * \param output_length Number of bytes to output.
3425  *
3426  * \retval #PSA_SUCCESS
3427  * \retval #PSA_ERROR_INSUFFICIENT_DATA
3428  * The operation's capacity was less than
3429  * \p output_length bytes. Note that in this case,
3430  * no output is written to the output buffer.
3431  * The operation's capacity is set to 0, thus
3432  * subsequent calls to this function will not
3433  * succeed, even with a smaller output buffer.
3434  * \retval #PSA_ERROR_BAD_STATE
3435  * The operation state is not valid (it must be active and completed
3436  * all required input steps).
3437  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3438  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3439  * \retval #PSA_ERROR_HARDWARE_FAILURE
3440  * \retval #PSA_ERROR_CORRUPTION_DETECTED
3441  * \retval #PSA_ERROR_STORAGE_FAILURE
3442  * \retval #PSA_ERROR_BAD_STATE
3443  * The library has not been previously initialized by psa_crypto_init().
3444  * It is implementation-dependent whether a failure to initialize
3445  * results in this error code.
3446  */
3447 psa_status_t psa_key_derivation_output_bytes(
3448  psa_key_derivation_operation_t *operation,
3449  uint8_t *output,
3450  size_t output_length);
3451 
3452 /** Derive a key from an ongoing key derivation operation.
3453  *
3454  * This function calculates output bytes from a key derivation algorithm
3455  * and uses those bytes to generate a key deterministically.
3456  * The key's location, usage policy, type and size are taken from
3457  * \p attributes.
3458  *
3459  * If you view the key derivation's output as a stream of bytes, this
3460  * function destructively reads as many bytes as required from the
3461  * stream.
3462  * The operation's capacity decreases by the number of bytes read.
3463  *
3464  * If this function returns an error status other than
3465  * #PSA_ERROR_INSUFFICIENT_DATA, the operation enters an error
3466  * state and must be aborted by calling psa_key_derivation_abort().
3467  *
3468  * How much output is produced and consumed from the operation, and how
3469  * the key is derived, depends on the key type:
3470  *
3471  * - For key types for which the key is an arbitrary sequence of bytes
3472  * of a given size, this function is functionally equivalent to
3473  * calling #psa_key_derivation_output_bytes
3474  * and passing the resulting output to #psa_import_key.
3475  * However, this function has a security benefit:
3476  * if the implementation provides an isolation boundary then
3477  * the key material is not exposed outside the isolation boundary.
3478  * As a consequence, for these key types, this function always consumes
3479  * exactly (\p bits / 8) bytes from the operation.
3480  * The following key types defined in this specification follow this scheme:
3481  *
3482  * - #PSA_KEY_TYPE_AES;
3483  * - #PSA_KEY_TYPE_ARC4;
3484  * - #PSA_KEY_TYPE_CAMELLIA;
3485  * - #PSA_KEY_TYPE_DERIVE;
3486  * - #PSA_KEY_TYPE_HMAC.
3487  *
3488  * - For ECC keys on a Montgomery elliptic curve
3489  * (#PSA_KEY_TYPE_ECC_KEY_PAIR(\c curve) where \c curve designates a
3490  * Montgomery curve), this function always draws a byte string whose
3491  * length is determined by the curve, and sets the mandatory bits
3492  * accordingly. That is:
3493  *
3494  * - Curve25519 (#PSA_ECC_FAMILY_MONTGOMERY, 255 bits): draw a 32-byte
3495  * string and process it as specified in RFC 7748 &sect;5.
3496  * - Curve448 (#PSA_ECC_FAMILY_MONTGOMERY, 448 bits): draw a 56-byte
3497  * string and process it as specified in RFC 7748 &sect;5.
3498  *
3499  * - For key types for which the key is represented by a single sequence of
3500  * \p bits bits with constraints as to which bit sequences are acceptable,
3501  * this function draws a byte string of length (\p bits / 8) bytes rounded
3502  * up to the nearest whole number of bytes. If the resulting byte string
3503  * is acceptable, it becomes the key, otherwise the drawn bytes are discarded.
3504  * This process is repeated until an acceptable byte string is drawn.
3505  * The byte string drawn from the operation is interpreted as specified
3506  * for the output produced by psa_export_key().
3507  * The following key types defined in this specification follow this scheme:
3508  *
3509  * - #PSA_KEY_TYPE_DES.
3510  * Force-set the parity bits, but discard forbidden weak keys.
3511  * For 2-key and 3-key triple-DES, the three keys are generated
3512  * successively (for example, for 3-key triple-DES,
3513  * if the first 8 bytes specify a weak key and the next 8 bytes do not,
3514  * discard the first 8 bytes, use the next 8 bytes as the first key,
3515  * and continue reading output from the operation to derive the other
3516  * two keys).
3517  * - Finite-field Diffie-Hellman keys (#PSA_KEY_TYPE_DH_KEY_PAIR(\c group)
3518  * where \c group designates any Diffie-Hellman group) and
3519  * ECC keys on a Weierstrass elliptic curve
3520  * (#PSA_KEY_TYPE_ECC_KEY_PAIR(\c curve) where \c curve designates a
3521  * Weierstrass curve).
3522  * For these key types, interpret the byte string as integer
3523  * in big-endian order. Discard it if it is not in the range
3524  * [0, *N* - 2] where *N* is the boundary of the private key domain
3525  * (the prime *p* for Diffie-Hellman, the subprime *q* for DSA,
3526  * or the order of the curve's base point for ECC).
3527  * Add 1 to the resulting integer and use this as the private key *x*.
3528  * This method allows compliance to NIST standards, specifically
3529  * the methods titled "key-pair generation by testing candidates"
3530  * in NIST SP 800-56A &sect;5.6.1.1.4 for Diffie-Hellman,
3531  * in FIPS 186-4 &sect;B.1.2 for DSA, and
3532  * in NIST SP 800-56A &sect;5.6.1.2.2 or
3533  * FIPS 186-4 &sect;B.4.2 for elliptic curve keys.
3534  *
3535  * - For other key types, including #PSA_KEY_TYPE_RSA_KEY_PAIR,
3536  * the way in which the operation output is consumed is
3537  * implementation-defined.
3538  *
3539  * In all cases, the data that is read is discarded from the operation.
3540  * The operation's capacity is decreased by the number of bytes read.
3541  *
3542  * For algorithms that take an input step #PSA_KEY_DERIVATION_INPUT_SECRET,
3543  * the input to that step must be provided with psa_key_derivation_input_key().
3544  * Future versions of this specification may include additional restrictions
3545  * on the derived key based on the attributes and strength of the secret key.
3546  *
3547  * \param[in] attributes The attributes for the new key.
3548  * \param[in,out] operation The key derivation operation object to read from.
3549  * \param[out] handle On success, a handle to the newly created key.
3550  * \c 0 on failure.
3551  *
3552  * \retval #PSA_SUCCESS
3553  * Success.
3554  * If the key is persistent, the key material and the key's metadata
3555  * have been saved to persistent storage.
3556  * \retval #PSA_ERROR_ALREADY_EXISTS
3557  * This is an attempt to create a persistent key, and there is
3558  * already a persistent key with the given identifier.
3559  * \retval #PSA_ERROR_INSUFFICIENT_DATA
3560  * There was not enough data to create the desired key.
3561  * Note that in this case, no output is written to the output buffer.
3562  * The operation's capacity is set to 0, thus subsequent calls to
3563  * this function will not succeed, even with a smaller output buffer.
3564  * \retval #PSA_ERROR_NOT_SUPPORTED
3565  * The key type or key size is not supported, either by the
3566  * implementation in general or in this particular location.
3567  * \retval #PSA_ERROR_INVALID_ARGUMENT
3568  * The provided key attributes are not valid for the operation.
3569  * \retval #PSA_ERROR_NOT_PERMITTED
3570  * The #PSA_KEY_DERIVATION_INPUT_SECRET input was not provided through
3571  * a key.
3572  * \retval #PSA_ERROR_BAD_STATE
3573  * The operation state is not valid (it must be active and completed
3574  * all required input steps).
3575  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3576  * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
3577  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3578  * \retval #PSA_ERROR_HARDWARE_FAILURE
3579  * \retval #PSA_ERROR_CORRUPTION_DETECTED
3580  * \retval #PSA_ERROR_STORAGE_FAILURE
3581  * \retval #PSA_ERROR_BAD_STATE
3582  * The library has not been previously initialized by psa_crypto_init().
3583  * It is implementation-dependent whether a failure to initialize
3584  * results in this error code.
3585  */
3586 psa_status_t psa_key_derivation_output_key(
3587  const psa_key_attributes_t *attributes,
3588  psa_key_derivation_operation_t *operation,
3589  psa_key_handle_t *handle);
3590 
3591 /** Abort a key derivation operation.
3592  *
3593  * Aborting an operation frees all associated resources except for the \c
3594  * operation structure itself. Once aborted, the operation object can be reused
3595  * for another operation by calling psa_key_derivation_setup() again.
3596  *
3597  * This function may be called at any time after the operation
3598  * object has been initialized as described in #psa_key_derivation_operation_t.
3599  *
3600  * In particular, it is valid to call psa_key_derivation_abort() twice, or to
3601  * call psa_key_derivation_abort() on an operation that has not been set up.
3602  *
3603  * \param[in,out] operation The operation to abort.
3604  *
3605  * \retval #PSA_SUCCESS
3606  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3607  * \retval #PSA_ERROR_HARDWARE_FAILURE
3608  * \retval #PSA_ERROR_CORRUPTION_DETECTED
3609  * \retval #PSA_ERROR_BAD_STATE
3610  * The library has not been previously initialized by psa_crypto_init().
3611  * It is implementation-dependent whether a failure to initialize
3612  * results in this error code.
3613  */
3614 psa_status_t psa_key_derivation_abort(
3615  psa_key_derivation_operation_t *operation);
3616 
3617 /** Perform a key agreement and return the raw shared secret.
3618  *
3619  * \warning The raw result of a key agreement algorithm such as finite-field
3620  * Diffie-Hellman or elliptic curve Diffie-Hellman has biases and should
3621  * not be used directly as key material. It should instead be passed as
3622  * input to a key derivation algorithm. To chain a key agreement with
3623  * a key derivation, use psa_key_derivation_key_agreement() and other
3624  * functions from the key derivation interface.
3625  *
3626  * \param alg The key agreement algorithm to compute
3627  * (\c PSA_ALG_XXX value such that
3628  * #PSA_ALG_IS_RAW_KEY_AGREEMENT(\p alg)
3629  * is true).
3630  * \param private_key Handle to the private key to use.
3631  * \param[in] peer_key Public key of the peer. It must be
3632  * in the same format that psa_import_key()
3633  * accepts. The standard formats for public
3634  * keys are documented in the documentation
3635  * of psa_export_public_key().
3636  * \param peer_key_length Size of \p peer_key in bytes.
3637  * \param[out] output Buffer where the decrypted message is to
3638  * be written.
3639  * \param output_size Size of the \c output buffer in bytes.
3640  * \param[out] output_length On success, the number of bytes
3641  * that make up the returned output.
3642  *
3643  * \retval #PSA_SUCCESS
3644  * Success.
3645  * \retval #PSA_ERROR_INVALID_HANDLE
3646  * \retval #PSA_ERROR_NOT_PERMITTED
3647  * \retval #PSA_ERROR_INVALID_ARGUMENT
3648  * \p alg is not a key agreement algorithm
3649  * \retval #PSA_ERROR_INVALID_ARGUMENT
3650  * \p private_key is not compatible with \p alg,
3651  * or \p peer_key is not valid for \p alg or not compatible with
3652  * \p private_key.
3653  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
3654  * \p output_size is too small
3655  * \retval #PSA_ERROR_NOT_SUPPORTED
3656  * \p alg is not a supported key agreement algorithm.
3657  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3658  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3659  * \retval #PSA_ERROR_HARDWARE_FAILURE
3660  * \retval #PSA_ERROR_CORRUPTION_DETECTED
3661  * \retval #PSA_ERROR_STORAGE_FAILURE
3662  * \retval #PSA_ERROR_BAD_STATE
3663  * The library has not been previously initialized by psa_crypto_init().
3664  * It is implementation-dependent whether a failure to initialize
3665  * results in this error code.
3666  */
3667 psa_status_t psa_raw_key_agreement(psa_algorithm_t alg,
3668  psa_key_handle_t private_key,
3669  const uint8_t *peer_key,
3670  size_t peer_key_length,
3671  uint8_t *output,
3672  size_t output_size,
3673  size_t *output_length);
3674 
3675 /**@}*/
3676 
3677 /** \defgroup random Random generation
3678  * @{
3679  */
3680 
3681 /**
3682  * \brief Generate random bytes.
3683  *
3684  * \warning This function **can** fail! Callers MUST check the return status
3685  * and MUST NOT use the content of the output buffer if the return
3686  * status is not #PSA_SUCCESS.
3687  *
3688  * \note To generate a key, use psa_generate_key() instead.
3689  *
3690  * \param[out] output Output buffer for the generated data.
3691  * \param output_size Number of bytes to generate and output.
3692  *
3693  * \retval #PSA_SUCCESS
3694  * \retval #PSA_ERROR_NOT_SUPPORTED
3695  * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
3696  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3697  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3698  * \retval #PSA_ERROR_HARDWARE_FAILURE
3699  * \retval #PSA_ERROR_CORRUPTION_DETECTED
3700  * \retval #PSA_ERROR_BAD_STATE
3701  * The library has not been previously initialized by psa_crypto_init().
3702  * It is implementation-dependent whether a failure to initialize
3703  * results in this error code.
3704  */
3705 psa_status_t psa_generate_random(uint8_t *output,
3706  size_t output_size);
3707 
3708 /**
3709  * \brief Generate a key or key pair.
3710  *
3711  * The key is generated randomly.
3712  * Its location, usage policy, type and size are taken from \p attributes.
3713  *
3714  * Implementations must reject an attempt to generate a key of size 0.
3715  *
3716  * The following type-specific considerations apply:
3717  * - For RSA keys (#PSA_KEY_TYPE_RSA_KEY_PAIR),
3718  * the public exponent is 65537.
3719  * The modulus is a product of two probabilistic primes
3720  * between 2^{n-1} and 2^n where n is the bit size specified in the
3721  * attributes.
3722  *
3723  * \param[in] attributes The attributes for the new key.
3724  * \param[out] handle On success, a handle to the newly created key.
3725  * \c 0 on failure.
3726  *
3727  * \retval #PSA_SUCCESS
3728  * Success.
3729  * If the key is persistent, the key material and the key's metadata
3730  * have been saved to persistent storage.
3731  * \retval #PSA_ERROR_ALREADY_EXISTS
3732  * This is an attempt to create a persistent key, and there is
3733  * already a persistent key with the given identifier.
3734  * \retval #PSA_ERROR_NOT_SUPPORTED
3735  * \retval #PSA_ERROR_INVALID_ARGUMENT
3736  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3737  * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
3738  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3739  * \retval #PSA_ERROR_HARDWARE_FAILURE
3740  * \retval #PSA_ERROR_CORRUPTION_DETECTED
3741  * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
3742  * \retval #PSA_ERROR_STORAGE_FAILURE
3743  * \retval #PSA_ERROR_BAD_STATE
3744  * The library has not been previously initialized by psa_crypto_init().
3745  * It is implementation-dependent whether a failure to initialize
3746  * results in this error code.
3747  */
3748 psa_status_t psa_generate_key(const psa_key_attributes_t *attributes,
3749  psa_key_handle_t *handle);
3750 
3751 /**@}*/
3752 
3753 #ifdef __cplusplus
3754 }
3755 #endif
3756 
3757 /* The file "crypto_sizes.h" contains definitions for size calculation
3758  * macros whose definitions are implementation-specific. */
3759 #include "psa/crypto_sizes.h"
3760 
3761 /* The file "crypto_client_struct.h" contains definitions for structures
3762  * whose definitions differ in the client view and the PSA server
3763  * implementation in TF-M. */
3764 #include "psa/crypto_client_struct.h"
3765 
3766 
3767 /* The file "crypto_struct.h" contains definitions for
3768  * implementation-specific structs that are declared above. */
3769 #include "psa/crypto_struct.h"
3770 
3771 /* The file "crypto_extra.h" contains vendor-specific definitions. This
3772  * can include vendor-defined algorithms, extra functions, etc. */
3773 #include "psa/crypto_extra.h"
3774 
3775 #endif /* PSA_CRYPTO_H */
psa_cipher_encrypt_setup
psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation, psa_key_handle_t handle, psa_algorithm_t alg)
Set the key for a multipart symmetric encryption operation.
psa_reset_key_attributes
void psa_reset_key_attributes(psa_key_attributes_t *attributes)
Reset a key attribute structure to a freshly initialized state.
psa_cipher_update
psa_status_t psa_cipher_update(psa_cipher_operation_t *operation, const uint8_t *input, size_t input_length, uint8_t *output, size_t output_size, size_t *output_length)
Encrypt or decrypt a message fragment in an active cipher operation.
psa_set_key_id
static void psa_set_key_id(psa_key_attributes_t *attributes, psa_key_id_t id)
Declare a key as persistent and set its key identifier.
psa_key_attributes_s
Definition: TARGET_MBED_PSA_SRV/mbedtls/crypto_struct.h:340
psa_generate_random
psa_status_t psa_generate_random(uint8_t *output, size_t output_size)
Generate random bytes.
psa_export_key
psa_status_t psa_export_key(psa_key_handle_t handle, uint8_t *data, size_t data_size, size_t *data_length)
Export a key in binary format.
psa_mac_sign_finish
psa_status_t psa_mac_sign_finish(psa_mac_operation_t *operation, uint8_t *mac, size_t mac_size, size_t *mac_length)
Finish the calculation of the MAC of a message.
psa_aead_operation_s
Definition: TARGET_MBED_PSA_SRV/mbedtls/crypto_struct.h:177
psa_destroy_key
psa_status_t psa_destroy_key(psa_key_handle_t handle)
Destroy a key.
psa_mac_operation_s
Definition: TARGET_MBED_PSA_SRV/mbedtls/crypto_struct.h:127
psa_cipher_decrypt_setup
psa_status_t psa_cipher_decrypt_setup(psa_cipher_operation_t *operation, psa_key_handle_t handle, psa_algorithm_t alg)
Set the key for a multipart symmetric decryption operation.
psa_sign_hash
psa_status_t psa_sign_hash(psa_key_handle_t handle, psa_algorithm_t alg, const uint8_t *hash, size_t hash_length, uint8_t *signature, size_t signature_size, size_t *signature_length)
Sign a hash or short message with a private key.
psa_aead_encrypt_setup
psa_status_t psa_aead_encrypt_setup(psa_aead_operation_t *operation, psa_key_handle_t handle, psa_algorithm_t alg)
Set the key for a multipart authenticated encryption operation.
psa_key_derivation_operation_init
static psa_key_derivation_operation_t psa_key_derivation_operation_init(void)
Return an initial value for a key derivation operation object.
psa_key_derivation_set_capacity
psa_status_t psa_key_derivation_set_capacity(psa_key_derivation_operation_t *operation, size_t capacity)
Set the maximum capacity of a key derivation operation.
psa_raw_key_agreement
psa_status_t psa_raw_key_agreement(psa_algorithm_t alg, psa_key_handle_t private_key, const uint8_t *peer_key, size_t peer_key_length, uint8_t *output, size_t output_size, size_t *output_length)
Perform a key agreement and return the raw shared secret.
psa_close_key
psa_status_t psa_close_key(psa_key_handle_t handle)
Close a key handle.
psa_key_derivation_abort
psa_status_t psa_key_derivation_abort(psa_key_derivation_operation_t *operation)
Abort a key derivation operation.
psa_cipher_decrypt
psa_status_t psa_cipher_decrypt(psa_key_handle_t handle, psa_algorithm_t alg, const uint8_t *input, size_t input_length, uint8_t *output, size_t output_size, size_t *output_length)
Decrypt a message using a symmetric cipher.
psa_mac_verify_finish
psa_status_t psa_mac_verify_finish(psa_mac_operation_t *operation, const uint8_t *mac, size_t mac_length)
Finish the calculation of the MAC of a message and compare it with an expected value.
psa_export_public_key
psa_status_t psa_export_public_key(psa_key_handle_t handle, uint8_t *data, size_t data_size, size_t *data_length)
Export a public key or the public part of a key pair in binary format.
psa_set_key_bits
static void psa_set_key_bits(psa_key_attributes_t *attributes, size_t bits)
Declare the size of a key.
psa_cipher_operation_s
Definition: TARGET_MBED_PSA_SRV/mbedtls/crypto_struct.h:155
psa_mac_abort
psa_status_t psa_mac_abort(psa_mac_operation_t *operation)
Abort a MAC operation.
psa_key_derivation_step_t
uint16_t psa_key_derivation_step_t
Encoding of the step of a key derivation.
Definition: TARGET_MBED_PSA_SRV/inc/psa/crypto_types.h:380
psa_key_id_t
uint32_t psa_key_id_t
Encoding of identifiers of persistent keys.
Definition: TARGET_MBED_PSA_SRV/inc/psa/crypto_types.h:235
psa_verify_hash
psa_status_t psa_verify_hash(psa_key_handle_t handle, psa_algorithm_t alg, const uint8_t *hash, size_t hash_length, const uint8_t *signature, size_t signature_length)
Verify the signature a hash or short message using a public key.
psa_hash_compute
psa_status_t psa_hash_compute(psa_algorithm_t alg, const uint8_t *input, size_t input_length, uint8_t *hash, size_t hash_size, size_t *hash_length)
Calculate the hash (digest) of a message.
psa_get_key_algorithm
static psa_algorithm_t psa_get_key_algorithm(const psa_key_attributes_t *attributes)
Retrieve the algorithm policy from key attributes.
psa_set_key_usage_flags
static void psa_set_key_usage_flags(psa_key_attributes_t *attributes, psa_key_usage_t usage_flags)
Declare usage flags for a key.
psa_key_derivation_input_key
psa_status_t psa_key_derivation_input_key(psa_key_derivation_operation_t *operation, psa_key_derivation_step_t step, psa_key_handle_t handle)
Provide an input for key derivation in the form of a key.
psa_hash_update
psa_status_t psa_hash_update(psa_hash_operation_t *operation, const uint8_t *input, size_t input_length)
Add a message fragment to a multipart hash operation.
psa_set_key_lifetime
static void psa_set_key_lifetime(psa_key_attributes_t *attributes, psa_key_lifetime_t lifetime)
Set the location of a persistent key.
psa_hash_operation_init
static psa_hash_operation_t psa_hash_operation_init(void)
Return an initial value for a hash operation object.
psa_aead_set_nonce
psa_status_t psa_aead_set_nonce(psa_aead_operation_t *operation, const uint8_t *nonce, size_t nonce_length)
Set the nonce for an authenticated encryption or decryption operation.
psa_get_key_lifetime
static psa_key_lifetime_t psa_get_key_lifetime(const psa_key_attributes_t *attributes)
Retrieve the lifetime from key attributes.
psa_key_derivation_get_capacity
psa_status_t psa_key_derivation_get_capacity(const psa_key_derivation_operation_t *operation, size_t *capacity)
Retrieve the current capacity of a key derivation operation.
psa_set_key_type
static void psa_set_key_type(psa_key_attributes_t *attributes, psa_key_type_t type)
Declare the type of a key.
psa_aead_finish
psa_status_t psa_aead_finish(psa_aead_operation_t *operation, uint8_t *ciphertext, size_t ciphertext_size, size_t *ciphertext_length, uint8_t *tag, size_t tag_size, size_t *tag_length)
Finish encrypting a message in an AEAD operation.
psa_get_key_id
static psa_key_id_t psa_get_key_id(const psa_key_attributes_t *attributes)
Retrieve the key identifier from key attributes.
psa_asymmetric_encrypt
psa_status_t psa_asymmetric_encrypt(psa_key_handle_t handle, psa_algorithm_t alg, const uint8_t *input, size_t input_length, const uint8_t *salt, size_t salt_length, uint8_t *output, size_t output_size, size_t *output_length)
Encrypt a short message with a public key.
psa_key_derivation_s
Definition: TARGET_MBED_PSA_SRV/mbedtls/crypto_struct.h:253
psa_get_key_bits
static size_t psa_get_key_bits(const psa_key_attributes_t *attributes)
Retrieve the key size from key attributes.
psa_mac_verify_setup
psa_status_t psa_mac_verify_setup(psa_mac_operation_t *operation, psa_key_handle_t handle, psa_algorithm_t alg)
Set up a multipart MAC verification operation.
psa_asymmetric_decrypt
psa_status_t psa_asymmetric_decrypt(psa_key_handle_t handle, psa_algorithm_t alg, const uint8_t *input, size_t input_length, const uint8_t *salt, size_t salt_length, uint8_t *output, size_t output_size, size_t *output_length)
Decrypt a short message with a private key.
psa_cipher_finish
psa_status_t psa_cipher_finish(psa_cipher_operation_t *operation, uint8_t *output, size_t output_size, size_t *output_length)
Finish encrypting or decrypting a message in a cipher operation.
psa_hash_operation_s
Definition: TARGET_MBED_PSA_SRV/mbedtls/crypto_struct.h:80
psa_aead_update_ad
psa_status_t psa_aead_update_ad(psa_aead_operation_t *operation, const uint8_t *input, size_t input_length)
Pass additional data to an active AEAD operation.
psa_import_key
psa_status_t psa_import_key(const psa_key_attributes_t *attributes, const uint8_t *data, size_t data_length, psa_key_handle_t *handle)
Import a key in binary format.
psa_hash_verify
psa_status_t psa_hash_verify(psa_hash_operation_t *operation, const uint8_t *hash, size_t hash_length)
Finish the calculation of the hash of a message and compare it with an expected value.
crypto_client_struct.h
PSA cryptography client key attribute definitions.
psa_aead_set_lengths
psa_status_t psa_aead_set_lengths(psa_aead_operation_t *operation, size_t ad_length, size_t plaintext_length)
Declare the lengths of the message and additional data for AEAD.
psa_aead_decrypt
psa_status_t psa_aead_decrypt(psa_key_handle_t handle, psa_algorithm_t alg, const uint8_t *nonce, size_t nonce_length, const uint8_t *additional_data, size_t additional_data_length, const uint8_t *ciphertext, size_t ciphertext_length, uint8_t *plaintext, size_t plaintext_size, size_t *plaintext_length)
Process an authenticated decryption operation.
psa_mac_verify
psa_status_t psa_mac_verify(psa_key_handle_t handle, psa_algorithm_t alg, const uint8_t *input, size_t input_length, const uint8_t *mac, size_t mac_length)
Calculate the MAC of a message and compare it with a reference value.
psa_hash_clone
psa_status_t psa_hash_clone(const psa_hash_operation_t *source_operation, psa_hash_operation_t *target_operation)
Clone a hash operation.
psa_copy_key
psa_status_t psa_copy_key(psa_key_handle_t source_handle, const psa_key_attributes_t *attributes, psa_key_handle_t *target_handle)
Make a copy of a key.
psa_algorithm_t
uint32_t psa_algorithm_t
Encoding of a cryptographic algorithm.
Definition: TARGET_MBED_PSA_SRV/inc/psa/crypto_types.h:96
psa_aead_encrypt
psa_status_t psa_aead_encrypt(psa_key_handle_t handle, psa_algorithm_t alg, const uint8_t *nonce, size_t nonce_length, const uint8_t *additional_data, size_t additional_data_length, const uint8_t *plaintext, size_t plaintext_length, uint8_t *ciphertext, size_t ciphertext_size, size_t *ciphertext_length)
Process an authenticated encryption operation.
psa_cipher_set_iv
psa_status_t psa_cipher_set_iv(psa_cipher_operation_t *operation, const uint8_t *iv, size_t iv_length)
Set the IV for a symmetric encryption or decryption operation.
psa_aead_generate_nonce
psa_status_t psa_aead_generate_nonce(psa_aead_operation_t *operation, uint8_t *nonce, size_t nonce_size, size_t *nonce_length)
Generate a random nonce for an authenticated encryption operation.
psa_cipher_operation_init
static psa_cipher_operation_t psa_cipher_operation_init(void)
Return an initial value for a cipher operation object.
psa_hash_setup
psa_status_t psa_hash_setup(psa_hash_operation_t *operation, psa_algorithm_t alg)
Set up a multipart hash operation.
psa_aead_decrypt_setup
psa_status_t psa_aead_decrypt_setup(psa_aead_operation_t *operation, psa_key_handle_t handle, psa_algorithm_t alg)
Set the key for a multipart authenticated decryption operation.
psa_cipher_generate_iv
psa_status_t psa_cipher_generate_iv(psa_cipher_operation_t *operation, uint8_t *iv, size_t iv_size, size_t *iv_length)
Generate an IV for a symmetric encryption operation.
psa_key_usage_t
uint32_t psa_key_usage_t
Encoding of permitted usage on a key.
Definition: TARGET_MBED_PSA_SRV/inc/psa/crypto_types.h:246
psa_set_key_algorithm
static void psa_set_key_algorithm(psa_key_attributes_t *attributes, psa_algorithm_t alg)
Declare the permitted algorithm policy for a key.
psa_mac_sign_setup
psa_status_t psa_mac_sign_setup(psa_mac_operation_t *operation, psa_key_handle_t handle, psa_algorithm_t alg)
Set up a multipart MAC calculation operation.
psa_key_type_t
uint16_t psa_key_type_t
Encoding of a key type.
Definition: TARGET_MBED_PSA_SRV/inc/psa/crypto_types.h:64
psa_get_key_attributes
psa_status_t psa_get_key_attributes(psa_key_handle_t handle, psa_key_attributes_t *attributes)
Retrieve the attributes of a key.
psa_crypto_init
psa_status_t psa_crypto_init(void)
Library initialization.
psa_key_derivation_output_bytes
psa_status_t psa_key_derivation_output_bytes(psa_key_derivation_operation_t *operation, uint8_t *output, size_t output_length)
Read some data from a key derivation operation.
psa_aead_operation_init
static psa_aead_operation_t psa_aead_operation_init(void)
Return an initial value for an AEAD operation object.
psa_key_derivation_input_bytes
psa_status_t psa_key_derivation_input_bytes(psa_key_derivation_operation_t *operation, psa_key_derivation_step_t step, const uint8_t *data, size_t data_length)
Provide an input for key derivation or key agreement.
psa_generate_key
psa_status_t psa_generate_key(const psa_key_attributes_t *attributes, psa_key_handle_t *handle)
Generate a key or key pair.
psa_get_key_type
static psa_key_type_t psa_get_key_type(const psa_key_attributes_t *attributes)
Retrieve the key type from key attributes.
psa_aead_verify
psa_status_t psa_aead_verify(psa_aead_operation_t *operation, uint8_t *plaintext, size_t plaintext_size, size_t *plaintext_length, const uint8_t *tag, size_t tag_length)
Finish authenticating and decrypting a message in an AEAD operation.
psa_key_derivation_key_agreement
psa_status_t psa_key_derivation_key_agreement(psa_key_derivation_operation_t *operation, psa_key_derivation_step_t step, psa_key_handle_t private_key, const uint8_t *peer_key, size_t peer_key_length)
Perform a key agreement and use the shared secret as input to a key derivation.
psa_get_key_usage_flags
static psa_key_usage_t psa_get_key_usage_flags(const psa_key_attributes_t *attributes)
Retrieve the usage flags from key attributes.
psa_hash_abort
psa_status_t psa_hash_abort(psa_hash_operation_t *operation)
Abort a hash operation.
psa_key_attributes_init
static psa_key_attributes_t psa_key_attributes_init(void)
Return an initial value for a key attributes structure.
psa_open_key
psa_status_t psa_open_key(psa_key_id_t id, psa_key_handle_t *handle)
Open a handle to an existing persistent key.
psa_key_derivation_setup
psa_status_t psa_key_derivation_setup(psa_key_derivation_operation_t *operation, psa_algorithm_t alg)
Set up a key derivation operation.
psa_mac_compute
psa_status_t psa_mac_compute(psa_key_handle_t handle, psa_algorithm_t alg, const uint8_t *input, size_t input_length, uint8_t *mac, size_t mac_size, size_t *mac_length)
Calculate the MAC (message authentication code) of a message.
psa_aead_abort
psa_status_t psa_aead_abort(psa_aead_operation_t *operation)
Abort an AEAD operation.
psa_aead_update
psa_status_t psa_aead_update(psa_aead_operation_t *operation, const uint8_t *input, size_t input_length, uint8_t *output, size_t output_size, size_t *output_length)
Encrypt or decrypt a message fragment in an active AEAD operation.
psa_key_lifetime_t
uint32_t psa_key_lifetime_t
Encoding of key lifetimes.
Definition: TARGET_MBED_PSA_SRV/inc/psa/crypto_types.h:139
psa_mac_operation_init
static psa_mac_operation_t psa_mac_operation_init(void)
Return an initial value for a MAC operation object.
psa_status_t
int32_t psa_status_t
Function return status.
Definition: TARGET_MBED_PSA_SRV/inc/psa/crypto_types.h:53
psa_mac_update
psa_status_t psa_mac_update(psa_mac_operation_t *operation, const uint8_t *input, size_t input_length)
Add a message fragment to a multipart MAC operation.
psa_cipher_abort
psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation)
Abort a cipher operation.
psa_hash_compare
psa_status_t psa_hash_compare(psa_algorithm_t alg, const uint8_t *input, size_t input_length, const uint8_t *hash, size_t hash_length)
Calculate the hash (digest) of a message and compare it with a reference value.
psa_key_derivation_output_key
psa_status_t psa_key_derivation_output_key(const psa_key_attributes_t *attributes, psa_key_derivation_operation_t *operation, psa_key_handle_t *handle)
Derive a key from an ongoing key derivation operation.
psa_cipher_encrypt
psa_status_t psa_cipher_encrypt(psa_key_handle_t handle, psa_algorithm_t alg, const uint8_t *input, size_t input_length, uint8_t *output, size_t output_size, size_t *output_length)
Encrypt a message using a symmetric cipher.
psa_hash_finish
psa_status_t psa_hash_finish(psa_hash_operation_t *operation, uint8_t *hash, size_t hash_size, size_t *hash_length)
Finish the calculation of the hash of a message.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.