psa_crypto_storage.h (15403B)
1 /** 2 * \file psa_crypto_storage.h 3 * 4 * \brief PSA cryptography module: Mbed TLS key storage 5 */ 6 /* 7 * Copyright The Mbed TLS Contributors 8 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 9 */ 10 11 #ifndef PSA_CRYPTO_STORAGE_H 12 #define PSA_CRYPTO_STORAGE_H 13 14 #ifdef __cplusplus 15 extern "C" { 16 #endif 17 18 #include "psa/crypto.h" 19 #include "psa/crypto_se_driver.h" 20 21 #include <stdint.h> 22 #include <string.h> 23 24 /* Limit the maximum key size in storage. */ 25 #if defined(MBEDTLS_PSA_STATIC_KEY_SLOTS) 26 /* Reflect the maximum size for the key buffer. */ 27 #define PSA_CRYPTO_MAX_STORAGE_SIZE (MBEDTLS_PSA_STATIC_KEY_SLOT_BUFFER_SIZE) 28 #else 29 /* Just set an upper boundary but it should have no effect since the key size 30 * is limited in memory. */ 31 #define PSA_CRYPTO_MAX_STORAGE_SIZE (PSA_BITS_TO_BYTES(PSA_MAX_KEY_BITS)) 32 #endif 33 34 /* Sanity check: a file size must fit in 32 bits. Allow a generous 35 * 64kB of metadata. */ 36 #if PSA_CRYPTO_MAX_STORAGE_SIZE > 0xffff0000 37 #error "PSA_CRYPTO_MAX_STORAGE_SIZE > 0xffff0000" 38 #endif 39 40 /** The maximum permitted persistent slot number. 41 * 42 * In Mbed Crypto 0.1.0b: 43 * - Using the file backend, all key ids are ok except 0. 44 * - Using the ITS backend, all key ids are ok except 0xFFFFFF52 45 * (#PSA_CRYPTO_ITS_RANDOM_SEED_UID) for which the file contains the 46 * device's random seed (if this feature is enabled). 47 * - Only key ids from 1 to #MBEDTLS_PSA_KEY_SLOT_COUNT are actually used. 48 * 49 * Since we need to preserve the random seed, avoid using that key slot. 50 * Reserve a whole range of key slots just in case something else comes up. 51 * 52 * This limitation will probably become moot when we implement client 53 * separation for key storage. 54 */ 55 #define PSA_MAX_PERSISTENT_KEY_IDENTIFIER PSA_KEY_ID_VENDOR_MAX 56 57 /** 58 * \brief Checks if persistent data is stored for the given key slot number 59 * 60 * This function checks if any key data or metadata exists for the key slot in 61 * the persistent storage. 62 * 63 * \param key Persistent identifier to check. 64 * 65 * \retval 0 66 * No persistent data present for slot number 67 * \retval 1 68 * Persistent data present for slot number 69 */ 70 int psa_is_key_present_in_storage(const mbedtls_svc_key_id_t key); 71 72 /** 73 * \brief Format key data and metadata and save to a location for given key 74 * slot. 75 * 76 * This function formats the key data and metadata and saves it to a 77 * persistent storage backend. The storage location corresponding to the 78 * key slot must be empty, otherwise this function will fail. This function 79 * should be called after loading the key into an internal slot to ensure the 80 * persistent key is not saved into a storage location corresponding to an 81 * already occupied non-persistent key, as well as ensuring the key data is 82 * validated. 83 * 84 * Note: This function will only succeed for key buffers which are not 85 * empty. If passed a NULL pointer or zero-length, the function will fail 86 * with #PSA_ERROR_INVALID_ARGUMENT. 87 * 88 * \param[in] attr The attributes of the key to save. 89 * The key identifier field in the attributes 90 * determines the key's location. 91 * \param[in] data Buffer containing the key data. 92 * \param data_length The number of bytes that make up the key data. 93 * 94 * \retval #PSA_SUCCESS \emptydescription 95 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription 96 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 97 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE \emptydescription 98 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 99 * \retval #PSA_ERROR_ALREADY_EXISTS \emptydescription 100 * \retval #PSA_ERROR_DATA_INVALID \emptydescription 101 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription 102 */ 103 psa_status_t psa_save_persistent_key(const psa_key_attributes_t *attr, 104 const uint8_t *data, 105 const size_t data_length); 106 107 /** 108 * \brief Parses key data and metadata and load persistent key for given 109 * key slot number. 110 * 111 * This function reads from a storage backend, parses the key data and 112 * metadata and writes them to the appropriate output parameters. 113 * 114 * Note: This function allocates a buffer and returns a pointer to it through 115 * the data parameter. On successful return, the pointer is guaranteed to be 116 * valid and the buffer contains at least one byte of data. 117 * psa_free_persistent_key_data() must be called on the data buffer 118 * afterwards to zeroize and free this buffer. 119 * 120 * \param[in,out] attr On input, the key identifier field identifies 121 * the key to load. Other fields are ignored. 122 * On success, the attribute structure contains 123 * the key metadata that was loaded from storage. 124 * \param[out] data Pointer to an allocated key data buffer on return. 125 * \param[out] data_length The number of bytes that make up the key data. 126 * 127 * \retval #PSA_SUCCESS \emptydescription 128 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 129 * \retval #PSA_ERROR_DATA_INVALID \emptydescription 130 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription 131 * \retval #PSA_ERROR_DOES_NOT_EXIST \emptydescription 132 */ 133 psa_status_t psa_load_persistent_key(psa_key_attributes_t *attr, 134 uint8_t **data, 135 size_t *data_length); 136 137 /** 138 * \brief Remove persistent data for the given key slot number. 139 * 140 * \param key Persistent identifier of the key to remove 141 * from persistent storage. 142 * 143 * \retval #PSA_SUCCESS 144 * The key was successfully removed, 145 * or the key did not exist. 146 * \retval #PSA_ERROR_DATA_INVALID \emptydescription 147 */ 148 psa_status_t psa_destroy_persistent_key(const mbedtls_svc_key_id_t key); 149 150 /** 151 * \brief Free the temporary buffer allocated by psa_load_persistent_key(). 152 * 153 * This function must be called at some point after psa_load_persistent_key() 154 * to zeroize and free the memory allocated to the buffer in that function. 155 * 156 * \param key_data Buffer for the key data. 157 * \param key_data_length Size of the key data buffer. 158 * 159 */ 160 void psa_free_persistent_key_data(uint8_t *key_data, size_t key_data_length); 161 162 /** 163 * \brief Formats key data and metadata for persistent storage 164 * 165 * \param[in] data Buffer containing the key data. 166 * \param data_length Length of the key data buffer. 167 * \param[in] attr The core attributes of the key. 168 * \param[out] storage_data Output buffer for the formatted data. 169 * 170 */ 171 void psa_format_key_data_for_storage(const uint8_t *data, 172 const size_t data_length, 173 const psa_key_attributes_t *attr, 174 uint8_t *storage_data); 175 176 /** 177 * \brief Parses persistent storage data into key data and metadata 178 * 179 * \param[in] storage_data Buffer for the storage data. 180 * \param storage_data_length Length of the storage data buffer 181 * \param[out] key_data On output, pointer to a newly allocated buffer 182 * containing the key data. This must be freed 183 * using psa_free_persistent_key_data() 184 * \param[out] key_data_length Length of the key data buffer 185 * \param[out] attr On success, the attribute structure is filled 186 * with the loaded key metadata. 187 * 188 * \retval #PSA_SUCCESS \emptydescription 189 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 190 * \retval #PSA_ERROR_DATA_INVALID \emptydescription 191 */ 192 psa_status_t psa_parse_key_data_from_storage(const uint8_t *storage_data, 193 size_t storage_data_length, 194 uint8_t **key_data, 195 size_t *key_data_length, 196 psa_key_attributes_t *attr); 197 198 #if defined(MBEDTLS_PSA_CRYPTO_SE_C) 199 /** This symbol is defined if transaction support is required. */ 200 #define PSA_CRYPTO_STORAGE_HAS_TRANSACTIONS 1 201 #endif 202 203 #if defined(PSA_CRYPTO_STORAGE_HAS_TRANSACTIONS) 204 205 /** The type of transaction that is in progress. 206 */ 207 /* This is an integer type rather than an enum for two reasons: to support 208 * unknown values when loading a transaction file, and to ensure that the 209 * type has a known size. 210 */ 211 typedef uint16_t psa_crypto_transaction_type_t; 212 213 /** No transaction is in progress. 214 * 215 * This has the value 0, so zero-initialization sets a transaction's type to 216 * this value. 217 */ 218 #define PSA_CRYPTO_TRANSACTION_NONE ((psa_crypto_transaction_type_t) 0x0000) 219 220 /** A key creation transaction. 221 * 222 * This is only used for keys in an external cryptoprocessor (secure element). 223 * Keys in RAM or in internal storage are created atomically in storage 224 * (simple file creation), so they do not need a transaction mechanism. 225 */ 226 #define PSA_CRYPTO_TRANSACTION_CREATE_KEY ((psa_crypto_transaction_type_t) 0x0001) 227 228 /** A key destruction transaction. 229 * 230 * This is only used for keys in an external cryptoprocessor (secure element). 231 * Keys in RAM or in internal storage are destroyed atomically in storage 232 * (simple file deletion), so they do not need a transaction mechanism. 233 */ 234 #define PSA_CRYPTO_TRANSACTION_DESTROY_KEY ((psa_crypto_transaction_type_t) 0x0002) 235 236 /** Transaction data. 237 * 238 * This type is designed to be serialized by writing the memory representation 239 * and reading it back on the same device. 240 * 241 * \note The transaction mechanism is not thread-safe. There can only be one 242 * single active transaction at a time. 243 * The transaction object is #psa_crypto_transaction. 244 * 245 * \note If an API call starts a transaction, it must complete this transaction 246 * before returning to the application. 247 * 248 * The lifetime of a transaction is the following (note that only one 249 * transaction may be active at a time): 250 * 251 * -# Call psa_crypto_prepare_transaction() to initialize the transaction 252 * object in memory and declare the type of transaction that is starting. 253 * -# Fill in the type-specific fields of #psa_crypto_transaction. 254 * -# Call psa_crypto_save_transaction() to start the transaction. This 255 * saves the transaction data to internal storage. 256 * -# Perform the work of the transaction by modifying files, contacting 257 * external entities, or whatever needs doing. Note that the transaction 258 * may be interrupted by a power failure, so you need to have a way 259 * recover from interruptions either by undoing what has been done 260 * so far or by resuming where you left off. 261 * -# If there are intermediate stages in the transaction, update 262 * the fields of #psa_crypto_transaction and call 263 * psa_crypto_save_transaction() again when each stage is reached. 264 * -# When the transaction is over, call psa_crypto_stop_transaction() to 265 * remove the transaction data in storage and in memory. 266 * 267 * If the system crashes while a transaction is in progress, psa_crypto_init() 268 * calls psa_crypto_load_transaction() and takes care of completing or 269 * rewinding the transaction. This is done in psa_crypto_recover_transaction() 270 * in psa_crypto.c. If you add a new type of transaction, be 271 * sure to add code for it in psa_crypto_recover_transaction(). 272 */ 273 typedef union { 274 /* Each element of this union must have the following properties 275 * to facilitate serialization and deserialization: 276 * 277 * - The element is a struct. 278 * - The first field of the struct is `psa_crypto_transaction_type_t type`. 279 * - Elements of the struct are arranged such a way that there is 280 * no padding. 281 */ 282 struct psa_crypto_transaction_unknown_s { 283 psa_crypto_transaction_type_t type; 284 uint16_t unused1; 285 uint32_t unused2; 286 uint64_t unused3; 287 uint64_t unused4; 288 } unknown; 289 /* ::type is #PSA_CRYPTO_TRANSACTION_CREATE_KEY or 290 * #PSA_CRYPTO_TRANSACTION_DESTROY_KEY. */ 291 struct psa_crypto_transaction_key_s { 292 psa_crypto_transaction_type_t type; 293 uint16_t unused1; 294 psa_key_lifetime_t lifetime; 295 psa_key_slot_number_t slot; 296 mbedtls_svc_key_id_t id; 297 } key; 298 } psa_crypto_transaction_t; 299 300 /** The single active transaction. 301 */ 302 extern psa_crypto_transaction_t psa_crypto_transaction; 303 304 /** Prepare for a transaction. 305 * 306 * There must not be an ongoing transaction. 307 * 308 * \param type The type of transaction to start. 309 */ 310 static inline void psa_crypto_prepare_transaction( 311 psa_crypto_transaction_type_t type) 312 { 313 psa_crypto_transaction.unknown.type = type; 314 } 315 316 /** Save the transaction data to storage. 317 * 318 * You may call this function multiple times during a transaction to 319 * atomically update the transaction state. 320 * 321 * \retval #PSA_SUCCESS \emptydescription 322 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription 323 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE \emptydescription 324 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 325 */ 326 psa_status_t psa_crypto_save_transaction(void); 327 328 /** Load the transaction data from storage, if any. 329 * 330 * This function is meant to be called from psa_crypto_init() to recover 331 * in case a transaction was interrupted by a system crash. 332 * 333 * \retval #PSA_SUCCESS 334 * The data about the ongoing transaction has been loaded to 335 * #psa_crypto_transaction. 336 * \retval #PSA_ERROR_DOES_NOT_EXIST 337 * There is no ongoing transaction. 338 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 339 * \retval #PSA_ERROR_DATA_INVALID \emptydescription 340 * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription 341 */ 342 psa_status_t psa_crypto_load_transaction(void); 343 344 /** Indicate that the current transaction is finished. 345 * 346 * Call this function at the very end of transaction processing. 347 * This function does not "commit" or "abort" the transaction: the storage 348 * subsystem has no concept of "commit" and "abort", just saving and 349 * removing the transaction information in storage. 350 * 351 * This function erases the transaction data in storage (if any) and 352 * resets the transaction data in memory. 353 * 354 * \retval #PSA_SUCCESS 355 * There was transaction data in storage. 356 * \retval #PSA_ERROR_DOES_NOT_EXIST 357 * There was no transaction data in storage. 358 * \retval #PSA_ERROR_STORAGE_FAILURE 359 * It was impossible to determine whether there was transaction data 360 * in storage, or the transaction data could not be erased. 361 */ 362 psa_status_t psa_crypto_stop_transaction(void); 363 364 /** The ITS file identifier for the transaction data. 365 * 366 * 0xffffffNN = special file; 0x74 = 't' for transaction. 367 */ 368 #define PSA_CRYPTO_ITS_TRANSACTION_UID ((psa_key_id_t) 0xffffff74) 369 370 #endif /* PSA_CRYPTO_STORAGE_HAS_TRANSACTIONS */ 371 372 #if defined(MBEDTLS_PSA_INJECT_ENTROPY) 373 /** Backend side of mbedtls_psa_inject_entropy(). 374 * 375 * This function stores the supplied data into the entropy seed file. 376 * 377 * \retval #PSA_SUCCESS 378 * Success 379 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 380 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE \emptydescription 381 * \retval #PSA_ERROR_NOT_PERMITTED 382 * The entropy seed file already exists. 383 */ 384 psa_status_t mbedtls_psa_storage_inject_entropy(const unsigned char *seed, 385 size_t seed_size); 386 #endif /* MBEDTLS_PSA_INJECT_ENTROPY */ 387 388 #ifdef __cplusplus 389 } 390 #endif 391 392 #endif /* PSA_CRYPTO_STORAGE_H */