Mbed TLS v3.6.3
crypto_se_driver.h
Go to the documentation of this file.
1 
18 /*
19  * Copyright The Mbed TLS Contributors
20  * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
21  */
22 #ifndef PSA_CRYPTO_SE_DRIVER_H
23 #define PSA_CRYPTO_SE_DRIVER_H
24 #include "mbedtls/private_access.h"
25 
26 #include "crypto_driver_common.h"
27 
28 #ifdef __cplusplus
29 extern "C" {
30 #endif
31 
44 typedef struct {
89  const void *const MBEDTLS_PRIVATE(persistent_data);
90 
96  const size_t MBEDTLS_PRIVATE(persistent_data_size);
97 
103  uintptr_t MBEDTLS_PRIVATE(transient_data);
105 
125  void *persistent_data,
126  psa_key_location_t location);
127 
128 #if defined(__DOXYGEN_ONLY__) || !defined(MBEDTLS_PSA_CRYPTO_SE_C)
129 /* Mbed TLS with secure element support enabled defines this type in
130  * crypto_types.h because it is also visible to applications through an
131  * implementation-specific extension.
132  * For the PSA Cryptography specification, this type is only visible
133  * via crypto_se_driver.h. */
137 typedef uint64_t psa_key_slot_number_t;
138 #endif /* __DOXYGEN_ONLY__ || !MBEDTLS_PSA_CRYPTO_SE_C */
139 
174  void *op_context,
175  psa_key_slot_number_t key_slot,
176  psa_algorithm_t algorithm);
177 
188 typedef psa_status_t (*psa_drv_se_mac_update_t)(void *op_context,
189  const uint8_t *p_input,
190  size_t input_length);
191 
208 typedef psa_status_t (*psa_drv_se_mac_finish_t)(void *op_context,
209  uint8_t *p_mac,
210  size_t mac_size,
211  size_t *p_mac_length);
212 
229 typedef psa_status_t (*psa_drv_se_mac_finish_verify_t)(void *op_context,
230  const uint8_t *p_mac,
231  size_t mac_length);
232 
239 typedef psa_status_t (*psa_drv_se_mac_abort_t)(void *op_context);
240 
260  const uint8_t *p_input,
261  size_t input_length,
262  psa_key_slot_number_t key_slot,
263  psa_algorithm_t alg,
264  uint8_t *p_mac,
265  size_t mac_size,
266  size_t *p_mac_length);
267 
289  const uint8_t *p_input,
290  size_t input_length,
291  psa_key_slot_number_t key_slot,
292  psa_algorithm_t alg,
293  const uint8_t *p_mac,
294  size_t mac_length);
295 
311 typedef struct {
315  size_t MBEDTLS_PRIVATE(context_size);
380  void *op_context,
381  psa_key_slot_number_t key_slot,
382  psa_algorithm_t algorithm,
383  psa_encrypt_or_decrypt_t direction);
384 
400 typedef psa_status_t (*psa_drv_se_cipher_set_iv_t)(void *op_context,
401  const uint8_t *p_iv,
402  size_t iv_length);
403 
422 typedef psa_status_t (*psa_drv_se_cipher_update_t)(void *op_context,
423  const uint8_t *p_input,
424  size_t input_size,
425  uint8_t *p_output,
426  size_t output_size,
427  size_t *p_output_length);
428 
443 typedef psa_status_t (*psa_drv_se_cipher_finish_t)(void *op_context,
444  uint8_t *p_output,
445  size_t output_size,
446  size_t *p_output_length);
447 
454 typedef psa_status_t (*psa_drv_se_cipher_abort_t)(void *op_context);
455 
480  psa_key_slot_number_t key_slot,
481  psa_algorithm_t algorithm,
482  psa_encrypt_or_decrypt_t direction,
483  const uint8_t *p_input,
484  size_t input_size,
485  uint8_t *p_output,
486  size_t output_size);
487 
498 typedef struct {
502  size_t MBEDTLS_PRIVATE(context_size);
519 
548  psa_key_slot_number_t key_slot,
549  psa_algorithm_t alg,
550  const uint8_t *p_hash,
551  size_t hash_length,
552  uint8_t *p_signature,
553  size_t signature_size,
554  size_t *p_signature_length);
555 
574  psa_key_slot_number_t key_slot,
575  psa_algorithm_t alg,
576  const uint8_t *p_hash,
577  size_t hash_length,
578  const uint8_t *p_signature,
579  size_t signature_length);
580 
612  psa_key_slot_number_t key_slot,
613  psa_algorithm_t alg,
614  const uint8_t *p_input,
615  size_t input_length,
616  const uint8_t *p_salt,
617  size_t salt_length,
618  uint8_t *p_output,
619  size_t output_size,
620  size_t *p_output_length);
621 
652  psa_key_slot_number_t key_slot,
653  psa_algorithm_t alg,
654  const uint8_t *p_input,
655  size_t input_length,
656  const uint8_t *p_salt,
657  size_t salt_length,
658  uint8_t *p_output,
659  size_t output_size,
660  size_t *p_output_length);
661 
671 typedef struct {
681 
725  psa_key_slot_number_t key_slot,
726  psa_algorithm_t algorithm,
727  const uint8_t *p_nonce,
728  size_t nonce_length,
729  const uint8_t *p_additional_data,
730  size_t additional_data_length,
731  const uint8_t *p_plaintext,
732  size_t plaintext_length,
733  uint8_t *p_ciphertext,
734  size_t ciphertext_size,
735  size_t *p_ciphertext_length);
736 
767  psa_key_slot_number_t key_slot,
768  psa_algorithm_t algorithm,
769  const uint8_t *p_nonce,
770  size_t nonce_length,
771  const uint8_t *p_additional_data,
772  size_t additional_data_length,
773  const uint8_t *p_ciphertext,
774  size_t ciphertext_length,
775  uint8_t *p_plaintext,
776  size_t plaintext_size,
777  size_t *p_plaintext_length);
778 
788 typedef struct {
806 typedef enum {
812 #ifndef __DOXYGEN_ONLY__
831 #endif
833 
899  psa_drv_se_context_t *drv_context,
900  void *persistent_data,
901  const psa_key_attributes_t *attributes,
903  psa_key_slot_number_t *key_slot);
904 
945  psa_drv_se_context_t *drv_context,
946  void *persistent_data,
947  const psa_key_attributes_t *attributes,
949  psa_key_slot_number_t key_slot);
950 
981  psa_drv_se_context_t *drv_context,
982  psa_key_slot_number_t key_slot,
983  const psa_key_attributes_t *attributes,
984  const uint8_t *data,
985  size_t data_length,
986  size_t *bits);
987 
1007  psa_drv_se_context_t *drv_context,
1008  void *persistent_data,
1009  psa_key_slot_number_t key_slot);
1010 
1044  uint8_t *p_data,
1045  size_t data_size,
1046  size_t *p_data_length);
1047 
1095  psa_drv_se_context_t *drv_context,
1096  psa_key_slot_number_t key_slot,
1097  const psa_key_attributes_t *attributes,
1098  uint8_t *pubkey, size_t pubkey_size, size_t *pubkey_length);
1099 
1109 typedef struct {
1125 
1190  void *op_context,
1191  psa_algorithm_t kdf_alg,
1192  psa_key_slot_number_t source_key);
1193 
1210  uint32_t collateral_id,
1211  const uint8_t *p_collateral,
1212  size_t collateral_size);
1213 
1225  psa_key_slot_number_t dest_key);
1226 
1239  uint8_t *p_output,
1240  size_t output_size,
1241  size_t *p_output_length);
1242 
1252 typedef struct {
1254  size_t MBEDTLS_PRIVATE(context_size);
1265 
1278 typedef struct {
1284  uint32_t MBEDTLS_PRIVATE(hal_version);
1285 
1294  size_t MBEDTLS_PRIVATE(persistent_data_size);
1295 
1307 
1314 } psa_drv_se_t;
1315 
1318 /* 0.0.0 patchlevel 5 */
1319 #define PSA_DRV_SE_HAL_VERSION 0x00000005
1320 
1374  psa_key_location_t location,
1375  const psa_drv_se_t *methods);
1376 
1379 #ifdef __cplusplus
1380 }
1381 #endif
1382 
1383 #endif /* PSA_CRYPTO_SE_DRIVER_H */
Definitions for all PSA crypto drivers.
psa_encrypt_or_decrypt_t
uint32_t psa_algorithm_t
Encoding of a cryptographic algorithm.
Definition: crypto_types.h:134
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...
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...
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...
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...
int32_t psa_status_t
Function return status.
Definition: crypto_types.h:59
uint32_t psa_key_location_t
Definition: crypto_types.h:260
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.
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)
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.
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.
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.
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...
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.
psa_status_t(* psa_drv_se_cipher_abort_t)(void *op_context)
A function that aborts a previously started secure element cipher operation.
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 a secure element cipher operation.
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.
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.
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.
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.
uint64_t psa_key_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.
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.
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.
psa_key_creation_method_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.
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.
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.
@ PSA_KEY_CREATION_COPY
@ PSA_KEY_CREATION_IMPORT
@ PSA_KEY_CREATION_DERIVE
@ PSA_KEY_CREATION_GENERATE
@ PSA_KEY_CREATION_REGISTER
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.
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.
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...
psa_status_t(* psa_drv_se_mac_abort_t)(void *op_context)
A function that aborts a previous started secure element MAC operation.
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...
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...
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...
psa_status_t psa_register_se_driver(psa_key_location_t location, const psa_drv_se_t *methods)
Macro wrapper for struct's members.
#define MBEDTLS_PRIVATE(member)
A struct containing all of the function pointers needed to implement secure element Authenticated Enc...
A struct containing all of the function pointers needed to implement asymmetric cryptographic operati...
A struct containing all of the function pointers needed to implement cipher operations using secure e...
Driver context structure.
A struct containing all of the function pointers needed to for secure element key derivation and agre...
A struct containing all of the function pointers needed to for secure element key management.
A struct containing all of the function pointers needed to perform secure element MAC operations.