| /** \file psa_crypto_its.h |
| * \brief Interface of trusted storage that crypto is built on. |
| */ |
| /* |
| * Copyright The Mbed TLS Contributors |
| * SPDX-License-Identifier: Apache-2.0 |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); you may |
| * not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT |
| * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| #ifndef PSA_CRYPTO_ITS_H |
| #define PSA_CRYPTO_ITS_H |
| |
| #include <stddef.h> |
| #include <stdint.h> |
| |
| #include <psa/crypto_types.h> |
| #include <psa/crypto_values.h> |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| /** \brief Flags used when creating a data entry |
| */ |
| typedef uint32_t psa_storage_create_flags_t; |
| |
| /** \brief A type for UIDs used for identifying data |
| */ |
| typedef uint64_t psa_storage_uid_t; |
| |
| #define PSA_STORAGE_FLAG_NONE 0 /**< No flags to pass */ |
| #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`*/ |
| |
| /** |
| * \brief A container for metadata associated with a specific uid |
| */ |
| struct psa_storage_info_t { |
| uint32_t size; /**< The size of the data associated with a uid **/ |
| psa_storage_create_flags_t flags; /**< The flags set when the uid was |
| created **/ |
| }; |
| |
| /** Flag indicating that \ref psa_storage_create and \ref |
| * psa_storage_set_extended are supported */ |
| #define PSA_STORAGE_SUPPORT_SET_EXTENDED (1 << 0) |
| |
| /** \brief PSA storage specific error codes |
| */ |
| #define PSA_ERROR_INVALID_SIGNATURE ((psa_status_t)-149) |
| #define PSA_ERROR_DATA_CORRUPT ((psa_status_t)-152) |
| |
| #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 */ |
| #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 */ |
| |
| /** |
| * \brief create a new or modify an existing uid/value pair |
| * |
| * \param[in] uid the identifier for the data |
| * \param[in] data_length The size in bytes of the data in `p_data` |
| * \param[in] p_data A buffer containing the data |
| * \param[in] create_flags The flags that the data will be stored with |
| * |
| * \return A status indicating the success/failure of the operation |
| * |
| * \retval #PSA_SUCCESS The operation completed |
| * successfully \retval #PSA_ERROR_NOT_PERMITTED The operation |
| * failed because the provided `uid` value was already created with |
| * PSA_STORAGE_WRITE_ONCE_FLAG \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 \retval #PSA_ERROR_INSUFFICIENT_STORAGE |
| * The operation failed because there was insufficient space on the storage |
| * medium \retval #PSA_ERROR_STORAGE_FAILURE The operation failed |
| * because the physical storage has failed (Fatal error) \retval |
| * #PSA_ERROR_INVALID_ARGUMENT The operation failed because one of the |
| * provided pointers(`p_data`) |
| * is invalid, for example is `NULL` or references memory the caller cannot access |
| */ |
| psa_status_t psa_its_set(psa_storage_uid_t uid, |
| uint32_t data_length, |
| const void *p_data, |
| psa_storage_create_flags_t create_flags); |
| |
| /** |
| * \brief Retrieve the value associated with a provided uid |
| * |
| * \param[in] uid The uid value |
| * \param[in] data_offset The starting offset of the data requested |
| * \param[in] data_length the amount of data requested (and the minimum allocated size of the `p_data` buffer) |
| * \param[out] p_data The buffer where the data will be placed upon successful completion |
| * \param[out] p_data_length The amount of data returned in the p_data buffer |
| * |
| * |
| * \return A status indicating the success/failure of the operation |
| * |
| * \retval #PSA_SUCCESS The operation completed |
| * successfully \retval #PSA_ERROR_DOES_NOT_EXIST The operation failed |
| * because the provided `uid` value was not found in the storage \retval |
| * #PSA_ERROR_STORAGE_FAILURE The operation failed because the physical |
| * storage has failed (Fatal error) \retval #PSA_ERROR_DATA_CORRUPT The |
| * operation failed because stored data has been corrupted \retval |
| * #PSA_ERROR_INVALID_ARGUMENT The operation failed because one of the provided |
| * pointers(`p_data`, `p_data_length`) |
| * is invalid. For example is `NULL` or references memory the caller cannot access. |
| * In addition, this can also happen if an invalid offset was provided. |
| */ |
| psa_status_t psa_its_get(psa_storage_uid_t uid, |
| uint32_t data_offset, |
| uint32_t data_length, |
| void *p_data, |
| size_t *p_data_length); |
| |
| /** |
| * \brief Retrieve the metadata about the provided uid |
| * |
| * \param[in] uid The uid value |
| * \param[out] p_info A pointer to the `psa_storage_info_t` struct that will be populated with the metadata |
| * |
| * \return A status indicating the success/failure of the operation |
| * |
| * \retval #PSA_SUCCESS The operation completed |
| * successfully \retval #PSA_ERROR_DOES_NOT_EXIST The operation failed |
| * because the provided uid value was not found in the storage \retval |
| * #PSA_ERROR_DATA_CORRUPT The operation failed because stored data has |
| * been corrupted \retval #PSA_ERROR_INVALID_ARGUMENT The operation failed |
| * because one of the provided pointers(`p_info`) |
| * is invalid, for example is `NULL` or references memory the caller cannot access |
| */ |
| psa_status_t psa_its_get_info(psa_storage_uid_t uid, |
| struct psa_storage_info_t *p_info); |
| |
| /** |
| * \brief Remove the provided key and its associated data from the storage |
| * |
| * \param[in] uid The uid value |
| * |
| * \return A status indicating the success/failure of the operation |
| * |
| * \retval #PSA_SUCCESS The operation completed |
| * successfully \retval #PSA_ERROR_DOES_NOT_EXIST The operation failed |
| * because the provided key value was not found in the storage \retval |
| * #PSA_ERROR_NOT_PERMITTED The operation failed because the provided key |
| * value was created with PSA_STORAGE_WRITE_ONCE_FLAG \retval |
| * #PSA_ERROR_STORAGE_FAILURE The operation failed because the physical |
| * storage has failed (Fatal error) |
| */ |
| psa_status_t psa_its_remove(psa_storage_uid_t uid); |
| |
| #ifdef __cplusplus |
| } |
| #endif |
| |
| #endif /* PSA_CRYPTO_ITS_H */ |