Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
crypto_se_driver.h
Go to the documentation of this file.
1 /**
2  * \file psa/crypto_se_driver.h
3  * \brief PSA external cryptoprocessor driver module
4  *
5  * This header declares types and function signatures for cryptography
6  * drivers that access key material via opaque references.
7  * This is meant for cryptoprocessors that have a separate key storage from the
8  * space in which the PSA Crypto implementation runs, typically secure
9  * elements (SEs).
10  *
11  * This file is part of the PSA Crypto Driver HAL (hardware abstraction layer),
12  * containing functions for driver developers to implement to enable hardware
13  * to be called in a standardized way by a PSA Cryptography API
14  * implementation. The functions comprising the driver HAL, which driver
15  * authors implement, are not intended to be called by application developers.
16  */
17 
18 /*
19  * Copyright The Mbed TLS Contributors
20  * SPDX-License-Identifier: Apache-2.0
21  *
22  * Licensed under the Apache License, Version 2.0 (the "License"); you may
23  * not use this file except in compliance with the License.
24  * You may obtain a copy of the License at
25  *
26  * http://www.apache.org/licenses/LICENSE-2.0
27  *
28  * Unless required by applicable law or agreed to in writing, software
29  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
30  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
31  * See the License for the specific language governing permissions and
32  * limitations under the License.
33  */
34 #ifndef PSA_CRYPTO_SE_DRIVER_H
35 #define PSA_CRYPTO_SE_DRIVER_H
36 
37 #include "crypto_driver_common.h"
38 
39 #ifdef __cplusplus
40 extern "C" {
41 #endif
42 
43 /** \defgroup se_init Secure element driver initialization
44  */
45 /**@{*/
46 
47 /** \brief Driver context structure
48  *
49  * Driver functions receive a pointer to this structure.
50  * Each registered driver has one instance of this structure.
51  *
52  * Implementations must include the fields specified here and
53  * may include other fields.
54  */
55 typedef struct {
56  /** A read-only pointer to the driver's persistent data.
57  *
58  * Drivers typically use this persistent data to keep track of
59  * which slot numbers are available. This is only a guideline:
60  * drivers may use the persistent data for any purpose, keeping
61  * in mind the restrictions on when the persistent data is saved
62  * to storage: the persistent data is only saved after calling
63  * certain functions that receive a writable pointer to the
64  * persistent data.
65  *
66  * The core allocates a memory buffer for the persistent data.
67  * The pointer is guaranteed to be suitably aligned for any data type,
68  * like a pointer returned by `malloc` (but the core can use any
69  * method to allocate the buffer, not necessarily `malloc`).
70  *
71  * The size of this buffer is in the \c persistent_data_size field of
72  * this structure.
73  *
74  * Before the driver is initialized for the first time, the content of
75  * the persistent data is all-bits-zero. After a driver upgrade, if the
76  * size of the persistent data has increased, the original data is padded
77  * on the right with zeros; if the size has decreased, the original data
78  * is truncated to the new size.
79  *
80  * This pointer is to read-only data. Only a few driver functions are
81  * allowed to modify the persistent data. These functions receive a
82  * writable pointer. These functions are:
83  * - psa_drv_se_t::p_init
84  * - psa_drv_se_key_management_t::p_allocate
85  * - psa_drv_se_key_management_t::p_destroy
86  *
87  * The PSA Cryptography core saves the persistent data from one
88  * session to the next. It does this before returning from API functions
89  * that call a driver method that is allowed to modify the persistent
90  * data, specifically:
91  * - psa_crypto_init() causes a call to psa_drv_se_t::p_init, and may call
92  * psa_drv_se_key_management_t::p_destroy to complete an action
93  * that was interrupted by a power failure.
94  * - Key creation functions cause a call to
95  * psa_drv_se_key_management_t::p_allocate, and may cause a call to
96  * psa_drv_se_key_management_t::p_destroy in case an error occurs.
97  * - psa_destroy_key() causes a call to
98  * psa_drv_se_key_management_t::p_destroy.
99  */
100  const void *const persistent_data;
101 
102  /** The size of \c persistent_data in bytes.
103  *
104  * This is always equal to the value of the `persistent_data_size` field
105  * of the ::psa_drv_se_t structure when the driver is registered.
106  */
107  const size_t persistent_data_size;
108 
109  /** Driver transient data.
110  *
111  * The core initializes this value to 0 and does not read or modify it
112  * afterwards. The driver may store whatever it wants in this field.
113  */
114  uintptr_t transient_data;
115 } psa_drv_se_context_t;
116 
117 /** \brief A driver initialization function.
118  *
119  * \param[in,out] drv_context The driver context structure.
120  * \param[in,out] persistent_data A pointer to the persistent data
121  * that allows writing.
122  * \param location The location value for which this driver
123  * is registered. The driver will be invoked
124  * for all keys whose lifetime is in this
125  * location.
126  *
127  * \retval #PSA_SUCCESS
128  * The driver is operational.
129  * The core will update the persistent data in storage.
130  * \return
131  * Any other return value prevents the driver from being used in
132  * this session.
133  * The core will NOT update the persistent data in storage.
134  */
135 typedef psa_status_t (*psa_drv_se_init_t)(psa_drv_se_context_t *drv_context,
136  void *persistent_data,
137  psa_key_location_t location);
138 
139 #if defined(__DOXYGEN_ONLY__) || !defined(MBEDTLS_PSA_CRYPTO_SE_C)
140 /* Mbed Crypto with secure element support enabled defines this type in
141  * crypto_types.h because it is also visible to applications through an
142  * implementation-specific extension.
143  * For the PSA Cryptography specification, this type is only visible
144  * via crypto_se_driver.h. */
145 /** An internal designation of a key slot between the core part of the
146  * PSA Crypto implementation and the driver. The meaning of this value
147  * is driver-dependent. */
148 typedef uint64_t psa_key_slot_number_t;
149 #endif /* __DOXYGEN_ONLY__ || !MBEDTLS_PSA_CRYPTO_SE_C */
150 
151 /**@}*/
152 
153 /** \defgroup se_mac Secure Element Message Authentication Codes
154  * Generation and authentication of Message Authentication Codes (MACs) using
155  * a secure element can be done either as a single function call (via the
156  * `psa_drv_se_mac_generate_t` or `psa_drv_se_mac_verify_t` functions), or in
157  * parts using the following sequence:
158  * - `psa_drv_se_mac_setup_t`
159  * - `psa_drv_se_mac_update_t`
160  * - `psa_drv_se_mac_update_t`
161  * - ...
162  * - `psa_drv_se_mac_finish_t` or `psa_drv_se_mac_finish_verify_t`
163  *
164  * If a previously started secure element MAC operation needs to be terminated,
165  * it should be done so by the `psa_drv_se_mac_abort_t`. Failure to do so may
166  * result in allocated resources not being freed or in other undefined
167  * behavior.
168  */
169 /**@{*/
170 /** \brief A function that starts a secure element MAC operation for a PSA
171  * Crypto Driver implementation
172  *
173  * \param[in,out] drv_context The driver context structure.
174  * \param[in,out] op_context A structure that will contain the
175  * hardware-specific MAC context
176  * \param[in] key_slot The slot of the key to be used for the
177  * operation
178  * \param[in] algorithm The algorithm to be used to underly the MAC
179  * operation
180  *
181  * \retval #PSA_SUCCESS
182  * Success.
183  */
184 typedef psa_status_t (*psa_drv_se_mac_setup_t)(psa_drv_se_context_t *drv_context,
185  void *op_context,
186  psa_key_slot_number_t key_slot,
187  psa_algorithm_t algorithm);
188 
189 /** \brief A function that continues a previously started secure element MAC
190  * operation
191  *
192  * \param[in,out] op_context A hardware-specific structure for the
193  * previously-established MAC operation to be
194  * updated
195  * \param[in] p_input A buffer containing the message to be appended
196  * to the MAC operation
197  * \param[in] input_length The size in bytes of the input message buffer
198  */
199 typedef psa_status_t (*psa_drv_se_mac_update_t)(void *op_context,
200  const uint8_t *p_input,
201  size_t input_length);
202 
203 /** \brief a function that completes a previously started secure element MAC
204  * operation by returning the resulting MAC.
205  *
206  * \param[in,out] op_context A hardware-specific structure for the
207  * previously started MAC operation to be
208  * finished
209  * \param[out] p_mac A buffer where the generated MAC will be
210  * placed
211  * \param[in] mac_size The size in bytes of the buffer that has been
212  * allocated for the `output` buffer
213  * \param[out] p_mac_length After completion, will contain the number of
214  * bytes placed in the `p_mac` buffer
215  *
216  * \retval #PSA_SUCCESS
217  * Success.
218  */
219 typedef psa_status_t (*psa_drv_se_mac_finish_t)(void *op_context,
220  uint8_t *p_mac,
221  size_t mac_size,
222  size_t *p_mac_length);
223 
224 /** \brief A function that completes a previously started secure element MAC
225  * operation by comparing the resulting MAC against a provided value
226  *
227  * \param[in,out] op_context A hardware-specific structure for the previously
228  * started MAC operation to be fiinished
229  * \param[in] p_mac The MAC value against which the resulting MAC
230  * will be compared against
231  * \param[in] mac_length The size in bytes of the value stored in `p_mac`
232  *
233  * \retval #PSA_SUCCESS
234  * The operation completed successfully and the MACs matched each
235  * other
236  * \retval #PSA_ERROR_INVALID_SIGNATURE
237  * The operation completed successfully, but the calculated MAC did
238  * not match the provided MAC
239  */
240 typedef psa_status_t (*psa_drv_se_mac_finish_verify_t)(void *op_context,
241  const uint8_t *p_mac,
242  size_t mac_length);
243 
244 /** \brief A function that aborts a previous started secure element MAC
245  * operation
246  *
247  * \param[in,out] op_context A hardware-specific structure for the previously
248  * started MAC operation to be aborted
249  */
250 typedef psa_status_t (*psa_drv_se_mac_abort_t)(void *op_context);
251 
252 /** \brief A function that performs a secure element MAC operation in one
253  * command and returns the calculated MAC
254  *
255  * \param[in,out] drv_context The driver context structure.
256  * \param[in] p_input A buffer containing the message to be MACed
257  * \param[in] input_length The size in bytes of `p_input`
258  * \param[in] key_slot The slot of the key to be used
259  * \param[in] alg The algorithm to be used to underlie the MAC
260  * operation
261  * \param[out] p_mac A buffer where the generated MAC will be
262  * placed
263  * \param[in] mac_size The size in bytes of the `p_mac` buffer
264  * \param[out] p_mac_length After completion, will contain the number of
265  * bytes placed in the `output` buffer
266  *
267  * \retval #PSA_SUCCESS
268  * Success.
269  */
270 typedef psa_status_t (*psa_drv_se_mac_generate_t)(psa_drv_se_context_t *drv_context,
271  const uint8_t *p_input,
272  size_t input_length,
273  psa_key_slot_number_t key_slot,
274  psa_algorithm_t alg,
275  uint8_t *p_mac,
276  size_t mac_size,
277  size_t *p_mac_length);
278 
279 /** \brief A function that performs a secure element MAC operation in one
280  * command and compares the resulting MAC against a provided value
281  *
282  * \param[in,out] drv_context The driver context structure.
283  * \param[in] p_input A buffer containing the message to be MACed
284  * \param[in] input_length The size in bytes of `input`
285  * \param[in] key_slot The slot of the key to be used
286  * \param[in] alg The algorithm to be used to underlie the MAC
287  * operation
288  * \param[in] p_mac The MAC value against which the resulting MAC will
289  * be compared against
290  * \param[in] mac_length The size in bytes of `mac`
291  *
292  * \retval #PSA_SUCCESS
293  * The operation completed successfully and the MACs matched each
294  * other
295  * \retval #PSA_ERROR_INVALID_SIGNATURE
296  * The operation completed successfully, but the calculated MAC did
297  * not match the provided MAC
298  */
299 typedef psa_status_t (*psa_drv_se_mac_verify_t)(psa_drv_se_context_t *drv_context,
300  const uint8_t *p_input,
301  size_t input_length,
302  psa_key_slot_number_t key_slot,
303  psa_algorithm_t alg,
304  const uint8_t *p_mac,
305  size_t mac_length);
306 
307 /** \brief A struct containing all of the function pointers needed to
308  * perform secure element MAC operations
309  *
310  * PSA Crypto API implementations should populate the table as appropriate
311  * upon startup.
312  *
313  * If one of the functions is not implemented (such as
314  * `psa_drv_se_mac_generate_t`), it should be set to NULL.
315  *
316  * Driver implementers should ensure that they implement all of the functions
317  * that make sense for their hardware, and that they provide a full solution
318  * (for example, if they support `p_setup`, they should also support
319  * `p_update` and at least one of `p_finish` or `p_finish_verify`).
320  *
321  */
322 typedef struct {
323  /**The size in bytes of the hardware-specific secure element MAC context
324  * structure
325  */
326  size_t context_size;
327  /** Function that performs a MAC setup operation
328  */
329  psa_drv_se_mac_setup_t p_setup;
330  /** Function that performs a MAC update operation
331  */
332  psa_drv_se_mac_update_t p_update;
333  /** Function that completes a MAC operation
334  */
335  psa_drv_se_mac_finish_t p_finish;
336  /** Function that completes a MAC operation with a verify check
337  */
338  psa_drv_se_mac_finish_verify_t p_finish_verify;
339  /** Function that aborts a previoustly started MAC operation
340  */
341  psa_drv_se_mac_abort_t p_abort;
342  /** Function that performs a MAC operation in one call
343  */
344  psa_drv_se_mac_generate_t p_mac;
345  /** Function that performs a MAC and verify operation in one call
346  */
347  psa_drv_se_mac_verify_t p_mac_verify;
348 } psa_drv_se_mac_t;
349 /**@}*/
350 
351 /** \defgroup se_cipher Secure Element Symmetric Ciphers
352  *
353  * Encryption and Decryption using secure element keys in block modes other
354  * than ECB must be done in multiple parts, using the following flow:
355  * - `psa_drv_se_cipher_setup_t`
356  * - `psa_drv_se_cipher_set_iv_t` (optional depending upon block mode)
357  * - `psa_drv_se_cipher_update_t`
358  * - `psa_drv_se_cipher_update_t`
359  * - ...
360  * - `psa_drv_se_cipher_finish_t`
361  *
362  * If a previously started secure element Cipher operation needs to be
363  * terminated, it should be done so by the `psa_drv_se_cipher_abort_t`. Failure
364  * to do so may result in allocated resources not being freed or in other
365  * undefined behavior.
366  *
367  * In situations where a PSA Cryptographic API implementation is using a block
368  * mode not-supported by the underlying hardware or driver, it can construct
369  * the block mode itself, while calling the `psa_drv_se_cipher_ecb_t` function
370  * for the cipher operations.
371  */
372 /**@{*/
373 
374 /** \brief A function that provides the cipher setup function for a
375  * secure element driver
376  *
377  * \param[in,out] drv_context The driver context structure.
378  * \param[in,out] op_context A structure that will contain the
379  * hardware-specific cipher context.
380  * \param[in] key_slot The slot of the key to be used for the
381  * operation
382  * \param[in] algorithm The algorithm to be used in the cipher
383  * operation
384  * \param[in] direction Indicates whether the operation is an encrypt
385  * or decrypt
386  *
387  * \retval #PSA_SUCCESS
388  * \retval #PSA_ERROR_NOT_SUPPORTED
389  */
390 typedef psa_status_t (*psa_drv_se_cipher_setup_t)(psa_drv_se_context_t *drv_context,
391  void *op_context,
392  psa_key_slot_number_t key_slot,
393  psa_algorithm_t algorithm,
394  psa_encrypt_or_decrypt_t direction);
395 
396 /** \brief A function that sets the initialization vector (if
397  * necessary) for an secure element cipher operation
398  *
399  * Rationale: The `psa_se_cipher_*` operation in the PSA Cryptographic API has
400  * two IV functions: one to set the IV, and one to generate it internally. The
401  * generate function is not necessary for the drivers to implement as the PSA
402  * Crypto implementation can do the generation using its RNG features.
403  *
404  * \param[in,out] op_context A structure that contains the previously set up
405  * hardware-specific cipher context
406  * \param[in] p_iv A buffer containing the initialization vector
407  * \param[in] iv_length The size (in bytes) of the `p_iv` buffer
408  *
409  * \retval #PSA_SUCCESS
410  */
411 typedef psa_status_t (*psa_drv_se_cipher_set_iv_t)(void *op_context,
412  const uint8_t *p_iv,
413  size_t iv_length);
414 
415 /** \brief A function that continues a previously started secure element cipher
416  * operation
417  *
418  * \param[in,out] op_context A hardware-specific structure for the
419  * previously started cipher operation
420  * \param[in] p_input A buffer containing the data to be
421  * encrypted/decrypted
422  * \param[in] input_size The size in bytes of the buffer pointed to
423  * by `p_input`
424  * \param[out] p_output The caller-allocated buffer where the
425  * output will be placed
426  * \param[in] output_size The allocated size in bytes of the
427  * `p_output` buffer
428  * \param[out] p_output_length After completion, will contain the number
429  * of bytes placed in the `p_output` buffer
430  *
431  * \retval #PSA_SUCCESS
432  */
433 typedef psa_status_t (*psa_drv_se_cipher_update_t)(void *op_context,
434  const uint8_t *p_input,
435  size_t input_size,
436  uint8_t *p_output,
437  size_t output_size,
438  size_t *p_output_length);
439 
440 /** \brief A function that completes a previously started secure element cipher
441  * operation
442  *
443  * \param[in,out] op_context A hardware-specific structure for the
444  * previously started cipher operation
445  * \param[out] p_output The caller-allocated buffer where the output
446  * will be placed
447  * \param[in] output_size The allocated size in bytes of the `p_output`
448  * buffer
449  * \param[out] p_output_length After completion, will contain the number of
450  * bytes placed in the `p_output` buffer
451  *
452  * \retval #PSA_SUCCESS
453  */
454 typedef psa_status_t (*psa_drv_se_cipher_finish_t)(void *op_context,
455  uint8_t *p_output,
456  size_t output_size,
457  size_t *p_output_length);
458 
459 /** \brief A function that aborts a previously started secure element cipher
460  * operation
461  *
462  * \param[in,out] op_context A hardware-specific structure for the
463  * previously started cipher operation
464  */
465 typedef psa_status_t (*psa_drv_se_cipher_abort_t)(void *op_context);
466 
467 /** \brief A function that performs the ECB block mode for secure element
468  * cipher operations
469  *
470  * Note: this function should only be used with implementations that do not
471  * provide a needed higher-level operation.
472  *
473  * \param[in,out] drv_context The driver context structure.
474  * \param[in] key_slot The slot of the key to be used for the operation
475  * \param[in] algorithm The algorithm to be used in the cipher operation
476  * \param[in] direction Indicates whether the operation is an encrypt or
477  * decrypt
478  * \param[in] p_input A buffer containing the data to be
479  * encrypted/decrypted
480  * \param[in] input_size The size in bytes of the buffer pointed to by
481  * `p_input`
482  * \param[out] p_output The caller-allocated buffer where the output
483  * will be placed
484  * \param[in] output_size The allocated size in bytes of the `p_output`
485  * buffer
486  *
487  * \retval #PSA_SUCCESS
488  * \retval #PSA_ERROR_NOT_SUPPORTED
489  */
490 typedef psa_status_t (*psa_drv_se_cipher_ecb_t)(psa_drv_se_context_t *drv_context,
491  psa_key_slot_number_t key_slot,
492  psa_algorithm_t algorithm,
493  psa_encrypt_or_decrypt_t direction,
494  const uint8_t *p_input,
495  size_t input_size,
496  uint8_t *p_output,
497  size_t output_size);
498 
499 /**
500  * \brief A struct containing all of the function pointers needed to implement
501  * cipher operations using secure elements.
502  *
503  * PSA Crypto API implementations should populate instances of the table as
504  * appropriate upon startup or at build time.
505  *
506  * If one of the functions is not implemented (such as
507  * `psa_drv_se_cipher_ecb_t`), it should be set to NULL.
508  */
509 typedef struct {
510  /** The size in bytes of the hardware-specific secure element cipher
511  * context structure
512  */
513  size_t context_size;
514  /** Function that performs a cipher setup operation */
515  psa_drv_se_cipher_setup_t p_setup;
516  /** Function that sets a cipher IV (if necessary) */
517  psa_drv_se_cipher_set_iv_t p_set_iv;
518  /** Function that performs a cipher update operation */
519  psa_drv_se_cipher_update_t p_update;
520  /** Function that completes a cipher operation */
521  psa_drv_se_cipher_finish_t p_finish;
522  /** Function that aborts a cipher operation */
523  psa_drv_se_cipher_abort_t p_abort;
524  /** Function that performs ECB mode for a cipher operation
525  * (Danger: ECB mode should not be used directly by clients of the PSA
526  * Crypto Client API)
527  */
528  psa_drv_se_cipher_ecb_t p_ecb;
529 } psa_drv_se_cipher_t;
530 
531 /**@}*/
532 
533 /** \defgroup se_asymmetric Secure Element Asymmetric Cryptography
534  *
535  * Since the amount of data that can (or should) be encrypted or signed using
536  * asymmetric keys is limited by the key size, asymmetric key operations using
537  * keys in a secure element must be done in single function calls.
538  */
539 /**@{*/
540 
541 /**
542  * \brief A function that signs a hash or short message with a private key in
543  * a secure element
544  *
545  * \param[in,out] drv_context The driver context structure.
546  * \param[in] key_slot Key slot of an asymmetric key pair
547  * \param[in] alg A signature algorithm that is compatible
548  * with the type of `key`
549  * \param[in] p_hash The hash to sign
550  * \param[in] hash_length Size of the `p_hash` buffer in bytes
551  * \param[out] p_signature Buffer where the signature is to be written
552  * \param[in] signature_size Size of the `p_signature` buffer in bytes
553  * \param[out] p_signature_length On success, the number of bytes
554  * that make up the returned signature value
555  *
556  * \retval #PSA_SUCCESS
557  */
558 typedef psa_status_t (*psa_drv_se_asymmetric_sign_t)(psa_drv_se_context_t *drv_context,
559  psa_key_slot_number_t key_slot,
560  psa_algorithm_t alg,
561  const uint8_t *p_hash,
562  size_t hash_length,
563  uint8_t *p_signature,
564  size_t signature_size,
565  size_t *p_signature_length);
566 
567 /**
568  * \brief A function that verifies the signature a hash or short message using
569  * an asymmetric public key in a secure element
570  *
571  * \param[in,out] drv_context The driver context structure.
572  * \param[in] key_slot Key slot of a public key or an asymmetric key
573  * pair
574  * \param[in] alg A signature algorithm that is compatible with
575  * the type of `key`
576  * \param[in] p_hash The hash whose signature is to be verified
577  * \param[in] hash_length Size of the `p_hash` buffer in bytes
578  * \param[in] p_signature Buffer containing the signature to verify
579  * \param[in] signature_length Size of the `p_signature` buffer in bytes
580  *
581  * \retval #PSA_SUCCESS
582  * The signature is valid.
583  */
584 typedef psa_status_t (*psa_drv_se_asymmetric_verify_t)(psa_drv_se_context_t *drv_context,
585  psa_key_slot_number_t key_slot,
586  psa_algorithm_t alg,
587  const uint8_t *p_hash,
588  size_t hash_length,
589  const uint8_t *p_signature,
590  size_t signature_length);
591 
592 /**
593  * \brief A function that encrypts a short message with an asymmetric public
594  * key in a secure element
595  *
596  * \param[in,out] drv_context The driver context structure.
597  * \param[in] key_slot Key slot of a public key or an asymmetric key
598  * pair
599  * \param[in] alg An asymmetric encryption algorithm that is
600  * compatible with the type of `key`
601  * \param[in] p_input The message to encrypt
602  * \param[in] input_length Size of the `p_input` buffer in bytes
603  * \param[in] p_salt A salt or label, if supported by the
604  * encryption algorithm
605  * If the algorithm does not support a
606  * salt, pass `NULL`.
607  * If the algorithm supports an optional
608  * salt and you do not want to pass a salt,
609  * pass `NULL`.
610  * For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is
611  * supported.
612  * \param[in] salt_length Size of the `p_salt` buffer in bytes
613  * If `p_salt` is `NULL`, pass 0.
614  * \param[out] p_output Buffer where the encrypted message is to
615  * be written
616  * \param[in] output_size Size of the `p_output` buffer in bytes
617  * \param[out] p_output_length On success, the number of bytes that make up
618  * the returned output
619  *
620  * \retval #PSA_SUCCESS
621  */
622 typedef psa_status_t (*psa_drv_se_asymmetric_encrypt_t)(psa_drv_se_context_t *drv_context,
623  psa_key_slot_number_t key_slot,
624  psa_algorithm_t alg,
625  const uint8_t *p_input,
626  size_t input_length,
627  const uint8_t *p_salt,
628  size_t salt_length,
629  uint8_t *p_output,
630  size_t output_size,
631  size_t *p_output_length);
632 
633 /**
634  * \brief A function that decrypts a short message with an asymmetric private
635  * key in a secure element.
636  *
637  * \param[in,out] drv_context The driver context structure.
638  * \param[in] key_slot Key slot of an asymmetric key pair
639  * \param[in] alg An asymmetric encryption algorithm that is
640  * compatible with the type of `key`
641  * \param[in] p_input The message to decrypt
642  * \param[in] input_length Size of the `p_input` buffer in bytes
643  * \param[in] p_salt A salt or label, if supported by the
644  * encryption algorithm
645  * If the algorithm does not support a
646  * salt, pass `NULL`.
647  * If the algorithm supports an optional
648  * salt and you do not want to pass a salt,
649  * pass `NULL`.
650  * For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is
651  * supported.
652  * \param[in] salt_length Size of the `p_salt` buffer in bytes
653  * If `p_salt` is `NULL`, pass 0.
654  * \param[out] p_output Buffer where the decrypted message is to
655  * be written
656  * \param[in] output_size Size of the `p_output` buffer in bytes
657  * \param[out] p_output_length On success, the number of bytes
658  * that make up the returned output
659  *
660  * \retval #PSA_SUCCESS
661  */
662 typedef psa_status_t (*psa_drv_se_asymmetric_decrypt_t)(psa_drv_se_context_t *drv_context,
663  psa_key_slot_number_t key_slot,
664  psa_algorithm_t alg,
665  const uint8_t *p_input,
666  size_t input_length,
667  const uint8_t *p_salt,
668  size_t salt_length,
669  uint8_t *p_output,
670  size_t output_size,
671  size_t *p_output_length);
672 
673 /**
674  * \brief A struct containing all of the function pointers needed to implement
675  * asymmetric cryptographic operations using secure elements.
676  *
677  * PSA Crypto API implementations should populate instances of the table as
678  * appropriate upon startup or at build time.
679  *
680  * If one of the functions is not implemented, it should be set to NULL.
681  */
682 typedef struct {
683  /** Function that performs an asymmetric sign operation */
684  psa_drv_se_asymmetric_sign_t p_sign;
685  /** Function that performs an asymmetric verify operation */
686  psa_drv_se_asymmetric_verify_t p_verify;
687  /** Function that performs an asymmetric encrypt operation */
688  psa_drv_se_asymmetric_encrypt_t p_encrypt;
689  /** Function that performs an asymmetric decrypt operation */
690  psa_drv_se_asymmetric_decrypt_t p_decrypt;
691 } psa_drv_se_asymmetric_t;
692 
693 /**@}*/
694 
695 /** \defgroup se_aead Secure Element Authenticated Encryption with Additional Data
696  * Authenticated Encryption with Additional Data (AEAD) operations with secure
697  * elements must be done in one function call. While this creates a burden for
698  * implementers as there must be sufficient space in memory for the entire
699  * message, it prevents decrypted data from being made available before the
700  * authentication operation is complete and the data is known to be authentic.
701  */
702 /**@{*/
703 
704 /** \brief A function that performs a secure element authenticated encryption
705  * operation
706  *
707  * \param[in,out] drv_context The driver context structure.
708  * \param[in] key_slot Slot containing the key to use.
709  * \param[in] algorithm The AEAD algorithm to compute
710  * (\c PSA_ALG_XXX value such that
711  * #PSA_ALG_IS_AEAD(`alg`) is true)
712  * \param[in] p_nonce Nonce or IV to use
713  * \param[in] nonce_length Size of the `p_nonce` buffer in bytes
714  * \param[in] p_additional_data Additional data that will be
715  * authenticated but not encrypted
716  * \param[in] additional_data_length Size of `p_additional_data` in bytes
717  * \param[in] p_plaintext Data that will be authenticated and
718  * encrypted
719  * \param[in] plaintext_length Size of `p_plaintext` in bytes
720  * \param[out] p_ciphertext Output buffer for the authenticated and
721  * encrypted data. The additional data is
722  * not part of this output. For algorithms
723  * where the encrypted data and the
724  * authentication tag are defined as
725  * separate outputs, the authentication
726  * tag is appended to the encrypted data.
727  * \param[in] ciphertext_size Size of the `p_ciphertext` buffer in
728  * bytes
729  * \param[out] p_ciphertext_length On success, the size of the output in
730  * the `p_ciphertext` buffer
731  *
732  * \retval #PSA_SUCCESS
733  * Success.
734  */
735 typedef psa_status_t (*psa_drv_se_aead_encrypt_t)(psa_drv_se_context_t *drv_context,
736  psa_key_slot_number_t key_slot,
737  psa_algorithm_t algorithm,
738  const uint8_t *p_nonce,
739  size_t nonce_length,
740  const uint8_t *p_additional_data,
741  size_t additional_data_length,
742  const uint8_t *p_plaintext,
743  size_t plaintext_length,
744  uint8_t *p_ciphertext,
745  size_t ciphertext_size,
746  size_t *p_ciphertext_length);
747 
748 /** A function that peforms a secure element authenticated decryption operation
749  *
750  * \param[in,out] drv_context The driver context structure.
751  * \param[in] key_slot Slot containing the key to use
752  * \param[in] algorithm The AEAD algorithm to compute
753  * (\c PSA_ALG_XXX value such that
754  * #PSA_ALG_IS_AEAD(`alg`) is true)
755  * \param[in] p_nonce Nonce or IV to use
756  * \param[in] nonce_length Size of the `p_nonce` buffer in bytes
757  * \param[in] p_additional_data Additional data that has been
758  * authenticated but not encrypted
759  * \param[in] additional_data_length Size of `p_additional_data` in bytes
760  * \param[in] p_ciphertext Data that has been authenticated and
761  * encrypted.
762  * For algorithms where the encrypted data
763  * and the authentication tag are defined
764  * as separate inputs, the buffer must
765  * contain the encrypted data followed by
766  * the authentication tag.
767  * \param[in] ciphertext_length Size of `p_ciphertext` in bytes
768  * \param[out] p_plaintext Output buffer for the decrypted data
769  * \param[in] plaintext_size Size of the `p_plaintext` buffer in
770  * bytes
771  * \param[out] p_plaintext_length On success, the size of the output in
772  * the `p_plaintext` buffer
773  *
774  * \retval #PSA_SUCCESS
775  * Success.
776  */
777 typedef psa_status_t (*psa_drv_se_aead_decrypt_t)(psa_drv_se_context_t *drv_context,
778  psa_key_slot_number_t key_slot,
779  psa_algorithm_t algorithm,
780  const uint8_t *p_nonce,
781  size_t nonce_length,
782  const uint8_t *p_additional_data,
783  size_t additional_data_length,
784  const uint8_t *p_ciphertext,
785  size_t ciphertext_length,
786  uint8_t *p_plaintext,
787  size_t plaintext_size,
788  size_t *p_plaintext_length);
789 
790 /**
791  * \brief A struct containing all of the function pointers needed to implement
792  * secure element Authenticated Encryption with Additional Data operations
793  *
794  * PSA Crypto API implementations should populate instances of the table as
795  * appropriate upon startup.
796  *
797  * If one of the functions is not implemented, it should be set to NULL.
798  */
799 typedef struct {
800  /** Function that performs the AEAD encrypt operation */
801  psa_drv_se_aead_encrypt_t p_encrypt;
802  /** Function that performs the AEAD decrypt operation */
803  psa_drv_se_aead_decrypt_t p_decrypt;
804 } psa_drv_se_aead_t;
805 /**@}*/
806 
807 /** \defgroup se_key_management Secure Element Key Management
808  * Currently, key management is limited to importing keys in the clear,
809  * destroying keys, and exporting keys in the clear.
810  * Whether a key may be exported is determined by the key policies in place
811  * on the key slot.
812  */
813 /**@{*/
814 
815 /** An enumeration indicating how a key is created.
816  */
817 typedef enum
818 {
819  PSA_KEY_CREATION_IMPORT, /**< During psa_import_key() */
820  PSA_KEY_CREATION_GENERATE, /**< During psa_generate_key() */
821  PSA_KEY_CREATION_DERIVE, /**< During psa_key_derivation_output_key() */
822  PSA_KEY_CREATION_COPY, /**< During psa_copy_key() */
823 
824 #ifndef __DOXYGEN_ONLY__
825  /** A key is being registered with mbedtls_psa_register_se_key().
826  *
827  * The core only passes this value to
828  * psa_drv_se_key_management_t::p_validate_slot_number, not to
829  * psa_drv_se_key_management_t::p_allocate. The call to
830  * `p_validate_slot_number` is not followed by any other call to the
831  * driver: the key is considered successfully registered if the call to
832  * `p_validate_slot_number` succeeds, or if `p_validate_slot_number` is
833  * null.
834  *
835  * With this creation method, the driver must return #PSA_SUCCESS if
836  * the given attributes are compatible with the existing key in the slot,
837  * and #PSA_ERROR_DOES_NOT_EXIST if the driver can determine that there
838  * is no key with the specified slot number.
839  *
840  * This is an Mbed Crypto extension.
841  */
842  PSA_KEY_CREATION_REGISTER,
843 #endif
844 } psa_key_creation_method_t;
845 
846 /** \brief A function that allocates a slot for a key.
847  *
848  * To create a key in a specific slot in a secure element, the core
849  * first calls this function to determine a valid slot number,
850  * then calls a function to create the key material in that slot.
851  * In nominal conditions (that is, if no error occurs),
852  * the effect of a call to a key creation function in the PSA Cryptography
853  * API with a lifetime that places the key in a secure element is the
854  * following:
855  * -# The core calls psa_drv_se_key_management_t::p_allocate
856  * (or in some implementations
857  * psa_drv_se_key_management_t::p_validate_slot_number). The driver
858  * selects (or validates) a suitable slot number given the key attributes
859  * and the state of the secure element.
860  * -# The core calls a key creation function in the driver.
861  *
862  * The key creation functions in the PSA Cryptography API are:
863  * - psa_import_key(), which causes
864  * a call to `p_allocate` with \p method = #PSA_KEY_CREATION_IMPORT
865  * then a call to psa_drv_se_key_management_t::p_import.
866  * - psa_generate_key(), which causes
867  * a call to `p_allocate` with \p method = #PSA_KEY_CREATION_GENERATE
868  * then a call to psa_drv_se_key_management_t::p_import.
869  * - psa_key_derivation_output_key(), which causes
870  * a call to `p_allocate` with \p method = #PSA_KEY_CREATION_DERIVE
871  * then a call to psa_drv_se_key_derivation_t::p_derive.
872  * - psa_copy_key(), which causes
873  * a call to `p_allocate` with \p method = #PSA_KEY_CREATION_COPY
874  * then a call to psa_drv_se_key_management_t::p_export.
875  *
876  * In case of errors, other behaviors are possible.
877  * - If the PSA Cryptography subsystem dies after the first step,
878  * for example because the device has lost power abruptly,
879  * the second step may never happen, or may happen after a reset
880  * and re-initialization. Alternatively, after a reset and
881  * re-initialization, the core may call
882  * psa_drv_se_key_management_t::p_destroy on the slot number that
883  * was allocated (or validated) instead of calling a key creation function.
884  * - If an error occurs, the core may call
885  * psa_drv_se_key_management_t::p_destroy on the slot number that
886  * was allocated (or validated) instead of calling a key creation function.
887  *
888  * Errors and system resets also have an impact on the driver's persistent
889  * data. If a reset happens before the overall key creation process is
890  * completed (before or after the second step above), it is unspecified
891  * whether the persistent data after the reset is identical to what it
892  * was before or after the call to `p_allocate` (or `p_validate_slot_number`).
893  *
894  * \param[in,out] drv_context The driver context structure.
895  * \param[in,out] persistent_data A pointer to the persistent data
896  * that allows writing.
897  * \param[in] attributes Attributes of the key.
898  * \param method The way in which the key is being created.
899  * \param[out] key_slot Slot where the key will be stored.
900  * This must be a valid slot for a key of the
901  * chosen type. It must be unoccupied.
902  *
903  * \retval #PSA_SUCCESS
904  * Success.
905  * The core will record \c *key_slot as the key slot where the key
906  * is stored and will update the persistent data in storage.
907  * \retval #PSA_ERROR_NOT_SUPPORTED
908  * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
909  */
910 typedef psa_status_t (*psa_drv_se_allocate_key_t)(
911  psa_drv_se_context_t *drv_context,
912  void *persistent_data,
913  const psa_key_attributes_t *attributes,
914  psa_key_creation_method_t method,
915  psa_key_slot_number_t *key_slot);
916 
917 /** \brief A function that determines whether a slot number is valid
918  * for a key.
919  *
920  * To create a key in a specific slot in a secure element, the core
921  * first calls this function to validate the choice of slot number,
922  * then calls a function to create the key material in that slot.
923  * See the documentation of #psa_drv_se_allocate_key_t for more details.
924  *
925  * As of the PSA Cryptography API specification version 1.0, there is no way
926  * for applications to trigger a call to this function. However some
927  * implementations offer the capability to create or declare a key in
928  * a specific slot via implementation-specific means, generally for the
929  * sake of initial device provisioning or onboarding. Such a mechanism may
930  * be added to a future version of the PSA Cryptography API specification.
931  *
932  * This function may update the driver's persistent data through
933  * \p persistent_data. The core will save the updated persistent data at the
934  * end of the key creation process. See the description of
935  * ::psa_drv_se_allocate_key_t for more information.
936  *
937  * \param[in,out] drv_context The driver context structure.
938  * \param[in,out] persistent_data A pointer to the persistent data
939  * that allows writing.
940  * \param[in] attributes Attributes of the key.
941  * \param method The way in which the key is being created.
942  * \param[in] key_slot Slot where the key is to be stored.
943  *
944  * \retval #PSA_SUCCESS
945  * The given slot number is valid for a key with the given
946  * attributes.
947  * \retval #PSA_ERROR_INVALID_ARGUMENT
948  * The given slot number is not valid for a key with the
949  * given attributes. This includes the case where the slot
950  * number is not valid at all.
951  * \retval #PSA_ERROR_ALREADY_EXISTS
952  * There is already a key with the specified slot number.
953  * Drivers may choose to return this error from the key
954  * creation function instead.
955  */
956 typedef psa_status_t (*psa_drv_se_validate_slot_number_t)(
957  psa_drv_se_context_t *drv_context,
958  void *persistent_data,
959  const psa_key_attributes_t *attributes,
960  psa_key_creation_method_t method,
961  psa_key_slot_number_t key_slot);
962 
963 /** \brief A function that imports a key into a secure element in binary format
964  *
965  * This function can support any output from psa_export_key(). Refer to the
966  * documentation of psa_export_key() for the format for each key type.
967  *
968  * \param[in,out] drv_context The driver context structure.
969  * \param key_slot Slot where the key will be stored.
970  * This must be a valid slot for a key of the
971  * chosen type. It must be unoccupied.
972  * \param[in] attributes The key attributes, including the lifetime,
973  * the key type and the usage policy.
974  * Drivers should not access the key size stored
975  * in the attributes: it may not match the
976  * data passed in \p data.
977  * Drivers can call psa_get_key_lifetime(),
978  * psa_get_key_type(),
979  * psa_get_key_usage_flags() and
980  * psa_get_key_algorithm() to access this
981  * information.
982  * \param[in] data Buffer containing the key data.
983  * \param[in] data_length Size of the \p data buffer in bytes.
984  * \param[out] bits On success, the key size in bits. The driver
985  * must determine this value after parsing the
986  * key according to the key type.
987  * This value is not used if the function fails.
988  *
989  * \retval #PSA_SUCCESS
990  * Success.
991  */
992 typedef psa_status_t (*psa_drv_se_import_key_t)(
993  psa_drv_se_context_t *drv_context,
994  psa_key_slot_number_t key_slot,
995  const psa_key_attributes_t *attributes,
996  const uint8_t *data,
997  size_t data_length,
998  size_t *bits);
999 
1000 /**
1001  * \brief A function that destroys a secure element key and restore the slot to
1002  * its default state
1003  *
1004  * This function destroys the content of the key from a secure element.
1005  * Implementations shall make a best effort to ensure that any previous content
1006  * of the slot is unrecoverable.
1007  *
1008  * This function returns the specified slot to its default state.
1009  *
1010  * \param[in,out] drv_context The driver context structure.
1011  * \param[in,out] persistent_data A pointer to the persistent data
1012  * that allows writing.
1013  * \param key_slot The key slot to erase.
1014  *
1015  * \retval #PSA_SUCCESS
1016  * The slot's content, if any, has been erased.
1017  */
1018 typedef psa_status_t (*psa_drv_se_destroy_key_t)(
1019  psa_drv_se_context_t *drv_context,
1020  void *persistent_data,
1021  psa_key_slot_number_t key_slot);
1022 
1023 /**
1024  * \brief A function that exports a secure element key in binary format
1025  *
1026  * The output of this function can be passed to psa_import_key() to
1027  * create an equivalent object.
1028  *
1029  * If a key is created with `psa_import_key()` and then exported with
1030  * this function, it is not guaranteed that the resulting data is
1031  * identical: the implementation may choose a different representation
1032  * of the same key if the format permits it.
1033  *
1034  * This function should generate output in the same format that
1035  * `psa_export_key()` does. Refer to the
1036  * documentation of `psa_export_key()` for the format for each key type.
1037  *
1038  * \param[in,out] drv_context The driver context structure.
1039  * \param[in] key Slot whose content is to be exported. This must
1040  * be an occupied key slot.
1041  * \param[out] p_data Buffer where the key data is to be written.
1042  * \param[in] data_size Size of the `p_data` buffer in bytes.
1043  * \param[out] p_data_length On success, the number of bytes
1044  * that make up the key data.
1045  *
1046  * \retval #PSA_SUCCESS
1047  * \retval #PSA_ERROR_DOES_NOT_EXIST
1048  * \retval #PSA_ERROR_NOT_PERMITTED
1049  * \retval #PSA_ERROR_NOT_SUPPORTED
1050  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1051  * \retval #PSA_ERROR_HARDWARE_FAILURE
1052  * \retval #PSA_ERROR_CORRUPTION_DETECTED
1053  */
1054 typedef psa_status_t (*psa_drv_se_export_key_t)(psa_drv_se_context_t *drv_context,
1055  psa_key_slot_number_t key,
1056  uint8_t *p_data,
1057  size_t data_size,
1058  size_t *p_data_length);
1059 
1060 /**
1061  * \brief A function that generates a symmetric or asymmetric key on a secure
1062  * element
1063  *
1064  * If \p type is asymmetric (#PSA_KEY_TYPE_IS_ASYMMETRIC(\p type) = 1),
1065  * the driver may export the public key at the time of generation,
1066  * in the format documented for psa_export_public_key() by writing it
1067  * to the \p pubkey buffer.
1068  * This is optional, intended for secure elements that output the
1069  * public key at generation time and that cannot export the public key
1070  * later. Drivers that do not need this feature should leave
1071  * \p *pubkey_length set to 0 and should
1072  * implement the psa_drv_key_management_t::p_export_public function.
1073  * Some implementations do not support this feature, in which case
1074  * \p pubkey is \c NULL and \p pubkey_size is 0.
1075  *
1076  * \param[in,out] drv_context The driver context structure.
1077  * \param key_slot Slot where the key will be stored.
1078  * This must be a valid slot for a key of the
1079  * chosen type. It must be unoccupied.
1080  * \param[in] attributes The key attributes, including the lifetime,
1081  * the key type and size, and the usage policy.
1082  * Drivers can call psa_get_key_lifetime(),
1083  * psa_get_key_type(), psa_get_key_bits(),
1084  * psa_get_key_usage_flags() and
1085  * psa_get_key_algorithm() to access this
1086  * information.
1087  * \param[out] pubkey A buffer where the driver can write the
1088  * public key, when generating an asymmetric
1089  * key pair.
1090  * This is \c NULL when generating a symmetric
1091  * key or if the core does not support
1092  * exporting the public key at generation time.
1093  * \param pubkey_size The size of the `pubkey` buffer in bytes.
1094  * This is 0 when generating a symmetric
1095  * key or if the core does not support
1096  * exporting the public key at generation time.
1097  * \param[out] pubkey_length On entry, this is always 0.
1098  * On success, the number of bytes written to
1099  * \p pubkey. If this is 0 or unchanged on return,
1100  * the core will not read the \p pubkey buffer,
1101  * and will instead call the driver's
1102  * psa_drv_key_management_t::p_export_public
1103  * function to export the public key when needed.
1104  */
1105 typedef psa_status_t (*psa_drv_se_generate_key_t)(
1106  psa_drv_se_context_t *drv_context,
1107  psa_key_slot_number_t key_slot,
1108  const psa_key_attributes_t *attributes,
1109  uint8_t *pubkey, size_t pubkey_size, size_t *pubkey_length);
1110 
1111 /**
1112  * \brief A struct containing all of the function pointers needed to for secure
1113  * element key management
1114  *
1115  * PSA Crypto API implementations should populate instances of the table as
1116  * appropriate upon startup or at build time.
1117  *
1118  * If one of the functions is not implemented, it should be set to NULL.
1119  */
1120 typedef struct {
1121  /** Function that allocates a slot for a key. */
1122  psa_drv_se_allocate_key_t p_allocate;
1123  /** Function that checks the validity of a slot for a key. */
1124  psa_drv_se_validate_slot_number_t p_validate_slot_number;
1125  /** Function that performs a key import operation */
1126  psa_drv_se_import_key_t p_import;
1127  /** Function that performs a generation */
1128  psa_drv_se_generate_key_t p_generate;
1129  /** Function that performs a key destroy operation */
1130  psa_drv_se_destroy_key_t p_destroy;
1131  /** Function that performs a key export operation */
1132  psa_drv_se_export_key_t p_export;
1133  /** Function that performs a public key export operation */
1134  psa_drv_se_export_key_t p_export_public;
1135 } psa_drv_se_key_management_t;
1136 
1137 /**@}*/
1138 
1139 /** \defgroup driver_derivation Secure Element Key Derivation and Agreement
1140  * Key derivation is the process of generating new key material using an
1141  * existing key and additional parameters, iterating through a basic
1142  * cryptographic function, such as a hash.
1143  * Key agreement is a part of cryptographic protocols that allows two parties
1144  * to agree on the same key value, but starting from different original key
1145  * material.
1146  * The flows are similar, and the PSA Crypto Driver Model uses the same functions
1147  * for both of the flows.
1148  *
1149  * There are two different final functions for the flows,
1150  * `psa_drv_se_key_derivation_derive` and `psa_drv_se_key_derivation_export`.
1151  * `psa_drv_se_key_derivation_derive` is used when the key material should be
1152  * placed in a slot on the hardware and not exposed to the caller.
1153  * `psa_drv_se_key_derivation_export` is used when the key material should be
1154  * returned to the PSA Cryptographic API implementation.
1155  *
1156  * Different key derivation algorithms require a different number of inputs.
1157  * Instead of having an API that takes as input variable length arrays, which
1158  * can be problemmatic to manage on embedded platforms, the inputs are passed
1159  * to the driver via a function, `psa_drv_se_key_derivation_collateral`, that
1160  * is called multiple times with different `collateral_id`s. Thus, for a key
1161  * derivation algorithm that required 3 paramter inputs, the flow would look
1162  * something like:
1163  * ~~~~~~~~~~~~~{.c}
1164  * psa_drv_se_key_derivation_setup(kdf_algorithm, source_key, dest_key_size_bytes);
1165  * psa_drv_se_key_derivation_collateral(kdf_algorithm_collateral_id_0,
1166  * p_collateral_0,
1167  * collateral_0_size);
1168  * psa_drv_se_key_derivation_collateral(kdf_algorithm_collateral_id_1,
1169  * p_collateral_1,
1170  * collateral_1_size);
1171  * psa_drv_se_key_derivation_collateral(kdf_algorithm_collateral_id_2,
1172  * p_collateral_2,
1173  * collateral_2_size);
1174  * psa_drv_se_key_derivation_derive();
1175  * ~~~~~~~~~~~~~
1176  *
1177  * key agreement example:
1178  * ~~~~~~~~~~~~~{.c}
1179  * psa_drv_se_key_derivation_setup(alg, source_key. dest_key_size_bytes);
1180  * psa_drv_se_key_derivation_collateral(DHE_PUBKEY, p_pubkey, pubkey_size);
1181  * psa_drv_se_key_derivation_export(p_session_key,
1182  * session_key_size,
1183  * &session_key_length);
1184  * ~~~~~~~~~~~~~
1185  */
1186 /**@{*/
1187 
1188 /** \brief A function that Sets up a secure element key derivation operation by
1189  * specifying the algorithm and the source key sot
1190  *
1191  * \param[in,out] drv_context The driver context structure.
1192  * \param[in,out] op_context A hardware-specific structure containing any
1193  * context information for the implementation
1194  * \param[in] kdf_alg The algorithm to be used for the key derivation
1195  * \param[in] source_key The key to be used as the source material for
1196  * the key derivation
1197  *
1198  * \retval #PSA_SUCCESS
1199  */
1200 typedef psa_status_t (*psa_drv_se_key_derivation_setup_t)(psa_drv_se_context_t *drv_context,
1201  void *op_context,
1202  psa_algorithm_t kdf_alg,
1203  psa_key_slot_number_t source_key);
1204 
1205 /** \brief A function that provides collateral (parameters) needed for a secure
1206  * element key derivation or key agreement operation
1207  *
1208  * Since many key derivation algorithms require multiple parameters, it is
1209  * expeced that this function may be called multiple times for the same
1210  * operation, each with a different algorithm-specific `collateral_id`
1211  *
1212  * \param[in,out] op_context A hardware-specific structure containing any
1213  * context information for the implementation
1214  * \param[in] collateral_id An ID for the collateral being provided
1215  * \param[in] p_collateral A buffer containing the collateral data
1216  * \param[in] collateral_size The size in bytes of the collateral
1217  *
1218  * \retval #PSA_SUCCESS
1219  */
1220 typedef psa_status_t (*psa_drv_se_key_derivation_collateral_t)(void *op_context,
1221  uint32_t collateral_id,
1222  const uint8_t *p_collateral,
1223  size_t collateral_size);
1224 
1225 /** \brief A function that performs the final secure element key derivation
1226  * step and place the generated key material in a slot
1227  *
1228  * \param[in,out] op_context A hardware-specific structure containing any
1229  * context information for the implementation
1230  * \param[in] dest_key The slot where the generated key material
1231  * should be placed
1232  *
1233  * \retval #PSA_SUCCESS
1234  */
1235 typedef psa_status_t (*psa_drv_se_key_derivation_derive_t)(void *op_context,
1236  psa_key_slot_number_t dest_key);
1237 
1238 /** \brief A function that performs the final step of a secure element key
1239  * agreement and place the generated key material in a buffer
1240  *
1241  * \param[out] p_output Buffer in which to place the generated key
1242  * material
1243  * \param[in] output_size The size in bytes of `p_output`
1244  * \param[out] p_output_length Upon success, contains the number of bytes of
1245  * key material placed in `p_output`
1246  *
1247  * \retval #PSA_SUCCESS
1248  */
1249 typedef psa_status_t (*psa_drv_se_key_derivation_export_t)(void *op_context,
1250  uint8_t *p_output,
1251  size_t output_size,
1252  size_t *p_output_length);
1253 
1254 /**
1255  * \brief A struct containing all of the function pointers needed to for secure
1256  * element key derivation and agreement
1257  *
1258  * PSA Crypto API implementations should populate instances of the table as
1259  * appropriate upon startup.
1260  *
1261  * If one of the functions is not implemented, it should be set to NULL.
1262  */
1263 typedef struct {
1264  /** The driver-specific size of the key derivation context */
1265  size_t context_size;
1266  /** Function that performs a key derivation setup */
1267  psa_drv_se_key_derivation_setup_t p_setup;
1268  /** Function that sets key derivation collateral */
1269  psa_drv_se_key_derivation_collateral_t p_collateral;
1270  /** Function that performs a final key derivation step */
1271  psa_drv_se_key_derivation_derive_t p_derive;
1272  /** Function that perforsm a final key derivation or agreement and
1273  * exports the key */
1274  psa_drv_se_key_derivation_export_t p_export;
1275 } psa_drv_se_key_derivation_t;
1276 
1277 /**@}*/
1278 
1279 /** \defgroup se_registration Secure element driver registration
1280  */
1281 /**@{*/
1282 
1283 /** A structure containing pointers to all the entry points of a
1284  * secure element driver.
1285  *
1286  * Future versions of this specification may add extra substructures at
1287  * the end of this structure.
1288  */
1289 typedef struct {
1290  /** The version of the driver HAL that this driver implements.
1291  * This is a protection against loading driver binaries built against
1292  * a different version of this specification.
1293  * Use #PSA_DRV_SE_HAL_VERSION.
1294  */
1295  uint32_t hal_version;
1296 
1297  /** The size of the driver's persistent data in bytes.
1298  *
1299  * This can be 0 if the driver does not need persistent data.
1300  *
1301  * See the documentation of psa_drv_se_context_t::persistent_data
1302  * for more information about why and how a driver can use
1303  * persistent data.
1304  */
1305  size_t persistent_data_size;
1306 
1307  /** The driver initialization function.
1308  *
1309  * This function is called once during the initialization of the
1310  * PSA Cryptography subsystem, before any other function of the
1311  * driver is called. If this function returns a failure status,
1312  * the driver will be unusable, at least until the next system reset.
1313  *
1314  * If this field is \c NULL, it is equivalent to a function that does
1315  * nothing and returns #PSA_SUCCESS.
1316  */
1317  psa_drv_se_init_t p_init;
1318 
1319  const psa_drv_se_key_management_t *key_management;
1320  const psa_drv_se_mac_t *mac;
1321  const psa_drv_se_cipher_t *cipher;
1322  const psa_drv_se_aead_t *aead;
1323  const psa_drv_se_asymmetric_t *asymmetric;
1324  const psa_drv_se_key_derivation_t *derivation;
1325 } psa_drv_se_t;
1326 
1327 /** The current version of the secure element driver HAL.
1328  */
1329 /* 0.0.0 patchlevel 5 */
1330 #define PSA_DRV_SE_HAL_VERSION 0x00000005
1331 
1332 /** Register an external cryptoprocessor (secure element) driver.
1333  *
1334  * This function is only intended to be used by driver code, not by
1335  * application code. In implementations with separation between the
1336  * PSA cryptography module and applications, this function should
1337  * only be available to callers that run in the same memory space as
1338  * the cryptography module, and should not be exposed to applications
1339  * running in a different memory space.
1340  *
1341  * This function may be called before psa_crypto_init(). It is
1342  * implementation-defined whether this function may be called
1343  * after psa_crypto_init().
1344  *
1345  * \note Implementations store metadata about keys including the lifetime
1346  * value, which contains the driver's location indicator. Therefore,
1347  * from one instantiation of the PSA Cryptography
1348  * library to the next one, if there is a key in storage with a certain
1349  * lifetime value, you must always register the same driver (or an
1350  * updated version that communicates with the same secure element)
1351  * with the same location value.
1352  *
1353  * \param location The location value through which this driver will
1354  * be exposed to applications.
1355  * This driver will be used for all keys such that
1356  * `location == #PSA_KEY_LIFETIME_GET_LOCATION( lifetime )`.
1357  * The value #PSA_KEY_LOCATION_LOCAL_STORAGE is reserved
1358  * and may not be used for drivers. Implementations
1359  * may reserve other values.
1360  * \param[in] methods The method table of the driver. This structure must
1361  * remain valid for as long as the cryptography
1362  * module keeps running. It is typically a global
1363  * constant.
1364  *
1365  * \return #PSA_SUCCESS
1366  * The driver was successfully registered. Applications can now
1367  * use \p lifetime to access keys through the methods passed to
1368  * this function.
1369  * \return #PSA_ERROR_BAD_STATE
1370  * This function was called after the initialization of the
1371  * cryptography module, and this implementation does not support
1372  * driver registration at this stage.
1373  * \return #PSA_ERROR_ALREADY_EXISTS
1374  * There is already a registered driver for this value of \p lifetime.
1375  * \return #PSA_ERROR_INVALID_ARGUMENT
1376  * \p lifetime is a reserved value.
1377  * \return #PSA_ERROR_NOT_SUPPORTED
1378  * `methods->hal_version` is not supported by this implementation.
1379  * \return #PSA_ERROR_INSUFFICIENT_MEMORY
1380  * \return #PSA_ERROR_NOT_PERMITTED
1381  */
1382 psa_status_t psa_register_se_driver(
1383  psa_key_location_t location,
1384  const psa_drv_se_t *methods);
1385 
1386 /**@}*/
1387 
1388 #ifdef __cplusplus
1389 }
1390 #endif
1391 
1392 #endif /* PSA_CRYPTO_SE_DRIVER_H */
psa_drv_se_mac_generate_t
psa_status_t(* psa_drv_se_mac_generate_t)(psa_drv_se_context_t *drv_context, const uint8_t *p_input, size_t input_length, psa_key_slot_number_t key_slot, psa_algorithm_t alg, uint8_t *p_mac, size_t mac_size, size_t *p_mac_length)
A function that performs a secure element MAC operation in one command and returns the calculated MAC...
Definition: crypto_se_driver.h:270
psa_drv_se_key_management_t::p_allocate
psa_drv_se_allocate_key_t p_allocate
Function that allocates a slot for a key.
Definition: crypto_se_driver.h:1122
psa_key_attributes_s
Definition: TARGET_MBED_PSA_SRV/mbedtls/crypto_struct.h:352
psa_encrypt_or_decrypt_t
psa_encrypt_or_decrypt_t
For encrypt-decrypt functions, whether the operation is an encryption or a decryption.
Definition: crypto_driver_common.h:49
psa_drv_se_mac_t::p_setup
psa_drv_se_mac_setup_t p_setup
Function that performs a MAC setup operation.
Definition: crypto_se_driver.h:329
PSA_KEY_CREATION_IMPORT
During psa_import_key()
Definition: crypto_se_driver.h:819
psa_drv_se_aead_decrypt_t
psa_status_t(* psa_drv_se_aead_decrypt_t)(psa_drv_se_context_t *drv_context, psa_key_slot_number_t key_slot, psa_algorithm_t algorithm, const uint8_t *p_nonce, size_t nonce_length, const uint8_t *p_additional_data, size_t additional_data_length, const uint8_t *p_ciphertext, size_t ciphertext_length, uint8_t *p_plaintext, size_t plaintext_size, size_t *p_plaintext_length)
A function that peforms a secure element authenticated decryption operation.
Definition: crypto_se_driver.h:777
psa_drv_se_cipher_update_t
psa_status_t(* psa_drv_se_cipher_update_t)(void *op_context, const uint8_t *p_input, size_t input_size, uint8_t *p_output, size_t output_size, size_t *p_output_length)
A function that continues a previously started secure element cipher operation.
Definition: crypto_se_driver.h:433
psa_drv_se_aead_t::p_decrypt
psa_drv_se_aead_decrypt_t p_decrypt
Function that performs the AEAD decrypt operation.
Definition: crypto_se_driver.h:803
psa_drv_se_asymmetric_sign_t
psa_status_t(* psa_drv_se_asymmetric_sign_t)(psa_drv_se_context_t *drv_context, psa_key_slot_number_t key_slot, psa_algorithm_t alg, const uint8_t *p_hash, size_t hash_length, uint8_t *p_signature, size_t signature_size, size_t *p_signature_length)
A function that signs a hash or short message with a private key in a secure element.
Definition: crypto_se_driver.h:558
psa_drv_se_context_t::persistent_data_size
const size_t persistent_data_size
The size of persistent_data in bytes.
Definition: crypto_se_driver.h:107
psa_drv_se_key_derivation_export_t
psa_status_t(* psa_drv_se_key_derivation_export_t)(void *op_context, uint8_t *p_output, size_t output_size, size_t *p_output_length)
A function that performs the final step of a secure element key agreement and place the generated key...
Definition: crypto_se_driver.h:1249
psa_drv_se_mac_finish_verify_t
psa_status_t(* psa_drv_se_mac_finish_verify_t)(void *op_context, const uint8_t *p_mac, size_t mac_length)
A function that completes a previously started secure element MAC operation by comparing the resultin...
Definition: crypto_se_driver.h:240
psa_drv_se_asymmetric_t::p_sign
psa_drv_se_asymmetric_sign_t p_sign
Function that performs an asymmetric sign operation.
Definition: crypto_se_driver.h:684
psa_drv_se_key_management_t
A struct containing all of the function pointers needed to for secure element key management...
Definition: crypto_se_driver.h:1120
psa_drv_se_key_derivation_t::p_export
psa_drv_se_key_derivation_export_t p_export
Function that perforsm a final key derivation or agreement and exports the key.
Definition: crypto_se_driver.h:1274
psa_drv_se_cipher_finish_t
psa_status_t(* psa_drv_se_cipher_finish_t)(void *op_context, uint8_t *p_output, size_t output_size, size_t *p_output_length)
A function that completes a previously started secure element cipher operation.
Definition: crypto_se_driver.h:454
psa_drv_se_key_management_t::p_destroy
psa_drv_se_destroy_key_t p_destroy
Function that performs a key destroy operation.
Definition: crypto_se_driver.h:1130
psa_drv_se_mac_abort_t
psa_status_t(* psa_drv_se_mac_abort_t)(void *op_context)
A function that aborts a previous started secure element MAC operation.
Definition: crypto_se_driver.h:250
psa_drv_se_mac_verify_t
psa_status_t(* psa_drv_se_mac_verify_t)(psa_drv_se_context_t *drv_context, const uint8_t *p_input, size_t input_length, psa_key_slot_number_t key_slot, psa_algorithm_t alg, const uint8_t *p_mac, size_t mac_length)
A function that performs a secure element MAC operation in one command and compares the resulting MAC...
Definition: crypto_se_driver.h:299
psa_key_location_t
uint32_t psa_key_location_t
Encoding of key location indicators.
Definition: TARGET_MBED_PSA_SRV/inc/psa/crypto_types.h:220
psa_drv_se_export_key_t
psa_status_t(* psa_drv_se_export_key_t)(psa_drv_se_context_t *drv_context, psa_key_slot_number_t key, uint8_t *p_data, size_t data_size, size_t *p_data_length)
A function that exports a secure element key in binary format.
Definition: crypto_se_driver.h:1054
psa_drv_se_mac_t::p_finish
psa_drv_se_mac_finish_t p_finish
Function that completes a MAC operation.
Definition: crypto_se_driver.h:335
psa_drv_se_asymmetric_decrypt_t
psa_status_t(* psa_drv_se_asymmetric_decrypt_t)(psa_drv_se_context_t *drv_context, psa_key_slot_number_t key_slot, psa_algorithm_t alg, const uint8_t *p_input, size_t input_length, const uint8_t *p_salt, size_t salt_length, uint8_t *p_output, size_t output_size, size_t *p_output_length)
A function that decrypts a short message with an asymmetric private key in a secure element...
Definition: crypto_se_driver.h:662
psa_drv_se_asymmetric_t::p_verify
psa_drv_se_asymmetric_verify_t p_verify
Function that performs an asymmetric verify operation.
Definition: crypto_se_driver.h:686
psa_drv_se_cipher_t::p_update
psa_drv_se_cipher_update_t p_update
Function that performs a cipher update operation.
Definition: crypto_se_driver.h:519
PSA_KEY_CREATION_DERIVE
During psa_key_derivation_output_key()
Definition: crypto_se_driver.h:821
psa_drv_se_mac_t::p_abort
psa_drv_se_mac_abort_t p_abort
Function that aborts a previoustly started MAC operation.
Definition: crypto_se_driver.h:341
psa_drv_se_validate_slot_number_t
psa_status_t(* psa_drv_se_validate_slot_number_t)(psa_drv_se_context_t *drv_context, void *persistent_data, const psa_key_attributes_t *attributes, psa_key_creation_method_t method, psa_key_slot_number_t key_slot)
A function that determines whether a slot number is valid for a key.
Definition: crypto_se_driver.h:956
psa_drv_se_mac_t::p_update
psa_drv_se_mac_update_t p_update
Function that performs a MAC update operation.
Definition: crypto_se_driver.h:332
psa_drv_se_t
A structure containing pointers to all the entry points of a secure element driver.
Definition: crypto_se_driver.h:1289
psa_drv_se_context_t
Driver context structure.
Definition: crypto_se_driver.h:55
psa_drv_se_cipher_t
A struct containing all of the function pointers needed to implement cipher operations using secure e...
Definition: crypto_se_driver.h:509
psa_drv_se_import_key_t
psa_status_t(* psa_drv_se_import_key_t)(psa_drv_se_context_t *drv_context, psa_key_slot_number_t key_slot, const psa_key_attributes_t *attributes, const uint8_t *data, size_t data_length, size_t *bits)
A function that imports a key into a secure element in binary format.
Definition: crypto_se_driver.h:992
psa_key_slot_number_t
uint64_t psa_key_slot_number_t
An internal designation of a key slot between the core part of the PSA Crypto implementation and the ...
Definition: crypto_se_driver.h:148
psa_drv_se_cipher_t::p_setup
psa_drv_se_cipher_setup_t p_setup
Function that performs a cipher setup operation.
Definition: crypto_se_driver.h:515
psa_drv_se_asymmetric_t
A struct containing all of the function pointers needed to implement asymmetric cryptographic operati...
Definition: crypto_se_driver.h:682
psa_register_se_driver
psa_status_t psa_register_se_driver(psa_key_location_t location, const psa_drv_se_t *methods)
Register an external cryptoprocessor (secure element) driver.
psa_drv_se_t::persistent_data_size
size_t persistent_data_size
The size of the driver&#39;s persistent data in bytes.
Definition: crypto_se_driver.h:1305
psa_drv_se_key_derivation_t::context_size
size_t context_size
The driver-specific size of the key derivation context.
Definition: crypto_se_driver.h:1265
psa_drv_se_cipher_setup_t
psa_status_t(* psa_drv_se_cipher_setup_t)(psa_drv_se_context_t *drv_context, void *op_context, psa_key_slot_number_t key_slot, psa_algorithm_t algorithm, psa_encrypt_or_decrypt_t direction)
A function that provides the cipher setup function for a secure element driver.
Definition: crypto_se_driver.h:390
psa_drv_se_key_derivation_t::p_derive
psa_drv_se_key_derivation_derive_t p_derive
Function that performs a final key derivation step.
Definition: crypto_se_driver.h:1271
psa_drv_se_generate_key_t
psa_status_t(* psa_drv_se_generate_key_t)(psa_drv_se_context_t *drv_context, psa_key_slot_number_t key_slot, const psa_key_attributes_t *attributes, uint8_t *pubkey, size_t pubkey_size, size_t *pubkey_length)
A function that generates a symmetric or asymmetric key on a secure element.
Definition: crypto_se_driver.h:1105
psa_algorithm_t
uint32_t psa_algorithm_t
Encoding of a cryptographic algorithm.
Definition: TARGET_MBED_PSA_SRV/inc/psa/crypto_types.h:98
psa_drv_se_mac_t::p_finish_verify
psa_drv_se_mac_finish_verify_t p_finish_verify
Function that completes a MAC operation with a verify check.
Definition: crypto_se_driver.h:338
psa_drv_se_context_t::transient_data
uintptr_t transient_data
Driver transient data.
Definition: crypto_se_driver.h:114
psa_drv_se_cipher_t::p_finish
psa_drv_se_cipher_finish_t p_finish
Function that completes a cipher operation.
Definition: crypto_se_driver.h:521
psa_drv_se_key_management_t::p_validate_slot_number
psa_drv_se_validate_slot_number_t p_validate_slot_number
Function that checks the validity of a slot for a key.
Definition: crypto_se_driver.h:1124
psa_drv_se_cipher_t::p_abort
psa_drv_se_cipher_abort_t p_abort
Function that aborts a cipher operation.
Definition: crypto_se_driver.h:523
psa_drv_se_cipher_abort_t
psa_status_t(* psa_drv_se_cipher_abort_t)(void *op_context)
A function that aborts a previously started secure element cipher operation.
Definition: crypto_se_driver.h:465
psa_drv_se_key_management_t::p_generate
psa_drv_se_generate_key_t p_generate
Function that performs a generation.
Definition: crypto_se_driver.h:1128
PSA_KEY_CREATION_COPY
During psa_copy_key()
Definition: crypto_se_driver.h:822
psa_drv_se_cipher_t::p_set_iv
psa_drv_se_cipher_set_iv_t p_set_iv
Function that sets a cipher IV (if necessary)
Definition: crypto_se_driver.h:517
psa_drv_se_cipher_t::p_ecb
psa_drv_se_cipher_ecb_t p_ecb
Function that performs ECB mode for a cipher operation (Danger: ECB mode should not be used directly ...
Definition: crypto_se_driver.h:528
psa_drv_se_mac_t::p_mac_verify
psa_drv_se_mac_verify_t p_mac_verify
Function that performs a MAC and verify operation in one call.
Definition: crypto_se_driver.h:347
psa_drv_se_destroy_key_t
psa_status_t(* psa_drv_se_destroy_key_t)(psa_drv_se_context_t *drv_context, void *persistent_data, psa_key_slot_number_t key_slot)
A function that destroys a secure element key and restore the slot to its default state...
Definition: crypto_se_driver.h:1018
psa_drv_se_key_derivation_t::p_setup
psa_drv_se_key_derivation_setup_t p_setup
Function that performs a key derivation setup.
Definition: crypto_se_driver.h:1267
psa_drv_se_asymmetric_verify_t
psa_status_t(* psa_drv_se_asymmetric_verify_t)(psa_drv_se_context_t *drv_context, psa_key_slot_number_t key_slot, psa_algorithm_t alg, const uint8_t *p_hash, size_t hash_length, const uint8_t *p_signature, size_t signature_length)
A function that verifies the signature a hash or short message using an asymmetric public key in a se...
Definition: crypto_se_driver.h:584
psa_drv_se_init_t
psa_status_t(* psa_drv_se_init_t)(psa_drv_se_context_t *drv_context, void *persistent_data, psa_key_location_t location)
A driver initialization function.
Definition: crypto_se_driver.h:135
psa_drv_se_key_derivation_t::p_collateral
psa_drv_se_key_derivation_collateral_t p_collateral
Function that sets key derivation collateral.
Definition: crypto_se_driver.h:1269
psa_drv_se_mac_t
A struct containing all of the function pointers needed to perform secure element MAC operations...
Definition: crypto_se_driver.h:322
psa_drv_se_key_derivation_setup_t
psa_status_t(* psa_drv_se_key_derivation_setup_t)(psa_drv_se_context_t *drv_context, void *op_context, psa_algorithm_t kdf_alg, psa_key_slot_number_t source_key)
A function that Sets up a secure element key derivation operation by specifying the algorithm and the...
Definition: crypto_se_driver.h:1200
psa_drv_se_asymmetric_encrypt_t
psa_status_t(* psa_drv_se_asymmetric_encrypt_t)(psa_drv_se_context_t *drv_context, psa_key_slot_number_t key_slot, psa_algorithm_t alg, const uint8_t *p_input, size_t input_length, const uint8_t *p_salt, size_t salt_length, uint8_t *p_output, size_t output_size, size_t *p_output_length)
A function that encrypts a short message with an asymmetric public key in a secure element...
Definition: crypto_se_driver.h:622
psa_drv_se_t::hal_version
uint32_t hal_version
The version of the driver HAL that this driver implements.
Definition: crypto_se_driver.h:1295
psa_drv_se_asymmetric_t::p_decrypt
psa_drv_se_asymmetric_decrypt_t p_decrypt
Function that performs an asymmetric decrypt operation.
Definition: crypto_se_driver.h:690
psa_drv_se_key_management_t::p_import
psa_drv_se_import_key_t p_import
Function that performs a key import operation.
Definition: crypto_se_driver.h:1126
psa_drv_se_key_derivation_collateral_t
psa_status_t(* psa_drv_se_key_derivation_collateral_t)(void *op_context, uint32_t collateral_id, const uint8_t *p_collateral, size_t collateral_size)
A function that provides collateral (parameters) needed for a secure element key derivation or key ag...
Definition: crypto_se_driver.h:1220
psa_drv_se_mac_t::p_mac
psa_drv_se_mac_generate_t p_mac
Function that performs a MAC operation in one call.
Definition: crypto_se_driver.h:344
psa_drv_se_mac_update_t
psa_status_t(* psa_drv_se_mac_update_t)(void *op_context, const uint8_t *p_input, size_t input_length)
A function that continues a previously started secure element MAC operation.
Definition: crypto_se_driver.h:199
psa_drv_se_key_derivation_t
A struct containing all of the function pointers needed to for secure element key derivation and agre...
Definition: crypto_se_driver.h:1263
PSA_KEY_CREATION_GENERATE
During psa_generate_key()
Definition: crypto_se_driver.h:820
psa_drv_se_aead_t
A struct containing all of the function pointers needed to implement secure element Authenticated Enc...
Definition: crypto_se_driver.h:799
psa_drv_se_mac_t::context_size
size_t context_size
The size in bytes of the hardware-specific secure element MAC context structure.
Definition: crypto_se_driver.h:326
psa_drv_se_aead_t::p_encrypt
psa_drv_se_aead_encrypt_t p_encrypt
Function that performs the AEAD encrypt operation.
Definition: crypto_se_driver.h:801
psa_drv_se_key_derivation_derive_t
psa_status_t(* psa_drv_se_key_derivation_derive_t)(void *op_context, psa_key_slot_number_t dest_key)
A function that performs the final secure element key derivation step and place the generated key mat...
Definition: crypto_se_driver.h:1235
psa_drv_se_mac_setup_t
psa_status_t(* psa_drv_se_mac_setup_t)(psa_drv_se_context_t *drv_context, void *op_context, psa_key_slot_number_t key_slot, psa_algorithm_t algorithm)
A function that starts a secure element MAC operation for a PSA Crypto Driver implementation.
Definition: crypto_se_driver.h:184
crypto_driver_common.h
Definitions for all PSA crypto drivers.
PSA_KEY_CREATION_REGISTER
A key is being registered with mbedtls_psa_register_se_key().
Definition: crypto_se_driver.h:842
psa_drv_se_allocate_key_t
psa_status_t(* psa_drv_se_allocate_key_t)(psa_drv_se_context_t *drv_context, void *persistent_data, const psa_key_attributes_t *attributes, psa_key_creation_method_t method, psa_key_slot_number_t *key_slot)
A function that allocates a slot for a key.
Definition: crypto_se_driver.h:910
psa_drv_se_context_t::persistent_data
const void *const persistent_data
A read-only pointer to the driver&#39;s persistent data.
Definition: crypto_se_driver.h:100
psa_drv_se_cipher_set_iv_t
psa_status_t(* psa_drv_se_cipher_set_iv_t)(void *op_context, const uint8_t *p_iv, size_t iv_length)
A function that sets the initialization vector (if necessary) for an secure element cipher operation...
Definition: crypto_se_driver.h:411
psa_drv_se_asymmetric_t::p_encrypt
psa_drv_se_asymmetric_encrypt_t p_encrypt
Function that performs an asymmetric encrypt operation.
Definition: crypto_se_driver.h:688
psa_status_t
int32_t psa_status_t
Function return status.
Definition: TARGET_MBED_PSA_SRV/inc/psa/crypto_types.h:55
psa_key_creation_method_t
psa_key_creation_method_t
An enumeration indicating how a key is created.
Definition: crypto_se_driver.h:817
psa_drv_se_key_management_t::p_export_public
psa_drv_se_export_key_t p_export_public
Function that performs a public key export operation.
Definition: crypto_se_driver.h:1134
psa_drv_se_aead_encrypt_t
psa_status_t(* psa_drv_se_aead_encrypt_t)(psa_drv_se_context_t *drv_context, psa_key_slot_number_t key_slot, psa_algorithm_t algorithm, const uint8_t *p_nonce, size_t nonce_length, const uint8_t *p_additional_data, size_t additional_data_length, const uint8_t *p_plaintext, size_t plaintext_length, uint8_t *p_ciphertext, size_t ciphertext_size, size_t *p_ciphertext_length)
A function that performs a secure element authenticated encryption operation.
Definition: crypto_se_driver.h:735
psa_drv_se_cipher_t::context_size
size_t context_size
The size in bytes of the hardware-specific secure element cipher context structure.
Definition: crypto_se_driver.h:513
psa_drv_se_cipher_ecb_t
psa_status_t(* psa_drv_se_cipher_ecb_t)(psa_drv_se_context_t *drv_context, psa_key_slot_number_t key_slot, psa_algorithm_t algorithm, psa_encrypt_or_decrypt_t direction, const uint8_t *p_input, size_t input_size, uint8_t *p_output, size_t output_size)
A function that performs the ECB block mode for secure element cipher operations. ...
Definition: crypto_se_driver.h:490
psa_drv_se_key_management_t::p_export
psa_drv_se_export_key_t p_export
Function that performs a key export operation.
Definition: crypto_se_driver.h:1132
psa_drv_se_t::p_init
psa_drv_se_init_t p_init
The driver initialization function.
Definition: crypto_se_driver.h:1317
psa_drv_se_mac_finish_t
psa_status_t(* psa_drv_se_mac_finish_t)(void *op_context, uint8_t *p_mac, size_t mac_size, size_t *p_mac_length)
a function that completes a previously started secure element MAC operation by returning the resultin...
Definition: crypto_se_driver.h:219
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.