/*
 * Copyright (c) 2019-2020, Arm Limited. All rights reserved.
 *
 * SPDX-License-Identifier: BSD-3-Clause
 *
 */

/* This file describes the PSA Protected Storage API */

#ifndef PSA_PROTECTED_STORAGE_H
#define PSA_PROTECTED_STORAGE_H

#include <stddef.h>
#include <stdint.h>

#include "psa/error.h"
#include "psa/storage_common.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * \brief PSA_PS_API_VERSION version
 *
 * Major and minor PSA_PS_API_VERSION numbers
 */
#define PSA_PS_API_VERSION_MAJOR  1
#define PSA_PS_API_VERSION_MINOR  0

// This version of the header file is associated with 1.0 final release

/**
 * \brief Create a new, or modify an existing, uid/value pair
 *
 * Stores data in the protected storage.
 *
 * \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_FLAG_WRITE_ONCE
 * \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
 * \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_GENERIC_ERROR         The operation failed because of an
 *                                         unspecified internal failure
 */
psa_status_t psa_ps_set(psa_storage_uid_t uid,
                        size_t data_length,
                        const void *p_data,
                        psa_storage_create_flags_t create_flags);

/**
 * \brief Retrieve data associated with a provided uid
 *
 * Retrieves up to `data_size` bytes of the data associated with `uid`, starting
 * at `data_offset` bytes from the beginning of the data. Upon successful
 * completion, the data will be placed in the `p_data` buffer, which must be at
 * least `data_size` bytes in size. The length of the data returned will be in
 * `p_data_length`. If `data_size` is 0, the contents of `p_data_length` will
 * be set to zero.
 *
 * \param[in]  uid            The uid value
 * \param[in]  data_offset    The starting offset of the data requested
 * \param[in]  data_size      The amount of data requested
 * \param[out] p_data         On success, the buffer where the data will
 *                            be placed
 * \param[out] p_data_length  On success, this will contain size of the data
 *                            placed in `p_data`
 *
 * \return A status indicating the success/failure of the operation
 *
 * \retval PSA_SUCCESS                 The operation completed successfully
 * \retval PSA_ERROR_INVALID_ARGUMENT  The operation failed because one of the
 *                                     provided arguments (`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 `data_offset` is
 *                                     larger than the size of the data
 *                                     associated with `uid`
 * \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_GENERIC_ERROR     The operation failed because of an
 *                                     unspecified internal failure
 * \retval PSA_ERROR_DATA_CORRUPT      The operation failed because the data
 *                                     associated with the UID was corrupt
 * \retval PSA_ERROR_INVALID_SIGNATURE The operation failed because the data
 *                                     associated with the UID failed
 *                                     authentication
 */
psa_status_t psa_ps_get(psa_storage_uid_t uid,
                        size_t data_offset,
                        size_t data_size,
                        void *p_data,
                        size_t *p_data_length);

/**
 * \brief Retrieve the metadata about the provided uid
 *
 * Retrieves the metadata stored for a given `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_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
 * \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_GENERIC_ERROR     The operation failed because of an
 *                                     unspecified internal failure
 * \retval PSA_ERROR_DATA_CORRUPT      The operation failed because the data
 *                                     associated with the UID was corrupt
 */
psa_status_t psa_ps_get_info(psa_storage_uid_t uid,
                             struct psa_storage_info_t *p_info);

/**
 * \brief Remove the provided uid and its associated data from the storage
 *
 * Removes previously stored data and any associated metadata,
 * including rollback protection data.
 *
 * \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_INVALID_ARGUMENT  The operation failed because one or more
 *                                     of the given arguments were invalid (null
 *                                     pointer, wrong flags and so on)
 * \retval PSA_ERROR_DOES_NOT_EXIST    The operation failed because the provided
 *                                     uid value was not found in the storage
 * \retval PSA_ERROR_NOT_PERMITTED     The operation failed because the provided
 *                                     uid value was created with
 *                                     PSA_STORAGE_FLAG_WRITE_ONCE
 * \retval PSA_ERROR_STORAGE_FAILURE   The operation failed because the physical
 *                                     storage has failed (Fatal error)
 * \retval PSA_ERROR_GENERIC_ERROR     The operation failed because of an
 *                                     unspecified internal failure
 */
psa_status_t psa_ps_remove(psa_storage_uid_t uid);

/**
 * \brief Reserves storage for the specified uid
 *
 * Upon success, the capacity of the storage will be capacity, and the size
 * will be 0. It is only necessary to call this function for assets that will
 * be written with the psa_ps_set_extended function. If only the psa_ps_set
 * function is needed, calls to this function are redundant.
 *
 * \param[in] uid           The `uid` value
 * \param[in] capacity      The capacity to be allocated in bytes
 * \param[in] create_flags  Flags indicating properties of storage
 *
 * \return A status indicating the success/failure of the operation
 *
 * \retval PSA_SUCCESS                     The operation completed successfully
 * \retval PSA_ERROR_STORAGE_FAILURE       The operation failed because the
 *                                         physical storage has failed
 *                                         (Fatal error)
 * \retval PSA_ERROR_INSUFFICIENT_STORAGE  The operation failed because the
 *                                         capacity is bigger than the current
 *                                         available space
 * \retval PSA_ERROR_NOT_SUPPORTED         The operation failed because the
 *                                         function is not implemented or one
 *                                         or more create_flags are not
 *                                         supported.
 * \retval PSA_ERROR_INVALID_ARGUMENT      The operation failed because uid was
 *                                         0 or create_flags specified flags
 *                                         that are not defined in the API.
 * \retval PSA_ERROR_GENERIC_ERROR         The operation failed due to an
 *                                         unspecified error
 * \retval PSA_ERROR_ALREADY_EXISTS        Storage for the specified uid
 *                                         already exists
 */
psa_status_t psa_ps_create(psa_storage_uid_t uid,
                           size_t capacity,
                           psa_storage_create_flags_t create_flags);

/**
 * \brief Sets partial data into an asset
 *
 * Before calling this function, the storage must have been reserved with a call
 * to psa_ps_create. It can also be used to overwrite data in an asset that was
 * created with a call to psa_ps_set. Calling this function with data_length = 0
 * is permitted, which will make no change to the stored data.This function can
 * overwrite existing data and/or extend it up to the capacity for the uid
 * specified in psa_ps_create, but cannot create gaps.
 *
 * That is, it has preconditions:
 * - data_offset <= size
 * - data_offset + data_length <= capacity
 * and postconditions:
 * - size = max(size, data_offset + data_length)
 * - capacity unchanged.
 *
 * \param[in] uid          The `uid` value
 * \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
 *
 * \return A status indicating the success/failure of the operation
 *
 * \retval PSA_SUCCESS                  The asset exists, the input parameters
 *                                      are correct and the data is correctly
 *                                      written in the physical storage.
 * \retval PSA_ERROR_STORAGE_FAILURE    The data was not written correctly in
 *                                      the physical storage
 * \retval PSA_ERROR_INVALID_ARGUMENT   The operation failed because one or more
 *                                      of the preconditions listed above
 *                                      regarding data_offset, size, or
 *                                      data_length was violated.
 * \retval PSA_ERROR_DOES_NOT_EXIST     The specified uid was not found
 * \retval PSA_ERROR_NOT_SUPPORTED      The implementation of the API does not
 *                                      support this function
 * \retval PSA_ERROR_GENERIC_ERROR      The operation failed due to an
 *                                      unspecified error
 * \retval PSA_ERROR_DATA_CORRUPT       The operation failed because the
 *                                      existing data has been corrupted.
 * \retval PSA_ERROR_INVALID_SIGNATURE  The operation failed because the
 *                                      existing data failed authentication
 *                                      (MAC check failed).
 * \retval PSA_ERROR_NOT_PERMITTED      The operation failed because it was
 *                                      attempted on an asset which was written
 *                                      with the flag
 *                                      PSA_STORAGE_FLAG_WRITE_ONCE
 */
psa_status_t psa_ps_set_extended(psa_storage_uid_t uid,
                                 size_t data_offset,
                                 size_t data_length,
                                 const void *p_data);

/**
 * \brief Lists optional features.
 *
 * \return                              A bitmask with flags set for all of
 *                                      the optional features supported by the
 *                                      implementation.Currently defined flags
 *                                      are limited to
 *                                      PSA_STORAGE_SUPPORT_SET_EXTENDED
 */
uint32_t psa_ps_get_support(void);

#ifdef __cplusplus
}
#endif

#endif /* PSA_PROTECTED_STORAGE_H */