SST: Add PSA Protected Storage header
Adds the PSA Protected Storage API header file to the interface
directory.
Derived from Git SHA a431fb9758b4cc315e0ce0083a56e13a9265f61f in the
following repository https://github.com/arm-software/psa-arch-tests
Change-Id: I0f063dbaef7e2560e0b2f07e38f0bb3d80643783
Signed-off-by: Jamie Fox <jamie.fox@arm.com>
diff --git a/interface/include/psa_protected_storage.h b/interface/include/psa_protected_storage.h
new file mode 100644
index 0000000..bd1d91e
--- /dev/null
+++ b/interface/include/psa_protected_storage.h
@@ -0,0 +1,232 @@
+/*
+ * Copyright (c) 2019, Arm Limited. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ */
+
+#ifndef __PSA_PROTECTED_STORAGE_H__
+#define __PSA_PROTECTED_STORAGE_H__
+
+/** @file
+@brief This file describes the PSA Protected Storage API
+*/
+
+#include <stddef.h>
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define PSA_PS_API_VERSION_MAJOR 1 /**< The major version number of the PSA PS API. It will be incremented on significant updates that may include breaking changes */
+#define PSA_PS_API_VERSION_MINOR 0 /**< The minor version number of the PSA PS API. It will be incremented in small updates that are unlikely to include breaking changes */
+
+/** \brief Flags used when creating a data entry
+ */
+typedef uint32_t psa_ps_create_flags_t;
+
+/** \brief A type for UIDs used for identifying data
+ */
+typedef uint64_t psa_ps_uid_t;
+
+#define PSA_PS_FLAG_NONE 0 /**< No flags to pass */
+#define PSA_PS_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_ps_create_flags_t`*/
+
+/**
+ * \brief A container for metadata associated with a specific uid
+ */
+struct psa_ps_info_t {
+ uint32_t size; /**< The size of the data associated with a uid **/
+ psa_ps_create_flags_t flags; /**< The flags set when the uid was created **/
+};
+/**
+ * \brief The return status type for the PSA Trusted Storage functions
+ */
+typedef uint32_t psa_ps_status_t;
+
+#define PSA_PS_SUCCESS 0 /**< The operation completed successfully */
+#define PSA_PS_ERROR_WRITE_ONCE 1 /**< The operation failed because the provided key value was already created with PSA_PS_WRITE_ONCE_FLAG */
+#define PSA_PS_ERROR_FLAGS_NOT_SUPPORTED 2 /**< The operation failed because one or more of the flags provided in `create_flags` is not supported or is not valid */
+#define PSA_PS_ERROR_INSUFFICIENT_SPACE 3 /**< The operation failed because there was insufficient space on the storage medium */
+#define PSA_PS_ERROR_STORAGE_FAILURE 4 /**< The operation failed because the physical storage has failed (Fatal error) */
+#define PSA_PS_ERROR_UID_NOT_FOUND 5 /**< The operation failed because the provided key value was not found in the storage */
+#define PSA_PS_ERROR_INCORRECT_SIZE 6 /**< The operation failed because the data associated with provided key is not the same size as `data_size`, or `offset+data_size` is too large for the data, but `offset` is less than the size */
+#define PSA_PS_ERROR_OFFSET_INVALID 7 /**< The operation failed because an offset was supplied that is invalid for the existing data associated with the uid. For example, offset is greater that the size of the data */
+#define PSA_PS_ERROR_INVALID_ARGUMENT 8 /**< The operation failed because one or more of the given arguments were invalid (null pointer, wrong flags etc.) */
+#define PSA_PS_ERROR_DATA_CORRUPT 9 /**< The operation failed because data was corrupt when attempting to get the key */
+#define PSA_PS_ERROR_AUTH_FAILED 10 /**< The operation failed because of an authentication failure when attempting to get the key */
+#define PSA_PS_ERROR_OPERATION_FAILED 11 /**< The operation failed because of an unspecified/internal failure */
+#define PSA_PS_ERROR_NOT_SUPPORTED 12 /**< The returning function is not supported in this implementation of the API */
+
+/** Flag indicating that \ref psa_ps_create and \ref psa_ps_set_extended are supported */
+#define PSA_PS_SUPPORT_SET_EXTENDED (1 << 0)
+
+/**
+ * \brief create a new or modify an existing key/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 indicating the properties of the data
+ *
+ * \return A status indicating the success/failure of the operation
+
+ * \retval PSA_PS_SUCCESS The operation completed successfully
+ * \retval PSA_PS_ERROR_WRITE_ONCE The operation failed because the provided uid value was already created with PSA_PS_WRITE_ONCE_FLAG
+ * \retval PSA_PS_ERROR_INVALID_ARGUMENT The operation failed because one or more of the given arguments were invalid.
+ * \retval PSA_PS_ERROR_FLAGS_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_PS_ERROR_INSUFFICIENT_SPACE The operation failed because there was insufficient space on the storage medium
+ * \retval PSA_PS_ERROR_STORAGE_FAILURE The operation failed because the physical storage has failed (Fatal error)
+ * \retval PSA_PS_ERROR_OPERATION_FAILED The operation failed because of an unspecified internal failure
+ */
+psa_ps_status_t psa_ps_set( psa_ps_uid_t uid,
+ uint32_t data_length,
+ const void *p_data,
+ psa_ps_create_flags_t create_flags );
+
+/**
+ * \brief Retrieve the value for a provided uid
+ *
+ * \param[in] uid The identifier for the data
+ * \param[in] data_offset The offset within the data associated with the `uid` to start retrieving data
+ * \param[in] data_length The amount of data to read (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
+ *
+ * \return A status indicating the success/failure of the operation
+ *
+ * \retval PSA_PS_SUCCESS The operation completed successfully
+ * \retval PSA_PS_ERROR_INVALID_ARGUMENT The operation failed because one or more of the given arguments were invalid (null pointer, wrong flags etc.)
+ * \retval PSA_PS_ERROR_UID_NOT_FOUND The operation failed because the provided uid value was not found in the storage
+ * \retval PSA_PS_ERROR_INCORRECT_SIZE The operation failed because the data associated with provided uid is not the same size as `data_size`
+ * \retval PSA_PS_ERROR_STORAGE_FAILURE The operation failed because the physical storage has failed (Fatal error)
+ * \retval PSA_PS_ERROR_OPERATION_FAILED The operation failed because of an unspecified internal failure
+ * \retval PSA_PS_ERROR_DATA_CORRUPT The operation failed because of an authentication failure when attempting to get the key
+ * \retval PSA_PS_ERROR_AUTH_FAILED The operation failed because the data associated with the UID failed authentication
+ */
+psa_ps_status_t psa_ps_get( psa_ps_uid_t uid,
+ uint32_t data_offset,
+ uint32_t data_length,
+ void *p_data );
+
+/**
+ * \brief Retrieve the metadata about the provided uid
+ *
+ * \param[in] uid The identifier for the data
+ * \param[out] p_info A pointer to the `psa_ps_info_t` struct that will be populated with the metadata
+ *
+ * \return A status indicating the success/failure of the operation
+ *
+ * \retval PSA_PS_SUCCESS The operation completed successfully
+ * \retval PSA_PS_ERROR_INVALID_ARGUMENT The operation failed because one or more of the given arguments were invalid (null pointer, wrong flags etc.)
+ * \retval PSA_PS_ERROR_UID_NOT_FOUND The operation failed because the provided uid value was not found in the storage
+ * \retval PSA_PS_ERROR_STORAGE_FAILURE The operation failed because the physical storage has failed (Fatal error)
+ * \retval PSA_PS_ERROR_OPERATION_FAILED The operation failed because of an unspecified internal failure
+ * \retval PSA_PS_ERROR_DATA_CORRUPT The operation failed because of an authentication failure when attempting to get the key
+ * \retval PSA_PS_ERROR_AUTH_FAILED The operation failed because the data associated with the UID failed authentication
+ */
+psa_ps_status_t psa_ps_get_info( psa_ps_uid_t uid, struct psa_ps_info_t *p_info );
+
+/**
+ * \brief Remove the provided uid and its associated data from the storage
+ *
+ * \param[in] uid The identifier for the data to be removed
+ *
+ * \return A status indicating the success/failure of the operation
+ *
+ * \retval PSA_PS_SUCCESS The operation completed successfully
+ * \retval PSA_PS_ERROR_INVALID_ARGUMENT The operation failed because one or more of the given arguments were invalid (null pointer, wrong flags etc.)
+ * \retval PSA_PS_ERROR_UID_NOT_FOUND The operation failed because the provided uid value was not found in the storage
+ * \retval PSA_PS_ERROR_WRITE_ONCE The operation failed because the provided uid value was created with psa_eps_WRITE_ONCE_FLAG
+ * \retval PSA_PS_ERROR_STORAGE_FAILURE The operation failed because the physical storage has failed (Fatal error)
+ * \retval PSA_PS_ERROR_OPERATION_FAILED The operation failed because of an unspecified internal failure
+ */
+psa_ps_status_t psa_ps_remove( psa_ps_uid_t uid );
+
+/**
+ * Creates an asset based on the given identifier, the maximum size and
+ * creation flags. This create allocates the space in the secure storage
+ * area without setting any data in the asset.
+ *
+ * It is only necessary to call this function for items that will be written
+ * with the \ref psa_ps_set_extended function. If only the \ref psa_ps_set function
+ * is needed, calls to this function are redundant.
+ *
+ * If the \ref PSA_PS_FLAG_WRITE_ONCE flag is passed, implementations should
+ * return \ref PSA_PS_ERROR_FLAGS_NOT_SUPPORTED.
+ *
+ * This function is optional. Not all PSA Protected Storage Implementations
+ * will implement this function. Consult the documentation of your chosen
+ * platform to determine if it is present.
+ *
+ * \param[in] uid A unique identifier for the asset.
+ * \param[in] size The maximum size in bytes of the asset.
+ * \param[in] create_flags Create flags \ref psa_ps_create_flags_t.
+ *
+ * \retval PSA_PS_SUCCESS The assest does not exist and the input parameters are correct or
+ * the asset already exists, the input parameters are the same that
+ * have been used to create the asset and the owner is the same and the current asset content is kept
+ * TDB: "Owner is the same" doesn't really make sense from a PSA perspective, as each partition
+ * has its own UID space, making other partitions' data unadressable
+ * \retval PSA_PS_ERROR_STORAGE_FAILURE The create action has a physical storage error
+ * \retval PSA_PS_ERROR_INSUFFICIENT_SPACE The maximum size is bigger of the current available space
+ * \retval PSA_PS_ERROR_FLAGS_NOT_SUPPORTED One or more create_flags are not valid or supported
+ * \retval PSA_PS_ERROR_INVALID_ARGUMENT The asset exists and the input paramters are not the same as the existing asset
+ * \retval PSA_PS_ERROR_NOT_SUPPORTED The implementation of the API does not support this function
+ * \retval PSA_PS_ERROR_OPERATION_FAILED The operation has failed due to an unspecified error
+ */
+psa_ps_status_t psa_ps_create( psa_ps_uid_t uid,
+ uint32_t size,
+ psa_ps_create_flags_t create_flags );
+
+/**
+ * Sets partial data into an asset based on the given identifier, data_offset,
+ * data length and p_data.
+ *
+ * Before calling this function, the asset must have been created with a call
+ * to \ref psa_ps_create.
+ *
+ * This function is optional. Not all PSA Protected Storage Implementations
+ * will implement this function. Consult the documentation of your chosen
+ * platform to determine if it is present.
+ *
+ * \param[in] uid The unique identifier for the asset.
+ * \param[in] data_offset Offset within the asset to start the write.
+ * \param[in] data_length The size in bytes of the data in p_data to write.
+ * \param[in] p_data Pointer to a buffer which contains the data to write.
+ *
+ * \retval PSA_SUCCESS If the asset exists, the input parameters are correct and the data
+ * is correctly written in the physical storage
+ * \retval PSA_PS_ERROR_STORAGE_FAILURE If the data is not written correctly in the physical storage
+ * \retval PSA_PS_ERROR_OFFSET_INVALID The operation failed because an offset was supplied that is invalid
+ * for the allocated size of the space
+ * reserved for the `uid` when \ref psa_psa_create
+ * was called. For example, offset + size
+ * is too large
+ * \retval PSA_PS_ERROR_INVALID_ARGUMENT The operation failed because one or more of the given arguments were invalid (null pointer, wrong flags, etc)
+ * \retval PSA_PS_ERROR_UID_NOT_FOUND The specified UID was not found
+ * \retval PSA_PS_ERROR_NOT_SUPPORTED The implementation of the API does not support this function
+ * \retval PSA_PS_ERROR_OPERATION_FAILED The operation failed due to an unspecified error
+ * \retval PSA_PS_ERROR_DATA_CORRUPT The operation failed because the existing data has been corrupted
+ * \retval PSA_PS_ERROR_AUTH_FAILED The operation failed because the existing data failed authentication (MAC check failed)
+ */
+psa_ps_status_t psa_ps_set_extended( psa_ps_uid_t uid,
+ uint32_t data_offset,
+ uint32_t data_length,
+ const void *p_data );
+
+/**
+ * Returns a bitmask with flags set for all of the optional features supported
+ * by the implementation.
+ *
+ * Currently defined flags are limited to:
+ * - \ref PSA_PS_SUPPORT_SET_EXTENDED
+ */
+uint32_t psa_ps_get_support( void );
+
+#ifdef __cplusplus
+}
+#endif
+
+
+#endif // __PSA_PROTECTED_STORAGE_H__