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