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