The PSA Protected Storage (PS) API. More...

#include <psa/storage_common.h>

Macros
#define	PSA_PS_API_VERSION_MAJOR 1

#define	PSA_PS_API_VERSION_MINOR 0

Functions
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)
	Creates a new or modifies an existing entry.

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)
	Retrieves data associated with the provided `uid`.

psa_status_t	psa_ps_get_info (psa_storage_uid_t uid, struct psa_storage_info_t *p_info)
	Retrieves the metadata of a given entry.

psa_status_t	psa_ps_remove (psa_storage_uid_t uid)
	Removes the provided `uid` and its associated data.

psa_status_t	psa_ps_create (psa_storage_uid_t uid, size_t capacity, psa_storage_create_flags_t create_flags)
	Reserves storage for the provided `uid`.

psa_status_t	psa_ps_set_extended (psa_storage_uid_t uid, size_t data_offset, size_t data_length, const void *p_data)
	Writes part of the data associated with the provided `uid`.

uint32_t	psa_ps_get_support (void)
	Lists optional features.

Detailed Description

The PSA Protected Storage (PS) API.

For more information on the PS, see The Protected Storage API.

Macro Definition Documentation

◆ PSA_PS_API_VERSION_MAJOR

#define PSA_PS_API_VERSION_MAJOR 1

◆ PSA_PS_API_VERSION_MINOR

#define PSA_PS_API_VERSION_MINOR 0

Function Documentation

◆ psa_ps_create()

psa_status_t psa_ps_create	(	psa_storage_uid_t	uid,
		size_t	capacity,
		psa_storage_create_flags_t	create_flags )

Reserves storage for the provided uid.

Upon success, the capacity of the storage for uid will be capacity, and the size will be 0. It is only necessary to call this function for data that will be written with the psa_ps_set_extended() function. If only the psa_ps_set() function is used, calls to this function are redundant. This function cannot be used to replace or resize an existing entry.

Parameters

uid	The identifier of the entry to reserve storage for.
capacity	The capacity, in bytes, to allocate.
create_flags	Flags indicating the properties of the entry.

Return values

PSA_SUCCESS	The operation completed successfully.
PSA_ERROR_GENERIC_ERROR	An unspecified internal failure happened.
PSA_ERROR_NOT_SUPPORTED	The implementation doesn't support this function or one or more of the flags provided in `create_flags` are not supported or invalid.
PSA_ERROR_INVALID_ARGUMENT	`uid` is invalid.
PSA_ERROR_ALREADY_EXISTS	An entry with the provided `uid` already exists.
PSA_ERROR_INSUFFICIENT_STORAGE	There is insufficient space on the storage medium.
PSA_ERROR_STORAGE_FAILURE	The physical storage has failed (fatal error).

◆ psa_ps_get()

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 )

Retrieves data associated with the provided uid.

Parameters

[in]	uid	The identifier of the data.
[in]	data_offset	The offset, in bytes, from which to start reading the data.
[in]	data_size	The number of bytes to read.
[out]	p_data	The buffer where the data will be placed on success. Must be at least `data_size` bytes long.
[out]	p_data_length	On success, the number of bytes placed in `p_data`.

Return values

PSA_SUCCESS	The operation completed successfully.
PSA_ERROR_GENERIC_ERROR	An unspecified internal failure happened.
PSA_ERROR_INVALID_ARGUMENT	One or more of the arguments are invalid. This can also happen if `data_offset` is larger than the size of the data associated with `uid`.
PSA_ERROR_DOES_NOT_EXIST	The provided `uid` was not found in the storage.
PSA_ERROR_STORAGE_FAILURE	The physical storage has failed (fatal error).
PSA_ERROR_INVALID_SIGNATURE	The data associated with `uid` failed authentication.
PSA_ERROR_DATA_CORRUPT	The data associated with `uid` is corrupt.

◆ psa_ps_get_info()

psa_status_t psa_ps_get_info	(	psa_storage_uid_t	uid,
		struct psa_storage_info_t *	p_info )

Retrieves the metadata of a given entry.

Parameters

[in]	uid	The identifier of the entry.
[out]	p_info	A pointer to a `psa_storage_info_t` struct that will be populated with the metadata on success.

Return values

PSA_SUCCESS	The operation completed successfully.
PSA_ERROR_GENERIC_ERROR	An unspecified internal failure happened.
PSA_ERROR_INVALID_ARGUMENT	One or more of the arguments are invalid.
PSA_ERROR_DOES_NOT_EXIST	The provided `uid` was not found in the storage.
PSA_ERROR_STORAGE_FAILURE	The physical storage has failed (fatal error).
PSA_ERROR_INVALID_SIGNATURE	The data associated with `uid` failed authentication.
PSA_ERROR_DATA_CORRUPT	The data associated with `uid` is corrupt.

◆ psa_ps_get_support()

uint32_t psa_ps_get_support ( void )

Lists optional features.

Returns: A bitmask with flags set for the optional features supported by the implementation. Currently defined flags are limited to PSA_STORAGE_SUPPORT_SET_EXTENDED.

◆ psa_ps_remove()

psa_status_t psa_ps_remove ( psa_storage_uid_t uid )

Removes the provided uid and its associated data.

Deletes previously stored data and any associated metadata, including rollback protection data.

Parameters

uid	The identifier of the entry to remove.

Returns: A status indicating the success/failure of the operation

Return values

PSA_SUCCESS	The operation completed successfully.
PSA_ERROR_GENERIC_ERROR	An unspecified internal failure happened.
PSA_ERROR_NOT_PERMITTED	The entry was created with `PSA_STORAGE_FLAG_WRITE_ONCE`.
PSA_ERROR_INVALID_ARGUMENT	`uid` is invalid.
PSA_ERROR_DOES_NOT_EXIST	The provided `uid` was not found in the storage.
PSA_ERROR_STORAGE_FAILURE	The physical storage has failed (fatal error).

◆ psa_ps_set()

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 )

Creates a new or modifies an existing entry.

Parameters

uid	The identifier of the data. Must be nonzero.
data_length	The size in bytes of the data in `p_data` to store.
p_data	A buffer containing the data to store.
create_flags	Flags indicating the properties of the entry.

Return values

PSA_SUCCESS	The operation completed successfully.
PSA_ERROR_GENERIC_ERROR	An unspecified internal failure happened.
PSA_ERROR_NOT_PERMITTED	An entry associated with the provided `uid` already exists and was created with `PSA_STORAGE_FLAG_WRITE_ONCE`.
PSA_ERROR_NOT_SUPPORTED	One or more of the flags provided in `create_flags` are not supported or invalid.
PSA_ERROR_INVALID_ARGUMENT	One or more arguments other than `create_flags` are invalid.
PSA_ERROR_INSUFFICIENT_STORAGE	There is insufficient space on the storage medium.
PSA_ERROR_STORAGE_FAILURE	The physical storage has failed (fatal error).

◆ psa_ps_set_extended()

psa_status_t psa_ps_set_extended	(	psa_storage_uid_t	uid,
		size_t	data_offset,
		size_t	data_length,
		const void *	p_data )

Writes part of the data associated with the provided uid.

Before calling this function, storage must have been reserved with a call to psa_ps_create(). This function can also be used to overwrite data that was written with psa_ps_set(). This function can overwrite existing data and/or extend it up to the capacity of the entry specified in psa_ps_create(), but cannot create gaps.

Parameters

uid	The identifier of the entry to write.
data_offset	The offset, in bytes, from which to start writing the data. Can be at most the current size of the data.
data_length	The size in bytes of the data in `p_data` to write. `data_offset` `data_length` can be at most the capacity of the entry.
p_data	A buffer containing the data to write.

Return values

PSA_SUCCESS	The operation completed successfully.
PSA_ERROR_GENERIC_ERROR	An unspecified internal failure happened.
PSA_ERROR_NOT_PERMITTED	The entry was created with `PSA_STORAGE_FLAG_WRITE_ONCE`.
PSA_ERROR_NOT_SUPPORTED	The implementation doesn't support this function.
PSA_ERROR_INVALID_ARGUMENT	One or more of the arguments are invalid.
PSA_ERROR_DOES_NOT_EXIST	The provided `uid` was not found in the storage.
PSA_ERROR_STORAGE_FAILURE	The physical storage has failed (fatal error).
PSA_ERROR_INVALID_SIGNATURE	The data associated with `uid` failed authentication.
PSA_ERROR_DATA_CORRUPT	The data associated with `uid` is corrupt.

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ PSA_PS_API_VERSION_MAJOR

◆ PSA_PS_API_VERSION_MINOR

Function Documentation

◆ psa_ps_create()

◆ psa_ps_get()

◆ psa_ps_get_info()

◆ psa_ps_get_support()

◆ psa_ps_remove()

◆ psa_ps_set()

◆ psa_ps_set_extended()