1 /** \file psa_crypto_its.h 2 * \brief Interface of trusted storage that crypto is built on. 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_ITS_H 10 #define PSA_CRYPTO_ITS_H 11 12 #include <stddef.h> 13 #include <stdint.h> 14 15 #include <psa/crypto_types.h> 16 #include <psa/crypto_values.h> 17 18 #ifdef __cplusplus 19 extern "C" { 20 #endif 21 22 /** \brief Flags used when creating a data entry 23 */ 24 typedef uint32_t psa_storage_create_flags_t; 25 26 /** \brief A type for UIDs used for identifying data 27 */ 28 typedef uint64_t psa_storage_uid_t; 29 30 #define PSA_STORAGE_FLAG_NONE 0 /**< No flags to pass */ 31 #define PSA_STORAGE_FLAG_WRITE_ONCE (1 << 0) /**< The data associated with the uid will not be able to be modified or deleted. Intended to be used to set bits in `psa_storage_create_flags_t`*/ 32 33 /** 34 * \brief A container for metadata associated with a specific uid 35 */ 36 struct psa_storage_info_t { 37 uint32_t size; /**< The size of the data associated with a uid **/ 38 psa_storage_create_flags_t flags; /**< The flags set when the uid was created **/ 39 }; 40 41 /** Flag indicating that \ref psa_storage_create and \ref psa_storage_set_extended are supported */ 42 #define PSA_STORAGE_SUPPORT_SET_EXTENDED (1 << 0) 43 44 #define PSA_ITS_API_VERSION_MAJOR 1 /**< The major version number of the PSA ITS API. It will be incremented on significant updates that may include breaking changes */ 45 #define PSA_ITS_API_VERSION_MINOR 1 /**< The minor version number of the PSA ITS API. It will be incremented in small updates that are unlikely to include breaking changes */ 46 47 /** 48 * \brief create a new or modify an existing uid/value pair 49 * 50 * \param[in] uid the identifier for the data 51 * \param[in] data_length The size in bytes of the data in `p_data` 52 * \param[in] p_data A buffer containing the data 53 * \param[in] create_flags The flags that the data will be stored with 54 * 55 * \return A status indicating the success/failure of the operation 56 * 57 * \retval #PSA_SUCCESS The operation completed successfully 58 * \retval #PSA_ERROR_NOT_PERMITTED The operation failed because the provided `uid` value was already created with PSA_STORAGE_FLAG_WRITE_ONCE 59 * \retval #PSA_ERROR_NOT_SUPPORTED The operation failed because one or more of the flags provided in `create_flags` is not supported or is not valid 60 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE The operation failed because there was insufficient space on the storage medium 61 * \retval #PSA_ERROR_STORAGE_FAILURE The operation failed because the physical storage has failed (Fatal error) 62 * \retval #PSA_ERROR_INVALID_ARGUMENT The operation failed because one of the provided pointers(`p_data`) 63 * is invalid, for example is `NULL` or references memory the caller cannot access 64 */ 65 psa_status_t psa_its_set(psa_storage_uid_t uid, 66 uint32_t data_length, 67 const void *p_data, 68 psa_storage_create_flags_t create_flags); 69 70 /** 71 * \brief Retrieve the value associated with a provided uid 72 * 73 * \param[in] uid The uid value 74 * \param[in] data_offset The starting offset of the data requested 75 * \param[in] data_length the amount of data requested (and the minimum allocated size of the `p_data` buffer) 76 * \param[out] p_data The buffer where the data will be placed upon successful completion 77 * \param[out] p_data_length The amount of data returned in the p_data buffer 78 * 79 * 80 * \return A status indicating the success/failure of the operation 81 * 82 * \retval #PSA_SUCCESS The operation completed successfully 83 * \retval #PSA_ERROR_DOES_NOT_EXIST The operation failed because the provided `uid` value was not found in the storage 84 * \retval #PSA_ERROR_STORAGE_FAILURE The operation failed because the physical storage has failed (Fatal error) 85 * \retval #PSA_ERROR_DATA_CORRUPT The operation failed because stored data has been corrupted 86 * \retval #PSA_ERROR_INVALID_ARGUMENT The operation failed because one of the provided pointers(`p_data`, `p_data_length`) 87 * is invalid. For example is `NULL` or references memory the caller cannot access. 88 * In addition, this can also happen if an invalid offset was provided. 89 */ 90 psa_status_t psa_its_get(psa_storage_uid_t uid, 91 uint32_t data_offset, 92 uint32_t data_length, 93 void *p_data, 94 size_t *p_data_length); 95 96 /** 97 * \brief Retrieve the metadata about the provided uid 98 * 99 * \param[in] uid The uid value 100 * \param[out] p_info A pointer to the `psa_storage_info_t` struct that will be populated with the metadata 101 * 102 * \return A status indicating the success/failure of the operation 103 * 104 * \retval #PSA_SUCCESS The operation completed successfully 105 * \retval #PSA_ERROR_DOES_NOT_EXIST The operation failed because the provided uid value was not found in the storage 106 * \retval #PSA_ERROR_DATA_CORRUPT The operation failed because stored data has been corrupted 107 * \retval #PSA_ERROR_INVALID_ARGUMENT The operation failed because one of the provided pointers(`p_info`) 108 * is invalid, for example is `NULL` or references memory the caller cannot access 109 */ 110 psa_status_t psa_its_get_info(psa_storage_uid_t uid, 111 struct psa_storage_info_t *p_info); 112 113 /** 114 * \brief Remove the provided key and its associated data from the storage 115 * 116 * \param[in] uid The uid value 117 * 118 * \return A status indicating the success/failure of the operation 119 * 120 * \retval #PSA_SUCCESS The operation completed successfully 121 * \retval #PSA_ERROR_DOES_NOT_EXIST The operation failed because the provided key value was not found in the storage 122 * \retval #PSA_ERROR_NOT_PERMITTED The operation failed because the provided key value was created with PSA_STORAGE_FLAG_WRITE_ONCE 123 * \retval #PSA_ERROR_STORAGE_FAILURE The operation failed because the physical storage has failed (Fatal error) 124 */ 125 psa_status_t psa_its_remove(psa_storage_uid_t uid); 126 127 #ifdef __cplusplus 128 } 129 #endif 130 131 #endif /* PSA_CRYPTO_ITS_H */ 132
