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

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