1 /* 2 * Copyright (c) 2019, Arm Limited. All rights reserved. 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 * 6 */ 7 8 /** This file describes the PSA Internal Trusted Storage API 9 */ 10 11 #ifndef PSA_INTERNAL_TRUSTED_STORAGE_H 12 #define PSA_INTERNAL_TRUSTED_STORAGE_H 13 14 #include <stddef.h> 15 #include <stdint.h> 16 17 #include "psa/error.h" 18 #include "psa/storage_common.h" 19 20 #ifdef __cplusplus 21 extern "C" { 22 #endif 23 #define PSA_ITS_API_VERSION_MAJOR 1 /**< The major version number of the 24 * PSA ITS API 25 */ 26 #define PSA_ITS_API_VERSION_MINOR 0 /**< The minor version number of the 27 * PSA ITS API 28 */ 29 // This version of the header file is associated with 1.0 final release. 30 31 /** 32 * \brief Create a new, or modify an existing, uid/value pair 33 * 34 * Stores data in the internal storage. 35 * 36 * \param[in] uid The identifier for the data 37 * \param[in] data_length The size in bytes of the data in `p_data` 38 * \param[in] p_data A buffer containing the data 39 * \param[in] create_flags The flags that the data will be stored with 40 * 41 * \return A status indicating the success/failure of the operation 42 * 43 * \retval PSA_SUCCESS The operation completed successfully 44 * \retval PSA_ERROR_NOT_PERMITTED The operation failed because the 45 * provided `uid` value was already 46 * created with 47 * PSA_STORAGE_FLAG_WRITE_ONCE 48 * \retval PSA_ERROR_NOT_SUPPORTED The operation failed because one or 49 * more of the flags provided in 50 * `create_flags` is not supported or is 51 * not valid 52 * \retval PSA_ERROR_INSUFFICIENT_STORAGE The operation failed because there 53 * was insufficient space on the 54 * storage medium 55 * \retval PSA_ERROR_STORAGE_FAILURE The operation failed because the 56 * physical storage has failed (Fatal 57 * error) 58 * \retval PSA_ERROR_INVALID_ARGUMENT The operation failed because one 59 * of the provided pointers(`p_data`) 60 * is invalid, for example is `NULL` or 61 * references memory the caller cannot 62 * access 63 */ 64 psa_status_t psa_its_set(psa_storage_uid_t uid, 65 size_t data_length, 66 const void *p_data, 67 psa_storage_create_flags_t create_flags); 68 69 /** 70 * \brief Retrieve data associated with a provided UID 71 * 72 * Retrieves up to `data_size` bytes of the data associated with `uid`, starting 73 * at `data_offset` bytes from the beginning of the data. Upon successful 74 * completion, the data will be placed in the `p_data` buffer, which must be at 75 * least `data_size` bytes in size. The length of the data returned will be in 76 * `p_data_length`. If `data_size` is 0, the contents of `p_data_length` will 77 * be set to zero. 78 * 79 * \param[in] uid The uid value 80 * \param[in] data_offset The starting offset of the data requested 81 * \param[in] data_size The amount of data requested 82 * \param[out] p_data On success, the buffer where the data will 83 * be placed 84 * \param[out] p_data_length On success, this will contain size of the data 85 * placed in `p_data` 86 * 87 * \return A status indicating the success/failure of the operation 88 * 89 * \retval PSA_SUCCESS The operation completed successfully 90 * \retval PSA_ERROR_DOES_NOT_EXIST The operation failed because the 91 * provided `uid` value was not found in 92 * the storage 93 * \retval PSA_ERROR_STORAGE_FAILURE The operation failed because the 94 * physical storage has failed (Fatal 95 * error) 96 * \retval PSA_ERROR_INVALID_ARGUMENT The operation failed because one of the 97 * provided arguments (`p_data`, 98 * `p_data_length`) is invalid, for example 99 * is `NULL` or references memory the 100 * caller cannot access. In addition, this 101 * can also happen if `data_offset` is 102 * larger than the size of the data 103 * associated with `uid` 104 */ 105 psa_status_t psa_its_get(psa_storage_uid_t uid, 106 size_t data_offset, 107 size_t data_size, 108 void *p_data, 109 size_t *p_data_length); 110 111 /** 112 * \brief Retrieve the metadata about the provided uid 113 * 114 * Retrieves the metadata stored for a given `uid` as a `psa_storage_info_t` 115 * structure. 116 * 117 * \param[in] uid The `uid` value 118 * \param[out] p_info A pointer to the `psa_storage_info_t` struct that will 119 * be populated with the metadata 120 * 121 * \return A status indicating the success/failure of the operation 122 * 123 * \retval PSA_SUCCESS The operation completed successfully 124 * \retval PSA_ERROR_DOES_NOT_EXIST The operation failed because the provided 125 * uid value was not found in the storage 126 * \retval PSA_ERROR_STORAGE_FAILURE The operation failed because the physical 127 * storage has failed (Fatal error) 128 * \retval PSA_ERROR_INVALID_ARGUMENT The operation failed because one of the 129 * provided pointers(`p_info`) 130 * is invalid, for example is `NULL` or 131 * references memory the caller cannot 132 * access 133 */ 134 psa_status_t psa_its_get_info(psa_storage_uid_t uid, 135 struct psa_storage_info_t *p_info); 136 137 /** 138 * \brief Remove the provided uid and its associated data from the storage 139 * 140 * Deletes the data from internal storage. 141 * 142 * \param[in] uid The `uid` value 143 * 144 * \return A status indicating the success/failure of the operation 145 * 146 * \retval PSA_SUCCESS The operation completed successfully 147 * \retval PSA_ERROR_INVALID_ARGUMENT The operation failed because one or more 148 * of the given arguments were invalid (null 149 * pointer, wrong flags and so on) 150 * \retval PSA_ERROR_DOES_NOT_EXIST The operation failed because the provided 151 * uid value was not found in the storage 152 * \retval PSA_ERROR_NOT_PERMITTED The operation failed because the provided 153 * uid value was created with 154 * PSA_STORAGE_FLAG_WRITE_ONCE 155 * \retval PSA_ERROR_STORAGE_FAILURE The operation failed because the physical 156 * storage has failed (Fatal error) 157 */ 158 psa_status_t psa_its_remove(psa_storage_uid_t uid); 159 160 #ifdef __cplusplus 161 } 162 #endif 163 164 #endif // PSA_INTERNAL_TRUSTED_STORAGE_H 165
