Kenji Arai
/
mbed-os_TYBLE16
Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Dependents: TYBLE16_simple_data_logger TYBLE16_MP3_Air
Embed:
(wiki syntax)
Show/hide line numbers
crypto_se_driver.h
Go to the documentation of this file.
00001 /** 00002 * \file psa/crypto_se_driver.h 00003 * \brief PSA external cryptoprocessor driver module 00004 * 00005 * This header declares types and function signatures for cryptography 00006 * drivers that access key material via opaque references. 00007 * This is meant for cryptoprocessors that have a separate key storage from the 00008 * space in which the PSA Crypto implementation runs, typically secure 00009 * elements (SEs). 00010 * 00011 * This file is part of the PSA Crypto Driver HAL (hardware abstraction layer), 00012 * containing functions for driver developers to implement to enable hardware 00013 * to be called in a standardized way by a PSA Cryptography API 00014 * implementation. The functions comprising the driver HAL, which driver 00015 * authors implement, are not intended to be called by application developers. 00016 */ 00017 00018 /* 00019 * Copyright (C) 2018, ARM Limited, All Rights Reserved 00020 * SPDX-License-Identifier: Apache-2.0 00021 * 00022 * Licensed under the Apache License, Version 2.0 (the "License"); you may 00023 * not use this file except in compliance with the License. 00024 * You may obtain a copy of the License at 00025 * 00026 * http://www.apache.org/licenses/LICENSE-2.0 00027 * 00028 * Unless required by applicable law or agreed to in writing, software 00029 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 00030 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00031 * See the License for the specific language governing permissions and 00032 * limitations under the License. 00033 */ 00034 #ifndef PSA_CRYPTO_SE_DRIVER_H 00035 #define PSA_CRYPTO_SE_DRIVER_H 00036 00037 #include "crypto_driver_common.h" 00038 00039 #ifdef __cplusplus 00040 extern "C" { 00041 #endif 00042 00043 /** \defgroup se_init Secure element driver initialization 00044 */ 00045 /**@{*/ 00046 00047 /** \brief Driver context structure 00048 * 00049 * Driver functions receive a pointer to this structure. 00050 * Each registered driver has one instance of this structure. 00051 * 00052 * Implementations must include the fields specified here and 00053 * may include other fields. 00054 */ 00055 typedef struct { 00056 /** A read-only pointer to the driver's persistent data. 00057 * 00058 * Drivers typically use this persistent data to keep track of 00059 * which slot numbers are available. This is only a guideline: 00060 * drivers may use the persistent data for any purpose, keeping 00061 * in mind the restrictions on when the persistent data is saved 00062 * to storage: the persistent data is only saved after calling 00063 * certain functions that receive a writable pointer to the 00064 * persistent data. 00065 * 00066 * The core allocates a memory buffer for the persistent data. 00067 * The pointer is guaranteed to be suitably aligned for any data type, 00068 * like a pointer returned by `malloc` (but the core can use any 00069 * method to allocate the buffer, not necessarily `malloc`). 00070 * 00071 * The size of this buffer is in the \c persistent_data_size field of 00072 * this structure. 00073 * 00074 * Before the driver is initialized for the first time, the content of 00075 * the persistent data is all-bits-zero. After a driver upgrade, if the 00076 * size of the persistent data has increased, the original data is padded 00077 * on the right with zeros; if the size has decreased, the original data 00078 * is truncated to the new size. 00079 * 00080 * This pointer is to read-only data. Only a few driver functions are 00081 * allowed to modify the persistent data. These functions receive a 00082 * writable pointer. These functions are: 00083 * - psa_drv_se_t::p_init 00084 * - psa_drv_se_key_management_t::p_allocate 00085 * - psa_drv_se_key_management_t::p_destroy 00086 * 00087 * The PSA Cryptography core saves the persistent data from one 00088 * session to the next. It does this before returning from API functions 00089 * that call a driver method that is allowed to modify the persistent 00090 * data, specifically: 00091 * - psa_crypto_init() causes a call to psa_drv_se_t::p_init, and may call 00092 * psa_drv_se_key_management_t::p_destroy to complete an action 00093 * that was interrupted by a power failure. 00094 * - Key creation functions cause a call to 00095 * psa_drv_se_key_management_t::p_allocate, and may cause a call to 00096 * psa_drv_se_key_management_t::p_destroy in case an error occurs. 00097 * - psa_destroy_key() causes a call to 00098 * psa_drv_se_key_management_t::p_destroy. 00099 */ 00100 const void *const persistent_data; 00101 00102 /** The size of \c persistent_data in bytes. 00103 * 00104 * This is always equal to the value of the `persistent_data_size` field 00105 * of the ::psa_drv_se_t structure when the driver is registered. 00106 */ 00107 const size_t persistent_data_size; 00108 00109 /** Driver transient data. 00110 * 00111 * The core initializes this value to 0 and does not read or modify it 00112 * afterwards. The driver may store whatever it wants in this field. 00113 */ 00114 uintptr_t transient_data; 00115 } psa_drv_se_context_t; 00116 00117 /** \brief A driver initialization function. 00118 * 00119 * \param[in,out] drv_context The driver context structure. 00120 * \param[in,out] persistent_data A pointer to the persistent data 00121 * that allows writing. 00122 * \param lifetime The lifetime value for which this driver 00123 * is registered. 00124 * 00125 * \retval #PSA_SUCCESS 00126 * The driver is operational. 00127 * The core will update the persistent data in storage. 00128 * \return 00129 * Any other return value prevents the driver from being used in 00130 * this session. 00131 * The core will NOT update the persistent data in storage. 00132 */ 00133 typedef psa_status_t (*psa_drv_se_init_t)(psa_drv_se_context_t *drv_context, 00134 void *persistent_data, 00135 psa_key_lifetime_t lifetime); 00136 00137 #if defined(__DOXYGEN_ONLY__) || !defined(MBEDTLS_PSA_CRYPTO_SE_C) 00138 /* Mbed Crypto with secure element support enabled defines this type in 00139 * crypto_types.h because it is also visible to applications through an 00140 * implementation-specific extension. 00141 * For the PSA Cryptography specification, this type is only visible 00142 * via crypto_se_driver.h. */ 00143 /** An internal designation of a key slot between the core part of the 00144 * PSA Crypto implementation and the driver. The meaning of this value 00145 * is driver-dependent. */ 00146 typedef uint64_t psa_key_slot_number_t; 00147 #endif /* __DOXYGEN_ONLY__ || !MBEDTLS_PSA_CRYPTO_SE_C */ 00148 00149 /**@}*/ 00150 00151 /** \defgroup se_mac Secure Element Message Authentication Codes 00152 * Generation and authentication of Message Authentication Codes (MACs) using 00153 * a secure element can be done either as a single function call (via the 00154 * `psa_drv_se_mac_generate_t` or `psa_drv_se_mac_verify_t` functions), or in 00155 * parts using the following sequence: 00156 * - `psa_drv_se_mac_setup_t` 00157 * - `psa_drv_se_mac_update_t` 00158 * - `psa_drv_se_mac_update_t` 00159 * - ... 00160 * - `psa_drv_se_mac_finish_t` or `psa_drv_se_mac_finish_verify_t` 00161 * 00162 * If a previously started secure element MAC operation needs to be terminated, 00163 * it should be done so by the `psa_drv_se_mac_abort_t`. Failure to do so may 00164 * result in allocated resources not being freed or in other undefined 00165 * behavior. 00166 */ 00167 /**@{*/ 00168 /** \brief A function that starts a secure element MAC operation for a PSA 00169 * Crypto Driver implementation 00170 * 00171 * \param[in,out] drv_context The driver context structure. 00172 * \param[in,out] op_context A structure that will contain the 00173 * hardware-specific MAC context 00174 * \param[in] key_slot The slot of the key to be used for the 00175 * operation 00176 * \param[in] algorithm The algorithm to be used to underly the MAC 00177 * operation 00178 * 00179 * \retval PSA_SUCCESS 00180 * Success. 00181 */ 00182 typedef psa_status_t (*psa_drv_se_mac_setup_t)(psa_drv_se_context_t *drv_context, 00183 void *op_context, 00184 psa_key_slot_number_t key_slot, 00185 psa_algorithm_t algorithm); 00186 00187 /** \brief A function that continues a previously started secure element MAC 00188 * operation 00189 * 00190 * \param[in,out] op_context A hardware-specific structure for the 00191 * previously-established MAC operation to be 00192 * updated 00193 * \param[in] p_input A buffer containing the message to be appended 00194 * to the MAC operation 00195 * \param[in] input_length The size in bytes of the input message buffer 00196 */ 00197 typedef psa_status_t (*psa_drv_se_mac_update_t)(void *op_context, 00198 const uint8_t *p_input, 00199 size_t input_length); 00200 00201 /** \brief a function that completes a previously started secure element MAC 00202 * operation by returning the resulting MAC. 00203 * 00204 * \param[in,out] op_context A hardware-specific structure for the 00205 * previously started MAC operation to be 00206 * finished 00207 * \param[out] p_mac A buffer where the generated MAC will be 00208 * placed 00209 * \param[in] mac_size The size in bytes of the buffer that has been 00210 * allocated for the `output` buffer 00211 * \param[out] p_mac_length After completion, will contain the number of 00212 * bytes placed in the `p_mac` buffer 00213 * 00214 * \retval PSA_SUCCESS 00215 * Success. 00216 */ 00217 typedef psa_status_t (*psa_drv_se_mac_finish_t)(void *op_context, 00218 uint8_t *p_mac, 00219 size_t mac_size, 00220 size_t *p_mac_length); 00221 00222 /** \brief A function that completes a previously started secure element MAC 00223 * operation by comparing the resulting MAC against a provided value 00224 * 00225 * \param[in,out] op_context A hardware-specific structure for the previously 00226 * started MAC operation to be fiinished 00227 * \param[in] p_mac The MAC value against which the resulting MAC 00228 * will be compared against 00229 * \param[in] mac_length The size in bytes of the value stored in `p_mac` 00230 * 00231 * \retval PSA_SUCCESS 00232 * The operation completed successfully and the MACs matched each 00233 * other 00234 * \retval PSA_ERROR_INVALID_SIGNATURE 00235 * The operation completed successfully, but the calculated MAC did 00236 * not match the provided MAC 00237 */ 00238 typedef psa_status_t (*psa_drv_se_mac_finish_verify_t)(void *op_context, 00239 const uint8_t *p_mac, 00240 size_t mac_length); 00241 00242 /** \brief A function that aborts a previous started secure element MAC 00243 * operation 00244 * 00245 * \param[in,out] op_context A hardware-specific structure for the previously 00246 * started MAC operation to be aborted 00247 */ 00248 typedef psa_status_t (*psa_drv_se_mac_abort_t)(void *op_context); 00249 00250 /** \brief A function that performs a secure element MAC operation in one 00251 * command and returns the calculated MAC 00252 * 00253 * \param[in,out] drv_context The driver context structure. 00254 * \param[in] p_input A buffer containing the message to be MACed 00255 * \param[in] input_length The size in bytes of `p_input` 00256 * \param[in] key_slot The slot of the key to be used 00257 * \param[in] alg The algorithm to be used to underlie the MAC 00258 * operation 00259 * \param[out] p_mac A buffer where the generated MAC will be 00260 * placed 00261 * \param[in] mac_size The size in bytes of the `p_mac` buffer 00262 * \param[out] p_mac_length After completion, will contain the number of 00263 * bytes placed in the `output` buffer 00264 * 00265 * \retval PSA_SUCCESS 00266 * Success. 00267 */ 00268 typedef psa_status_t (*psa_drv_se_mac_generate_t)(psa_drv_se_context_t *drv_context, 00269 const uint8_t *p_input, 00270 size_t input_length, 00271 psa_key_slot_number_t key_slot, 00272 psa_algorithm_t alg, 00273 uint8_t *p_mac, 00274 size_t mac_size, 00275 size_t *p_mac_length); 00276 00277 /** \brief A function that performs a secure element MAC operation in one 00278 * command and compares the resulting MAC against a provided value 00279 * 00280 * \param[in,out] drv_context The driver context structure. 00281 * \param[in] p_input A buffer containing the message to be MACed 00282 * \param[in] input_length The size in bytes of `input` 00283 * \param[in] key_slot The slot of the key to be used 00284 * \param[in] alg The algorithm to be used to underlie the MAC 00285 * operation 00286 * \param[in] p_mac The MAC value against which the resulting MAC will 00287 * be compared against 00288 * \param[in] mac_length The size in bytes of `mac` 00289 * 00290 * \retval PSA_SUCCESS 00291 * The operation completed successfully and the MACs matched each 00292 * other 00293 * \retval PSA_ERROR_INVALID_SIGNATURE 00294 * The operation completed successfully, but the calculated MAC did 00295 * not match the provided MAC 00296 */ 00297 typedef psa_status_t (*psa_drv_se_mac_verify_t)(psa_drv_se_context_t *drv_context, 00298 const uint8_t *p_input, 00299 size_t input_length, 00300 psa_key_slot_number_t key_slot, 00301 psa_algorithm_t alg, 00302 const uint8_t *p_mac, 00303 size_t mac_length); 00304 00305 /** \brief A struct containing all of the function pointers needed to 00306 * perform secure element MAC operations 00307 * 00308 * PSA Crypto API implementations should populate the table as appropriate 00309 * upon startup. 00310 * 00311 * If one of the functions is not implemented (such as 00312 * `psa_drv_se_mac_generate_t`), it should be set to NULL. 00313 * 00314 * Driver implementers should ensure that they implement all of the functions 00315 * that make sense for their hardware, and that they provide a full solution 00316 * (for example, if they support `p_setup`, they should also support 00317 * `p_update` and at least one of `p_finish` or `p_finish_verify`). 00318 * 00319 */ 00320 typedef struct { 00321 /**The size in bytes of the hardware-specific secure element MAC context 00322 * structure 00323 */ 00324 size_t context_size; 00325 /** Function that performs a MAC setup operation 00326 */ 00327 psa_drv_se_mac_setup_t p_setup; 00328 /** Function that performs a MAC update operation 00329 */ 00330 psa_drv_se_mac_update_t p_update; 00331 /** Function that completes a MAC operation 00332 */ 00333 psa_drv_se_mac_finish_t p_finish; 00334 /** Function that completes a MAC operation with a verify check 00335 */ 00336 psa_drv_se_mac_finish_verify_t p_finish_verify; 00337 /** Function that aborts a previoustly started MAC operation 00338 */ 00339 psa_drv_se_mac_abort_t p_abort; 00340 /** Function that performs a MAC operation in one call 00341 */ 00342 psa_drv_se_mac_generate_t p_mac; 00343 /** Function that performs a MAC and verify operation in one call 00344 */ 00345 psa_drv_se_mac_verify_t p_mac_verify; 00346 } psa_drv_se_mac_t; 00347 /**@}*/ 00348 00349 /** \defgroup se_cipher Secure Element Symmetric Ciphers 00350 * 00351 * Encryption and Decryption using secure element keys in block modes other 00352 * than ECB must be done in multiple parts, using the following flow: 00353 * - `psa_drv_se_cipher_setup_t` 00354 * - `psa_drv_se_cipher_set_iv_t` (optional depending upon block mode) 00355 * - `psa_drv_se_cipher_update_t` 00356 * - `psa_drv_se_cipher_update_t` 00357 * - ... 00358 * - `psa_drv_se_cipher_finish_t` 00359 * 00360 * If a previously started secure element Cipher operation needs to be 00361 * terminated, it should be done so by the `psa_drv_se_cipher_abort_t`. Failure 00362 * to do so may result in allocated resources not being freed or in other 00363 * undefined behavior. 00364 * 00365 * In situations where a PSA Cryptographic API implementation is using a block 00366 * mode not-supported by the underlying hardware or driver, it can construct 00367 * the block mode itself, while calling the `psa_drv_se_cipher_ecb_t` function 00368 * for the cipher operations. 00369 */ 00370 /**@{*/ 00371 00372 /** \brief A function that provides the cipher setup function for a 00373 * secure element driver 00374 * 00375 * \param[in,out] drv_context The driver context structure. 00376 * \param[in,out] op_context A structure that will contain the 00377 * hardware-specific cipher context. 00378 * \param[in] key_slot The slot of the key to be used for the 00379 * operation 00380 * \param[in] algorithm The algorithm to be used in the cipher 00381 * operation 00382 * \param[in] direction Indicates whether the operation is an encrypt 00383 * or decrypt 00384 * 00385 * \retval PSA_SUCCESS 00386 * \retval PSA_ERROR_NOT_SUPPORTED 00387 */ 00388 typedef psa_status_t (*psa_drv_se_cipher_setup_t)(psa_drv_se_context_t *drv_context, 00389 void *op_context, 00390 psa_key_slot_number_t key_slot, 00391 psa_algorithm_t algorithm, 00392 psa_encrypt_or_decrypt_t direction); 00393 00394 /** \brief A function that sets the initialization vector (if 00395 * necessary) for an secure element cipher operation 00396 * 00397 * Rationale: The `psa_se_cipher_*` operation in the PSA Cryptographic API has 00398 * two IV functions: one to set the IV, and one to generate it internally. The 00399 * generate function is not necessary for the drivers to implement as the PSA 00400 * Crypto implementation can do the generation using its RNG features. 00401 * 00402 * \param[in,out] op_context A structure that contains the previously set up 00403 * hardware-specific cipher context 00404 * \param[in] p_iv A buffer containing the initialization vector 00405 * \param[in] iv_length The size (in bytes) of the `p_iv` buffer 00406 * 00407 * \retval PSA_SUCCESS 00408 */ 00409 typedef psa_status_t (*psa_drv_se_cipher_set_iv_t)(void *op_context, 00410 const uint8_t *p_iv, 00411 size_t iv_length); 00412 00413 /** \brief A function that continues a previously started secure element cipher 00414 * operation 00415 * 00416 * \param[in,out] op_context A hardware-specific structure for the 00417 * previously started cipher operation 00418 * \param[in] p_input A buffer containing the data to be 00419 * encrypted/decrypted 00420 * \param[in] input_size The size in bytes of the buffer pointed to 00421 * by `p_input` 00422 * \param[out] p_output The caller-allocated buffer where the 00423 * output will be placed 00424 * \param[in] output_size The allocated size in bytes of the 00425 * `p_output` buffer 00426 * \param[out] p_output_length After completion, will contain the number 00427 * of bytes placed in the `p_output` buffer 00428 * 00429 * \retval PSA_SUCCESS 00430 */ 00431 typedef psa_status_t (*psa_drv_se_cipher_update_t)(void *op_context, 00432 const uint8_t *p_input, 00433 size_t input_size, 00434 uint8_t *p_output, 00435 size_t output_size, 00436 size_t *p_output_length); 00437 00438 /** \brief A function that completes a previously started secure element cipher 00439 * operation 00440 * 00441 * \param[in,out] op_context A hardware-specific structure for the 00442 * previously started cipher operation 00443 * \param[out] p_output The caller-allocated buffer where the output 00444 * will be placed 00445 * \param[in] output_size The allocated size in bytes of the `p_output` 00446 * buffer 00447 * \param[out] p_output_length After completion, will contain the number of 00448 * bytes placed in the `p_output` buffer 00449 * 00450 * \retval PSA_SUCCESS 00451 */ 00452 typedef psa_status_t (*psa_drv_se_cipher_finish_t)(void *op_context, 00453 uint8_t *p_output, 00454 size_t output_size, 00455 size_t *p_output_length); 00456 00457 /** \brief A function that aborts a previously started secure element cipher 00458 * operation 00459 * 00460 * \param[in,out] op_context A hardware-specific structure for the 00461 * previously started cipher operation 00462 */ 00463 typedef psa_status_t (*psa_drv_se_cipher_abort_t)(void *op_context); 00464 00465 /** \brief A function that performs the ECB block mode for secure element 00466 * cipher operations 00467 * 00468 * Note: this function should only be used with implementations that do not 00469 * provide a needed higher-level operation. 00470 * 00471 * \param[in,out] drv_context The driver context structure. 00472 * \param[in] key_slot The slot of the key to be used for the operation 00473 * \param[in] algorithm The algorithm to be used in the cipher operation 00474 * \param[in] direction Indicates whether the operation is an encrypt or 00475 * decrypt 00476 * \param[in] p_input A buffer containing the data to be 00477 * encrypted/decrypted 00478 * \param[in] input_size The size in bytes of the buffer pointed to by 00479 * `p_input` 00480 * \param[out] p_output The caller-allocated buffer where the output 00481 * will be placed 00482 * \param[in] output_size The allocated size in bytes of the `p_output` 00483 * buffer 00484 * 00485 * \retval PSA_SUCCESS 00486 * \retval PSA_ERROR_NOT_SUPPORTED 00487 */ 00488 typedef psa_status_t (*psa_drv_se_cipher_ecb_t)(psa_drv_se_context_t *drv_context, 00489 psa_key_slot_number_t key_slot, 00490 psa_algorithm_t algorithm, 00491 psa_encrypt_or_decrypt_t direction, 00492 const uint8_t *p_input, 00493 size_t input_size, 00494 uint8_t *p_output, 00495 size_t output_size); 00496 00497 /** 00498 * \brief A struct containing all of the function pointers needed to implement 00499 * cipher operations using secure elements. 00500 * 00501 * PSA Crypto API implementations should populate instances of the table as 00502 * appropriate upon startup or at build time. 00503 * 00504 * If one of the functions is not implemented (such as 00505 * `psa_drv_se_cipher_ecb_t`), it should be set to NULL. 00506 */ 00507 typedef struct { 00508 /** The size in bytes of the hardware-specific secure element cipher 00509 * context structure 00510 */ 00511 size_t context_size; 00512 /** Function that performs a cipher setup operation */ 00513 psa_drv_se_cipher_setup_t p_setup; 00514 /** Function that sets a cipher IV (if necessary) */ 00515 psa_drv_se_cipher_set_iv_t p_set_iv; 00516 /** Function that performs a cipher update operation */ 00517 psa_drv_se_cipher_update_t p_update; 00518 /** Function that completes a cipher operation */ 00519 psa_drv_se_cipher_finish_t p_finish; 00520 /** Function that aborts a cipher operation */ 00521 psa_drv_se_cipher_abort_t p_abort; 00522 /** Function that performs ECB mode for a cipher operation 00523 * (Danger: ECB mode should not be used directly by clients of the PSA 00524 * Crypto Client API) 00525 */ 00526 psa_drv_se_cipher_ecb_t p_ecb; 00527 } psa_drv_se_cipher_t; 00528 00529 /**@}*/ 00530 00531 /** \defgroup se_asymmetric Secure Element Asymmetric Cryptography 00532 * 00533 * Since the amount of data that can (or should) be encrypted or signed using 00534 * asymmetric keys is limited by the key size, asymmetric key operations using 00535 * keys in a secure element must be done in single function calls. 00536 */ 00537 /**@{*/ 00538 00539 /** 00540 * \brief A function that signs a hash or short message with a private key in 00541 * a secure element 00542 * 00543 * \param[in,out] drv_context The driver context structure. 00544 * \param[in] key_slot Key slot of an asymmetric key pair 00545 * \param[in] alg A signature algorithm that is compatible 00546 * with the type of `key` 00547 * \param[in] p_hash The hash to sign 00548 * \param[in] hash_length Size of the `p_hash` buffer in bytes 00549 * \param[out] p_signature Buffer where the signature is to be written 00550 * \param[in] signature_size Size of the `p_signature` buffer in bytes 00551 * \param[out] p_signature_length On success, the number of bytes 00552 * that make up the returned signature value 00553 * 00554 * \retval PSA_SUCCESS 00555 */ 00556 typedef psa_status_t (*psa_drv_se_asymmetric_sign_t)(psa_drv_se_context_t *drv_context, 00557 psa_key_slot_number_t key_slot, 00558 psa_algorithm_t alg, 00559 const uint8_t *p_hash, 00560 size_t hash_length, 00561 uint8_t *p_signature, 00562 size_t signature_size, 00563 size_t *p_signature_length); 00564 00565 /** 00566 * \brief A function that verifies the signature a hash or short message using 00567 * an asymmetric public key in a secure element 00568 * 00569 * \param[in,out] drv_context The driver context structure. 00570 * \param[in] key_slot Key slot of a public key or an asymmetric key 00571 * pair 00572 * \param[in] alg A signature algorithm that is compatible with 00573 * the type of `key` 00574 * \param[in] p_hash The hash whose signature is to be verified 00575 * \param[in] hash_length Size of the `p_hash` buffer in bytes 00576 * \param[in] p_signature Buffer containing the signature to verify 00577 * \param[in] signature_length Size of the `p_signature` buffer in bytes 00578 * 00579 * \retval PSA_SUCCESS 00580 * The signature is valid. 00581 */ 00582 typedef psa_status_t (*psa_drv_se_asymmetric_verify_t)(psa_drv_se_context_t *drv_context, 00583 psa_key_slot_number_t key_slot, 00584 psa_algorithm_t alg, 00585 const uint8_t *p_hash, 00586 size_t hash_length, 00587 const uint8_t *p_signature, 00588 size_t signature_length); 00589 00590 /** 00591 * \brief A function that encrypts a short message with an asymmetric public 00592 * key in a secure element 00593 * 00594 * \param[in,out] drv_context The driver context structure. 00595 * \param[in] key_slot Key slot of a public key or an asymmetric key 00596 * pair 00597 * \param[in] alg An asymmetric encryption algorithm that is 00598 * compatible with the type of `key` 00599 * \param[in] p_input The message to encrypt 00600 * \param[in] input_length Size of the `p_input` buffer in bytes 00601 * \param[in] p_salt A salt or label, if supported by the 00602 * encryption algorithm 00603 * If the algorithm does not support a 00604 * salt, pass `NULL`. 00605 * If the algorithm supports an optional 00606 * salt and you do not want to pass a salt, 00607 * pass `NULL`. 00608 * For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is 00609 * supported. 00610 * \param[in] salt_length Size of the `p_salt` buffer in bytes 00611 * If `p_salt` is `NULL`, pass 0. 00612 * \param[out] p_output Buffer where the encrypted message is to 00613 * be written 00614 * \param[in] output_size Size of the `p_output` buffer in bytes 00615 * \param[out] p_output_length On success, the number of bytes that make up 00616 * the returned output 00617 * 00618 * \retval PSA_SUCCESS 00619 */ 00620 typedef psa_status_t (*psa_drv_se_asymmetric_encrypt_t)(psa_drv_se_context_t *drv_context, 00621 psa_key_slot_number_t key_slot, 00622 psa_algorithm_t alg, 00623 const uint8_t *p_input, 00624 size_t input_length, 00625 const uint8_t *p_salt, 00626 size_t salt_length, 00627 uint8_t *p_output, 00628 size_t output_size, 00629 size_t *p_output_length); 00630 00631 /** 00632 * \brief A function that decrypts a short message with an asymmetric private 00633 * key in a secure element. 00634 * 00635 * \param[in,out] drv_context The driver context structure. 00636 * \param[in] key_slot Key slot of an asymmetric key pair 00637 * \param[in] alg An asymmetric encryption algorithm that is 00638 * compatible with the type of `key` 00639 * \param[in] p_input The message to decrypt 00640 * \param[in] input_length Size of the `p_input` buffer in bytes 00641 * \param[in] p_salt A salt or label, if supported by the 00642 * encryption algorithm 00643 * If the algorithm does not support a 00644 * salt, pass `NULL`. 00645 * If the algorithm supports an optional 00646 * salt and you do not want to pass a salt, 00647 * pass `NULL`. 00648 * For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is 00649 * supported. 00650 * \param[in] salt_length Size of the `p_salt` buffer in bytes 00651 * If `p_salt` is `NULL`, pass 0. 00652 * \param[out] p_output Buffer where the decrypted message is to 00653 * be written 00654 * \param[in] output_size Size of the `p_output` buffer in bytes 00655 * \param[out] p_output_length On success, the number of bytes 00656 * that make up the returned output 00657 * 00658 * \retval PSA_SUCCESS 00659 */ 00660 typedef psa_status_t (*psa_drv_se_asymmetric_decrypt_t)(psa_drv_se_context_t *drv_context, 00661 psa_key_slot_number_t key_slot, 00662 psa_algorithm_t alg, 00663 const uint8_t *p_input, 00664 size_t input_length, 00665 const uint8_t *p_salt, 00666 size_t salt_length, 00667 uint8_t *p_output, 00668 size_t output_size, 00669 size_t *p_output_length); 00670 00671 /** 00672 * \brief A struct containing all of the function pointers needed to implement 00673 * asymmetric cryptographic operations using secure elements. 00674 * 00675 * PSA Crypto API implementations should populate instances of the table as 00676 * appropriate upon startup or at build time. 00677 * 00678 * If one of the functions is not implemented, it should be set to NULL. 00679 */ 00680 typedef struct { 00681 /** Function that performs an asymmetric sign operation */ 00682 psa_drv_se_asymmetric_sign_t p_sign; 00683 /** Function that performs an asymmetric verify operation */ 00684 psa_drv_se_asymmetric_verify_t p_verify; 00685 /** Function that performs an asymmetric encrypt operation */ 00686 psa_drv_se_asymmetric_encrypt_t p_encrypt; 00687 /** Function that performs an asymmetric decrypt operation */ 00688 psa_drv_se_asymmetric_decrypt_t p_decrypt; 00689 } psa_drv_se_asymmetric_t; 00690 00691 /**@}*/ 00692 00693 /** \defgroup se_aead Secure Element Authenticated Encryption with Additional Data 00694 * Authenticated Encryption with Additional Data (AEAD) operations with secure 00695 * elements must be done in one function call. While this creates a burden for 00696 * implementers as there must be sufficient space in memory for the entire 00697 * message, it prevents decrypted data from being made available before the 00698 * authentication operation is complete and the data is known to be authentic. 00699 */ 00700 /**@{*/ 00701 00702 /** \brief A function that performs a secure element authenticated encryption 00703 * operation 00704 * 00705 * \param[in,out] drv_context The driver context structure. 00706 * \param[in] key_slot Slot containing the key to use. 00707 * \param[in] algorithm The AEAD algorithm to compute 00708 * (\c PSA_ALG_XXX value such that 00709 * #PSA_ALG_IS_AEAD(`alg`) is true) 00710 * \param[in] p_nonce Nonce or IV to use 00711 * \param[in] nonce_length Size of the `p_nonce` buffer in bytes 00712 * \param[in] p_additional_data Additional data that will be 00713 * authenticated but not encrypted 00714 * \param[in] additional_data_length Size of `p_additional_data` in bytes 00715 * \param[in] p_plaintext Data that will be authenticated and 00716 * encrypted 00717 * \param[in] plaintext_length Size of `p_plaintext` in bytes 00718 * \param[out] p_ciphertext Output buffer for the authenticated and 00719 * encrypted data. The additional data is 00720 * not part of this output. For algorithms 00721 * where the encrypted data and the 00722 * authentication tag are defined as 00723 * separate outputs, the authentication 00724 * tag is appended to the encrypted data. 00725 * \param[in] ciphertext_size Size of the `p_ciphertext` buffer in 00726 * bytes 00727 * \param[out] p_ciphertext_length On success, the size of the output in 00728 * the `p_ciphertext` buffer 00729 * 00730 * \retval #PSA_SUCCESS 00731 * Success. 00732 */ 00733 typedef psa_status_t (*psa_drv_se_aead_encrypt_t)(psa_drv_se_context_t *drv_context, 00734 psa_key_slot_number_t key_slot, 00735 psa_algorithm_t algorithm, 00736 const uint8_t *p_nonce, 00737 size_t nonce_length, 00738 const uint8_t *p_additional_data, 00739 size_t additional_data_length, 00740 const uint8_t *p_plaintext, 00741 size_t plaintext_length, 00742 uint8_t *p_ciphertext, 00743 size_t ciphertext_size, 00744 size_t *p_ciphertext_length); 00745 00746 /** A function that peforms a secure element authenticated decryption operation 00747 * 00748 * \param[in,out] drv_context The driver context structure. 00749 * \param[in] key_slot Slot containing the key to use 00750 * \param[in] algorithm The AEAD algorithm to compute 00751 * (\c PSA_ALG_XXX value such that 00752 * #PSA_ALG_IS_AEAD(`alg`) is true) 00753 * \param[in] p_nonce Nonce or IV to use 00754 * \param[in] nonce_length Size of the `p_nonce` buffer in bytes 00755 * \param[in] p_additional_data Additional data that has been 00756 * authenticated but not encrypted 00757 * \param[in] additional_data_length Size of `p_additional_data` in bytes 00758 * \param[in] p_ciphertext Data that has been authenticated and 00759 * encrypted. 00760 * For algorithms where the encrypted data 00761 * and the authentication tag are defined 00762 * as separate inputs, the buffer must 00763 * contain the encrypted data followed by 00764 * the authentication tag. 00765 * \param[in] ciphertext_length Size of `p_ciphertext` in bytes 00766 * \param[out] p_plaintext Output buffer for the decrypted data 00767 * \param[in] plaintext_size Size of the `p_plaintext` buffer in 00768 * bytes 00769 * \param[out] p_plaintext_length On success, the size of the output in 00770 * the `p_plaintext` buffer 00771 * 00772 * \retval #PSA_SUCCESS 00773 * Success. 00774 */ 00775 typedef psa_status_t (*psa_drv_se_aead_decrypt_t)(psa_drv_se_context_t *drv_context, 00776 psa_key_slot_number_t key_slot, 00777 psa_algorithm_t algorithm, 00778 const uint8_t *p_nonce, 00779 size_t nonce_length, 00780 const uint8_t *p_additional_data, 00781 size_t additional_data_length, 00782 const uint8_t *p_ciphertext, 00783 size_t ciphertext_length, 00784 uint8_t *p_plaintext, 00785 size_t plaintext_size, 00786 size_t *p_plaintext_length); 00787 00788 /** 00789 * \brief A struct containing all of the function pointers needed to implement 00790 * secure element Authenticated Encryption with Additional Data operations 00791 * 00792 * PSA Crypto API implementations should populate instances of the table as 00793 * appropriate upon startup. 00794 * 00795 * If one of the functions is not implemented, it should be set to NULL. 00796 */ 00797 typedef struct { 00798 /** Function that performs the AEAD encrypt operation */ 00799 psa_drv_se_aead_encrypt_t p_encrypt; 00800 /** Function that performs the AEAD decrypt operation */ 00801 psa_drv_se_aead_decrypt_t p_decrypt; 00802 } psa_drv_se_aead_t; 00803 /**@}*/ 00804 00805 /** \defgroup se_key_management Secure Element Key Management 00806 * Currently, key management is limited to importing keys in the clear, 00807 * destroying keys, and exporting keys in the clear. 00808 * Whether a key may be exported is determined by the key policies in place 00809 * on the key slot. 00810 */ 00811 /**@{*/ 00812 00813 /** An enumeration indicating how a key is created. 00814 */ 00815 typedef enum 00816 { 00817 PSA_KEY_CREATION_IMPORT, /**< During psa_import_key() */ 00818 PSA_KEY_CREATION_GENERATE, /**< During psa_generate_key() */ 00819 PSA_KEY_CREATION_DERIVE, /**< During psa_key_derivation_output_key() */ 00820 PSA_KEY_CREATION_COPY, /**< During psa_copy_key() */ 00821 00822 #ifndef __DOXYGEN_ONLY__ 00823 /** A key is being registered with mbedtls_psa_register_se_key(). 00824 * 00825 * The core only passes this value to 00826 * psa_drv_se_key_management_t::p_validate_slot_number, not to 00827 * psa_drv_se_key_management_t::p_allocate. The call to 00828 * `p_validate_slot_number` is not followed by any other call to the 00829 * driver: the key is considered successfully registered if the call to 00830 * `p_validate_slot_number` succeeds, or if `p_validate_slot_number` is 00831 * null. 00832 * 00833 * With this creation method, the driver must return #PSA_SUCCESS if 00834 * the given attributes are compatible with the existing key in the slot, 00835 * and #PSA_ERROR_DOES_NOT_EXIST if the driver can determine that there 00836 * is no key with the specified slot number. 00837 * 00838 * This is an Mbed Crypto extension. 00839 */ 00840 PSA_KEY_CREATION_REGISTER, 00841 #endif 00842 } psa_key_creation_method_t; 00843 00844 /** \brief A function that allocates a slot for a key. 00845 * 00846 * To create a key in a specific slot in a secure element, the core 00847 * first calls this function to determine a valid slot number, 00848 * then calls a function to create the key material in that slot. 00849 * In nominal conditions (that is, if no error occurs), 00850 * the effect of a call to a key creation function in the PSA Cryptography 00851 * API with a lifetime that places the key in a secure element is the 00852 * following: 00853 * -# The core calls psa_drv_se_key_management_t::p_allocate 00854 * (or in some implementations 00855 * psa_drv_se_key_management_t::p_validate_slot_number). The driver 00856 * selects (or validates) a suitable slot number given the key attributes 00857 * and the state of the secure element. 00858 * -# The core calls a key creation function in the driver. 00859 * 00860 * The key creation functions in the PSA Cryptography API are: 00861 * - psa_import_key(), which causes 00862 * a call to `p_allocate` with \p method = #PSA_KEY_CREATION_IMPORT 00863 * then a call to psa_drv_se_key_management_t::p_import. 00864 * - psa_generate_key(), which causes 00865 * a call to `p_allocate` with \p method = #PSA_KEY_CREATION_GENERATE 00866 * then a call to psa_drv_se_key_management_t::p_import. 00867 * - psa_key_derivation_output_key(), which causes 00868 * a call to `p_allocate` with \p method = #PSA_KEY_CREATION_DERIVE 00869 * then a call to psa_drv_se_key_derivation_t::p_derive. 00870 * - psa_copy_key(), which causes 00871 * a call to `p_allocate` with \p method = #PSA_KEY_CREATION_COPY 00872 * then a call to psa_drv_se_key_management_t::p_export. 00873 * 00874 * In case of errors, other behaviors are possible. 00875 * - If the PSA Cryptography subsystem dies after the first step, 00876 * for example because the device has lost power abruptly, 00877 * the second step may never happen, or may happen after a reset 00878 * and re-initialization. Alternatively, after a reset and 00879 * re-initialization, the core may call 00880 * psa_drv_se_key_management_t::p_destroy on the slot number that 00881 * was allocated (or validated) instead of calling a key creation function. 00882 * - If an error occurs, the core may call 00883 * psa_drv_se_key_management_t::p_destroy on the slot number that 00884 * was allocated (or validated) instead of calling a key creation function. 00885 * 00886 * Errors and system resets also have an impact on the driver's persistent 00887 * data. If a reset happens before the overall key creation process is 00888 * completed (before or after the second step above), it is unspecified 00889 * whether the persistent data after the reset is identical to what it 00890 * was before or after the call to `p_allocate` (or `p_validate_slot_number`). 00891 * 00892 * \param[in,out] drv_context The driver context structure. 00893 * \param[in,out] persistent_data A pointer to the persistent data 00894 * that allows writing. 00895 * \param[in] attributes Attributes of the key. 00896 * \param method The way in which the key is being created. 00897 * \param[out] key_slot Slot where the key will be stored. 00898 * This must be a valid slot for a key of the 00899 * chosen type. It must be unoccupied. 00900 * 00901 * \retval #PSA_SUCCESS 00902 * Success. 00903 * The core will record \c *key_slot as the key slot where the key 00904 * is stored and will update the persistent data in storage. 00905 * \retval #PSA_ERROR_NOT_SUPPORTED 00906 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE 00907 */ 00908 typedef psa_status_t (*psa_drv_se_allocate_key_t)( 00909 psa_drv_se_context_t *drv_context, 00910 void *persistent_data, 00911 const psa_key_attributes_t *attributes, 00912 psa_key_creation_method_t method, 00913 psa_key_slot_number_t *key_slot); 00914 00915 /** \brief A function that determines whether a slot number is valid 00916 * for a key. 00917 * 00918 * To create a key in a specific slot in a secure element, the core 00919 * first calls this function to validate the choice of slot number, 00920 * then calls a function to create the key material in that slot. 00921 * See the documentation of #psa_drv_se_allocate_key_t for more details. 00922 * 00923 * As of the PSA Cryptography API specification version 1.0, there is no way 00924 * for applications to trigger a call to this function. However some 00925 * implementations offer the capability to create or declare a key in 00926 * a specific slot via implementation-specific means, generally for the 00927 * sake of initial device provisioning or onboarding. Such a mechanism may 00928 * be added to a future version of the PSA Cryptography API specification. 00929 * 00930 * This function may update the driver's persistent data through 00931 * \p persistent_data. The core will save the updated persistent data at the 00932 * end of the key creation process. See the description of 00933 * ::psa_drv_se_allocate_key_t for more information. 00934 * 00935 * \param[in,out] drv_context The driver context structure. 00936 * \param[in,out] persistent_data A pointer to the persistent data 00937 * that allows writing. 00938 * \param[in] attributes Attributes of the key. 00939 * \param method The way in which the key is being created. 00940 * \param[in] key_slot Slot where the key is to be stored. 00941 * 00942 * \retval #PSA_SUCCESS 00943 * The given slot number is valid for a key with the given 00944 * attributes. 00945 * \retval #PSA_ERROR_INVALID_ARGUMENT 00946 * The given slot number is not valid for a key with the 00947 * given attributes. This includes the case where the slot 00948 * number is not valid at all. 00949 * \retval #PSA_ERROR_ALREADY_EXISTS 00950 * There is already a key with the specified slot number. 00951 * Drivers may choose to return this error from the key 00952 * creation function instead. 00953 */ 00954 typedef psa_status_t (*psa_drv_se_validate_slot_number_t)( 00955 psa_drv_se_context_t *drv_context, 00956 void *persistent_data, 00957 const psa_key_attributes_t *attributes, 00958 psa_key_creation_method_t method, 00959 psa_key_slot_number_t key_slot); 00960 00961 /** \brief A function that imports a key into a secure element in binary format 00962 * 00963 * This function can support any output from psa_export_key(). Refer to the 00964 * documentation of psa_export_key() for the format for each key type. 00965 * 00966 * \param[in,out] drv_context The driver context structure. 00967 * \param key_slot Slot where the key will be stored. 00968 * This must be a valid slot for a key of the 00969 * chosen type. It must be unoccupied. 00970 * \param[in] attributes The key attributes, including the lifetime, 00971 * the key type and the usage policy. 00972 * Drivers should not access the key size stored 00973 * in the attributes: it may not match the 00974 * data passed in \p data. 00975 * Drivers can call psa_get_key_lifetime(), 00976 * psa_get_key_type(), 00977 * psa_get_key_usage_flags() and 00978 * psa_get_key_algorithm() to access this 00979 * information. 00980 * \param[in] data Buffer containing the key data. 00981 * \param[in] data_length Size of the \p data buffer in bytes. 00982 * \param[out] bits On success, the key size in bits. The driver 00983 * must determine this value after parsing the 00984 * key according to the key type. 00985 * This value is not used if the function fails. 00986 * 00987 * \retval #PSA_SUCCESS 00988 * Success. 00989 */ 00990 typedef psa_status_t (*psa_drv_se_import_key_t)( 00991 psa_drv_se_context_t *drv_context, 00992 psa_key_slot_number_t key_slot, 00993 const psa_key_attributes_t *attributes, 00994 const uint8_t *data, 00995 size_t data_length, 00996 size_t *bits); 00997 00998 /** 00999 * \brief A function that destroys a secure element key and restore the slot to 01000 * its default state 01001 * 01002 * This function destroys the content of the key from a secure element. 01003 * Implementations shall make a best effort to ensure that any previous content 01004 * of the slot is unrecoverable. 01005 * 01006 * This function returns the specified slot to its default state. 01007 * 01008 * \param[in,out] drv_context The driver context structure. 01009 * \param[in,out] persistent_data A pointer to the persistent data 01010 * that allows writing. 01011 * \param key_slot The key slot to erase. 01012 * 01013 * \retval #PSA_SUCCESS 01014 * The slot's content, if any, has been erased. 01015 */ 01016 typedef psa_status_t (*psa_drv_se_destroy_key_t)( 01017 psa_drv_se_context_t *drv_context, 01018 void *persistent_data, 01019 psa_key_slot_number_t key_slot); 01020 01021 /** 01022 * \brief A function that exports a secure element key in binary format 01023 * 01024 * The output of this function can be passed to psa_import_key() to 01025 * create an equivalent object. 01026 * 01027 * If a key is created with `psa_import_key()` and then exported with 01028 * this function, it is not guaranteed that the resulting data is 01029 * identical: the implementation may choose a different representation 01030 * of the same key if the format permits it. 01031 * 01032 * This function should generate output in the same format that 01033 * `psa_export_key()` does. Refer to the 01034 * documentation of `psa_export_key()` for the format for each key type. 01035 * 01036 * \param[in,out] drv_context The driver context structure. 01037 * \param[in] key Slot whose content is to be exported. This must 01038 * be an occupied key slot. 01039 * \param[out] p_data Buffer where the key data is to be written. 01040 * \param[in] data_size Size of the `p_data` buffer in bytes. 01041 * \param[out] p_data_length On success, the number of bytes 01042 * that make up the key data. 01043 * 01044 * \retval #PSA_SUCCESS 01045 * \retval #PSA_ERROR_DOES_NOT_EXIST 01046 * \retval #PSA_ERROR_NOT_PERMITTED 01047 * \retval #PSA_ERROR_NOT_SUPPORTED 01048 * \retval #PSA_ERROR_COMMUNICATION_FAILURE 01049 * \retval #PSA_ERROR_HARDWARE_FAILURE 01050 * \retval #PSA_ERROR_CORRUPTION_DETECTED 01051 */ 01052 typedef psa_status_t (*psa_drv_se_export_key_t)(psa_drv_se_context_t *drv_context, 01053 psa_key_slot_number_t key, 01054 uint8_t *p_data, 01055 size_t data_size, 01056 size_t *p_data_length); 01057 01058 /** 01059 * \brief A function that generates a symmetric or asymmetric key on a secure 01060 * element 01061 * 01062 * If \p type is asymmetric (#PSA_KEY_TYPE_IS_ASYMMETRIC(\p type) = 1), 01063 * the driver may export the public key at the time of generation, 01064 * in the format documented for psa_export_public_key() by writing it 01065 * to the \p pubkey buffer. 01066 * This is optional, intended for secure elements that output the 01067 * public key at generation time and that cannot export the public key 01068 * later. Drivers that do not need this feature should leave 01069 * \p *pubkey_length set to 0 and should 01070 * implement the psa_drv_key_management_t::p_export_public function. 01071 * Some implementations do not support this feature, in which case 01072 * \p pubkey is \c NULL and \p pubkey_size is 0. 01073 * 01074 * \param[in,out] drv_context The driver context structure. 01075 * \param key_slot Slot where the key will be stored. 01076 * This must be a valid slot for a key of the 01077 * chosen type. It must be unoccupied. 01078 * \param[in] attributes The key attributes, including the lifetime, 01079 * the key type and size, and the usage policy. 01080 * Drivers can call psa_get_key_lifetime(), 01081 * psa_get_key_type(), psa_get_key_bits(), 01082 * psa_get_key_usage_flags() and 01083 * psa_get_key_algorithm() to access this 01084 * information. 01085 * \param[out] pubkey A buffer where the driver can write the 01086 * public key, when generating an asymmetric 01087 * key pair. 01088 * This is \c NULL when generating a symmetric 01089 * key or if the core does not support 01090 * exporting the public key at generation time. 01091 * \param pubkey_size The size of the `pubkey` buffer in bytes. 01092 * This is 0 when generating a symmetric 01093 * key or if the core does not support 01094 * exporting the public key at generation time. 01095 * \param[out] pubkey_length On entry, this is always 0. 01096 * On success, the number of bytes written to 01097 * \p pubkey. If this is 0 or unchanged on return, 01098 * the core will not read the \p pubkey buffer, 01099 * and will instead call the driver's 01100 * psa_drv_key_management_t::p_export_public 01101 * function to export the public key when needed. 01102 */ 01103 typedef psa_status_t (*psa_drv_se_generate_key_t)( 01104 psa_drv_se_context_t *drv_context, 01105 psa_key_slot_number_t key_slot, 01106 const psa_key_attributes_t *attributes, 01107 uint8_t *pubkey, size_t pubkey_size, size_t *pubkey_length); 01108 01109 /** 01110 * \brief A struct containing all of the function pointers needed to for secure 01111 * element key management 01112 * 01113 * PSA Crypto API implementations should populate instances of the table as 01114 * appropriate upon startup or at build time. 01115 * 01116 * If one of the functions is not implemented, it should be set to NULL. 01117 */ 01118 typedef struct { 01119 /** Function that allocates a slot for a key. */ 01120 psa_drv_se_allocate_key_t p_allocate; 01121 /** Function that checks the validity of a slot for a key. */ 01122 psa_drv_se_validate_slot_number_t p_validate_slot_number; 01123 /** Function that performs a key import operation */ 01124 psa_drv_se_import_key_t p_import; 01125 /** Function that performs a generation */ 01126 psa_drv_se_generate_key_t p_generate; 01127 /** Function that performs a key destroy operation */ 01128 psa_drv_se_destroy_key_t p_destroy; 01129 /** Function that performs a key export operation */ 01130 psa_drv_se_export_key_t p_export; 01131 /** Function that performs a public key export operation */ 01132 psa_drv_se_export_key_t p_export_public; 01133 } psa_drv_se_key_management_t; 01134 01135 /**@}*/ 01136 01137 /** \defgroup driver_derivation Secure Element Key Derivation and Agreement 01138 * Key derivation is the process of generating new key material using an 01139 * existing key and additional parameters, iterating through a basic 01140 * cryptographic function, such as a hash. 01141 * Key agreement is a part of cryptographic protocols that allows two parties 01142 * to agree on the same key value, but starting from different original key 01143 * material. 01144 * The flows are similar, and the PSA Crypto Driver Model uses the same functions 01145 * for both of the flows. 01146 * 01147 * There are two different final functions for the flows, 01148 * `psa_drv_se_key_derivation_derive` and `psa_drv_se_key_derivation_export`. 01149 * `psa_drv_se_key_derivation_derive` is used when the key material should be 01150 * placed in a slot on the hardware and not exposed to the caller. 01151 * `psa_drv_se_key_derivation_export` is used when the key material should be 01152 * returned to the PSA Cryptographic API implementation. 01153 * 01154 * Different key derivation algorithms require a different number of inputs. 01155 * Instead of having an API that takes as input variable length arrays, which 01156 * can be problemmatic to manage on embedded platforms, the inputs are passed 01157 * to the driver via a function, `psa_drv_se_key_derivation_collateral`, that 01158 * is called multiple times with different `collateral_id`s. Thus, for a key 01159 * derivation algorithm that required 3 paramter inputs, the flow would look 01160 * something like: 01161 * ~~~~~~~~~~~~~{.c} 01162 * psa_drv_se_key_derivation_setup(kdf_algorithm, source_key, dest_key_size_bytes); 01163 * psa_drv_se_key_derivation_collateral(kdf_algorithm_collateral_id_0, 01164 * p_collateral_0, 01165 * collateral_0_size); 01166 * psa_drv_se_key_derivation_collateral(kdf_algorithm_collateral_id_1, 01167 * p_collateral_1, 01168 * collateral_1_size); 01169 * psa_drv_se_key_derivation_collateral(kdf_algorithm_collateral_id_2, 01170 * p_collateral_2, 01171 * collateral_2_size); 01172 * psa_drv_se_key_derivation_derive(); 01173 * ~~~~~~~~~~~~~ 01174 * 01175 * key agreement example: 01176 * ~~~~~~~~~~~~~{.c} 01177 * psa_drv_se_key_derivation_setup(alg, source_key. dest_key_size_bytes); 01178 * psa_drv_se_key_derivation_collateral(DHE_PUBKEY, p_pubkey, pubkey_size); 01179 * psa_drv_se_key_derivation_export(p_session_key, 01180 * session_key_size, 01181 * &session_key_length); 01182 * ~~~~~~~~~~~~~ 01183 */ 01184 /**@{*/ 01185 01186 /** \brief A function that Sets up a secure element key derivation operation by 01187 * specifying the algorithm and the source key sot 01188 * 01189 * \param[in,out] drv_context The driver context structure. 01190 * \param[in,out] op_context A hardware-specific structure containing any 01191 * context information for the implementation 01192 * \param[in] kdf_alg The algorithm to be used for the key derivation 01193 * \param[in] source_key The key to be used as the source material for 01194 * the key derivation 01195 * 01196 * \retval PSA_SUCCESS 01197 */ 01198 typedef psa_status_t (*psa_drv_se_key_derivation_setup_t)(psa_drv_se_context_t *drv_context, 01199 void *op_context, 01200 psa_algorithm_t kdf_alg, 01201 psa_key_slot_number_t source_key); 01202 01203 /** \brief A function that provides collateral (parameters) needed for a secure 01204 * element key derivation or key agreement operation 01205 * 01206 * Since many key derivation algorithms require multiple parameters, it is 01207 * expeced that this function may be called multiple times for the same 01208 * operation, each with a different algorithm-specific `collateral_id` 01209 * 01210 * \param[in,out] op_context A hardware-specific structure containing any 01211 * context information for the implementation 01212 * \param[in] collateral_id An ID for the collateral being provided 01213 * \param[in] p_collateral A buffer containing the collateral data 01214 * \param[in] collateral_size The size in bytes of the collateral 01215 * 01216 * \retval PSA_SUCCESS 01217 */ 01218 typedef psa_status_t (*psa_drv_se_key_derivation_collateral_t)(void *op_context, 01219 uint32_t collateral_id, 01220 const uint8_t *p_collateral, 01221 size_t collateral_size); 01222 01223 /** \brief A function that performs the final secure element key derivation 01224 * step and place the generated key material in a slot 01225 * 01226 * \param[in,out] op_context A hardware-specific structure containing any 01227 * context information for the implementation 01228 * \param[in] dest_key The slot where the generated key material 01229 * should be placed 01230 * 01231 * \retval PSA_SUCCESS 01232 */ 01233 typedef psa_status_t (*psa_drv_se_key_derivation_derive_t)(void *op_context, 01234 psa_key_slot_number_t dest_key); 01235 01236 /** \brief A function that performs the final step of a secure element key 01237 * agreement and place the generated key material in a buffer 01238 * 01239 * \param[out] p_output Buffer in which to place the generated key 01240 * material 01241 * \param[in] output_size The size in bytes of `p_output` 01242 * \param[out] p_output_length Upon success, contains the number of bytes of 01243 * key material placed in `p_output` 01244 * 01245 * \retval PSA_SUCCESS 01246 */ 01247 typedef psa_status_t (*psa_drv_se_key_derivation_export_t)(void *op_context, 01248 uint8_t *p_output, 01249 size_t output_size, 01250 size_t *p_output_length); 01251 01252 /** 01253 * \brief A struct containing all of the function pointers needed to for secure 01254 * element key derivation and agreement 01255 * 01256 * PSA Crypto API implementations should populate instances of the table as 01257 * appropriate upon startup. 01258 * 01259 * If one of the functions is not implemented, it should be set to NULL. 01260 */ 01261 typedef struct { 01262 /** The driver-specific size of the key derivation context */ 01263 size_t context_size; 01264 /** Function that performs a key derivation setup */ 01265 psa_drv_se_key_derivation_setup_t p_setup; 01266 /** Function that sets key derivation collateral */ 01267 psa_drv_se_key_derivation_collateral_t p_collateral; 01268 /** Function that performs a final key derivation step */ 01269 psa_drv_se_key_derivation_derive_t p_derive; 01270 /** Function that perforsm a final key derivation or agreement and 01271 * exports the key */ 01272 psa_drv_se_key_derivation_export_t p_export; 01273 } psa_drv_se_key_derivation_t; 01274 01275 /**@}*/ 01276 01277 /** \defgroup se_registration Secure element driver registration 01278 */ 01279 /**@{*/ 01280 01281 /** A structure containing pointers to all the entry points of a 01282 * secure element driver. 01283 * 01284 * Future versions of this specification may add extra substructures at 01285 * the end of this structure. 01286 */ 01287 typedef struct { 01288 /** The version of the driver HAL that this driver implements. 01289 * This is a protection against loading driver binaries built against 01290 * a different version of this specification. 01291 * Use #PSA_DRV_SE_HAL_VERSION. 01292 */ 01293 uint32_t hal_version; 01294 01295 /** The size of the driver's persistent data in bytes. 01296 * 01297 * This can be 0 if the driver does not need persistent data. 01298 * 01299 * See the documentation of psa_drv_se_context_t::persistent_data 01300 * for more information about why and how a driver can use 01301 * persistent data. 01302 */ 01303 size_t persistent_data_size; 01304 01305 /** The driver initialization function. 01306 * 01307 * This function is called once during the initialization of the 01308 * PSA Cryptography subsystem, before any other function of the 01309 * driver is called. If this function returns a failure status, 01310 * the driver will be unusable, at least until the next system reset. 01311 * 01312 * If this field is \c NULL, it is equivalent to a function that does 01313 * nothing and returns #PSA_SUCCESS. 01314 */ 01315 psa_drv_se_init_t p_init; 01316 01317 const psa_drv_se_key_management_t *key_management; 01318 const psa_drv_se_mac_t *mac; 01319 const psa_drv_se_cipher_t *cipher; 01320 const psa_drv_se_aead_t *aead; 01321 const psa_drv_se_asymmetric_t *asymmetric; 01322 const psa_drv_se_key_derivation_t *derivation; 01323 } psa_drv_se_t; 01324 01325 /** The current version of the secure element driver HAL. 01326 */ 01327 /* 0.0.0 patchlevel 5 */ 01328 #define PSA_DRV_SE_HAL_VERSION 0x00000005 01329 01330 /** Register an external cryptoprocessor (secure element) driver. 01331 * 01332 * This function is only intended to be used by driver code, not by 01333 * application code. In implementations with separation between the 01334 * PSA cryptography module and applications, this function should 01335 * only be available to callers that run in the same memory space as 01336 * the cryptography module, and should not be exposed to applications 01337 * running in a different memory space. 01338 * 01339 * This function may be called before psa_crypto_init(). It is 01340 * implementation-defined whether this function may be called 01341 * after psa_crypto_init(). 01342 * 01343 * \note Implementations store metadata about keys including the lifetime 01344 * value. Therefore, from one instantiation of the PSA Cryptography 01345 * library to the next one, if there is a key in storage with a certain 01346 * lifetime value, you must always register the same driver (or an 01347 * updated version that communicates with the same secure element) 01348 * with the same lifetime value. 01349 * 01350 * \param lifetime The lifetime value through which this driver will 01351 * be exposed to applications. 01352 * The values #PSA_KEY_LIFETIME_VOLATILE and 01353 * #PSA_KEY_LIFETIME_PERSISTENT are reserved and 01354 * may not be used for drivers. Implementations 01355 * may reserve other values. 01356 * \param[in] methods The method table of the driver. This structure must 01357 * remain valid for as long as the cryptography 01358 * module keeps running. It is typically a global 01359 * constant. 01360 * 01361 * \return PSA_SUCCESS 01362 * The driver was successfully registered. Applications can now 01363 * use \p lifetime to access keys through the methods passed to 01364 * this function. 01365 * \return PSA_ERROR_BAD_STATE 01366 * This function was called after the initialization of the 01367 * cryptography module, and this implementation does not support 01368 * driver registration at this stage. 01369 * \return PSA_ERROR_ALREADY_EXISTS 01370 * There is already a registered driver for this value of \p lifetime. 01371 * \return PSA_ERROR_INVALID_ARGUMENT 01372 * \p lifetime is a reserved value. 01373 * \return PSA_ERROR_NOT_SUPPORTED 01374 * `methods->hal_version` is not supported by this implementation. 01375 * \return PSA_ERROR_INSUFFICIENT_MEMORY 01376 * \return PSA_ERROR_NOT_PERMITTED 01377 */ 01378 psa_status_t psa_register_se_driver( 01379 psa_key_lifetime_t lifetime, 01380 const psa_drv_se_t *methods); 01381 01382 /**@}*/ 01383 01384 #ifdef __cplusplus 01385 } 01386 #endif 01387 01388 #endif /* PSA_CRYPTO_SE_DRIVER_H */
Generated on Tue Jul 12 2022 13:54:14 by
1.7.2