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