1 /* 2 * PSA crypto support for secure element drivers 3 */ 4 /* 5 * Copyright The Mbed TLS Contributors 6 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 7 */ 8 9 #ifndef PSA_CRYPTO_SE_H 10 #define PSA_CRYPTO_SE_H 11 12 /* 13 * Include the build-time configuration information header. Here, we do not 14 * include `"mbedtls/build_info.h"` directly but `"psa/build_info.h"`, which 15 * is basically just an alias to it. This is to ease the maintenance of the 16 * TF-PSA-Crypto repository which has a different build system and 17 * configuration. 18 */ 19 #include "psa/build_info.h" 20 21 #include "psa/crypto.h" 22 #include "psa/crypto_se_driver.h" 23 24 /** The maximum location value that this implementation supports 25 * for a secure element. 26 * 27 * This is not a characteristic that each PSA implementation has, but a 28 * limitation of the current implementation due to the constraints imposed 29 * by storage. See #PSA_CRYPTO_SE_DRIVER_ITS_UID_BASE. 30 * 31 * The minimum location value for a secure element is 1, like on any 32 * PSA implementation (0 means a transparent key). 33 */ 34 #define PSA_MAX_SE_LOCATION 255 35 36 /** The base of the range of ITS file identifiers for secure element 37 * driver persistent data. 38 * 39 * We use a slice of the implementation reserved range 0xffff0000..0xffffffff, 40 * specifically the range 0xfffffe00..0xfffffeff. The length of this range 41 * drives the value of #PSA_MAX_SE_LOCATION. The identifier 0xfffffe00 is 42 * actually not used since it corresponds to #PSA_KEY_LOCATION_LOCAL_STORAGE 43 * which doesn't have a driver. 44 */ 45 #define PSA_CRYPTO_SE_DRIVER_ITS_UID_BASE ((psa_key_id_t) 0xfffffe00) 46 47 /** The maximum number of registered secure element driver locations. */ 48 #define PSA_MAX_SE_DRIVERS 4 49 50 /** Unregister all secure element drivers. 51 * 52 * \warning Do not call this function while the library is in the initialized 53 * state. This function is only intended to be called at the end 54 * of mbedtls_psa_crypto_free(). 55 */ 56 void psa_unregister_all_se_drivers(void); 57 58 /** Initialize all secure element drivers. 59 * 60 * Called from psa_crypto_init(). 61 */ 62 psa_status_t psa_init_all_se_drivers(void); 63 64 /** A structure that describes a registered secure element driver. 65 * 66 * A secure element driver table entry contains a pointer to the 67 * driver's method table as well as the driver context structure. 68 */ 69 typedef struct psa_se_drv_table_entry_s psa_se_drv_table_entry_t; 70 71 /** Return the secure element driver information for a lifetime value. 72 * 73 * \param lifetime The lifetime value to query. 74 * \param[out] p_methods On output, if there is a driver, 75 * \c *methods points to its method table. 76 * Otherwise \c *methods is \c NULL. 77 * \param[out] p_drv_context On output, if there is a driver, 78 * \c *drv_context points to its context 79 * structure. 80 * Otherwise \c *drv_context is \c NULL. 81 * 82 * \retval 1 83 * \p lifetime corresponds to a registered driver. 84 * \retval 0 85 * \p lifetime does not correspond to a registered driver. 86 */ 87 int psa_get_se_driver(psa_key_lifetime_t lifetime, 88 const psa_drv_se_t **p_methods, 89 psa_drv_se_context_t **p_drv_context); 90 91 /** Return the secure element driver table entry for a lifetime value. 92 * 93 * \param lifetime The lifetime value to query. 94 * 95 * \return The driver table entry for \p lifetime, or 96 * \p NULL if \p lifetime does not correspond to a registered driver. 97 */ 98 psa_se_drv_table_entry_t *psa_get_se_driver_entry( 99 psa_key_lifetime_t lifetime); 100 101 /** Return the method table for a secure element driver. 102 * 103 * \param[in] driver The driver table entry to access, or \c NULL. 104 * 105 * \return The driver's method table. 106 * \c NULL if \p driver is \c NULL. 107 */ 108 const psa_drv_se_t *psa_get_se_driver_methods( 109 const psa_se_drv_table_entry_t *driver); 110 111 /** Return the context of a secure element driver. 112 * 113 * \param[in] driver The driver table entry to access, or \c NULL. 114 * 115 * \return A pointer to the driver context. 116 * \c NULL if \p driver is \c NULL. 117 */ 118 psa_drv_se_context_t *psa_get_se_driver_context( 119 psa_se_drv_table_entry_t *driver); 120 121 /** Find a free slot for a key that is to be created. 122 * 123 * This function calls the relevant method in the driver to find a suitable 124 * slot for a key with the given attributes. 125 * 126 * \param[in] attributes Metadata about the key that is about to be created. 127 * \param[in] driver The driver table entry to query. 128 * \param[out] slot_number On success, a slot number that is free in this 129 * secure element. 130 */ 131 psa_status_t psa_find_se_slot_for_key( 132 const psa_key_attributes_t *attributes, 133 psa_key_creation_method_t method, 134 psa_se_drv_table_entry_t *driver, 135 psa_key_slot_number_t *slot_number); 136 137 /** Destroy a key in a secure element. 138 * 139 * This function calls the relevant driver method to destroy a key 140 * and updates the driver's persistent data. 141 */ 142 psa_status_t psa_destroy_se_key(psa_se_drv_table_entry_t *driver, 143 psa_key_slot_number_t slot_number); 144 145 /** Load the persistent data of a secure element driver. 146 * 147 * \param driver The driver table entry containing the persistent 148 * data to load from storage. 149 * 150 * \return #PSA_SUCCESS 151 * \return #PSA_ERROR_NOT_SUPPORTED 152 * \return #PSA_ERROR_DOES_NOT_EXIST 153 * \return #PSA_ERROR_STORAGE_FAILURE 154 * \return #PSA_ERROR_DATA_CORRUPT 155 * \return #PSA_ERROR_INVALID_ARGUMENT 156 */ 157 psa_status_t psa_load_se_persistent_data( 158 const psa_se_drv_table_entry_t *driver); 159 160 /** Save the persistent data of a secure element driver. 161 * 162 * \param[in] driver The driver table entry containing the persistent 163 * data to save to storage. 164 * 165 * \return #PSA_SUCCESS 166 * \return #PSA_ERROR_NOT_SUPPORTED 167 * \return #PSA_ERROR_NOT_PERMITTED 168 * \return #PSA_ERROR_NOT_SUPPORTED 169 * \return #PSA_ERROR_INSUFFICIENT_STORAGE 170 * \return #PSA_ERROR_STORAGE_FAILURE 171 * \return #PSA_ERROR_INVALID_ARGUMENT 172 */ 173 psa_status_t psa_save_se_persistent_data( 174 const psa_se_drv_table_entry_t *driver); 175 176 /** Destroy the persistent data of a secure element driver. 177 * 178 * This is currently only used for testing. 179 * 180 * \param[in] location The location identifier for the driver whose 181 * persistent data is to be erased. 182 */ 183 psa_status_t psa_destroy_se_persistent_data(psa_key_location_t location); 184 185 186 /** The storage representation of a key whose data is in a secure element. 187 */ 188 typedef struct { 189 uint8_t slot_number[sizeof(psa_key_slot_number_t)]; 190 } psa_se_key_data_storage_t; 191 192 #endif /* PSA_CRYPTO_SE_H */ 193
