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

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