Mbed TLS v2.28.7
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 
25 #include "crypto_driver_common.h"
26 
27 #ifdef __cplusplus
28 extern "C" {
29 #endif
30 
43 typedef struct {
88  const void *const persistent_data;
89 
95  const size_t persistent_data_size;
96 
102  uintptr_t transient_data;
104 
124  void *persistent_data,
125  psa_key_location_t location);
126 
127 #if defined(__DOXYGEN_ONLY__) || !defined(MBEDTLS_PSA_CRYPTO_SE_C)
128 /* Mbed TLS with secure element support enabled defines this type in
129  * crypto_types.h because it is also visible to applications through an
130  * implementation-specific extension.
131  * For the PSA Cryptography specification, this type is only visible
132  * via crypto_se_driver.h. */
136 typedef uint64_t psa_key_slot_number_t;
137 #endif /* __DOXYGEN_ONLY__ || !MBEDTLS_PSA_CRYPTO_SE_C */
138 
173  void *op_context,
174  psa_key_slot_number_t key_slot,
175  psa_algorithm_t algorithm);
176 
187 typedef psa_status_t (*psa_drv_se_mac_update_t)(void *op_context,
188  const uint8_t *p_input,
189  size_t input_length);
190 
207 typedef psa_status_t (*psa_drv_se_mac_finish_t)(void *op_context,
208  uint8_t *p_mac,
209  size_t mac_size,
210  size_t *p_mac_length);
211 
228 typedef psa_status_t (*psa_drv_se_mac_finish_verify_t)(void *op_context,
229  const uint8_t *p_mac,
230  size_t mac_length);
231 
238 typedef psa_status_t (*psa_drv_se_mac_abort_t)(void *op_context);
239 
259  const uint8_t *p_input,
260  size_t input_length,
261  psa_key_slot_number_t key_slot,
262  psa_algorithm_t alg,
263  uint8_t *p_mac,
264  size_t mac_size,
265  size_t *p_mac_length);
266 
288  const uint8_t *p_input,
289  size_t input_length,
290  psa_key_slot_number_t key_slot,
291  psa_algorithm_t alg,
292  const uint8_t *p_mac,
293  size_t mac_length);
294 
310 typedef struct {
314  size_t context_size;
379  void *op_context,
380  psa_key_slot_number_t key_slot,
381  psa_algorithm_t algorithm,
382  psa_encrypt_or_decrypt_t direction);
383 
399 typedef psa_status_t (*psa_drv_se_cipher_set_iv_t)(void *op_context,
400  const uint8_t *p_iv,
401  size_t iv_length);
402 
421 typedef psa_status_t (*psa_drv_se_cipher_update_t)(void *op_context,
422  const uint8_t *p_input,
423  size_t input_size,
424  uint8_t *p_output,
425  size_t output_size,
426  size_t *p_output_length);
427 
442 typedef psa_status_t (*psa_drv_se_cipher_finish_t)(void *op_context,
443  uint8_t *p_output,
444  size_t output_size,
445  size_t *p_output_length);
446 
453 typedef psa_status_t (*psa_drv_se_cipher_abort_t)(void *op_context);
454 
479  psa_key_slot_number_t key_slot,
480  psa_algorithm_t algorithm,
481  psa_encrypt_or_decrypt_t direction,
482  const uint8_t *p_input,
483  size_t input_size,
484  uint8_t *p_output,
485  size_t output_size);
486 
497 typedef struct {
501  size_t context_size;
518 
547  psa_key_slot_number_t key_slot,
548  psa_algorithm_t alg,
549  const uint8_t *p_hash,
550  size_t hash_length,
551  uint8_t *p_signature,
552  size_t signature_size,
553  size_t *p_signature_length);
554 
573  psa_key_slot_number_t key_slot,
574  psa_algorithm_t alg,
575  const uint8_t *p_hash,
576  size_t hash_length,
577  const uint8_t *p_signature,
578  size_t signature_length);
579 
611  psa_key_slot_number_t key_slot,
612  psa_algorithm_t alg,
613  const uint8_t *p_input,
614  size_t input_length,
615  const uint8_t *p_salt,
616  size_t salt_length,
617  uint8_t *p_output,
618  size_t output_size,
619  size_t *p_output_length);
620 
651  psa_key_slot_number_t key_slot,
652  psa_algorithm_t alg,
653  const uint8_t *p_input,
654  size_t input_length,
655  const uint8_t *p_salt,
656  size_t salt_length,
657  uint8_t *p_output,
658  size_t output_size,
659  size_t *p_output_length);
660 
670 typedef struct {
680 
724  psa_key_slot_number_t key_slot,
725  psa_algorithm_t algorithm,
726  const uint8_t *p_nonce,
727  size_t nonce_length,
728  const uint8_t *p_additional_data,
729  size_t additional_data_length,
730  const uint8_t *p_plaintext,
731  size_t plaintext_length,
732  uint8_t *p_ciphertext,
733  size_t ciphertext_size,
734  size_t *p_ciphertext_length);
735 
766  psa_key_slot_number_t key_slot,
767  psa_algorithm_t algorithm,
768  const uint8_t *p_nonce,
769  size_t nonce_length,
770  const uint8_t *p_additional_data,
771  size_t additional_data_length,
772  const uint8_t *p_ciphertext,
773  size_t ciphertext_length,
774  uint8_t *p_plaintext,
775  size_t plaintext_size,
776  size_t *p_plaintext_length);
777 
787 typedef struct {
805 typedef enum {
811 #ifndef __DOXYGEN_ONLY__
812 
830 #endif
832 
898  psa_drv_se_context_t *drv_context,
899  void *persistent_data,
900  const psa_key_attributes_t *attributes,
902  psa_key_slot_number_t *key_slot);
903 
944  psa_drv_se_context_t *drv_context,
945  void *persistent_data,
946  const psa_key_attributes_t *attributes,
948  psa_key_slot_number_t key_slot);
949 
980  psa_drv_se_context_t *drv_context,
981  psa_key_slot_number_t key_slot,
982  const psa_key_attributes_t *attributes,
983  const uint8_t *data,
984  size_t data_length,
985  size_t *bits);
986 
1006  psa_drv_se_context_t *drv_context,
1007  void *persistent_data,
1008  psa_key_slot_number_t key_slot);
1009 
1043  uint8_t *p_data,
1044  size_t data_size,
1045  size_t *p_data_length);
1046 
1094  psa_drv_se_context_t *drv_context,
1095  psa_key_slot_number_t key_slot,
1096  const psa_key_attributes_t *attributes,
1097  uint8_t *pubkey, size_t pubkey_size, size_t *pubkey_length);
1098 
1108 typedef struct {
1124 
1189  void *op_context,
1190  psa_algorithm_t kdf_alg,
1191  psa_key_slot_number_t source_key);
1192 
1209  uint32_t collateral_id,
1210  const uint8_t *p_collateral,
1211  size_t collateral_size);
1212 
1224  psa_key_slot_number_t dest_key);
1225 
1238  uint8_t *p_output,
1239  size_t output_size,
1240  size_t *p_output_length);
1241 
1251 typedef struct {
1264 
1277 typedef struct {
1283  uint32_t hal_version;
1284 
1294 
1306 
1313 } psa_drv_se_t;
1314 
1317 /* 0.0.0 patchlevel 5 */
1318 #define PSA_DRV_SE_HAL_VERSION 0x00000005
1319 
1373  psa_key_location_t location,
1374  const psa_drv_se_t *methods);
1375 
1378 #ifdef __cplusplus
1379 }
1380 #endif
1381 
1382 #endif /* PSA_CRYPTO_SE_DRIVER_H */
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_drv_se_mac_generate_t p_mac
const psa_drv_se_aead_t * aead
psa_drv_se_key_derivation_derive_t p_derive
psa_encrypt_or_decrypt_t
const void *const persistent_data
psa_drv_se_cipher_setup_t p_setup
const psa_drv_se_key_derivation_t * derivation
psa_drv_se_mac_update_t p_update
psa_drv_se_key_derivation_collateral_t p_collateral
psa_drv_se_aead_encrypt_t p_encrypt
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_drv_se_cipher_finish_t p_finish
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_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_drv_se_allocate_key_t p_allocate
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_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...
A struct containing all of the function pointers needed to for secure element key management...
const psa_drv_se_asymmetric_t * asymmetric
psa_drv_se_validate_slot_number_t p_validate_slot_number
psa_drv_se_mac_finish_t p_finish
psa_drv_se_cipher_set_iv_t p_set_iv
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_drv_se_asymmetric_verify_t p_verify
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...
uint32_t psa_key_location_t
Definition: crypto_types.h:251
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_drv_se_mac_setup_t p_setup
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...
const psa_drv_se_cipher_t * cipher
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_drv_se_mac_finish_verify_t p_finish_verify
Driver context structure.
A struct containing all of the function pointers needed to implement cipher operations using secure e...
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.
uint64_t psa_key_slot_number_t
A struct containing all of the function pointers needed to implement asymmetric cryptographic operati...
psa_status_t psa_register_se_driver(psa_key_location_t location, const psa_drv_se_t *methods)
psa_drv_se_import_key_t p_import
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_drv_se_export_key_t p_export
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.
uint32_t psa_algorithm_t
Encoding of a cryptographic algorithm.
Definition: crypto_types.h:125
psa_status_t(* psa_drv_se_cipher_abort_t)(void *op_context)
A function that aborts a previously started secure element cipher operation.
uint32_t hal_version
psa_drv_se_cipher_abort_t p_abort
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_drv_se_cipher_update_t p_update
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_drv_se_aead_decrypt_t p_decrypt
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.
A struct containing all of the function pointers needed to perform secure element MAC operations...
psa_drv_se_mac_verify_t p_mac_verify
psa_drv_se_asymmetric_sign_t p_sign
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...
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_drv_se_init_t p_init
psa_drv_se_asymmetric_encrypt_t p_encrypt
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_drv_se_mac_abort_t p_abort
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.
A struct containing all of the function pointers needed to for secure element key derivation and agre...
const size_t persistent_data_size
A struct containing all of the function pointers needed to implement secure element Authenticated Enc...
const psa_drv_se_key_management_t * key_management
psa_drv_se_destroy_key_t p_destroy
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_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_drv_se_cipher_ecb_t p_ecb
Definitions for all PSA crypto drivers.
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_drv_se_key_derivation_setup_t p_setup
size_t persistent_data_size
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...
int32_t psa_status_t
Function return status.
Definition: crypto_types.h:50
psa_drv_se_asymmetric_decrypt_t p_decrypt
psa_key_creation_method_t
const psa_drv_se_mac_t * mac
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_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_drv_se_export_key_t p_export_public
psa_drv_se_generate_key_t p_generate
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_drv_se_key_derivation_export_t p_export