crypto_se_driver.h (67908B)
1 /** 2 * \file psa/crypto_se_driver.h 3 * \brief PSA external cryptoprocessor driver module 4 * 5 * This header declares types and function signatures for cryptography 6 * drivers that access key material via opaque references. 7 * This is meant for cryptoprocessors that have a separate key storage from the 8 * space in which the PSA Crypto implementation runs, typically secure 9 * elements (SEs). 10 * 11 * This file is part of the PSA Crypto Driver HAL (hardware abstraction layer), 12 * containing functions for driver developers to implement to enable hardware 13 * to be called in a standardized way by a PSA Cryptography API 14 * implementation. The functions comprising the driver HAL, which driver 15 * authors implement, are not intended to be called by application developers. 16 */ 17 18 /* 19 * Copyright The Mbed TLS Contributors 20 * SPDX-License-Identifier: Apache-2.0 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 32 /** \defgroup se_init Secure element driver initialization 33 */ 34 /**@{*/ 35 36 /** \brief Driver context structure 37 * 38 * Driver functions receive a pointer to this structure. 39 * Each registered driver has one instance of this structure. 40 * 41 * Implementations must include the fields specified here and 42 * may include other fields. 43 */ 44 typedef struct { 45 /** A read-only pointer to the driver's persistent data. 46 * 47 * Drivers typically use this persistent data to keep track of 48 * which slot numbers are available. This is only a guideline: 49 * drivers may use the persistent data for any purpose, keeping 50 * in mind the restrictions on when the persistent data is saved 51 * to storage: the persistent data is only saved after calling 52 * certain functions that receive a writable pointer to the 53 * persistent data. 54 * 55 * The core allocates a memory buffer for the persistent data. 56 * The pointer is guaranteed to be suitably aligned for any data type, 57 * like a pointer returned by `malloc` (but the core can use any 58 * method to allocate the buffer, not necessarily `malloc`). 59 * 60 * The size of this buffer is in the \c persistent_data_size field of 61 * this structure. 62 * 63 * Before the driver is initialized for the first time, the content of 64 * the persistent data is all-bits-zero. After a driver upgrade, if the 65 * size of the persistent data has increased, the original data is padded 66 * on the right with zeros; if the size has decreased, the original data 67 * is truncated to the new size. 68 * 69 * This pointer is to read-only data. Only a few driver functions are 70 * allowed to modify the persistent data. These functions receive a 71 * writable pointer. These functions are: 72 * - psa_drv_se_t::p_init 73 * - psa_drv_se_key_management_t::p_allocate 74 * - psa_drv_se_key_management_t::p_destroy 75 * 76 * The PSA Cryptography core saves the persistent data from one 77 * session to the next. It does this before returning from API functions 78 * that call a driver method that is allowed to modify the persistent 79 * data, specifically: 80 * - psa_crypto_init() causes a call to psa_drv_se_t::p_init, and may call 81 * psa_drv_se_key_management_t::p_destroy to complete an action 82 * that was interrupted by a power failure. 83 * - Key creation functions cause a call to 84 * psa_drv_se_key_management_t::p_allocate, and may cause a call to 85 * psa_drv_se_key_management_t::p_destroy in case an error occurs. 86 * - psa_destroy_key() causes a call to 87 * psa_drv_se_key_management_t::p_destroy. 88 */ 89 const void *const MBEDTLS_PRIVATE(persistent_data); 90 91 /** The size of \c persistent_data in bytes. 92 * 93 * This is always equal to the value of the `persistent_data_size` field 94 * of the ::psa_drv_se_t structure when the driver is registered. 95 */ 96 const size_t MBEDTLS_PRIVATE(persistent_data_size); 97 98 /** Driver transient data. 99 * 100 * The core initializes this value to 0 and does not read or modify it 101 * afterwards. The driver may store whatever it wants in this field. 102 */ 103 uintptr_t MBEDTLS_PRIVATE(transient_data); 104 } psa_drv_se_context_t; 105 106 /** \brief A driver initialization function. 107 * 108 * \param[in,out] drv_context The driver context structure. 109 * \param[in,out] persistent_data A pointer to the persistent data 110 * that allows writing. 111 * \param location The location value for which this driver 112 * is registered. The driver will be invoked 113 * for all keys whose lifetime is in this 114 * location. 115 * 116 * \retval #PSA_SUCCESS 117 * The driver is operational. 118 * The core will update the persistent data in storage. 119 * \return 120 * Any other return value prevents the driver from being used in 121 * this session. 122 * The core will NOT update the persistent data in storage. 123 */ 124 typedef psa_status_t (*psa_drv_se_init_t)(psa_drv_se_context_t *drv_context, 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. */ 134 /** An internal designation of a key slot between the core part of the 135 * PSA Crypto implementation and the driver. The meaning of this value 136 * is driver-dependent. */ 137 typedef uint64_t psa_key_slot_number_t; 138 #endif /* __DOXYGEN_ONLY__ || !MBEDTLS_PSA_CRYPTO_SE_C */ 139 140 /**@}*/ 141 142 /** \defgroup se_mac Secure Element Message Authentication Codes 143 * Generation and authentication of Message Authentication Codes (MACs) using 144 * a secure element can be done either as a single function call (via the 145 * `psa_drv_se_mac_generate_t` or `psa_drv_se_mac_verify_t` functions), or in 146 * parts using the following sequence: 147 * - `psa_drv_se_mac_setup_t` 148 * - `psa_drv_se_mac_update_t` 149 * - `psa_drv_se_mac_update_t` 150 * - ... 151 * - `psa_drv_se_mac_finish_t` or `psa_drv_se_mac_finish_verify_t` 152 * 153 * If a previously started secure element MAC operation needs to be terminated, 154 * it should be done so by the `psa_drv_se_mac_abort_t`. Failure to do so may 155 * result in allocated resources not being freed or in other undefined 156 * behavior. 157 */ 158 /**@{*/ 159 /** \brief A function that starts a secure element MAC operation for a PSA 160 * Crypto Driver implementation 161 * 162 * \param[in,out] drv_context The driver context structure. 163 * \param[in,out] op_context A structure that will contain the 164 * hardware-specific MAC context 165 * \param[in] key_slot The slot of the key to be used for the 166 * operation 167 * \param[in] algorithm The algorithm to be used to underly the MAC 168 * operation 169 * 170 * \retval #PSA_SUCCESS 171 * Success. 172 */ 173 typedef psa_status_t (*psa_drv_se_mac_setup_t)(psa_drv_se_context_t *drv_context, 174 void *op_context, 175 psa_key_slot_number_t key_slot, 176 psa_algorithm_t algorithm); 177 178 /** \brief A function that continues a previously started secure element MAC 179 * operation 180 * 181 * \param[in,out] op_context A hardware-specific structure for the 182 * previously-established MAC operation to be 183 * updated 184 * \param[in] p_input A buffer containing the message to be appended 185 * to the MAC operation 186 * \param[in] input_length The size in bytes of the input message buffer 187 */ 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 192 /** \brief a function that completes a previously started secure element MAC 193 * operation by returning the resulting MAC. 194 * 195 * \param[in,out] op_context A hardware-specific structure for the 196 * previously started MAC operation to be 197 * finished 198 * \param[out] p_mac A buffer where the generated MAC will be 199 * placed 200 * \param[in] mac_size The size in bytes of the buffer that has been 201 * allocated for the `output` buffer 202 * \param[out] p_mac_length After completion, will contain the number of 203 * bytes placed in the `p_mac` buffer 204 * 205 * \retval #PSA_SUCCESS 206 * Success. 207 */ 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 213 /** \brief A function that completes a previously started secure element MAC 214 * operation by comparing the resulting MAC against a provided value 215 * 216 * \param[in,out] op_context A hardware-specific structure for the previously 217 * started MAC operation to be finished 218 * \param[in] p_mac The MAC value against which the resulting MAC 219 * will be compared against 220 * \param[in] mac_length The size in bytes of the value stored in `p_mac` 221 * 222 * \retval #PSA_SUCCESS 223 * The operation completed successfully and the MACs matched each 224 * other 225 * \retval #PSA_ERROR_INVALID_SIGNATURE 226 * The operation completed successfully, but the calculated MAC did 227 * not match the provided MAC 228 */ 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 233 /** \brief A function that aborts a previous started secure element MAC 234 * operation 235 * 236 * \param[in,out] op_context A hardware-specific structure for the previously 237 * started MAC operation to be aborted 238 */ 239 typedef psa_status_t (*psa_drv_se_mac_abort_t)(void *op_context); 240 241 /** \brief A function that performs a secure element MAC operation in one 242 * command and returns the calculated MAC 243 * 244 * \param[in,out] drv_context The driver context structure. 245 * \param[in] p_input A buffer containing the message to be MACed 246 * \param[in] input_length The size in bytes of `p_input` 247 * \param[in] key_slot The slot of the key to be used 248 * \param[in] alg The algorithm to be used to underlie the MAC 249 * operation 250 * \param[out] p_mac A buffer where the generated MAC will be 251 * placed 252 * \param[in] mac_size The size in bytes of the `p_mac` buffer 253 * \param[out] p_mac_length After completion, will contain the number of 254 * bytes placed in the `output` buffer 255 * 256 * \retval #PSA_SUCCESS 257 * Success. 258 */ 259 typedef psa_status_t (*psa_drv_se_mac_generate_t)(psa_drv_se_context_t *drv_context, 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 268 /** \brief A function that performs a secure element MAC operation in one 269 * command and compares the resulting MAC against a provided value 270 * 271 * \param[in,out] drv_context The driver context structure. 272 * \param[in] p_input A buffer containing the message to be MACed 273 * \param[in] input_length The size in bytes of `input` 274 * \param[in] key_slot The slot of the key to be used 275 * \param[in] alg The algorithm to be used to underlie the MAC 276 * operation 277 * \param[in] p_mac The MAC value against which the resulting MAC will 278 * be compared against 279 * \param[in] mac_length The size in bytes of `mac` 280 * 281 * \retval #PSA_SUCCESS 282 * The operation completed successfully and the MACs matched each 283 * other 284 * \retval #PSA_ERROR_INVALID_SIGNATURE 285 * The operation completed successfully, but the calculated MAC did 286 * not match the provided MAC 287 */ 288 typedef psa_status_t (*psa_drv_se_mac_verify_t)(psa_drv_se_context_t *drv_context, 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 296 /** \brief A struct containing all of the function pointers needed to 297 * perform secure element MAC operations 298 * 299 * PSA Crypto API implementations should populate the table as appropriate 300 * upon startup. 301 * 302 * If one of the functions is not implemented (such as 303 * `psa_drv_se_mac_generate_t`), it should be set to NULL. 304 * 305 * Driver implementers should ensure that they implement all of the functions 306 * that make sense for their hardware, and that they provide a full solution 307 * (for example, if they support `p_setup`, they should also support 308 * `p_update` and at least one of `p_finish` or `p_finish_verify`). 309 * 310 */ 311 typedef struct { 312 /**The size in bytes of the hardware-specific secure element MAC context 313 * structure 314 */ 315 size_t MBEDTLS_PRIVATE(context_size); 316 /** Function that performs a MAC setup operation 317 */ 318 psa_drv_se_mac_setup_t MBEDTLS_PRIVATE(p_setup); 319 /** Function that performs a MAC update operation 320 */ 321 psa_drv_se_mac_update_t MBEDTLS_PRIVATE(p_update); 322 /** Function that completes a MAC operation 323 */ 324 psa_drv_se_mac_finish_t MBEDTLS_PRIVATE(p_finish); 325 /** Function that completes a MAC operation with a verify check 326 */ 327 psa_drv_se_mac_finish_verify_t MBEDTLS_PRIVATE(p_finish_verify); 328 /** Function that aborts a previously started MAC operation 329 */ 330 psa_drv_se_mac_abort_t MBEDTLS_PRIVATE(p_abort); 331 /** Function that performs a MAC operation in one call 332 */ 333 psa_drv_se_mac_generate_t MBEDTLS_PRIVATE(p_mac); 334 /** Function that performs a MAC and verify operation in one call 335 */ 336 psa_drv_se_mac_verify_t MBEDTLS_PRIVATE(p_mac_verify); 337 } psa_drv_se_mac_t; 338 /**@}*/ 339 340 /** \defgroup se_cipher Secure Element Symmetric Ciphers 341 * 342 * Encryption and Decryption using secure element keys in block modes other 343 * than ECB must be done in multiple parts, using the following flow: 344 * - `psa_drv_se_cipher_setup_t` 345 * - `psa_drv_se_cipher_set_iv_t` (optional depending upon block mode) 346 * - `psa_drv_se_cipher_update_t` 347 * - `psa_drv_se_cipher_update_t` 348 * - ... 349 * - `psa_drv_se_cipher_finish_t` 350 * 351 * If a previously started secure element Cipher operation needs to be 352 * terminated, it should be done so by the `psa_drv_se_cipher_abort_t`. Failure 353 * to do so may result in allocated resources not being freed or in other 354 * undefined behavior. 355 * 356 * In situations where a PSA Cryptographic API implementation is using a block 357 * mode not-supported by the underlying hardware or driver, it can construct 358 * the block mode itself, while calling the `psa_drv_se_cipher_ecb_t` function 359 * for the cipher operations. 360 */ 361 /**@{*/ 362 363 /** \brief A function that provides the cipher setup function for a 364 * secure element driver 365 * 366 * \param[in,out] drv_context The driver context structure. 367 * \param[in,out] op_context A structure that will contain the 368 * hardware-specific cipher context. 369 * \param[in] key_slot The slot of the key to be used for the 370 * operation 371 * \param[in] algorithm The algorithm to be used in the cipher 372 * operation 373 * \param[in] direction Indicates whether the operation is an encrypt 374 * or decrypt 375 * 376 * \retval #PSA_SUCCESS \emptydescription 377 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 378 */ 379 typedef psa_status_t (*psa_drv_se_cipher_setup_t)(psa_drv_se_context_t *drv_context, 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 385 /** \brief A function that sets the initialization vector (if 386 * necessary) for a secure element cipher operation 387 * 388 * Rationale: The `psa_se_cipher_*` operation in the PSA Cryptographic API has 389 * two IV functions: one to set the IV, and one to generate it internally. The 390 * generate function is not necessary for the drivers to implement as the PSA 391 * Crypto implementation can do the generation using its RNG features. 392 * 393 * \param[in,out] op_context A structure that contains the previously set up 394 * hardware-specific cipher context 395 * \param[in] p_iv A buffer containing the initialization vector 396 * \param[in] iv_length The size (in bytes) of the `p_iv` buffer 397 * 398 * \retval #PSA_SUCCESS \emptydescription 399 */ 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 404 /** \brief A function that continues a previously started secure element cipher 405 * operation 406 * 407 * \param[in,out] op_context A hardware-specific structure for the 408 * previously started cipher operation 409 * \param[in] p_input A buffer containing the data to be 410 * encrypted/decrypted 411 * \param[in] input_size The size in bytes of the buffer pointed to 412 * by `p_input` 413 * \param[out] p_output The caller-allocated buffer where the 414 * output will be placed 415 * \param[in] output_size The allocated size in bytes of the 416 * `p_output` buffer 417 * \param[out] p_output_length After completion, will contain the number 418 * of bytes placed in the `p_output` buffer 419 * 420 * \retval #PSA_SUCCESS \emptydescription 421 */ 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 429 /** \brief A function that completes a previously started secure element cipher 430 * operation 431 * 432 * \param[in,out] op_context A hardware-specific structure for the 433 * previously started cipher operation 434 * \param[out] p_output The caller-allocated buffer where the output 435 * will be placed 436 * \param[in] output_size The allocated size in bytes of the `p_output` 437 * buffer 438 * \param[out] p_output_length After completion, will contain the number of 439 * bytes placed in the `p_output` buffer 440 * 441 * \retval #PSA_SUCCESS \emptydescription 442 */ 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 448 /** \brief A function that aborts a previously started secure element cipher 449 * operation 450 * 451 * \param[in,out] op_context A hardware-specific structure for the 452 * previously started cipher operation 453 */ 454 typedef psa_status_t (*psa_drv_se_cipher_abort_t)(void *op_context); 455 456 /** \brief A function that performs the ECB block mode for secure element 457 * cipher operations 458 * 459 * Note: this function should only be used with implementations that do not 460 * provide a needed higher-level operation. 461 * 462 * \param[in,out] drv_context The driver context structure. 463 * \param[in] key_slot The slot of the key to be used for the operation 464 * \param[in] algorithm The algorithm to be used in the cipher operation 465 * \param[in] direction Indicates whether the operation is an encrypt or 466 * decrypt 467 * \param[in] p_input A buffer containing the data to be 468 * encrypted/decrypted 469 * \param[in] input_size The size in bytes of the buffer pointed to by 470 * `p_input` 471 * \param[out] p_output The caller-allocated buffer where the output 472 * will be placed 473 * \param[in] output_size The allocated size in bytes of the `p_output` 474 * buffer 475 * 476 * \retval #PSA_SUCCESS \emptydescription 477 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 478 */ 479 typedef psa_status_t (*psa_drv_se_cipher_ecb_t)(psa_drv_se_context_t *drv_context, 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 488 /** 489 * \brief A struct containing all of the function pointers needed to implement 490 * cipher operations using secure elements. 491 * 492 * PSA Crypto API implementations should populate instances of the table as 493 * appropriate upon startup or at build time. 494 * 495 * If one of the functions is not implemented (such as 496 * `psa_drv_se_cipher_ecb_t`), it should be set to NULL. 497 */ 498 typedef struct { 499 /** The size in bytes of the hardware-specific secure element cipher 500 * context structure 501 */ 502 size_t MBEDTLS_PRIVATE(context_size); 503 /** Function that performs a cipher setup operation */ 504 psa_drv_se_cipher_setup_t MBEDTLS_PRIVATE(p_setup); 505 /** Function that sets a cipher IV (if necessary) */ 506 psa_drv_se_cipher_set_iv_t MBEDTLS_PRIVATE(p_set_iv); 507 /** Function that performs a cipher update operation */ 508 psa_drv_se_cipher_update_t MBEDTLS_PRIVATE(p_update); 509 /** Function that completes a cipher operation */ 510 psa_drv_se_cipher_finish_t MBEDTLS_PRIVATE(p_finish); 511 /** Function that aborts a cipher operation */ 512 psa_drv_se_cipher_abort_t MBEDTLS_PRIVATE(p_abort); 513 /** Function that performs ECB mode for a cipher operation 514 * (Danger: ECB mode should not be used directly by clients of the PSA 515 * Crypto Client API) 516 */ 517 psa_drv_se_cipher_ecb_t MBEDTLS_PRIVATE(p_ecb); 518 } psa_drv_se_cipher_t; 519 520 /**@}*/ 521 522 /** \defgroup se_asymmetric Secure Element Asymmetric Cryptography 523 * 524 * Since the amount of data that can (or should) be encrypted or signed using 525 * asymmetric keys is limited by the key size, asymmetric key operations using 526 * keys in a secure element must be done in single function calls. 527 */ 528 /**@{*/ 529 530 /** 531 * \brief A function that signs a hash or short message with a private key in 532 * a secure element 533 * 534 * \param[in,out] drv_context The driver context structure. 535 * \param[in] key_slot Key slot of an asymmetric key pair 536 * \param[in] alg A signature algorithm that is compatible 537 * with the type of `key` 538 * \param[in] p_hash The hash to sign 539 * \param[in] hash_length Size of the `p_hash` buffer in bytes 540 * \param[out] p_signature Buffer where the signature is to be written 541 * \param[in] signature_size Size of the `p_signature` buffer in bytes 542 * \param[out] p_signature_length On success, the number of bytes 543 * that make up the returned signature value 544 * 545 * \retval #PSA_SUCCESS \emptydescription 546 */ 547 typedef psa_status_t (*psa_drv_se_asymmetric_sign_t)(psa_drv_se_context_t *drv_context, 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 556 /** 557 * \brief A function that verifies the signature a hash or short message using 558 * an asymmetric public key in a secure element 559 * 560 * \param[in,out] drv_context The driver context structure. 561 * \param[in] key_slot Key slot of a public key or an asymmetric key 562 * pair 563 * \param[in] alg A signature algorithm that is compatible with 564 * the type of `key` 565 * \param[in] p_hash The hash whose signature is to be verified 566 * \param[in] hash_length Size of the `p_hash` buffer in bytes 567 * \param[in] p_signature Buffer containing the signature to verify 568 * \param[in] signature_length Size of the `p_signature` buffer in bytes 569 * 570 * \retval #PSA_SUCCESS 571 * The signature is valid. 572 */ 573 typedef psa_status_t (*psa_drv_se_asymmetric_verify_t)(psa_drv_se_context_t *drv_context, 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 581 /** 582 * \brief A function that encrypts a short message with an asymmetric public 583 * key in a secure element 584 * 585 * \param[in,out] drv_context The driver context structure. 586 * \param[in] key_slot Key slot of a public key or an asymmetric key 587 * pair 588 * \param[in] alg An asymmetric encryption algorithm that is 589 * compatible with the type of `key` 590 * \param[in] p_input The message to encrypt 591 * \param[in] input_length Size of the `p_input` buffer in bytes 592 * \param[in] p_salt A salt or label, if supported by the 593 * encryption algorithm 594 * If the algorithm does not support a 595 * salt, pass `NULL`. 596 * If the algorithm supports an optional 597 * salt and you do not want to pass a salt, 598 * pass `NULL`. 599 * For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is 600 * supported. 601 * \param[in] salt_length Size of the `p_salt` buffer in bytes 602 * If `p_salt` is `NULL`, pass 0. 603 * \param[out] p_output Buffer where the encrypted message is to 604 * be written 605 * \param[in] output_size Size of the `p_output` buffer in bytes 606 * \param[out] p_output_length On success, the number of bytes that make up 607 * the returned output 608 * 609 * \retval #PSA_SUCCESS \emptydescription 610 */ 611 typedef psa_status_t (*psa_drv_se_asymmetric_encrypt_t)(psa_drv_se_context_t *drv_context, 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 622 /** 623 * \brief A function that decrypts a short message with an asymmetric private 624 * key in a secure element. 625 * 626 * \param[in,out] drv_context The driver context structure. 627 * \param[in] key_slot Key slot of an asymmetric key pair 628 * \param[in] alg An asymmetric encryption algorithm that is 629 * compatible with the type of `key` 630 * \param[in] p_input The message to decrypt 631 * \param[in] input_length Size of the `p_input` buffer in bytes 632 * \param[in] p_salt A salt or label, if supported by the 633 * encryption algorithm 634 * If the algorithm does not support a 635 * salt, pass `NULL`. 636 * If the algorithm supports an optional 637 * salt and you do not want to pass a salt, 638 * pass `NULL`. 639 * For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is 640 * supported. 641 * \param[in] salt_length Size of the `p_salt` buffer in bytes 642 * If `p_salt` is `NULL`, pass 0. 643 * \param[out] p_output Buffer where the decrypted message is to 644 * be written 645 * \param[in] output_size Size of the `p_output` buffer in bytes 646 * \param[out] p_output_length On success, the number of bytes 647 * that make up the returned output 648 * 649 * \retval #PSA_SUCCESS \emptydescription 650 */ 651 typedef psa_status_t (*psa_drv_se_asymmetric_decrypt_t)(psa_drv_se_context_t *drv_context, 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 662 /** 663 * \brief A struct containing all of the function pointers needed to implement 664 * asymmetric cryptographic operations using secure elements. 665 * 666 * PSA Crypto API implementations should populate instances of the table as 667 * appropriate upon startup or at build time. 668 * 669 * If one of the functions is not implemented, it should be set to NULL. 670 */ 671 typedef struct { 672 /** Function that performs an asymmetric sign operation */ 673 psa_drv_se_asymmetric_sign_t MBEDTLS_PRIVATE(p_sign); 674 /** Function that performs an asymmetric verify operation */ 675 psa_drv_se_asymmetric_verify_t MBEDTLS_PRIVATE(p_verify); 676 /** Function that performs an asymmetric encrypt operation */ 677 psa_drv_se_asymmetric_encrypt_t MBEDTLS_PRIVATE(p_encrypt); 678 /** Function that performs an asymmetric decrypt operation */ 679 psa_drv_se_asymmetric_decrypt_t MBEDTLS_PRIVATE(p_decrypt); 680 } psa_drv_se_asymmetric_t; 681 682 /**@}*/ 683 684 /** \defgroup se_aead Secure Element Authenticated Encryption with Additional Data 685 * Authenticated Encryption with Additional Data (AEAD) operations with secure 686 * elements must be done in one function call. While this creates a burden for 687 * implementers as there must be sufficient space in memory for the entire 688 * message, it prevents decrypted data from being made available before the 689 * authentication operation is complete and the data is known to be authentic. 690 */ 691 /**@{*/ 692 693 /** \brief A function that performs a secure element authenticated encryption 694 * operation 695 * 696 * \param[in,out] drv_context The driver context structure. 697 * \param[in] key_slot Slot containing the key to use. 698 * \param[in] algorithm The AEAD algorithm to compute 699 * (\c PSA_ALG_XXX value such that 700 * #PSA_ALG_IS_AEAD(`alg`) is true) 701 * \param[in] p_nonce Nonce or IV to use 702 * \param[in] nonce_length Size of the `p_nonce` buffer in bytes 703 * \param[in] p_additional_data Additional data that will be 704 * authenticated but not encrypted 705 * \param[in] additional_data_length Size of `p_additional_data` in bytes 706 * \param[in] p_plaintext Data that will be authenticated and 707 * encrypted 708 * \param[in] plaintext_length Size of `p_plaintext` in bytes 709 * \param[out] p_ciphertext Output buffer for the authenticated and 710 * encrypted data. The additional data is 711 * not part of this output. For algorithms 712 * where the encrypted data and the 713 * authentication tag are defined as 714 * separate outputs, the authentication 715 * tag is appended to the encrypted data. 716 * \param[in] ciphertext_size Size of the `p_ciphertext` buffer in 717 * bytes 718 * \param[out] p_ciphertext_length On success, the size of the output in 719 * the `p_ciphertext` buffer 720 * 721 * \retval #PSA_SUCCESS 722 * Success. 723 */ 724 typedef psa_status_t (*psa_drv_se_aead_encrypt_t)(psa_drv_se_context_t *drv_context, 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 737 /** A function that performs a secure element authenticated decryption operation 738 * 739 * \param[in,out] drv_context The driver context structure. 740 * \param[in] key_slot Slot containing the key to use 741 * \param[in] algorithm The AEAD algorithm to compute 742 * (\c PSA_ALG_XXX value such that 743 * #PSA_ALG_IS_AEAD(`alg`) is true) 744 * \param[in] p_nonce Nonce or IV to use 745 * \param[in] nonce_length Size of the `p_nonce` buffer in bytes 746 * \param[in] p_additional_data Additional data that has been 747 * authenticated but not encrypted 748 * \param[in] additional_data_length Size of `p_additional_data` in bytes 749 * \param[in] p_ciphertext Data that has been authenticated and 750 * encrypted. 751 * For algorithms where the encrypted data 752 * and the authentication tag are defined 753 * as separate inputs, the buffer must 754 * contain the encrypted data followed by 755 * the authentication tag. 756 * \param[in] ciphertext_length Size of `p_ciphertext` in bytes 757 * \param[out] p_plaintext Output buffer for the decrypted data 758 * \param[in] plaintext_size Size of the `p_plaintext` buffer in 759 * bytes 760 * \param[out] p_plaintext_length On success, the size of the output in 761 * the `p_plaintext` buffer 762 * 763 * \retval #PSA_SUCCESS 764 * Success. 765 */ 766 typedef psa_status_t (*psa_drv_se_aead_decrypt_t)(psa_drv_se_context_t *drv_context, 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 779 /** 780 * \brief A struct containing all of the function pointers needed to implement 781 * secure element Authenticated Encryption with Additional Data operations 782 * 783 * PSA Crypto API implementations should populate instances of the table as 784 * appropriate upon startup. 785 * 786 * If one of the functions is not implemented, it should be set to NULL. 787 */ 788 typedef struct { 789 /** Function that performs the AEAD encrypt operation */ 790 psa_drv_se_aead_encrypt_t MBEDTLS_PRIVATE(p_encrypt); 791 /** Function that performs the AEAD decrypt operation */ 792 psa_drv_se_aead_decrypt_t MBEDTLS_PRIVATE(p_decrypt); 793 } psa_drv_se_aead_t; 794 /**@}*/ 795 796 /** \defgroup se_key_management Secure Element Key Management 797 * Currently, key management is limited to importing keys in the clear, 798 * destroying keys, and exporting keys in the clear. 799 * Whether a key may be exported is determined by the key policies in place 800 * on the key slot. 801 */ 802 /**@{*/ 803 804 /** An enumeration indicating how a key is created. 805 */ 806 typedef enum { 807 PSA_KEY_CREATION_IMPORT, /**< During psa_import_key() */ 808 PSA_KEY_CREATION_GENERATE, /**< During psa_generate_key() */ 809 PSA_KEY_CREATION_DERIVE, /**< During psa_key_derivation_output_key() */ 810 PSA_KEY_CREATION_COPY, /**< During psa_copy_key() */ 811 812 #ifndef __DOXYGEN_ONLY__ 813 /** A key is being registered with mbedtls_psa_register_se_key(). 814 * 815 * The core only passes this value to 816 * psa_drv_se_key_management_t::p_validate_slot_number, not to 817 * psa_drv_se_key_management_t::p_allocate. The call to 818 * `p_validate_slot_number` is not followed by any other call to the 819 * driver: the key is considered successfully registered if the call to 820 * `p_validate_slot_number` succeeds, or if `p_validate_slot_number` is 821 * null. 822 * 823 * With this creation method, the driver must return #PSA_SUCCESS if 824 * the given attributes are compatible with the existing key in the slot, 825 * and #PSA_ERROR_DOES_NOT_EXIST if the driver can determine that there 826 * is no key with the specified slot number. 827 * 828 * This is an Mbed TLS extension. 829 */ 830 PSA_KEY_CREATION_REGISTER, 831 #endif 832 } psa_key_creation_method_t; 833 834 /** \brief A function that allocates a slot for a key. 835 * 836 * To create a key in a specific slot in a secure element, the core 837 * first calls this function to determine a valid slot number, 838 * then calls a function to create the key material in that slot. 839 * In nominal conditions (that is, if no error occurs), 840 * the effect of a call to a key creation function in the PSA Cryptography 841 * API with a lifetime that places the key in a secure element is the 842 * following: 843 * -# The core calls psa_drv_se_key_management_t::p_allocate 844 * (or in some implementations 845 * psa_drv_se_key_management_t::p_validate_slot_number). The driver 846 * selects (or validates) a suitable slot number given the key attributes 847 * and the state of the secure element. 848 * -# The core calls a key creation function in the driver. 849 * 850 * The key creation functions in the PSA Cryptography API are: 851 * - psa_import_key(), which causes 852 * a call to `p_allocate` with \p method = #PSA_KEY_CREATION_IMPORT 853 * then a call to psa_drv_se_key_management_t::p_import. 854 * - psa_generate_key(), which causes 855 * a call to `p_allocate` with \p method = #PSA_KEY_CREATION_GENERATE 856 * then a call to psa_drv_se_key_management_t::p_import. 857 * - psa_key_derivation_output_key(), which causes 858 * a call to `p_allocate` with \p method = #PSA_KEY_CREATION_DERIVE 859 * then a call to psa_drv_se_key_derivation_t::p_derive. 860 * - psa_copy_key(), which causes 861 * a call to `p_allocate` with \p method = #PSA_KEY_CREATION_COPY 862 * then a call to psa_drv_se_key_management_t::p_export. 863 * 864 * In case of errors, other behaviors are possible. 865 * - If the PSA Cryptography subsystem dies after the first step, 866 * for example because the device has lost power abruptly, 867 * the second step may never happen, or may happen after a reset 868 * and re-initialization. Alternatively, after a reset and 869 * re-initialization, the core may call 870 * psa_drv_se_key_management_t::p_destroy on the slot number that 871 * was allocated (or validated) instead of calling a key creation function. 872 * - If an error occurs, the core may call 873 * psa_drv_se_key_management_t::p_destroy on the slot number that 874 * was allocated (or validated) instead of calling a key creation function. 875 * 876 * Errors and system resets also have an impact on the driver's persistent 877 * data. If a reset happens before the overall key creation process is 878 * completed (before or after the second step above), it is unspecified 879 * whether the persistent data after the reset is identical to what it 880 * was before or after the call to `p_allocate` (or `p_validate_slot_number`). 881 * 882 * \param[in,out] drv_context The driver context structure. 883 * \param[in,out] persistent_data A pointer to the persistent data 884 * that allows writing. 885 * \param[in] attributes Attributes of the key. 886 * \param method The way in which the key is being created. 887 * \param[out] key_slot Slot where the key will be stored. 888 * This must be a valid slot for a key of the 889 * chosen type. It must be unoccupied. 890 * 891 * \retval #PSA_SUCCESS 892 * Success. 893 * The core will record \c *key_slot as the key slot where the key 894 * is stored and will update the persistent data in storage. 895 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 896 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE \emptydescription 897 */ 898 typedef psa_status_t (*psa_drv_se_allocate_key_t)( 899 psa_drv_se_context_t *drv_context, 900 void *persistent_data, 901 const psa_key_attributes_t *attributes, 902 psa_key_creation_method_t method, 903 psa_key_slot_number_t *key_slot); 904 905 /** \brief A function that determines whether a slot number is valid 906 * for a key. 907 * 908 * To create a key in a specific slot in a secure element, the core 909 * first calls this function to validate the choice of slot number, 910 * then calls a function to create the key material in that slot. 911 * See the documentation of #psa_drv_se_allocate_key_t for more details. 912 * 913 * As of the PSA Cryptography API specification version 1.0, there is no way 914 * for applications to trigger a call to this function. However some 915 * implementations offer the capability to create or declare a key in 916 * a specific slot via implementation-specific means, generally for the 917 * sake of initial device provisioning or onboarding. Such a mechanism may 918 * be added to a future version of the PSA Cryptography API specification. 919 * 920 * This function may update the driver's persistent data through 921 * \p persistent_data. The core will save the updated persistent data at the 922 * end of the key creation process. See the description of 923 * ::psa_drv_se_allocate_key_t for more information. 924 * 925 * \param[in,out] drv_context The driver context structure. 926 * \param[in,out] persistent_data A pointer to the persistent data 927 * that allows writing. 928 * \param[in] attributes Attributes of the key. 929 * \param method The way in which the key is being created. 930 * \param[in] key_slot Slot where the key is to be stored. 931 * 932 * \retval #PSA_SUCCESS 933 * The given slot number is valid for a key with the given 934 * attributes. 935 * \retval #PSA_ERROR_INVALID_ARGUMENT 936 * The given slot number is not valid for a key with the 937 * given attributes. This includes the case where the slot 938 * number is not valid at all. 939 * \retval #PSA_ERROR_ALREADY_EXISTS 940 * There is already a key with the specified slot number. 941 * Drivers may choose to return this error from the key 942 * creation function instead. 943 */ 944 typedef psa_status_t (*psa_drv_se_validate_slot_number_t)( 945 psa_drv_se_context_t *drv_context, 946 void *persistent_data, 947 const psa_key_attributes_t *attributes, 948 psa_key_creation_method_t method, 949 psa_key_slot_number_t key_slot); 950 951 /** \brief A function that imports a key into a secure element in binary format 952 * 953 * This function can support any output from psa_export_key(). Refer to the 954 * documentation of psa_export_key() for the format for each key type. 955 * 956 * \param[in,out] drv_context The driver context structure. 957 * \param key_slot Slot where the key will be stored. 958 * This must be a valid slot for a key of the 959 * chosen type. It must be unoccupied. 960 * \param[in] attributes The key attributes, including the lifetime, 961 * the key type and the usage policy. 962 * Drivers should not access the key size stored 963 * in the attributes: it may not match the 964 * data passed in \p data. 965 * Drivers can call psa_get_key_lifetime(), 966 * psa_get_key_type(), 967 * psa_get_key_usage_flags() and 968 * psa_get_key_algorithm() to access this 969 * information. 970 * \param[in] data Buffer containing the key data. 971 * \param[in] data_length Size of the \p data buffer in bytes. 972 * \param[out] bits On success, the key size in bits. The driver 973 * must determine this value after parsing the 974 * key according to the key type. 975 * This value is not used if the function fails. 976 * 977 * \retval #PSA_SUCCESS 978 * Success. 979 */ 980 typedef psa_status_t (*psa_drv_se_import_key_t)( 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 988 /** 989 * \brief A function that destroys a secure element key and restore the slot to 990 * its default state 991 * 992 * This function destroys the content of the key from a secure element. 993 * Implementations shall make a best effort to ensure that any previous content 994 * of the slot is unrecoverable. 995 * 996 * This function returns the specified slot to its default state. 997 * 998 * \param[in,out] drv_context The driver context structure. 999 * \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 */