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