EIC code displayed by LXR |
|
|
|
|||
File indexing completed on 2025-08-27 09:43:22
0001 /** 0002 * \file psa/crypto_se_driver.h 0003 * \brief PSA external cryptoprocessor driver module 0004 * 0005 * This header declares types and function signatures for cryptography 0006 * drivers that access key material via opaque references. 0007 * This is meant for cryptoprocessors that have a separate key storage from the 0008 * space in which the PSA Crypto implementation runs, typically secure 0009 * elements (SEs). 0010 * 0011 * This file is part of the PSA Crypto Driver HAL (hardware abstraction layer), 0012 * containing functions for driver developers to implement to enable hardware 0013 * to be called in a standardized way by a PSA Cryptography API 0014 * implementation. The functions comprising the driver HAL, which driver 0015 * authors implement, are not intended to be called by application developers. 0016 */ 0017 0018 /* 0019 * Copyright The Mbed TLS Contributors 0020 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 0021 */ 0022 #ifndef PSA_CRYPTO_SE_DRIVER_H 0023 #define PSA_CRYPTO_SE_DRIVER_H 0024 #include "mbedtls/private_access.h" 0025 0026 #include "crypto_driver_common.h" 0027 0028 #ifdef __cplusplus 0029 extern "C" { 0030 #endif 0031 0032 /** \defgroup se_init Secure element driver initialization 0033 */ 0034 /**@{*/ 0035 0036 /** \brief Driver context structure 0037 * 0038 * Driver functions receive a pointer to this structure. 0039 * Each registered driver has one instance of this structure. 0040 * 0041 * Implementations must include the fields specified here and 0042 * may include other fields. 0043 */ 0044 typedef struct { 0045 /** A read-only pointer to the driver's persistent data. 0046 * 0047 * Drivers typically use this persistent data to keep track of 0048 * which slot numbers are available. This is only a guideline: 0049 * drivers may use the persistent data for any purpose, keeping 0050 * in mind the restrictions on when the persistent data is saved 0051 * to storage: the persistent data is only saved after calling 0052 * certain functions that receive a writable pointer to the 0053 * persistent data. 0054 * 0055 * The core allocates a memory buffer for the persistent data. 0056 * The pointer is guaranteed to be suitably aligned for any data type, 0057 * like a pointer returned by `malloc` (but the core can use any 0058 * method to allocate the buffer, not necessarily `malloc`). 0059 * 0060 * The size of this buffer is in the \c persistent_data_size field of 0061 * this structure. 0062 * 0063 * Before the driver is initialized for the first time, the content of 0064 * the persistent data is all-bits-zero. After a driver upgrade, if the 0065 * size of the persistent data has increased, the original data is padded 0066 * on the right with zeros; if the size has decreased, the original data 0067 * is truncated to the new size. 0068 * 0069 * This pointer is to read-only data. Only a few driver functions are 0070 * allowed to modify the persistent data. These functions receive a 0071 * writable pointer. These functions are: 0072 * - psa_drv_se_t::p_init 0073 * - psa_drv_se_key_management_t::p_allocate 0074 * - psa_drv_se_key_management_t::p_destroy 0075 * 0076 * The PSA Cryptography core saves the persistent data from one 0077 * session to the next. It does this before returning from API functions 0078 * that call a driver method that is allowed to modify the persistent 0079 * data, specifically: 0080 * - psa_crypto_init() causes a call to psa_drv_se_t::p_init, and may call 0081 * psa_drv_se_key_management_t::p_destroy to complete an action 0082 * that was interrupted by a power failure. 0083 * - Key creation functions cause a call to 0084 * psa_drv_se_key_management_t::p_allocate, and may cause a call to 0085 * psa_drv_se_key_management_t::p_destroy in case an error occurs. 0086 * - psa_destroy_key() causes a call to 0087 * psa_drv_se_key_management_t::p_destroy. 0088 */ 0089 const void *const MBEDTLS_PRIVATE(persistent_data); 0090 0091 /** The size of \c persistent_data in bytes. 0092 * 0093 * This is always equal to the value of the `persistent_data_size` field 0094 * of the ::psa_drv_se_t structure when the driver is registered. 0095 */ 0096 const size_t MBEDTLS_PRIVATE(persistent_data_size); 0097 0098 /** Driver transient data. 0099 * 0100 * The core initializes this value to 0 and does not read or modify it 0101 * afterwards. The driver may store whatever it wants in this field. 0102 */ 0103 uintptr_t MBEDTLS_PRIVATE(transient_data); 0104 } psa_drv_se_context_t; 0105 0106 /** \brief A driver initialization function. 0107 * 0108 * \param[in,out] drv_context The driver context structure. 0109 * \param[in,out] persistent_data A pointer to the persistent data 0110 * that allows writing. 0111 * \param location The location value for which this driver 0112 * is registered. The driver will be invoked 0113 * for all keys whose lifetime is in this 0114 * location. 0115 * 0116 * \retval #PSA_SUCCESS 0117 * The driver is operational. 0118 * The core will update the persistent data in storage. 0119 * \return 0120 * Any other return value prevents the driver from being used in 0121 * this session. 0122 * The core will NOT update the persistent data in storage. 0123 */ 0124 typedef psa_status_t (*psa_drv_se_init_t)(psa_drv_se_context_t *drv_context, 0125 void *persistent_data, 0126 psa_key_location_t location); 0127 0128 #if defined(__DOXYGEN_ONLY__) || !defined(MBEDTLS_PSA_CRYPTO_SE_C) 0129 /* Mbed TLS with secure element support enabled defines this type in 0130 * crypto_types.h because it is also visible to applications through an 0131 * implementation-specific extension. 0132 * For the PSA Cryptography specification, this type is only visible 0133 * via crypto_se_driver.h. */ 0134 /** An internal designation of a key slot between the core part of the 0135 * PSA Crypto implementation and the driver. The meaning of this value 0136 * is driver-dependent. */ 0137 typedef uint64_t psa_key_slot_number_t; 0138 #endif /* __DOXYGEN_ONLY__ || !MBEDTLS_PSA_CRYPTO_SE_C */ 0139 0140 /**@}*/ 0141 0142 /** \defgroup se_mac Secure Element Message Authentication Codes 0143 * Generation and authentication of Message Authentication Codes (MACs) using 0144 * a secure element can be done either as a single function call (via the 0145 * `psa_drv_se_mac_generate_t` or `psa_drv_se_mac_verify_t` functions), or in 0146 * parts using the following sequence: 0147 * - `psa_drv_se_mac_setup_t` 0148 * - `psa_drv_se_mac_update_t` 0149 * - `psa_drv_se_mac_update_t` 0150 * - ... 0151 * - `psa_drv_se_mac_finish_t` or `psa_drv_se_mac_finish_verify_t` 0152 * 0153 * If a previously started secure element MAC operation needs to be terminated, 0154 * it should be done so by the `psa_drv_se_mac_abort_t`. Failure to do so may 0155 * result in allocated resources not being freed or in other undefined 0156 * behavior. 0157 */ 0158 /**@{*/ 0159 /** \brief A function that starts a secure element MAC operation for a PSA 0160 * Crypto Driver implementation 0161 * 0162 * \param[in,out] drv_context The driver context structure. 0163 * \param[in,out] op_context A structure that will contain the 0164 * hardware-specific MAC context 0165 * \param[in] key_slot The slot of the key to be used for the 0166 * operation 0167 * \param[in] algorithm The algorithm to be used to underly the MAC 0168 * operation 0169 * 0170 * \retval #PSA_SUCCESS 0171 * Success. 0172 */ 0173 typedef psa_status_t (*psa_drv_se_mac_setup_t)(psa_drv_se_context_t *drv_context, 0174 void *op_context, 0175 psa_key_slot_number_t key_slot, 0176 psa_algorithm_t algorithm); 0177 0178 /** \brief A function that continues a previously started secure element MAC 0179 * operation 0180 * 0181 * \param[in,out] op_context A hardware-specific structure for the 0182 * previously-established MAC operation to be 0183 * updated 0184 * \param[in] p_input A buffer containing the message to be appended 0185 * to the MAC operation 0186 * \param[in] input_length The size in bytes of the input message buffer 0187 */ 0188 typedef psa_status_t (*psa_drv_se_mac_update_t)(void *op_context, 0189 const uint8_t *p_input, 0190 size_t input_length); 0191 0192 /** \brief a function that completes a previously started secure element MAC 0193 * operation by returning the resulting MAC. 0194 * 0195 * \param[in,out] op_context A hardware-specific structure for the 0196 * previously started MAC operation to be 0197 * finished 0198 * \param[out] p_mac A buffer where the generated MAC will be 0199 * placed 0200 * \param[in] mac_size The size in bytes of the buffer that has been 0201 * allocated for the `output` buffer 0202 * \param[out] p_mac_length After completion, will contain the number of 0203 * bytes placed in the `p_mac` buffer 0204 * 0205 * \retval #PSA_SUCCESS 0206 * Success. 0207 */ 0208 typedef psa_status_t (*psa_drv_se_mac_finish_t)(void *op_context, 0209 uint8_t *p_mac, 0210 size_t mac_size, 0211 size_t *p_mac_length); 0212 0213 /** \brief A function that completes a previously started secure element MAC 0214 * operation by comparing the resulting MAC against a provided value 0215 * 0216 * \param[in,out] op_context A hardware-specific structure for the previously 0217 * started MAC operation to be finished 0218 * \param[in] p_mac The MAC value against which the resulting MAC 0219 * will be compared against 0220 * \param[in] mac_length The size in bytes of the value stored in `p_mac` 0221 * 0222 * \retval #PSA_SUCCESS 0223 * The operation completed successfully and the MACs matched each 0224 * other 0225 * \retval #PSA_ERROR_INVALID_SIGNATURE 0226 * The operation completed successfully, but the calculated MAC did 0227 * not match the provided MAC 0228 */ 0229 typedef psa_status_t (*psa_drv_se_mac_finish_verify_t)(void *op_context, 0230 const uint8_t *p_mac, 0231 size_t mac_length); 0232 0233 /** \brief A function that aborts a previous started secure element MAC 0234 * operation 0235 * 0236 * \param[in,out] op_context A hardware-specific structure for the previously 0237 * started MAC operation to be aborted 0238 */ 0239 typedef psa_status_t (*psa_drv_se_mac_abort_t)(void *op_context); 0240 0241 /** \brief A function that performs a secure element MAC operation in one 0242 * command and returns the calculated MAC 0243 * 0244 * \param[in,out] drv_context The driver context structure. 0245 * \param[in] p_input A buffer containing the message to be MACed 0246 * \param[in] input_length The size in bytes of `p_input` 0247 * \param[in] key_slot The slot of the key to be used 0248 * \param[in] alg The algorithm to be used to underlie the MAC 0249 * operation 0250 * \param[out] p_mac A buffer where the generated MAC will be 0251 * placed 0252 * \param[in] mac_size The size in bytes of the `p_mac` buffer 0253 * \param[out] p_mac_length After completion, will contain the number of 0254 * bytes placed in the `output` buffer 0255 * 0256 * \retval #PSA_SUCCESS 0257 * Success. 0258 */ 0259 typedef psa_status_t (*psa_drv_se_mac_generate_t)(psa_drv_se_context_t *drv_context, 0260 const uint8_t *p_input, 0261 size_t input_length, 0262 psa_key_slot_number_t key_slot, 0263 psa_algorithm_t alg, 0264 uint8_t *p_mac, 0265 size_t mac_size, 0266 size_t *p_mac_length); 0267 0268 /** \brief A function that performs a secure element MAC operation in one 0269 * command and compares the resulting MAC against a provided value 0270 * 0271 * \param[in,out] drv_context The driver context structure. 0272 * \param[in] p_input A buffer containing the message to be MACed 0273 * \param[in] input_length The size in bytes of `input` 0274 * \param[in] key_slot The slot of the key to be used 0275 * \param[in] alg The algorithm to be used to underlie the MAC 0276 * operation 0277 * \param[in] p_mac The MAC value against which the resulting MAC will 0278 * be compared against 0279 * \param[in] mac_length The size in bytes of `mac` 0280 * 0281 * \retval #PSA_SUCCESS 0282 * The operation completed successfully and the MACs matched each 0283 * other 0284 * \retval #PSA_ERROR_INVALID_SIGNATURE 0285 * The operation completed successfully, but the calculated MAC did 0286 * not match the provided MAC 0287 */ 0288 typedef psa_status_t (*psa_drv_se_mac_verify_t)(psa_drv_se_context_t *drv_context, 0289 const uint8_t *p_input, 0290 size_t input_length, 0291 psa_key_slot_number_t key_slot, 0292 psa_algorithm_t alg, 0293 const uint8_t *p_mac, 0294 size_t mac_length); 0295 0296 /** \brief A struct containing all of the function pointers needed to 0297 * perform secure element MAC operations 0298 * 0299 * PSA Crypto API implementations should populate the table as appropriate 0300 * upon startup. 0301 * 0302 * If one of the functions is not implemented (such as 0303 * `psa_drv_se_mac_generate_t`), it should be set to NULL. 0304 * 0305 * Driver implementers should ensure that they implement all of the functions 0306 * that make sense for their hardware, and that they provide a full solution 0307 * (for example, if they support `p_setup`, they should also support 0308 * `p_update` and at least one of `p_finish` or `p_finish_verify`). 0309 * 0310 */ 0311 typedef struct { 0312 /**The size in bytes of the hardware-specific secure element MAC context 0313 * structure 0314 */ 0315 size_t MBEDTLS_PRIVATE(context_size); 0316 /** Function that performs a MAC setup operation 0317 */ 0318 psa_drv_se_mac_setup_t MBEDTLS_PRIVATE(p_setup); 0319 /** Function that performs a MAC update operation 0320 */ 0321 psa_drv_se_mac_update_t MBEDTLS_PRIVATE(p_update); 0322 /** Function that completes a MAC operation 0323 */ 0324 psa_drv_se_mac_finish_t MBEDTLS_PRIVATE(p_finish); 0325 /** Function that completes a MAC operation with a verify check 0326 */ 0327 psa_drv_se_mac_finish_verify_t MBEDTLS_PRIVATE(p_finish_verify); 0328 /** Function that aborts a previously started MAC operation 0329 */ 0330 psa_drv_se_mac_abort_t MBEDTLS_PRIVATE(p_abort); 0331 /** Function that performs a MAC operation in one call 0332 */ 0333 psa_drv_se_mac_generate_t MBEDTLS_PRIVATE(p_mac); 0334 /** Function that performs a MAC and verify operation in one call 0335 */ 0336 psa_drv_se_mac_verify_t MBEDTLS_PRIVATE(p_mac_verify); 0337 } psa_drv_se_mac_t; 0338 /**@}*/ 0339 0340 /** \defgroup se_cipher Secure Element Symmetric Ciphers 0341 * 0342 * Encryption and Decryption using secure element keys in block modes other 0343 * than ECB must be done in multiple parts, using the following flow: 0344 * - `psa_drv_se_cipher_setup_t` 0345 * - `psa_drv_se_cipher_set_iv_t` (optional depending upon block mode) 0346 * - `psa_drv_se_cipher_update_t` 0347 * - `psa_drv_se_cipher_update_t` 0348 * - ... 0349 * - `psa_drv_se_cipher_finish_t` 0350 * 0351 * If a previously started secure element Cipher operation needs to be 0352 * terminated, it should be done so by the `psa_drv_se_cipher_abort_t`. Failure 0353 * to do so may result in allocated resources not being freed or in other 0354 * undefined behavior. 0355 * 0356 * In situations where a PSA Cryptographic API implementation is using a block 0357 * mode not-supported by the underlying hardware or driver, it can construct 0358 * the block mode itself, while calling the `psa_drv_se_cipher_ecb_t` function 0359 * for the cipher operations. 0360 */ 0361 /**@{*/ 0362 0363 /** \brief A function that provides the cipher setup function for a 0364 * secure element driver 0365 * 0366 * \param[in,out] drv_context The driver context structure. 0367 * \param[in,out] op_context A structure that will contain the 0368 * hardware-specific cipher context. 0369 * \param[in] key_slot The slot of the key to be used for the 0370 * operation 0371 * \param[in] algorithm The algorithm to be used in the cipher 0372 * operation 0373 * \param[in] direction Indicates whether the operation is an encrypt 0374 * or decrypt 0375 * 0376 * \retval #PSA_SUCCESS \emptydescription 0377 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 0378 */ 0379 typedef psa_status_t (*psa_drv_se_cipher_setup_t)(psa_drv_se_context_t *drv_context, 0380 void *op_context, 0381 psa_key_slot_number_t key_slot, 0382 psa_algorithm_t algorithm, 0383 psa_encrypt_or_decrypt_t direction); 0384 0385 /** \brief A function that sets the initialization vector (if 0386 * necessary) for a secure element cipher operation 0387 * 0388 * Rationale: The `psa_se_cipher_*` operation in the PSA Cryptographic API has 0389 * two IV functions: one to set the IV, and one to generate it internally. The 0390 * generate function is not necessary for the drivers to implement as the PSA 0391 * Crypto implementation can do the generation using its RNG features. 0392 * 0393 * \param[in,out] op_context A structure that contains the previously set up 0394 * hardware-specific cipher context 0395 * \param[in] p_iv A buffer containing the initialization vector 0396 * \param[in] iv_length The size (in bytes) of the `p_iv` buffer 0397 * 0398 * \retval #PSA_SUCCESS \emptydescription 0399 */ 0400 typedef psa_status_t (*psa_drv_se_cipher_set_iv_t)(void *op_context, 0401 const uint8_t *p_iv, 0402 size_t iv_length); 0403 0404 /** \brief A function that continues a previously started secure element cipher 0405 * operation 0406 * 0407 * \param[in,out] op_context A hardware-specific structure for the 0408 * previously started cipher operation 0409 * \param[in] p_input A buffer containing the data to be 0410 * encrypted/decrypted 0411 * \param[in] input_size The size in bytes of the buffer pointed to 0412 * by `p_input` 0413 * \param[out] p_output The caller-allocated buffer where the 0414 * output will be placed 0415 * \param[in] output_size The allocated size in bytes of the 0416 * `p_output` buffer 0417 * \param[out] p_output_length After completion, will contain the number 0418 * of bytes placed in the `p_output` buffer 0419 * 0420 * \retval #PSA_SUCCESS \emptydescription 0421 */ 0422 typedef psa_status_t (*psa_drv_se_cipher_update_t)(void *op_context, 0423 const uint8_t *p_input, 0424 size_t input_size, 0425 uint8_t *p_output, 0426 size_t output_size, 0427 size_t *p_output_length); 0428 0429 /** \brief A function that completes a previously started secure element cipher 0430 * operation 0431 * 0432 * \param[in,out] op_context A hardware-specific structure for the 0433 * previously started cipher operation 0434 * \param[out] p_output The caller-allocated buffer where the output 0435 * will be placed 0436 * \param[in] output_size The allocated size in bytes of the `p_output` 0437 * buffer 0438 * \param[out] p_output_length After completion, will contain the number of 0439 * bytes placed in the `p_output` buffer 0440 * 0441 * \retval #PSA_SUCCESS \emptydescription 0442 */ 0443 typedef psa_status_t (*psa_drv_se_cipher_finish_t)(void *op_context, 0444 uint8_t *p_output, 0445 size_t output_size, 0446 size_t *p_output_length); 0447 0448 /** \brief A function that aborts a previously started secure element cipher 0449 * operation 0450 * 0451 * \param[in,out] op_context A hardware-specific structure for the 0452 * previously started cipher operation 0453 */ 0454 typedef psa_status_t (*psa_drv_se_cipher_abort_t)(void *op_context); 0455 0456 /** \brief A function that performs the ECB block mode for secure element 0457 * cipher operations 0458 * 0459 * Note: this function should only be used with implementations that do not 0460 * provide a needed higher-level operation. 0461 * 0462 * \param[in,out] drv_context The driver context structure. 0463 * \param[in] key_slot The slot of the key to be used for the operation 0464 * \param[in] algorithm The algorithm to be used in the cipher operation 0465 * \param[in] direction Indicates whether the operation is an encrypt or 0466 * decrypt 0467 * \param[in] p_input A buffer containing the data to be 0468 * encrypted/decrypted 0469 * \param[in] input_size The size in bytes of the buffer pointed to by 0470 * `p_input` 0471 * \param[out] p_output The caller-allocated buffer where the output 0472 * will be placed 0473 * \param[in] output_size The allocated size in bytes of the `p_output` 0474 * buffer 0475 * 0476 * \retval #PSA_SUCCESS \emptydescription 0477 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 0478 */ 0479 typedef psa_status_t (*psa_drv_se_cipher_ecb_t)(psa_drv_se_context_t *drv_context, 0480 psa_key_slot_number_t key_slot, 0481 psa_algorithm_t algorithm, 0482 psa_encrypt_or_decrypt_t direction, 0483 const uint8_t *p_input, 0484 size_t input_size, 0485 uint8_t *p_output, 0486 size_t output_size); 0487 0488 /** 0489 * \brief A struct containing all of the function pointers needed to implement 0490 * cipher operations using secure elements. 0491 * 0492 * PSA Crypto API implementations should populate instances of the table as 0493 * appropriate upon startup or at build time. 0494 * 0495 * If one of the functions is not implemented (such as 0496 * `psa_drv_se_cipher_ecb_t`), it should be set to NULL. 0497 */ 0498 typedef struct { 0499 /** The size in bytes of the hardware-specific secure element cipher 0500 * context structure 0501 */ 0502 size_t MBEDTLS_PRIVATE(context_size); 0503 /** Function that performs a cipher setup operation */ 0504 psa_drv_se_cipher_setup_t MBEDTLS_PRIVATE(p_setup); 0505 /** Function that sets a cipher IV (if necessary) */ 0506 psa_drv_se_cipher_set_iv_t MBEDTLS_PRIVATE(p_set_iv); 0507 /** Function that performs a cipher update operation */ 0508 psa_drv_se_cipher_update_t MBEDTLS_PRIVATE(p_update); 0509 /** Function that completes a cipher operation */ 0510 psa_drv_se_cipher_finish_t MBEDTLS_PRIVATE(p_finish); 0511 /** Function that aborts a cipher operation */ 0512 psa_drv_se_cipher_abort_t MBEDTLS_PRIVATE(p_abort); 0513 /** Function that performs ECB mode for a cipher operation 0514 * (Danger: ECB mode should not be used directly by clients of the PSA 0515 * Crypto Client API) 0516 */ 0517 psa_drv_se_cipher_ecb_t MBEDTLS_PRIVATE(p_ecb); 0518 } psa_drv_se_cipher_t; 0519 0520 /**@}*/ 0521 0522 /** \defgroup se_asymmetric Secure Element Asymmetric Cryptography 0523 * 0524 * Since the amount of data that can (or should) be encrypted or signed using 0525 * asymmetric keys is limited by the key size, asymmetric key operations using 0526 * keys in a secure element must be done in single function calls. 0527 */ 0528 /**@{*/ 0529 0530 /** 0531 * \brief A function that signs a hash or short message with a private key in 0532 * a secure element 0533 * 0534 * \param[in,out] drv_context The driver context structure. 0535 * \param[in] key_slot Key slot of an asymmetric key pair 0536 * \param[in] alg A signature algorithm that is compatible 0537 * with the type of `key` 0538 * \param[in] p_hash The hash to sign 0539 * \param[in] hash_length Size of the `p_hash` buffer in bytes 0540 * \param[out] p_signature Buffer where the signature is to be written 0541 * \param[in] signature_size Size of the `p_signature` buffer in bytes 0542 * \param[out] p_signature_length On success, the number of bytes 0543 * that make up the returned signature value 0544 * 0545 * \retval #PSA_SUCCESS \emptydescription 0546 */ 0547 typedef psa_status_t (*psa_drv_se_asymmetric_sign_t)(psa_drv_se_context_t *drv_context, 0548 psa_key_slot_number_t key_slot, 0549 psa_algorithm_t alg, 0550 const uint8_t *p_hash, 0551 size_t hash_length, 0552 uint8_t *p_signature, 0553 size_t signature_size, 0554 size_t *p_signature_length); 0555 0556 /** 0557 * \brief A function that verifies the signature a hash or short message using 0558 * an asymmetric public key in a secure element 0559 * 0560 * \param[in,out] drv_context The driver context structure. 0561 * \param[in] key_slot Key slot of a public key or an asymmetric key 0562 * pair 0563 * \param[in] alg A signature algorithm that is compatible with 0564 * the type of `key` 0565 * \param[in] p_hash The hash whose signature is to be verified 0566 * \param[in] hash_length Size of the `p_hash` buffer in bytes 0567 * \param[in] p_signature Buffer containing the signature to verify 0568 * \param[in] signature_length Size of the `p_signature` buffer in bytes 0569 * 0570 * \retval #PSA_SUCCESS 0571 * The signature is valid. 0572 */ 0573 typedef psa_status_t (*psa_drv_se_asymmetric_verify_t)(psa_drv_se_context_t *drv_context, 0574 psa_key_slot_number_t key_slot, 0575 psa_algorithm_t alg, 0576 const uint8_t *p_hash, 0577 size_t hash_length, 0578 const uint8_t *p_signature, 0579 size_t signature_length); 0580 0581 /** 0582 * \brief A function that encrypts a short message with an asymmetric public 0583 * key in a secure element 0584 * 0585 * \param[in,out] drv_context The driver context structure. 0586 * \param[in] key_slot Key slot of a public key or an asymmetric key 0587 * pair 0588 * \param[in] alg An asymmetric encryption algorithm that is 0589 * compatible with the type of `key` 0590 * \param[in] p_input The message to encrypt 0591 * \param[in] input_length Size of the `p_input` buffer in bytes 0592 * \param[in] p_salt A salt or label, if supported by the 0593 * encryption algorithm 0594 * If the algorithm does not support a 0595 * salt, pass `NULL`. 0596 * If the algorithm supports an optional 0597 * salt and you do not want to pass a salt, 0598 * pass `NULL`. 0599 * For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is 0600 * supported. 0601 * \param[in] salt_length Size of the `p_salt` buffer in bytes 0602 * If `p_salt` is `NULL`, pass 0. 0603 * \param[out] p_output Buffer where the encrypted message is to 0604 * be written 0605 * \param[in] output_size Size of the `p_output` buffer in bytes 0606 * \param[out] p_output_length On success, the number of bytes that make up 0607 * the returned output 0608 * 0609 * \retval #PSA_SUCCESS \emptydescription 0610 */ 0611 typedef psa_status_t (*psa_drv_se_asymmetric_encrypt_t)(psa_drv_se_context_t *drv_context, 0612 psa_key_slot_number_t key_slot, 0613 psa_algorithm_t alg, 0614 const uint8_t *p_input, 0615 size_t input_length, 0616 const uint8_t *p_salt, 0617 size_t salt_length, 0618 uint8_t *p_output, 0619 size_t output_size, 0620 size_t *p_output_length); 0621 0622 /** 0623 * \brief A function that decrypts a short message with an asymmetric private 0624 * key in a secure element. 0625 * 0626 * \param[in,out] drv_context The driver context structure. 0627 * \param[in] key_slot Key slot of an asymmetric key pair 0628 * \param[in] alg An asymmetric encryption algorithm that is 0629 * compatible with the type of `key` 0630 * \param[in] p_input The message to decrypt 0631 * \param[in] input_length Size of the `p_input` buffer in bytes 0632 * \param[in] p_salt A salt or label, if supported by the 0633 * encryption algorithm 0634 * If the algorithm does not support a 0635 * salt, pass `NULL`. 0636 * If the algorithm supports an optional 0637 * salt and you do not want to pass a salt, 0638 * pass `NULL`. 0639 * For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is 0640 * supported. 0641 * \param[in] salt_length Size of the `p_salt` buffer in bytes 0642 * If `p_salt` is `NULL`, pass 0. 0643 * \param[out] p_output Buffer where the decrypted message is to 0644 * be written 0645 * \param[in] output_size Size of the `p_output` buffer in bytes 0646 * \param[out] p_output_length On success, the number of bytes 0647 * that make up the returned output 0648 * 0649 * \retval #PSA_SUCCESS \emptydescription 0650 */ 0651 typedef psa_status_t (*psa_drv_se_asymmetric_decrypt_t)(psa_drv_se_context_t *drv_context, 0652 psa_key_slot_number_t key_slot, 0653 psa_algorithm_t alg, 0654 const uint8_t *p_input, 0655 size_t input_length, 0656 const uint8_t *p_salt, 0657 size_t salt_length, 0658 uint8_t *p_output, 0659 size_t output_size, 0660 size_t *p_output_length); 0661 0662 /** 0663 * \brief A struct containing all of the function pointers needed to implement 0664 * asymmetric cryptographic operations using secure elements. 0665 * 0666 * PSA Crypto API implementations should populate instances of the table as 0667 * appropriate upon startup or at build time. 0668 * 0669 * If one of the functions is not implemented, it should be set to NULL. 0670 */ 0671 typedef struct { 0672 /** Function that performs an asymmetric sign operation */ 0673 psa_drv_se_asymmetric_sign_t MBEDTLS_PRIVATE(p_sign); 0674 /** Function that performs an asymmetric verify operation */ 0675 psa_drv_se_asymmetric_verify_t MBEDTLS_PRIVATE(p_verify); 0676 /** Function that performs an asymmetric encrypt operation */ 0677 psa_drv_se_asymmetric_encrypt_t MBEDTLS_PRIVATE(p_encrypt); 0678 /** Function that performs an asymmetric decrypt operation */ 0679 psa_drv_se_asymmetric_decrypt_t MBEDTLS_PRIVATE(p_decrypt); 0680 } psa_drv_se_asymmetric_t; 0681 0682 /**@}*/ 0683 0684 /** \defgroup se_aead Secure Element Authenticated Encryption with Additional Data 0685 * Authenticated Encryption with Additional Data (AEAD) operations with secure 0686 * elements must be done in one function call. While this creates a burden for 0687 * implementers as there must be sufficient space in memory for the entire 0688 * message, it prevents decrypted data from being made available before the 0689 * authentication operation is complete and the data is known to be authentic. 0690 */ 0691 /**@{*/ 0692 0693 /** \brief A function that performs a secure element authenticated encryption 0694 * operation 0695 * 0696 * \param[in,out] drv_context The driver context structure. 0697 * \param[in] key_slot Slot containing the key to use. 0698 * \param[in] algorithm The AEAD algorithm to compute 0699 * (\c PSA_ALG_XXX value such that 0700 * #PSA_ALG_IS_AEAD(`alg`) is true) 0701 * \param[in] p_nonce Nonce or IV to use 0702 * \param[in] nonce_length Size of the `p_nonce` buffer in bytes 0703 * \param[in] p_additional_data Additional data that will be 0704 * authenticated but not encrypted 0705 * \param[in] additional_data_length Size of `p_additional_data` in bytes 0706 * \param[in] p_plaintext Data that will be authenticated and 0707 * encrypted 0708 * \param[in] plaintext_length Size of `p_plaintext` in bytes 0709 * \param[out] p_ciphertext Output buffer for the authenticated and 0710 * encrypted data. The additional data is 0711 * not part of this output. For algorithms 0712 * where the encrypted data and the 0713 * authentication tag are defined as 0714 * separate outputs, the authentication 0715 * tag is appended to the encrypted data. 0716 * \param[in] ciphertext_size Size of the `p_ciphertext` buffer in 0717 * bytes 0718 * \param[out] p_ciphertext_length On success, the size of the output in 0719 * the `p_ciphertext` buffer 0720 * 0721 * \retval #PSA_SUCCESS 0722 * Success. 0723 */ 0724 typedef psa_status_t (*psa_drv_se_aead_encrypt_t)(psa_drv_se_context_t *drv_context, 0725 psa_key_slot_number_t key_slot, 0726 psa_algorithm_t algorithm, 0727 const uint8_t *p_nonce, 0728 size_t nonce_length, 0729 const uint8_t *p_additional_data, 0730 size_t additional_data_length, 0731 const uint8_t *p_plaintext, 0732 size_t plaintext_length, 0733 uint8_t *p_ciphertext, 0734 size_t ciphertext_size, 0735 size_t *p_ciphertext_length); 0736 0737 /** A function that performs a secure element authenticated decryption operation 0738 * 0739 * \param[in,out] drv_context The driver context structure. 0740 * \param[in] key_slot Slot containing the key to use 0741 * \param[in] algorithm The AEAD algorithm to compute 0742 * (\c PSA_ALG_XXX value such that 0743 * #PSA_ALG_IS_AEAD(`alg`) is true) 0744 * \param[in] p_nonce Nonce or IV to use 0745 * \param[in] nonce_length Size of the `p_nonce` buffer in bytes 0746 * \param[in] p_additional_data Additional data that has been 0747 * authenticated but not encrypted 0748 * \param[in] additional_data_length Size of `p_additional_data` in bytes 0749 * \param[in] p_ciphertext Data that has been authenticated and 0750 * encrypted. 0751 * For algorithms where the encrypted data 0752 * and the authentication tag are defined 0753 * as separate inputs, the buffer must 0754 * contain the encrypted data followed by 0755 * the authentication tag. 0756 * \param[in] ciphertext_length Size of `p_ciphertext` in bytes 0757 * \param[out] p_plaintext Output buffer for the decrypted data 0758 * \param[in] plaintext_size Size of the `p_plaintext` buffer in 0759 * bytes 0760 * \param[out] p_plaintext_length On success, the size of the output in 0761 * the `p_plaintext` buffer 0762 * 0763 * \retval #PSA_SUCCESS 0764 * Success. 0765 */ 0766 typedef psa_status_t (*psa_drv_se_aead_decrypt_t)(psa_drv_se_context_t *drv_context, 0767 psa_key_slot_number_t key_slot, 0768 psa_algorithm_t algorithm, 0769 const uint8_t *p_nonce, 0770 size_t nonce_length, 0771 const uint8_t *p_additional_data, 0772 size_t additional_data_length, 0773 const uint8_t *p_ciphertext, 0774 size_t ciphertext_length, 0775 uint8_t *p_plaintext, 0776 size_t plaintext_size, 0777 size_t *p_plaintext_length); 0778 0779 /** 0780 * \brief A struct containing all of the function pointers needed to implement 0781 * secure element Authenticated Encryption with Additional Data operations 0782 * 0783 * PSA Crypto API implementations should populate instances of the table as 0784 * appropriate upon startup. 0785 * 0786 * If one of the functions is not implemented, it should be set to NULL. 0787 */ 0788 typedef struct { 0789 /** Function that performs the AEAD encrypt operation */ 0790 psa_drv_se_aead_encrypt_t MBEDTLS_PRIVATE(p_encrypt); 0791 /** Function that performs the AEAD decrypt operation */ 0792 psa_drv_se_aead_decrypt_t MBEDTLS_PRIVATE(p_decrypt); 0793 } psa_drv_se_aead_t; 0794 /**@}*/ 0795 0796 /** \defgroup se_key_management Secure Element Key Management 0797 * Currently, key management is limited to importing keys in the clear, 0798 * destroying keys, and exporting keys in the clear. 0799 * Whether a key may be exported is determined by the key policies in place 0800 * on the key slot. 0801 */ 0802 /**@{*/ 0803 0804 /** An enumeration indicating how a key is created. 0805 */ 0806 typedef enum { 0807 PSA_KEY_CREATION_IMPORT, /**< During psa_import_key() */ 0808 PSA_KEY_CREATION_GENERATE, /**< During psa_generate_key() */ 0809 PSA_KEY_CREATION_DERIVE, /**< During psa_key_derivation_output_key() */ 0810 PSA_KEY_CREATION_COPY, /**< During psa_copy_key() */ 0811 0812 #ifndef __DOXYGEN_ONLY__ 0813 /** A key is being registered with mbedtls_psa_register_se_key(). 0814 * 0815 * The core only passes this value to 0816 * psa_drv_se_key_management_t::p_validate_slot_number, not to 0817 * psa_drv_se_key_management_t::p_allocate. The call to 0818 * `p_validate_slot_number` is not followed by any other call to the 0819 * driver: the key is considered successfully registered if the call to 0820 * `p_validate_slot_number` succeeds, or if `p_validate_slot_number` is 0821 * null. 0822 * 0823 * With this creation method, the driver must return #PSA_SUCCESS if 0824 * the given attributes are compatible with the existing key in the slot, 0825 * and #PSA_ERROR_DOES_NOT_EXIST if the driver can determine that there 0826 * is no key with the specified slot number. 0827 * 0828 * This is an Mbed TLS extension. 0829 */ 0830 PSA_KEY_CREATION_REGISTER, 0831 #endif 0832 } psa_key_creation_method_t; 0833 0834 /** \brief A function that allocates a slot for a key. 0835 * 0836 * To create a key in a specific slot in a secure element, the core 0837 * first calls this function to determine a valid slot number, 0838 * then calls a function to create the key material in that slot. 0839 * In nominal conditions (that is, if no error occurs), 0840 * the effect of a call to a key creation function in the PSA Cryptography 0841 * API with a lifetime that places the key in a secure element is the 0842 * following: 0843 * -# The core calls psa_drv_se_key_management_t::p_allocate 0844 * (or in some implementations 0845 * psa_drv_se_key_management_t::p_validate_slot_number). The driver 0846 * selects (or validates) a suitable slot number given the key attributes 0847 * and the state of the secure element. 0848 * -# The core calls a key creation function in the driver. 0849 * 0850 * The key creation functions in the PSA Cryptography API are: 0851 * - psa_import_key(), which causes 0852 * a call to `p_allocate` with \p method = #PSA_KEY_CREATION_IMPORT 0853 * then a call to psa_drv_se_key_management_t::p_import. 0854 * - psa_generate_key(), which causes 0855 * a call to `p_allocate` with \p method = #PSA_KEY_CREATION_GENERATE 0856 * then a call to psa_drv_se_key_management_t::p_import. 0857 * - psa_key_derivation_output_key(), which causes 0858 * a call to `p_allocate` with \p method = #PSA_KEY_CREATION_DERIVE 0859 * then a call to psa_drv_se_key_derivation_t::p_derive. 0860 * - psa_copy_key(), which causes 0861 * a call to `p_allocate` with \p method = #PSA_KEY_CREATION_COPY 0862 * then a call to psa_drv_se_key_management_t::p_export. 0863 * 0864 * In case of errors, other behaviors are possible. 0865 * - If the PSA Cryptography subsystem dies after the first step, 0866 * for example because the device has lost power abruptly, 0867 * the second step may never happen, or may happen after a reset 0868 * and re-initialization. Alternatively, after a reset and 0869 * re-initialization, the core may call 0870 * psa_drv_se_key_management_t::p_destroy on the slot number that 0871 * was allocated (or validated) instead of calling a key creation function. 0872 * - If an error occurs, the core may call 0873 * psa_drv_se_key_management_t::p_destroy on the slot number that 0874 * was allocated (or validated) instead of calling a key creation function. 0875 * 0876 * Errors and system resets also have an impact on the driver's persistent 0877 * data. If a reset happens before the overall key creation process is 0878 * completed (before or after the second step above), it is unspecified 0879 * whether the persistent data after the reset is identical to what it 0880 * was before or after the call to `p_allocate` (or `p_validate_slot_number`). 0881 * 0882 * \param[in,out] drv_context The driver context structure. 0883 * \param[in,out] persistent_data A pointer to the persistent data 0884 * that allows writing. 0885 * \param[in] attributes Attributes of the key. 0886 * \param method The way in which the key is being created. 0887 * \param[out] key_slot Slot where the key will be stored. 0888 * This must be a valid slot for a key of the 0889 * chosen type. It must be unoccupied. 0890 * 0891 * \retval #PSA_SUCCESS 0892 * Success. 0893 * The core will record \c *key_slot as the key slot where the key 0894 * is stored and will update the persistent data in storage. 0895 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 0896 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE \emptydescription 0897 */ 0898 typedef psa_status_t (*psa_drv_se_allocate_key_t)( 0899 psa_drv_se_context_t *drv_context, 0900 void *persistent_data, 0901 const psa_key_attributes_t *attributes, 0902 psa_key_creation_method_t method, 0903 psa_key_slot_number_t *key_slot); 0904 0905 /** \brief A function that determines whether a slot number is valid 0906 * for a key. 0907 * 0908 * To create a key in a specific slot in a secure element, the core 0909 * first calls this function to validate the choice of slot number, 0910 * then calls a function to create the key material in that slot. 0911 * See the documentation of #psa_drv_se_allocate_key_t for more details. 0912 * 0913 * As of the PSA Cryptography API specification version 1.0, there is no way 0914 * for applications to trigger a call to this function. However some 0915 * implementations offer the capability to create or declare a key in 0916 * a specific slot via implementation-specific means, generally for the 0917 * sake of initial device provisioning or onboarding. Such a mechanism may 0918 * be added to a future version of the PSA Cryptography API specification. 0919 * 0920 * This function may update the driver's persistent data through 0921 * \p persistent_data. The core will save the updated persistent data at the 0922 * end of the key creation process. See the description of 0923 * ::psa_drv_se_allocate_key_t for more information. 0924 * 0925 * \param[in,out] drv_context The driver context structure. 0926 * \param[in,out] persistent_data A pointer to the persistent data 0927 * that allows writing. 0928 * \param[in] attributes Attributes of the key. 0929 * \param method The way in which the key is being created. 0930 * \param[in] key_slot Slot where the key is to be stored. 0931 * 0932 * \retval #PSA_SUCCESS 0933 * The given slot number is valid for a key with the given 0934 * attributes. 0935 * \retval #PSA_ERROR_INVALID_ARGUMENT 0936 * The given slot number is not valid for a key with the 0937 * given attributes. This includes the case where the slot 0938 * number is not valid at all. 0939 * \retval #PSA_ERROR_ALREADY_EXISTS 0940 * There is already a key with the specified slot number. 0941 * Drivers may choose to return this error from the key 0942 * creation function instead. 0943 */ 0944 typedef psa_status_t (*psa_drv_se_validate_slot_number_t)( 0945 psa_drv_se_context_t *drv_context, 0946 void *persistent_data, 0947 const psa_key_attributes_t *attributes, 0948 psa_key_creation_method_t method, 0949 psa_key_slot_number_t key_slot); 0950 0951 /** \brief A function that imports a key into a secure element in binary format 0952 * 0953 * This function can support any output from psa_export_key(). Refer to the 0954 * documentation of psa_export_key() for the format for each key type. 0955 * 0956 * \param[in,out] drv_context The driver context structure. 0957 * \param key_slot Slot where the key will be stored. 0958 * This must be a valid slot for a key of the 0959 * chosen type. It must be unoccupied. 0960 * \param[in] attributes The key attributes, including the lifetime, 0961 * the key type and the usage policy. 0962 * Drivers should not access the key size stored 0963 * in the attributes: it may not match the 0964 * data passed in \p data. 0965 * Drivers can call psa_get_key_lifetime(), 0966 * psa_get_key_type(), 0967 * psa_get_key_usage_flags() and 0968 * psa_get_key_algorithm() to access this 0969 * information. 0970 * \param[in] data Buffer containing the key data. 0971 * \param[in] data_length Size of the \p data buffer in bytes. 0972 * \param[out] bits On success, the key size in bits. The driver 0973 * must determine this value after parsing the 0974 * key according to the key type. 0975 * This value is not used if the function fails. 0976 * 0977 * \retval #PSA_SUCCESS 0978 * Success. 0979 */ 0980 typedef psa_status_t (*psa_drv_se_import_key_t)( 0981 psa_drv_se_context_t *drv_context, 0982 psa_key_slot_number_t key_slot, 0983 const psa_key_attributes_t *attributes, 0984 const uint8_t *data, 0985 size_t data_length, 0986 size_t *bits); 0987 0988 /** 0989 * \brief A function that destroys a secure element key and restore the slot to 0990 * its default state 0991 * 0992 * This function destroys the content of the key from a secure element. 0993 * Implementations shall make a best effort to ensure that any previous content 0994 * of the slot is unrecoverable. 0995 * 0996 * This function returns the specified slot to its default state. 0997 * 0998 * \param[in,out] drv_context The driver context structure. 0999 * \param[in,out] persistent_data A pointer to the persistent data 1000 * that allows writing. 1001 * \param key_slot The key slot to erase. 1002 * 1003 * \retval #PSA_SUCCESS 1004 * The slot's content, if any, has been erased. 1005 */ 1006 typedef psa_status_t (*psa_drv_se_destroy_key_t)( 1007 psa_drv_se_context_t *drv_context, 1008 void *persistent_data, 1009 psa_key_slot_number_t key_slot); 1010 1011 /** 1012 * \brief A function that exports a secure element key in binary format 1013 * 1014 * The output of this function can be passed to psa_import_key() to 1015 * create an equivalent object. 1016 * 1017 * If a key is created with `psa_import_key()` and then exported with 1018 * this function, it is not guaranteed that the resulting data is 1019 * identical: the implementation may choose a different representation 1020 * of the same key if the format permits it. 1021 * 1022 * This function should generate output in the same format that 1023 * `psa_export_key()` does. Refer to the 1024 * documentation of `psa_export_key()` for the format for each key type. 1025 * 1026 * \param[in,out] drv_context The driver context structure. 1027 * \param[in] key Slot whose content is to be exported. This must 1028 * be an occupied key slot. 1029 * \param[out] p_data Buffer where the key data is to be written. 1030 * \param[in] data_size Size of the `p_data` buffer in bytes. 1031 * \param[out] p_data_length On success, the number of bytes 1032 * that make up the key data. 1033 * 1034 * \retval #PSA_SUCCESS \emptydescription 1035 * \retval #PSA_ERROR_DOES_NOT_EXIST \emptydescription 1036 * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription 1037 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 1038 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 1039 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 1040 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 1041 */ 1042 typedef psa_status_t (*psa_drv_se_export_key_t)(psa_drv_se_context_t *drv_context, 1043 psa_key_slot_number_t key, 1044 uint8_t *p_data, 1045 size_t data_size, 1046 size_t *p_data_length); 1047 1048 /** 1049 * \brief A function that generates a symmetric or asymmetric key on a secure 1050 * element 1051 * 1052 * If the key type \c type recorded in \p attributes 1053 * is asymmetric (#PSA_KEY_TYPE_IS_ASYMMETRIC(\c type) = 1), 1054 * the driver may export the public key at the time of generation, 1055 * in the format documented for psa_export_public_key() by writing it 1056 * to the \p pubkey buffer. 1057 * This is optional, intended for secure elements that output the 1058 * public key at generation time and that cannot export the public key 1059 * later. Drivers that do not need this feature should leave 1060 * \p *pubkey_length set to 0 and should 1061 * implement the psa_drv_key_management_t::p_export_public function. 1062 * Some implementations do not support this feature, in which case 1063 * \p pubkey is \c NULL and \p pubkey_size is 0. 1064 * 1065 * \param[in,out] drv_context The driver context structure. 1066 * \param key_slot Slot where the key will be stored. 1067 * This must be a valid slot for a key of the 1068 * chosen type. It must be unoccupied. 1069 * \param[in] attributes The key attributes, including the lifetime, 1070 * the key type and size, and the usage policy. 1071 * Drivers can call psa_get_key_lifetime(), 1072 * psa_get_key_type(), psa_get_key_bits(), 1073 * psa_get_key_usage_flags() and 1074 * psa_get_key_algorithm() to access this 1075 * information. 1076 * \param[out] pubkey A buffer where the driver can write the 1077 * public key, when generating an asymmetric 1078 * key pair. 1079 * This is \c NULL when generating a symmetric 1080 * key or if the core does not support 1081 * exporting the public key at generation time. 1082 * \param pubkey_size The size of the `pubkey` buffer in bytes. 1083 * This is 0 when generating a symmetric 1084 * key or if the core does not support 1085 * exporting the public key at generation time. 1086 * \param[out] pubkey_length On entry, this is always 0. 1087 * On success, the number of bytes written to 1088 * \p pubkey. If this is 0 or unchanged on return, 1089 * the core will not read the \p pubkey buffer, 1090 * and will instead call the driver's 1091 * psa_drv_key_management_t::p_export_public 1092 * function to export the public key when needed. 1093 */ 1094 typedef psa_status_t (*psa_drv_se_generate_key_t)( 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 1100 /** 1101 * \brief A struct containing all of the function pointers needed to for secure 1102 * element key management 1103 * 1104 * PSA Crypto API implementations should populate instances of the table as 1105 * appropriate upon startup or at build time. 1106 * 1107 * If one of the functions is not implemented, it should be set to NULL. 1108 */ 1109 typedef struct { 1110 /** Function that allocates a slot for a key. */ 1111 psa_drv_se_allocate_key_t MBEDTLS_PRIVATE(p_allocate); 1112 /** Function that checks the validity of a slot for a key. */ 1113 psa_drv_se_validate_slot_number_t MBEDTLS_PRIVATE(p_validate_slot_number); 1114 /** Function that performs a key import operation */ 1115 psa_drv_se_import_key_t MBEDTLS_PRIVATE(p_import); 1116 /** Function that performs a generation */ 1117 psa_drv_se_generate_key_t MBEDTLS_PRIVATE(p_generate); 1118 /** Function that performs a key destroy operation */ 1119 psa_drv_se_destroy_key_t MBEDTLS_PRIVATE(p_destroy); 1120 /** Function that performs a key export operation */ 1121 psa_drv_se_export_key_t MBEDTLS_PRIVATE(p_export); 1122 /** Function that performs a public key export operation */ 1123 psa_drv_se_export_key_t MBEDTLS_PRIVATE(p_export_public); 1124 } psa_drv_se_key_management_t; 1125 1126 /**@}*/ 1127 1128 /** \defgroup driver_derivation Secure Element Key Derivation and Agreement 1129 * Key derivation is the process of generating new key material using an 1130 * existing key and additional parameters, iterating through a basic 1131 * cryptographic function, such as a hash. 1132 * Key agreement is a part of cryptographic protocols that allows two parties 1133 * to agree on the same key value, but starting from different original key 1134 * material. 1135 * The flows are similar, and the PSA Crypto Driver Model uses the same functions 1136 * for both of the flows. 1137 * 1138 * There are two different final functions for the flows, 1139 * `psa_drv_se_key_derivation_derive` and `psa_drv_se_key_derivation_export`. 1140 * `psa_drv_se_key_derivation_derive` is used when the key material should be 1141 * placed in a slot on the hardware and not exposed to the caller. 1142 * `psa_drv_se_key_derivation_export` is used when the key material should be 1143 * returned to the PSA Cryptographic API implementation. 1144 * 1145 * Different key derivation algorithms require a different number of inputs. 1146 * Instead of having an API that takes as input variable length arrays, which 1147 * can be problematic to manage on embedded platforms, the inputs are passed 1148 * to the driver via a function, `psa_drv_se_key_derivation_collateral`, that 1149 * is called multiple times with different `collateral_id`s. Thus, for a key 1150 * derivation algorithm that required 3 parameter inputs, the flow would look 1151 * something like: 1152 * ~~~~~~~~~~~~~{.c} 1153 * psa_drv_se_key_derivation_setup(kdf_algorithm, source_key, dest_key_size_bytes); 1154 * psa_drv_se_key_derivation_collateral(kdf_algorithm_collateral_id_0, 1155 * p_collateral_0, 1156 * collateral_0_size); 1157 * psa_drv_se_key_derivation_collateral(kdf_algorithm_collateral_id_1, 1158 * p_collateral_1, 1159 * collateral_1_size); 1160 * psa_drv_se_key_derivation_collateral(kdf_algorithm_collateral_id_2, 1161 * p_collateral_2, 1162 * collateral_2_size); 1163 * psa_drv_se_key_derivation_derive(); 1164 * ~~~~~~~~~~~~~ 1165 * 1166 * key agreement example: 1167 * ~~~~~~~~~~~~~{.c} 1168 * psa_drv_se_key_derivation_setup(alg, source_key. dest_key_size_bytes); 1169 * psa_drv_se_key_derivation_collateral(DHE_PUBKEY, p_pubkey, pubkey_size); 1170 * psa_drv_se_key_derivation_export(p_session_key, 1171 * session_key_size, 1172 * &session_key_length); 1173 * ~~~~~~~~~~~~~ 1174 */ 1175 /**@{*/ 1176 1177 /** \brief A function that Sets up a secure element key derivation operation by 1178 * specifying the algorithm and the source key sot 1179 * 1180 * \param[in,out] drv_context The driver context structure. 1181 * \param[in,out] op_context A hardware-specific structure containing any 1182 * context information for the implementation 1183 * \param[in] kdf_alg The algorithm to be used for the key derivation 1184 * \param[in] source_key The key to be used as the source material for 1185 * the key derivation 1186 * 1187 * \retval #PSA_SUCCESS \emptydescription 1188 */ 1189 typedef psa_status_t (*psa_drv_se_key_derivation_setup_t)(psa_drv_se_context_t *drv_context, 1190 void *op_context, 1191 psa_algorithm_t kdf_alg, 1192 psa_key_slot_number_t source_key); 1193 1194 /** \brief A function that provides collateral (parameters) needed for a secure 1195 * element key derivation or key agreement operation 1196 * 1197 * Since many key derivation algorithms require multiple parameters, it is 1198 * expected that this function may be called multiple times for the same 1199 * operation, each with a different algorithm-specific `collateral_id` 1200 * 1201 * \param[in,out] op_context A hardware-specific structure containing any 1202 * context information for the implementation 1203 * \param[in] collateral_id An ID for the collateral being provided 1204 * \param[in] p_collateral A buffer containing the collateral data 1205 * \param[in] collateral_size The size in bytes of the collateral 1206 * 1207 * \retval #PSA_SUCCESS \emptydescription 1208 */ 1209 typedef psa_status_t (*psa_drv_se_key_derivation_collateral_t)(void *op_context, 1210 uint32_t collateral_id, 1211 const uint8_t *p_collateral, 1212 size_t collateral_size); 1213 1214 /** \brief A function that performs the final secure element key derivation 1215 * step and place the generated key material in a slot 1216 * 1217 * \param[in,out] op_context A hardware-specific structure containing any 1218 * context information for the implementation 1219 * \param[in] dest_key The slot where the generated key material 1220 * should be placed 1221 * 1222 * \retval #PSA_SUCCESS \emptydescription 1223 */ 1224 typedef psa_status_t (*psa_drv_se_key_derivation_derive_t)(void *op_context, 1225 psa_key_slot_number_t dest_key); 1226 1227 /** \brief A function that performs the final step of a secure element key 1228 * agreement and place the generated key material in a buffer 1229 * 1230 * \param[out] p_output Buffer in which to place the generated key 1231 * material 1232 * \param[in] output_size The size in bytes of `p_output` 1233 * \param[out] p_output_length Upon success, contains the number of bytes of 1234 * key material placed in `p_output` 1235 * 1236 * \retval #PSA_SUCCESS \emptydescription 1237 */ 1238 typedef psa_status_t (*psa_drv_se_key_derivation_export_t)(void *op_context, 1239 uint8_t *p_output, 1240 size_t output_size, 1241 size_t *p_output_length); 1242 1243 /** 1244 * \brief A struct containing all of the function pointers needed to for secure 1245 * element key derivation and agreement 1246 * 1247 * PSA Crypto API implementations should populate instances of the table as 1248 * appropriate upon startup. 1249 * 1250 * If one of the functions is not implemented, it should be set to NULL. 1251 */ 1252 typedef struct { 1253 /** The driver-specific size of the key derivation context */ 1254 size_t MBEDTLS_PRIVATE(context_size); 1255 /** Function that performs a key derivation setup */ 1256 psa_drv_se_key_derivation_setup_t MBEDTLS_PRIVATE(p_setup); 1257 /** Function that sets key derivation collateral */ 1258 psa_drv_se_key_derivation_collateral_t MBEDTLS_PRIVATE(p_collateral); 1259 /** Function that performs a final key derivation step */ 1260 psa_drv_se_key_derivation_derive_t MBEDTLS_PRIVATE(p_derive); 1261 /** Function that performs a final key derivation or agreement and 1262 * exports the key */ 1263 psa_drv_se_key_derivation_export_t MBEDTLS_PRIVATE(p_export); 1264 } psa_drv_se_key_derivation_t; 1265 1266 /**@}*/ 1267 1268 /** \defgroup se_registration Secure element driver registration 1269 */ 1270 /**@{*/ 1271 1272 /** A structure containing pointers to all the entry points of a 1273 * secure element driver. 1274 * 1275 * Future versions of this specification may add extra substructures at 1276 * the end of this structure. 1277 */ 1278 typedef struct { 1279 /** The version of the driver HAL that this driver implements. 1280 * This is a protection against loading driver binaries built against 1281 * a different version of this specification. 1282 * Use #PSA_DRV_SE_HAL_VERSION. 1283 */ 1284 uint32_t MBEDTLS_PRIVATE(hal_version); 1285 1286 /** The size of the driver's persistent data in bytes. 1287 * 1288 * This can be 0 if the driver does not need persistent data. 1289 * 1290 * See the documentation of psa_drv_se_context_t::persistent_data 1291 * for more information about why and how a driver can use 1292 * persistent data. 1293 */ 1294 size_t MBEDTLS_PRIVATE(persistent_data_size); 1295 1296 /** The driver initialization function. 1297 * 1298 * This function is called once during the initialization of the 1299 * PSA Cryptography subsystem, before any other function of the 1300 * driver is called. If this function returns a failure status, 1301 * the driver will be unusable, at least until the next system reset. 1302 * 1303 * If this field is \c NULL, it is equivalent to a function that does 1304 * nothing and returns #PSA_SUCCESS. 1305 */ 1306 psa_drv_se_init_t MBEDTLS_PRIVATE(p_init); 1307 1308 const psa_drv_se_key_management_t *MBEDTLS_PRIVATE(key_management); 1309 const psa_drv_se_mac_t *MBEDTLS_PRIVATE(mac); 1310 const psa_drv_se_cipher_t *MBEDTLS_PRIVATE(cipher); 1311 const psa_drv_se_aead_t *MBEDTLS_PRIVATE(aead); 1312 const psa_drv_se_asymmetric_t *MBEDTLS_PRIVATE(asymmetric); 1313 const psa_drv_se_key_derivation_t *MBEDTLS_PRIVATE(derivation); 1314 } psa_drv_se_t; 1315 1316 /** The current version of the secure element driver HAL. 1317 */ 1318 /* 0.0.0 patchlevel 5 */ 1319 #define PSA_DRV_SE_HAL_VERSION 0x00000005 1320 1321 /** Register an external cryptoprocessor (secure element) driver. 1322 * 1323 * This function is only intended to be used by driver code, not by 1324 * application code. In implementations with separation between the 1325 * PSA cryptography module and applications, this function should 1326 * only be available to callers that run in the same memory space as 1327 * the cryptography module, and should not be exposed to applications 1328 * running in a different memory space. 1329 * 1330 * This function may be called before psa_crypto_init(). It is 1331 * implementation-defined whether this function may be called 1332 * after psa_crypto_init(). 1333 * 1334 * \note Implementations store metadata about keys including the lifetime 1335 * value, which contains the driver's location indicator. Therefore, 1336 * from one instantiation of the PSA Cryptography 1337 * library to the next one, if there is a key in storage with a certain 1338 * lifetime value, you must always register the same driver (or an 1339 * updated version that communicates with the same secure element) 1340 * with the same location value. 1341 * 1342 * \param location The location value through which this driver will 1343 * be exposed to applications. 1344 * This driver will be used for all keys such that 1345 * `location == #PSA_KEY_LIFETIME_GET_LOCATION( lifetime )`. 1346 * The value #PSA_KEY_LOCATION_LOCAL_STORAGE is reserved 1347 * and may not be used for drivers. Implementations 1348 * may reserve other values. 1349 * \param[in] methods The method table of the driver. This structure must 1350 * remain valid for as long as the cryptography 1351 * module keeps running. It is typically a global 1352 * constant. 1353 * 1354 * \return #PSA_SUCCESS 1355 * The driver was successfully registered. Applications can now 1356 * use \p location to access keys through the methods passed to 1357 * this function. 1358 * \return #PSA_ERROR_BAD_STATE 1359 * This function was called after the initialization of the 1360 * cryptography module, and this implementation does not support 1361 * driver registration at this stage. 1362 * \return #PSA_ERROR_ALREADY_EXISTS 1363 * There is already a registered driver for this value of \p location. 1364 * \return #PSA_ERROR_INVALID_ARGUMENT 1365 * \p location is a reserved value. 1366 * \return #PSA_ERROR_NOT_SUPPORTED 1367 * `methods->hal_version` is not supported by this implementation. 1368 * \return #PSA_ERROR_INSUFFICIENT_MEMORY 1369 * \return #PSA_ERROR_NOT_PERMITTED 1370 * \return #PSA_ERROR_STORAGE_FAILURE 1371 * \return #PSA_ERROR_DATA_CORRUPT 1372 */ 1373 psa_status_t psa_register_se_driver( 1374 psa_key_location_t location, 1375 const psa_drv_se_t *methods); 1376 1377 /**@}*/ 1378 1379 #ifdef __cplusplus 1380 } 1381 #endif 1382 1383 #endif /* PSA_CRYPTO_SE_DRIVER_H */
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated by the 2.3.7 LXR engine. The LXR team |
|