This file describes the PSA Protected Storage API. More...

#include <stddef.h>
#include <stdint.h>
#include "psa/error.h"
#include "psa/storage_common.h"

Macros
#define	PSA_PS_API_VERSION_MAJOR 1
	The major version number of the PSA PS API. More...

#define	PSA_PS_API_VERSION_MINOR 1
	The minor version number of the PSA PS API. More...

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)
	create a new or modify an existing key/value pair More...

psa_status_t	psa_ps_get (psa_storage_uid_t uid, size_t data_offset, size_t data_length, void p_data, size_t p_data_length)
	Retrieve the value for a provided uid. More...

psa_status_t	psa_ps_get_info (psa_storage_uid_t uid, struct psa_storage_info_t *p_info)
	Retrieve the metadata about the provided uid. More...

psa_status_t	psa_ps_remove (psa_storage_uid_t uid)
	Remove the provided uid and its associated data from the storage. More...

psa_status_t	psa_ps_create (psa_storage_uid_t uid, size_t size, psa_storage_create_flags_t create_flags)
	Creates an asset based on the given identifier, the maximum size and creation flags. More...

psa_status_t	psa_ps_set_extended (psa_storage_uid_t uid, size_t data_offset, size_t data_length, const void *p_data)
	Sets partial data into an asset based on the given identifier, data_offset, data length and p_data. More...

uint32_t	psa_ps_get_support (void)
	Returns a bitmask with flags set for all of the optional features supported by the implementation. More...

Detailed Description

This file describes the PSA Protected Storage API.

Definition in file protected_storage.h.

Macro Definition Documentation

◆ PSA_PS_API_VERSION_MAJOR

#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

Definition at line 34 of file protected_storage.h.

◆ PSA_PS_API_VERSION_MINOR

#define PSA_PS_API_VERSION_MINOR 1

The minor version number of the PSA PS API.

It will be incremented in small updates that are unlikely to include breaking changes

Definition at line 35 of file protected_storage.h.

Function Documentation

◆ 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
	)

create a new or modify an existing key/value pair

Parameters

[in]	uid	the identifier for the data
[in]	data_length	The size in bytes of the data in `p_data`
[in]	p_data	A buffer containing the data
[in]	create_flags	The flags indicating the properties of the data

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

Return values

PSA_SUCCESS	The operation completed successfully
PSA_ERROR_NOT_PERMITTED	The operation failed because the provided uid value was already created with PSA_STORAGE_WRITE_ONCE_FLAG
PSA_ERROR_INVALID_ARGUMENT	The operation failed because one or more of the given arguments were invalid.
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
PSA_ERROR_INSUFFICIENT_STORAGE	The operation failed because there was insufficient space on the storage medium
PSA_ERROR_STORAGE_FAILURE	The operation failed because the physical storage has failed (Fatal error)
PSA_ERROR_GENERIC_ERROR	The operation failed because of an unspecified internal failure

◆ psa_ps_get()

psa_status_t psa_ps_get	(	psa_storage_uid_t	uid,
		size_t	data_offset,
		size_t	data_length,
		void *	p_data,
		size_t *	p_data_length
	)

Retrieve the value for a provided uid.

Parameters

[in]	uid	The identifier for the data
[in]	data_offset	The offset within the data associated with the `uid` to start retrieving data
[in]	data_length	The amount of data to read (and the minimum allocated size of the `p_data` buffer)
[out]	p_data	The buffer where the data will be placed upon successful completion
[out]	p_data_length	The actual amount of data returned

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

Return values

PSA_SUCCESS	The operation completed successfully
PSA_ERROR_INVALID_ARGUMENT	The operation failed because one or more of the given arguments were invalid (null pointer, wrong flags etc.)
PSA_ERROR_DOES_NOT_EXIST	The operation failed because the provided uid value was not found in the storage
PSA_ERROR_BUFFER_TOO_SMALL	The operation failed because the data associated with provided uid does not fit `data_size`
PSA_ERROR_STORAGE_FAILURE	The operation failed because the physical storage has failed (Fatal error)
PSA_ERROR_GENERIC_ERROR	The operation failed because of an unspecified internal failure
PSA_ERROR_DATA_CORRUPT	The operation failed because of an authentication failure when attempting to get the key
PSA_ERROR_INVALID_SIGNATURE	The operation failed because the data associated with the UID failed authentication

◆ psa_ps_get_info()

psa_status_t psa_ps_get_info	(	psa_storage_uid_t	uid,
		struct psa_storage_info_t *	p_info
	)

Retrieve the metadata about the provided uid.

Parameters

[in]	uid	The identifier for the data
[out]	p_info	A pointer to the `psa_storage_info_t` struct that will be populated with the metadata

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

Return values

PSA_SUCCESS	The operation completed successfully
PSA_ERROR_INVALID_ARGUMENT	The operation failed because one or more of the given arguments were invalid (null pointer, wrong flags etc.)
PSA_ERROR_DOES_NOT_EXIST	The operation failed because the provided uid value was not found in the storage
PSA_ERROR_STORAGE_FAILURE	The operation failed because the physical storage has failed (Fatal error)
PSA_ERROR_GENERIC_ERROR	The operation failed because of an unspecified internal failure
PSA_ERROR_DATA_CORRUPT	The operation failed because of an authentication failure when attempting to get the key
PSA_ERROR_INVALID_SIGNATURE	The operation failed because the data associated with the UID failed authentication

◆ psa_ps_remove()

psa_status_t psa_ps_remove ( psa_storage_uid_t uid )

Remove the provided uid and its associated data from the storage.

Parameters

[in] uid The identifier for the data to be removed

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

Return values

PSA_SUCCESS	The operation completed successfully
PSA_ERROR_INVALID_ARGUMENT	The operation failed because one or more of the given arguments were invalid (null pointer, wrong flags etc.)
PSA_ERROR_DOES_NOT_EXIST	The operation failed because the provided uid value was not found in the storage
PSA_ERROR_NOT_PERMITTED	The operation failed because the provided uid value was created with psa_eps_WRITE_ONCE_FLAG
PSA_ERROR_STORAGE_FAILURE	The operation failed because the physical storage has failed (Fatal error)
PSA_ERROR_GENERIC_ERROR	The operation failed because of an unspecified internal failure

◆ psa_ps_create()

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

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 psa_ps_set_extended function. If only the psa_ps_set function is needed, calls to this function are redundant.

If the PSA_STORAGE_FLAG_WRITE_ONCE flag is passed, implementations should return PSA_ERROR_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.

Parameters

[in]	uid	A unique identifier for the asset.
[in]	size	The maximum size in bytes of the asset.
[in]	create_flags	Create flags psa_storage_create_flags_t.

Return values

PSA_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
PSA_ERROR_STORAGE_FAILURE	The create action has a physical storage error
PSA_ERROR_INSUFFICIENT_STORAGE	The maximum size is bigger of the current available space
PSA_ERROR_NOT_SUPPORTED	One or more create_flags are not valid or supported. Or, the implementation of the API does not support this function
PSA_ERROR_INVALID_ARGUMENT	The asset exists and the input paramters are not the same as the existing asset
PSA_ERROR_GENERIC_ERROR	The operation has failed due to an unspecified 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
	)

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 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.

Parameters

[in]	uid	The unique identifier for the asset.
[in]	data_offset	Offset within the asset to start the write.
[in]	data_length	The size in bytes of the data in p_data to write.
[in]	p_data	Pointer to a buffer which contains the data to write.

Return values

PSA_SUCCESS	If the asset exists, the input parameters are correct and the data is correctly written in the physical storage
PSA_ERROR_STORAGE_FAILURE	If the data is not written correctly in the physical storage
PSA_ERROR_INVALID_ARGUMENT	The operation failed because one or more of the given arguments were invalid (null pointer, wrong flags, etc)
PSA_ERROR_DOES_NOT_EXIST	The specified UID was not found
PSA_ERROR_NOT_SUPPORTED	The implementation of the API does not support this function
PSA_ERROR_GENERIC_ERROR	The operation failed due to an unspecified error
PSA_ERROR_DATA_CORRUPT	The operation failed because the existing data has been corrupted
PSA_ERROR_INVALID_SIGNATURE	The operation failed because the existing data failed authentication (MAC check failed)

◆ psa_ps_get_support()

uint32_t psa_ps_get_support ( void )

Returns 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

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ PSA_PS_API_VERSION_MAJOR

◆ PSA_PS_API_VERSION_MINOR

Function Documentation

◆ psa_ps_set()

◆ psa_ps_get()

◆ psa_ps_get_info()

◆ psa_ps_remove()

◆ psa_ps_create()

◆ psa_ps_set_extended()

◆ psa_ps_get_support()