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