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