psa_crypto_its.h

00001 /** \file psa_crypto_its.h
00002  * \brief Interface of trusted storage that crypto is built on.
00003  */
00004 /*  Copyright (C) 2019, ARM Limited, All Rights Reserved
00005  *  SPDX-License-Identifier: Apache-2.0
00006  *
00007  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00008  *  not use this file except in compliance with the License.
00009  *  You may obtain a copy of the License at
00010  *
00011  *  http://www.apache.org/licenses/LICENSE-2.0
00012  *
00013  *  Unless required by applicable law or agreed to in writing, software
00014  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00015  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00016  *  See the License for the specific language governing permissions and
00017  *  limitations under the License.
00018  */
00019 
00020 #ifndef PSA_CRYPTO_ITS_H
00021 #define PSA_CRYPTO_ITS_H
00022 
00023 #include <stddef.h>
00024 #include <stdint.h>
00025 
00026 #include <psa/crypto_types.h>
00027 #include <psa/crypto_values.h>
00028 
00029 #ifdef __cplusplus
00030 extern "C" {
00031 #endif
00032 
00033 /** \brief Flags used when creating a data entry
00034  */
00035 typedef uint32_t psa_storage_create_flags_t;
00036 
00037 /** \brief A type for UIDs used for identifying data
00038  */
00039 typedef uint64_t psa_storage_uid_t;
00040 
00041 #define PSA_STORAGE_FLAG_NONE        0         /**< No flags to pass */
00042 #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`*/
00043 
00044 /**
00045  * \brief A container for metadata associated with a specific uid
00046  */
00047 struct psa_storage_info_t
00048 {
00049     uint32_t size;                  /**< The size of the data associated with a uid **/
00050     psa_storage_create_flags_t flags;    /**< The flags set when the uid was created **/
00051 };
00052 
00053 /** Flag indicating that \ref psa_storage_create and \ref psa_storage_set_extended are supported */
00054 #define PSA_STORAGE_SUPPORT_SET_EXTENDED (1 << 0)
00055 
00056 /** \brief PSA storage specific error codes
00057  */
00058 #define PSA_ERROR_INVALID_SIGNATURE     ((psa_status_t)-149)
00059 #define PSA_ERROR_DATA_CORRUPT          ((psa_status_t)-152)
00060 
00061 #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 */
00062 #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 */
00063 
00064 /**
00065  * \brief create a new or modify an existing uid/value pair
00066  *
00067  * \param[in] uid           the identifier for the data
00068  * \param[in] data_length   The size in bytes of the data in `p_data`
00069  * \param[in] p_data        A buffer containing the data
00070  * \param[in] create_flags  The flags that the data will be stored with
00071  *
00072  * \return      A status indicating the success/failure of the operation
00073  *
00074  * \retval      PSA_SUCCESS                      The operation completed successfully
00075  * \retval      PSA_ERROR_NOT_PERMITTED          The operation failed because the provided `uid` value was already created with PSA_STORAGE_WRITE_ONCE_FLAG
00076  * \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
00077  * \retval      PSA_ERROR_INSUFFICIENT_STORAGE   The operation failed because there was insufficient space on the storage medium
00078  * \retval      PSA_ERROR_STORAGE_FAILURE        The operation failed because the physical storage has failed (Fatal error)
00079  * \retval      PSA_ERROR_INVALID_ARGUMENT       The operation failed because one of the provided pointers(`p_data`)
00080  *                                               is invalid, for example is `NULL` or references memory the caller cannot access
00081  */
00082 psa_status_t psa_its_set(psa_storage_uid_t uid,
00083                          uint32_t data_length,
00084                          const void *p_data,
00085                          psa_storage_create_flags_t create_flags);
00086 
00087 /**
00088  * \brief Retrieve the value associated with a provided uid
00089  *
00090  * \param[in] uid               The uid value
00091  * \param[in] data_offset       The starting offset of the data requested
00092  * \param[in] data_length       the amount of data requested (and the minimum allocated size of the `p_data` buffer)
00093  * \param[out] p_data           The buffer where the data will be placed upon successful completion
00094  * \param[out] p_data_length    The amount of data returned in the p_data buffer
00095  *
00096  *
00097  * \return      A status indicating the success/failure of the operation
00098  *
00099  * \retval      PSA_SUCCESS                  The operation completed successfully
00100  * \retval      PSA_ERROR_DOES_NOT_EXIST     The operation failed because the provided `uid` value was not found in the storage
00101  * \retval      PSA_ERROR_INVALID_SIZE       The operation failed because the data associated with provided uid is larger than `data_size`
00102  * \retval      PSA_ERROR_STORAGE_FAILURE    The operation failed because the physical storage has failed (Fatal error)
00103  * \retval      PSA_ERROR_INVALID_ARGUMENT   The operation failed because one of the provided pointers(`p_data`, `p_data_length`)
00104  *                                           is invalid. For example is `NULL` or references memory the caller cannot access.
00105  *                                           In addition, this can also happen if an invalid offset was provided.
00106  */
00107 psa_status_t psa_its_get(psa_storage_uid_t uid,
00108                          uint32_t data_offset,
00109                          uint32_t data_length,
00110                          void *p_data,
00111                          size_t *p_data_length );
00112 
00113 /**
00114  * \brief Retrieve the metadata about the provided uid
00115  *
00116  * \param[in] uid           The uid value
00117  * \param[out] p_info       A pointer to the `psa_storage_info_t` struct that will be populated with the metadata
00118  *
00119  * \return      A status indicating the success/failure of the operation
00120  *
00121  * \retval      PSA_SUCCESS                  The operation completed successfully
00122  * \retval      PSA_ERROR_DOES_NOT_EXIST     The operation failed because the provided uid value was not found in the storage
00123  * \retval      PSA_ERROR_STORAGE_FAILURE    The operation failed because the physical storage has failed (Fatal error)
00124  * \retval      PSA_ERROR_INVALID_ARGUMENT   The operation failed because one of the provided pointers(`p_info`)
00125  *                                           is invalid, for example is `NULL` or references memory the caller cannot access
00126  */
00127 psa_status_t psa_its_get_info(psa_storage_uid_t uid,
00128                               struct psa_storage_info_t *p_info);
00129 
00130 /**
00131  * \brief Remove the provided key and its associated data from the storage
00132  *
00133  * \param[in] uid   The uid value
00134  *
00135  * \return  A status indicating the success/failure of the operation
00136  *
00137  * \retval      PSA_SUCCESS                  The operation completed successfully
00138  * \retval      PSA_ERROR_DOES_NOT_EXIST     The operation failed because the provided key value was not found in the storage
00139  * \retval      PSA_ERROR_NOT_PERMITTED      The operation failed because the provided key value was created with PSA_STORAGE_WRITE_ONCE_FLAG
00140  * \retval      PSA_ERROR_STORAGE_FAILURE    The operation failed because the physical storage has failed (Fatal error)
00141  */
00142 psa_status_t psa_its_remove(psa_storage_uid_t uid);
00143 
00144 #endif /* PSA_CRYPTO_ITS_H */