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