5 API Reference¶
5.1 Status codes¶
The Secure Storage API uses the status code definitions that are shared with the other PSA Certified APIs.
The following elements are defined in psa/error.h from PSA Certified Status code API [PSA-STAT] (previously defined in [PSA-FFM]):
typedef int32_t psa_status_t; #define PSA_SUCCESS ((psa_status_t)0) #define PSA_ERROR_GENERIC_ERROR ((psa_status_t)-132) #define PSA_ERROR_NOT_PERMITTED ((psa_status_t)-133) #define PSA_ERROR_NOT_SUPPORTED ((psa_status_t)-134) #define PSA_ERROR_INVALID_ARGUMENT ((psa_status_t)-135) #define PSA_ERROR_DOES_NOT_EXIST ((psa_status_t)-140) #define PSA_ERROR_INSUFFICIENT_STORAGE ((psa_status_t)-142) #define PSA_ERROR_STORAGE_FAILURE ((psa_status_t)-146) #define PSA_ERROR_INVALID_SIGNATURE ((psa_status_t)-149) #define PSA_ERROR_DATA_CORRUPT ((psa_status_t)-152)
These definitions must be available to an application that includes either of the psa/internal_trusted_storage.h or psa/protected_storage.h header files.
Implementation note
An implementation is permitted to define the status code interface elements within the Secure Storage API header files, or to define them via inclusion of a psa/error.h header file that is shared with the implementation of other PSA Certified APIs.
5.2 General Definitions¶
These definitions must be defined in the header file psa/storage_common.h.
5.2.1 psa_storage_info_t (struct)¶
A container for metadata associated with a specific uid.
struct psa_storage_info_t { size_t capacity; size_t size; psa_storage_create_flags_t flags; };
Fields
capacityThe allocated capacity of the storage associated with a
uid.sizeThe size of the data associated with a
uid.flagsThe flags set when the
uidwas create
5.2.2 psa_storage_create_flags_t (typedef)¶
Flags used when creating a data entry.
typedef uint32_t psa_storage_create_flags_t;
5.2.3 psa_storage_uid_t (typedef)¶
A type for uid used for identifying data.
typedef uint64_t psa_storage_uid_t;
5.2.4 PSA_STORAGE_FLAG_NONE (macro)¶
#define PSA_STORAGE_FLAG_NONE 0u
No flags to pass.
5.2.5 PSA_STORAGE_FLAG_WRITE_ONCE (macro)¶
#define PSA_STORAGE_FLAG_WRITE_ONCE (1u << 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_storage_create_flags_t.
5.2.6 PSA_STORAGE_FLAG_NO_CONFIDENTIALITY (macro)¶
#define PSA_STORAGE_FLAG_NO_CONFIDENTIALITY (1u << 1)
The data associated with the uid is public and therefore does not require confidentiality. It therefore only needs to be integrity protected.
5.2.7 PSA_STORAGE_FLAG_NO_REPLAY_PROTECTION (macro)¶
#define PSA_STORAGE_FLAG_NO_REPLAY_PROTECTION (1u << 2)
The data associated with the uid does not require replay protection. This can permit faster storage — but it permits an attacker with physical access to revert to an earlier version of the data.
5.2.8 PSA_STORAGE_SUPPORT_SET_EXTENDED (macro)¶
#define PSA_STORAGE_SUPPORT_SET_EXTENDED (1u << 0)
Flag indicating that psa_ps_create() and psa_ps_set_extended() are supported.
5.3 Internal Trusted Storage API¶
These definitions must be defined in the header file psa/internal_trusted_storage.h.
5.3.1 PSA_ITS_API_VERSION_MAJOR (macro)¶
The major version number of the Internal Trusted Storage API.
#define PSA_ITS_API_VERSION_MAJOR 1
It will be incremented on significant updates that can include breaking changes.
5.3.2 PSA_ITS_API_VERSION_MINOR (macro)¶
The minor version number of the Internal Trusted Storage API.
#define PSA_ITS_API_VERSION_MINOR 0
It will be incremented in small updates that are unlikely to include breaking changes.
5.3.3 psa_its_set (function)¶
Set the data associated with the specified uid.
psa_status_t psa_its_set(psa_storage_uid_t uid, size_t data_length, const void * p_data, psa_storage_create_flags_t create_flags);
Parameters
uidThe identifier for the data.
data_lengthThe size in bytes of the data in
p_data. Ifdata_length == 0the implementation will create a zero-length asset associated with theuid. While no data can be stored in such an asset, a call topsa_its_get_info()will returnPSA_SUCCESS.p_dataA buffer of
data_lengthcontaining the data to store.create_flagsThe flags that the data will be stored with.
Returns: psa_status_t
A status indicating the success or failure of the operation.
PSA_SUCCESSThe operation completed successfully.
PSA_ERROR_NOT_PERMITTEDThe operation failed because the provided
uidvalue was already created withPSA_STORAGE_FLAG_WRITE_ONCE.PSA_ERROR_INVALID_ARGUMENTThe operation failed because either:
the
uidis0.caller cannot access some or all of the memory in the range [
p_data,p_data + data_length - 1].
PSA_ERROR_NOT_SUPPORTEDThe operation failed because one or more of the flags provided in
create_flagsis not supported or is not valid.PSA_ERROR_INSUFFICIENT_STORAGEThe operation failed because there was insufficient space on the storage medium.
PSA_ERROR_STORAGE_FAILUREThe operation failed because the physical storage has failed (Fatal error).
Description
Stores data in the internal storage.
The
uidvalue must not be zero.If
uidexists it must not have been created as withPSA_STORAGE_FLAG_WRITE_ONCE— would result inPSA_ERROR_NOT_PERMITTEDThe caller must have access all memory from
p_datatop_data + data_length.Even if all parameters are correct, the function can fail if there is insufficient storage space or in the case of a storage failure.
5.3.4 psa_its_get (function)¶
Retrieve data associated with a provided uid.
psa_status_t psa_its_get(psa_storage_uid_t uid, size_t data_offset, size_t data_size, void * p_data, size_t * p_data_length);
Parameters
uidThe
uidvalue.data_offsetThe starting offset of the data requested.
data_sizeThe amount of data requested.
p_dataOn success, the buffer where the data will be placed.
p_data_lengthOn success, this will contain size of the data placed in
p_data.
Returns: psa_status_t
A status indicating the success or failure of the operation.
PSA_SUCCESSThe operation completed successfully.
PSA_ERROR_DOES_NOT_EXISTThe operation failed because the provided
uidvalue was not found in the storage.PSA_ERROR_INVALID_ARGUMENTThe operation failed because either:
The
uidis0.The caller cannot access some or all of the memory in the range [
p_data,p_data + data_size - 1].data_offsetis larger than the size of the data associated withuid.
PSA_ERROR_STORAGE_FAILUREThe operation failed because the physical storage has failed (Fatal error).
Description
Retrieves data associated with uid, starting at data_offset bytes from the beginning of the data. Fetches the lesser of data_size or uid.size - data_offset bytes, which can be zero.
psa_its_get() must not return bytes from beyond the end of uid.
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. Any bytes beyond p_data_length are left unmodified.
If data_size is 0 or data_offset == uid.size, the contents of p_data_length will be set to zero, but the contents of p_data are unchanged. The function returns PSA_SUCCESS.
The
uidvalue must not be zero.The value of
data_offsetmust be less than or equal to the length ofuid.If
data_ffsetis greater thanuid.size, no data is retrieved and the functions returns PSA_INVALID_ARGUMENT.If
data_sizeis not zero,p_datamust mot beNULL.The call must have access to the memory from
p_datatop_data + data_size - 1.If the location
uidexists the lesser ofdata_sizeoruid.size - data_offsetbytes are written to the output buffer andp_data_lengthis set to the number of bytes written, which can be zero.Even if all parameters are correct, the function can fail in the case of a storage failure.
5.3.5 psa_its_get_info (function)¶
Retrieve the metadata about the provided uid.
psa_status_t psa_its_get_info(psa_storage_uid_t uid, struct psa_storage_info_t * p_info);
Parameters
uidThe
uidvalue.p_infoA pointer to the
psa_storage_info_tstruct that will be populated with the metadata.
Returns: psa_status_t
A status indicating the success or failure of the operation.
PSA_SUCCESSThe operation completed successfully.
PSA_ERROR_DOES_NOT_EXISTThe operation failed because the provided
uidvalue was not found in the storage.PSA_ERROR_INVALID_ARGUMENTThe operation failed because either:
The
uidis0.The caller cannot access some or all of the memory in the range [
p_info,p_info+sizeof(psa_storage_info_t) - 1]
PSA_ERROR_STORAGE_FAILUREThe operation failed because the physical storage has failed (Fatal error).
Description
Retrieves the metadata stored for a given uid as a psa_storage_info_t structure.
The
uidvalue must not be zero.The call must have access to the memory from
p_infotop_info+sizeof(psa_storage_info_t) - 1.If the location
uidexists the metadata for the object is written top_info.Even if all parameters are correct, the function can fail in the case of a storage failure.
5.3.6 psa_its_remove (function)¶
Remove the provided uid and its associated data from the storage.
psa_status_t psa_its_remove(psa_storage_uid_t uid);
Parameters
uidThe
uidvalue.
Returns: psa_status_t
A status indicating the success or failure of the operation.
PSA_SUCCESSThe operation completed successfully.
PSA_ERROR_NOT_PERMITTEDThe operation failed because the provided
uidvalue was created withPSA_STORAGE_FLAG_WRITE_ONCE.PSA_ERROR_DOES_NOT_EXISTThe operation failed because the provided
uidvalue was not found in the storage.PSA_ERROR_INVALID_ARGUMENTThe
uidis0.PSA_ERROR_STORAGE_FAILUREThe operation failed because the physical storage has failed (Fatal error).
Description
Deletes the data from internal storage.
The
uidvalue must not be zero.If
uidexists it and any metadata are removed from storage.Even if all parameters are correct, the function can fail in the case of a storage failure.
5.4 Protected Storage API¶
These definitions must be defined in the header file psa/protected_storage.h.
5.4.1 PSA_PS_API_VERSION_MAJOR (macro)¶
The major version number of the Protected Storage API.
#define PSA_PS_API_VERSION_MAJOR 1
It will be incremented on significant updates that can include breaking changes.
5.4.2 PSA_PS_API_VERSION_MINOR (macro)¶
The minor version number of the Protected Storage API.
#define PSA_PS_API_VERSION_MINOR 0
It will be incremented in small updates that are unlikely to include breaking changes.
5.4.3 psa_ps_set (function)¶
Set the data associated with the specified uid.
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);
Parameters
uidThe identifier for the data.
data_lengthThe size in bytes of the data in
p_data. Ifdata_length == 0the implementation will create a zero-length asset associated with theuid. While no data can be stored in such an asset, a call topsa_ps_get_info()will returnPSA_SUCCESS.p_dataA buffer containing the data.
create_flagsThe flags indicating the properties of the data.
Returns: psa_status_t
A status indicating the success or failure of the operation.
PSA_SUCCESSThe operation completed successfully.
PSA_ERROR_NOT_PERMITTEDThe operation failed because the provided
uidvalue was already created withPSA_STORAGE_FLAG_WRITE_ONCE.PSA_ERROR_INVALID_ARGUMENTThe operation failed because either:
The
uidis0.The operation failed because caller cannot access some or all of the memory in the range [
p_data,p_data + data_length - 1].
PSA_ERROR_NOT_SUPPORTEDThe operation failed because one or more of the flags provided in
create_flagsis not supported or is not valid.PSA_ERROR_INSUFFICIENT_STORAGEThe operation failed because there was insufficient space on the storage medium.
PSA_ERROR_STORAGE_FAILUREThe operation failed because the physical storage has failed (Fatal error).
PSA_ERROR_GENERIC_ERRORThe operation failed because of an unspecified internal failure.
Description
The newly created asset has a capacity and size that are equal to data_length.
The
uidvalue must not be zero.If
uidexists it must not have been created as withPSA_STORAGE_FLAG_WRITE_ONCE- would result inPSA_ERROR_NOT_PERMITTEDThe caller must have access all memory from
p_datatop_data + data_length.Even if all parameters are correct, the function can fail if there is insufficient storage space or in the case of a storage failure.
5.4.4 psa_ps_get (function)¶
Retrieve data associated with a provided uid.
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);
Parameters
uidThe
uidvalue.data_offsetThe starting offset of the data requested. This must be less than or equal to
uid.size.data_sizeThe amount of data requested.
p_dataOn success, the buffer where the data will be placed.
p_data_lengthOn success, will contain size of the data placed in
p_data.
Returns: psa_status_t
A status indicating the success or failure of the operation.
PSA_SUCCESSThe operation completed successfully.
PSA_ERROR_INVALID_SIGNATUREThe operation failed because the data associated with the
uidfailed authentication.PSA_ERROR_DOES_NOT_EXISTThe operation failed because the provided
uidvalue was not found in the storage.PSA_ERROR_INVALID_ARGUMENTThe operation failed because either:
The
uidis0.The caller cannot access some or all of the memory in the range [
p_data,p_data + data_size - 1].data_offsetis larger than the size of the data associated withuid.
PSA_ERROR_STORAGE_FAILUREThe operation failed because the physical storage has failed (Fatal error).
PSA_ERROR_DATA_CORRUPTThe operation failed because the data associated with the
uidhas been corrupted.PSA_ERROR_GENERIC_ERRORThe operation failed because of an unspecified internal failure.
Description
Retrieves data associated with uid, starting at data_offset bytes from the beginning of the data. Fetches the smaller of data_size or uid.size - data_offset bytes. This can be zero.
psa_ps_get() must not return bytes from beyond the end of uid.
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. Any bytes beyond p_data_length are left unmodified.
If data_size is 0 or data_offset == uid.size, the contents of p_data_length will be set to zero, but the contents of p_data are unchanged. The function returns PSA_SUCCESS.
The
uidvalue must not be zero.The value of
data_offsetmust be less than or equal to the length ofuid.If
data_offsetis greater thanuid.sizethe function retrieves no data and returnsPSA_ERROR_INVALID_ARGUMENTIf
data_sizeis not zero,p_datamust mot beNULL.The call must have access to the memory from
p_datatop_data + data_size - 1.If the location
uidexists the lesser ofdata_sizeanduid.size - data_offsetbytes are written to the output buffer andp_data_lengthis set to the number of bytes written, which can be zero.Any bytes in the buffer beyond
p_data_lengthare left unmodified.Even if all parameters are correct, the function can fail in the case of a storage failure.
5.4.5 psa_ps_get_info (function)¶
Retrieve the metadata about the provided uid.
psa_status_t psa_ps_get_info(psa_storage_uid_t uid, struct psa_storage_info_t * p_info);
Parameters
uidThe identifier for the data.
p_infoA pointer to the
psa_storage_info_tstruct that will be populated with the metadata.
Returns: psa_status_t
A status indicating the success or failure of the operation.
PSA_SUCCESSThe operation completed successfully.
PSA_ERROR_INVALID_SIGNATUREThe operation failed because the data associated with the
uidfailed authentication.PSA_ERROR_DOES_NOT_EXISTThe operation failed because the provided
uidvalue was not found in the storage.PSA_ERROR_INVALID_ARGUMENTThe operation failed because either:
The
uidis0.The caller cannot access some or all of the memory in the range [
p_info,p_info+sizeof(psa_storage_info_t) - 1]
PSA_ERROR_STORAGE_FAILUREThe operation failed because the physical storage has failed (Fatal error).
PSA_ERROR_DATA_CORRUPTThe operation failed because the data associated with the
uidhas been corrupted.PSA_ERROR_GENERIC_ERRORThe operation failed because of an unspecified internal failure.
Description
Retrieves the metadata stored for a given uid as a psa_storage_info_t structure.
The
uidvalue must not be zero.The call must have access to the memory from
p_infotop_info+sizeof(psa_storage_info_t) - 1.If the location
uidexists the metadata for the object is written top_info.Even if all parameters are correct, the function can fail in the case of a storage failure.
5.4.6 psa_ps_remove (function)¶
Remove the provided uid and its associated data from the storage.
psa_status_t psa_ps_remove(psa_storage_uid_t uid);
Parameters
uidThe identifier for the data to be removed.
Returns: psa_status_t
A status indicating the success or failure of the operation.
PSA_SUCCESSThe operation completed successfully.
PSA_ERROR_NOT_PERMITTEDThe operation failed because the provided
uidvalue was created withPSA_STORAGE_FLAG_WRITE_ONCE.PSA_ERROR_DOES_NOT_EXISTThe operation failed because the provided
uidvalue was not found in the storage.PSA_ERROR_INVALID_ARGUMENTThe
uidis0.PSA_ERROR_STORAGE_FAILUREThe operation failed because the physical storage has failed (Fatal error).
PSA_ERROR_GENERIC_ERRORThe operation failed because of an unspecified internal failure.
Description
Removes previously stored data and any associated metadata, including rollback protection data.
The
uidvalue must not be zero.If the location
uidexists, it and any metadata are removed.Even if all parameters are correct, the function can fail in the case of a storage failure.
5.4.7 psa_ps_create (function)¶
Reserves storage for the specified uid.
psa_status_t psa_ps_create(psa_storage_uid_t uid, size_t capacity, psa_storage_create_flags_t create_flags);
Parameters
uidA unique identifier for the asset.
capacityThe allocated capacity, in bytes, of the
uid.create_flagsFlags indicating properties of the storage.
Returns: psa_status_t
PSA_SUCCESSThe storage was successfully reserved.
PSA_ERROR_INVALID_ARGUMENTThe operation failed because the
uidis0.PSA_ERROR_NOT_SUPPORTEDThe function is not implemented or one or more
create_flagsare not supported.PSA_ERROR_INSUFFICIENT_STORAGEcapacityis bigger than the current available space.PSA_ERROR_STORAGE_FAILUREThe operation failed because the physical storage has failed (Fatal error).
PSA_ERROR_GENERIC_ERRORThe operation has failed due to an unspecified error.
PSA_ERROR_ALREADY_EXISTSStorage for the specified
uidalready exists.
Description
Reserves storage for the specified uid. Upon success, the capacity of the storage is capacity, and the size is 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.
This function cannot be used to replace or resize an existing asset and attempting to do so will return PSA_ERROR_ALREADY_EXISTS.
If the PSA_STORAGE_FLAG_WRITE_ONCE flag is passed, psa_ps_create() will return PSA_ERROR_NOT_SUPPORTED.
This function is optional. Consult the platform documentation to determine if it is implemented or perform a call to psa_ps_get_support(). This function must be implemented if psa_ps_get_support() returns PSA_STORAGE_SUPPORT_SET_EXTENDED.
The
uidvalue must not be zero.If
uidmust not exist.The flag
PSA_STORAGE_FLAG_WRITE_ONCEmust not be set.Even if all parameters are correct, the function can fail if there is insufficient storage space or in the case of a storage failure.
5.4.8 psa_ps_set_extended (function)¶
Overwrite part of the data of the specified 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);
Parameters
uidThe unique identifier for the asset.
data_offsetOffset within the asset to start the write.
data_lengthThe size in bytes of the data in
p_datato write.p_dataPointer to a buffer which contains the data to write.
Returns: psa_status_t
PSA_SUCCESSThe asset exists, the input parameters are correct and the data is correctly written in the physical storage.
PSA_ERROR_NOT_PERMITTEDThe operation failed because it was attempted on an asset which was written with the flag
PSA_STORAGE_FLAG_WRITE_ONCE.PSA_ERROR_INVALID_SIGNATUREThe operation failed because the existing data failed authentication (MAC check failed).
PSA_ERROR_DOES_NOT_EXISTThe specified
uidwas not found.PSA_ERROR_INVALID_ARGUMENTThe operation failed because either:
The
uidis0.The caller cannot access some or all of the memory in the range [
p_data,p_data + data_size - 1].One or more of the preconditions regarding
data_offset,size, ordata_lengthwas violated.
PSA_ERROR_NOT_SUPPORTEDThe implementation does not support this function.
PSA_ERROR_STORAGE_FAILUREThe operation failed because the physical storage has failed (Fatal error).
PSA_ERROR_DATA_CORRUPTThe operation failed because the existing data has been corrupted.
PSA_ERROR_GENERIC_ERRORThe operation failed due to an unspecified error.
Description
Sets partial data into an asset based on the given identifier, data_offset, data length and p_data.
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. This makes 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.
This function is optional. Consult the platform documentation to determine if it is implemented or perform a call to psa_ps_get_support(). This function must be implemented if psa_ps_get_support() returns PSA_STORAGE_SUPPORT_SET_EXTENDED.
The
uidvalue must not be zero.If
uidexists it must not have been created as withPSA_STORAGE_FLAG_WRITE_ONCE- would result inPSA_ERROR_NOT_PERMITTEDdata_offset <= sizedata_offset + data_length <= capacityEven if all parameters are correct, the function can fail in the case of a storage failure.
On Success:
size = max(size, data_offset + data_length)capacityunchanged.
5.4.9 psa_ps_get_support (function)¶
Returns a bitmask with flags set for the optional features supported by the implementation.
uint32_t psa_ps_get_support(void);
Returns: uint32_t
Description
Currently defined flags are limited to: