283 lines
14 KiB
C
283 lines
14 KiB
C
/*
|
|
* 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 */
|