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