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