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