PSA Protected Storage APIs Alignment

Updated 2,095 Days AgoPublic

Actions

Table of contents

• Scope
• Terms and abbreviations
• References
• Introduction
• Design content
  • PSA Protected Storage APIs
  • TF-M SST Interfaces
    • TF-M SST non-secure APIs
    • SST secure APIs
    • SST veneers
    • SST service components
    • Protected Storage
    • SST Manifest file
    • Object System
      • Object definition
      • Object Table
• Platform-specific SST configuration
• SST tools
• Validation tests

Scope

The scope of this page is to describe the SST secure service re-design to align it with the mandatory set of PSA Protected Storage APIs version 1.0.

It is out of the design scope the use of Uniform Secure Service Signatures for all the secure functions. The support for the uniform secure service signatures will be added later and it will part of another design document.

Terms and abbreviations

This document uses the following terms and abbreviations.

References

Introduction

As described in [1], PSA Protected Storage is designed to protect larger data sets against physical attacks and switched-off devices. It aims to provide the ability for a firmware developer to store data into external flash, with a promise of data-at-rest protection, including device-bound encryption, integrity, and rollback protection. It should be possible to select the appropriate protection level, e.g. encryption only, or integrity only, or both.

The PSA Protected Storage API (PPS API) is the general-purpose API that most developers should use.

On platforms with external storage, implementations of this API should provide authenticated encryption of the data, as well as rollback protection values stored using the PSA Internal Trusted Storage API (PITS API).

PSA Protected Storage requirements are [1]:

1. The technology and techniques used by the PSA Protected Storage Service MUST allow for frequent writes and data updates.
2. If writing to external storage, the PSA Protected Storage Service MUST provide confidentiality.
3. Confidentiality for a PSA Protected Storage service may be provided by cryptographic ciphers using device-bound keys, a tamper resistant enclosure, or an inaccessible deployment location, depending on the threat model of the deployed system.
4. If writing to external storage, the PSA Protected Storage Service MUST provide integrity protection.
5. Integrity protection for a PSA Protected Storage service may be provided by cryptographic Message Authentication Codes (MAC) or signatures generated using device-bound keys, a tamper resistant enclosure, or an inaccessible deployment location, depending on the threat model of the deployed system.
6. If writing to external storage, the PSA Protected Storage Service MUST provide replay protection by writing replay protection values through the PSA Internal Trusted Storage API.
7. If providing services to secure partitions, and the PSA Isolation level is 3, the PSA Protected Storage Service MUST provide protection from one PSA partition accessing the storage assets of a different partition.
8. The PSA Protected Storage Service MUST use the partition ID information associated with each request for its access control mechanism.
9. If the PSA Protected Storage Service is providing services to other ARoT services, it MUST be implemented inside the ARoT itself.
10. If implemented inside the ARoT, the PSA Protected Storage Service MAY use helper services outside of the ARoT to perform actual read and write operations through the external interface or file system.
11. In the event of power failures or unexpected flash write failures, the implementation must attempt to fall back to allow retention of old content.
12. The creation of a UID with value 0 (zero) must be treated as an error.

The current TF-M SST service implementation addresses all the PSA Protected Storage requirements mentioned above [3]. However, the current SST implementation differs in terms of APIs. This document will cover the required modification to be applied in the current TF-M SST service implementation to align its APIs with the PPS APIs version 1.0 [2].

Design content

This design does not keep compatibility with the deprecated APIs to force the transition to the new PPS APIs. This decision simplifies the service, less code and memory usage, and removes the requirement to maintain the deprecated APIs until there are removed from the service.

PSA Protected Storage APIs

The new SST service exposes the mandatory set of PSA Protected Storage APIs as they are described in [2]. A detailed description of these interfaces is outside of the scope of this document.

The list of mandatory PPS APIs exposed by the SST service are:

psa_ps_set()

This function creates a new or modify an existing key/value pair.

psa_ps_status_t psa_ps_set(psa_ps_uid_t uid,  uint32_t data_length, const void *p_data,  psa_ps_create_flags_t create_flags);

Parameters

Return
A status indicating the success/failure of the operation based on psa_ps_status_t type.

psa_ps_get()

This function retrieves the value for a provided uid.

psa_ps_status_t psa_ps_get(psa_ps_uid_t uid, uint32_t data_offset, uint32_t data_length, void *p_data);

Parameters

Return
A status indicating the success/failure of the operation based on psa_ps_status_t type.

psa_ps_get_info()

This function retrieves the metadata about the provided uid.

psa_ps_status_t psa_ps_get_info(psa_ps_uid_t uid, struct psa_ps_info_t *p_info);

Parameters

Return
A status indicating the success/failure of the operation based on psa_ps_status_t type.

psa_ps_remove()

This function removes the provided uid and its associated data from the storage.

psa_ps_status_t psa_ps_remove(psa_ps_uid_t uid);

Parameters

Return
A status indicating the success/failure of the operation based on psa_ps_status_t type.

psa_ps_get_support()

This function returns a bitmask with flags set for all the optional features supported by the implementation.

uint32_t psa_ps_get_support(void);

Parameters

Return
A bitmask with the flags set for all the optional features supported by the implementation.

The extended set of PPS APIs are not going to be implemented for the moment. However, an empty implementation is required, which returns PSA_PS_ERROR_NOT_SUPPORTED, for each extended function. The extended set of PPS APIs will be supported in the future.

The list of extended PPS APIs are:

psa_ps_create()

This function 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.
This function is optional. Not all PSA Protected Storage implementations will implement this function.

psa_ps_status_t psa_ps_create(psa_ps_uid_t uid, uint32_t size, psa_ps_create_flags_t create_flags);

Parameters

Return
A status indicating the success/failure of the operation based on psa_ps_status_t type.

psa_ps_set_extended()

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

psa_ps_status_t psa_ps_set_extended(psa_ps_uid_t uid, uint32_t data_offset, uint32_t data_length, const void *p_data);

Parameters

Return
A status indicating the success/failure of the operation based on psa_ps_status_t type.

TF-M SST Interfaces

The SST header files in “<TF-M REPO>/interface/include” must be updated or removed as follows:

• Remove psa_sst_assets_XX.h files as the content of those files are not part of the PPS API specification.
• Remove tfm_sst_defs.h as its content is not longer required.
• Rename psa_sst_api.h to psa_sst_defs.h and update its content.

The protected_storage.h with the PSA PS APIs definitions must be added in this location “<TF-M REPO>/interface/include” under the psa_protected_storage.h to be aligned with the other psa header files in the folder. The psa_protected_storage.h is included by the tfm_sst_defs.h file, which is the top header file of SST service.

The “psa_sst_defs.h” file must be updated to include protected_storage.h as it is the header file which specifies the new SST service interfaces. The SST error enumeration needs to be modified to incorporate the new errors defined by the psa_ps_status_t type, and remove the obsolete once.

The TF-M SST error codes have an offset to make sure those return values do not overlap with predefined TF-M status values used by TF-M Core. The definition name of each value starts with TFM_SST_ERR prefix.

The new TF-M SST errors are:

The removed TF-M SST errors are:

The “tfm_sst_defs.h” file defines a macro, or another mechanism, to translate the TF-M SST error types to PSA PS error type.

The translation table is as follows:

TF-M SST non-secure APIs

The SST source file tfm_sst_api.c, located in “<TF-M REPO>/interface/src”, must be updated in order to be aligned with PPS APIs. This file is the entry point for the non-secure applications to perform a request to the SST service. The implementation in this file is the one responsible to call the veneer function, via tfm_ns_lock_dispatch, and translate TF-M SST error codes to PSA PS error codes accordingly.

SST secure APIs

The tfm_sst_secure_api.c file, located in “<TF-M REPO>/secure_fw/services/secure_storage”, must be updated in order to be aligned with PSA PS APIs. This file is the entry point for the secure partitions to perform a request to the SST service. The implementation in this file is the one responsible to call the veneer functions and translate TF-M SST error codes to PSA PS error codes accordingly.
The functions which implements the PSA PS APIs needs to have the __attribute__(( section("SFN"))) attribute set, in order to make sure the code is located in the unprivilege memory partition when the TF-M Level 3 is required.

SST veneers

The tfm_sst_veneers.c file, located in “<TF-M REPO>/secure_fw/ns_callable”, must be updated in order to be aligned with the PPS APIs, and perform the proper calls to the TFM_CORE_SFN_REQUEST. The error type to be used by the veneer interfaces is the TF-M SST error type.
The new Protected Storage component in SST service is the component which process the SST request. Detailed information about this Protected Storage layer and the SST manifest can be found in sections below.

SST service components

The current SST service implements a set of components, each one dedicated to implementing a specific functionality in each layer of the SST service firmware stack [3].

The set of functionalities are:

• Asset Policy Management: This layer contains asset's access policy management code. It validates all the request received by the SST services based on the access policy database.
• Object System: This component contains the object system implementation to manage all objects store in the SST area.
• File System: It abstracts the flash filesystem operations for the secure storage service. The purpose of this abstraction is to have the ability to plug-in other filesystems or filesystem proxies (supplicant). Currently, it implements a custom filesystem based on a non-hierarchical storage model where all the files are managed by linearly indexed list of metadata.

The current SST firmware stack is:

The new design replaces the asset policy management layer by the Protected Storage layer, and it removes the policy database. This new layer exposes the new set of asset manipulation interfaces which are compliant with the PPS APIs specification.
A more detailed information about the interfaces exposed by this layer can be found in the section below.

The new SST firmware layers are:

Protected Storage

Protected storage (PS) layer replaces the old asset management layer in order to implement the new PSA PS APIs. This layer interacts with the object system layer to create, read, write and delete assets in the secure storage area, as well as to get the asset information.

The list of TF-M SST PS APIs exposed by the protected storage layer are:

tfm_sst_set()

This function creates a new or modify an existing key/value pair.

enum tfm_sst_err_t tfm_sst_set(psa_ps_uid_t *uid,  uint32_t data_length, const void *p_data,  psa_ps_create_flags_t create_flags);

Parameters

Return
A status indicating the success/failure of the operation based on enum tfm_sst_err_t type.

tfm_sst_get()

This function gets the asset data for a provided uid.

enum tfm_sst_err_t tfm_sst_get(psa_ps_uid_t *uid, uint32_t data_offset, uint32_t data_length, void *p_data);

Parameters

Return
A status indicating the success/failure of the operation based on enum tfm_sst_err_t type.

tfm_sst_get_info()

This function gets the asset information about the provided uid.

enum tfm_sst_err_t tfm_sst_get_info(psa_ps_uid_t *uid, struct psa_ps_info_t *p_info);

Parameters

Return
A status indicating the success/failure of the operation based on enum tfm_sst_err_t type.

tfm_sst_remove()

This his function removes the asset from the storage.

enum tfm_sst_err_t tfm_sst_remove(psa_ps_uid_t *uid);

Parameters

Return
A status indicating the success/failure of the operation based on enum tfm_sst_err_t type.

tfm_sst_get_support()

This function returns a bitmask with flags set for all the optional features supported by the implementation.

enum tfm_sst_err_t tfm_sst_get_support(uint32_t *support_flags);

Parameters

Return
A status indicating the success/failure of the operation based on enum tfm_sst_err_t type.

For the current implementation, this function must return 0 as the optional functions are not going to be implemented at this phase.

tfm_sst_init()

This function initializes the secure storage system.

enum tfm_sst_err_t tfm_sst_init(void);

Parameters

Return
A status indicating the success/failure of the operation based on enum tfm_sst_err_t type.

failed (Fatal error)

SST Manifest file

The SST manifest file must be updated to expose the Protected Storage layer functions instead of the old asset management functions. The “tfm_init_symbol” and “secure_functions” entries in the manifest file must be updated according to the new Protected Storage layer functions, as well as the “source_file” list.

Object System

The SST object system layer must be updated to accommodate it to the PPS specification. According to the PPS requirements [1], the service must provide protection from one PSA partition accessing the storage assets of a different partition. In order to achieve this requirement, the object system must associate the asset UID with the secure partition (SP) or non-secure application which has created the asset (client ID). If another SP or non-secure application requests the access to an asset which does not belongs to it, the request must be rejected with the proper error type. Different clients can use the same UID to references different assets.

The object system interfaces must be updated to reflect the following changes:

• Rename uuid to uid
• Remove token structures
• Add client ID and create_flags
• Update create function to write in the file the data provided as an input
• Add check if the write once flag is set
• Update error codes in the code accordingly

The updated list of interfaces exposed by the object system layer are:

sst_object_create()

This function creates a new object about the provided UID.

enum tfm_sst_err_t sst_object_create(psa_ps_uid_t uid, int32_t client_id, psa_ps_create_flags_t create_flags, uint32_t size, const uint8_t *p_data);

Parameters

Return
A status indicating the success/failure of the operation based on enum tfm_sst_err_t type.

sst_object_read()

This function gets object's data about the provided UID.

enum tfm_sst_err_t sst_object_read(psa_ps_uid_t uid, int32_t client_id, uint32_t offset, uint32_t size, uint8_t *p_data);

Parameters

Return
A status indicating the success/failure of the operation based on enum tfm_sst_err_t type.

sst_object_write()

This function writes data into the object about the provided UID.

enum tfm_sst_err_t sst_object_write(psa_ps_uid_t uid, int32_t client_id, uint32_t offset, uint32_t size, const uint8_t *p_data);

Parameters

Return
A status indicating the success/failure of the operation based on enum tfm_sst_err_t type.

sst_object_delete()

This function deletes the object about the provided UID.

enum tfm_sst_err_t sst_object_delete(psa_ps_uid_t uid, int32_t client_id);

Parameters

Return
A status indicating the success/failure of the operation based on enum tfm_sst_err_t type.

sst_object_get_info()

This function gets the asset information about the provided UID.

enum tfm_sst_err_t sst_object_get_info(psa_ps_uid_t uid, int32_t client_id, psa_ps_info_t *info);

Parameters

Return
A status indicating the success/failure of the operation based on enum tfm_sst_err_t type.

The following interfaces are not available in the new design. So, they must be removed.

enum psa_sst_err_t sst_object_get_attributes(uint32_t uuid, const struct tfm_sst_token_t *s_token, struct psa_sst_asset_attrs_t *p_info);

enum psa_sst_err_t sst_object_set_attributes(uint32_t uuid, const struct tfm_sst_token_t *s_token, const struct psa_sst_asset_attrs_t *attrs);

Object definition

The object definition must be updated as follows:

• Remove struct psa_sst_asset_attrs_t attr
• Rename struct psa_sst_asset_info_t by struct sst_object_info_t

This is required to define sst_object_info_t structure as follows:

/*!
 * \struct sst_object_info_t
 *
 * \brief Object information.
 */
struct sst_object_info_t {
    uint32_t current_size;  /*!< The current size of the object content */
    uint32_t max_size;      /*!< The maximum size of the object content in bytes */
    psa_ps_create_flags_t create_flags;  /*!< Object creation flags */
};

The new object header version is as follows:

struct sst_obj_header_t {
#ifdef SST_ENCRYPTION
    /* Metadata attached as a header to encrypted object data before storage */
    union sst_crypto_t crypto;  /*!< Crypto metadata */
#else
    uint32_t version;           /*!< Object version */
    uint32_t fid;               /*!< File ID */
#endif
    struct sst_object_info_t  info;  /*!< Object information */
};

Object Table

The object table interfaces need to be updated to reflect the following changes:

• Rename uuid to uid
• Add client ID to be added in the object table

The object table contains the following information for each object stored in the system:

struct sst_obj_table_entry_t {
#ifdef SST_ENCRYPTION
    uint8_t tag[SST_TAG_LEN_BYTES];  /*!< MAC value of AEAD object */
#else
    uint32_t version;   /*!< File version */
#endif
    psa_ps_uid_t uid   /*!< Object UID */
    int32_t client_id;   /*!< Client ID */
};

The list of interfaces to be modified in the object table layer are:

sst_object_table_obj_exist()
This function checks if there is an entry in the table about the provided UID and client ID pair.

enum tfm_sst_err_t sst_object_table_obj_exist(psa_ps_uid_t uid, int32_t client_id);

Parameters

Return
A status indicating the success/failure of the operation based on enum tfm_sst_err_t type.

sst_object_table_set_obj_tbl_info()
This function sets object table information in the object table, stores it persistently, about the provided UID and client ID pair.

enum tfm_sst_err_t sst_object_table_set_obj_tbl_info(psa_ps_uid_t uid, int32_t client_id, const struct sst_obj_table_info_t *obj_tbl_info);

Parameters

Return
A status indicating the success/failure of the operation based on enum tfm_sst_err_t type.

sst_object_table_get_obj_tbl_info()
This function gets the object table information from the object table about the provided UID and client ID pair.

enum tfm_sst_err_t sst_object_table_get_obj_tbl_info(psa_ps_uid_t uid, int32_t client_id, struct sst_obj_table_info_t *obj_tbl_info);

Parameters

Return
A status indicating the success/failure of the operation based on enum tfm_sst_err_t type.

sst_object_table_delete_object()
This function deletes the object entry about the provided UID and client ID pair and stores this change persistently.

enum tfm_sst_err_t sst_object_table_delete_object(psa_ps_uid_t uid, int32_t client_id);

Parameters

Return
A status indicating the success/failure of the operation based on enum tfm_sst_err_t type.

Platform-specific SST configuration

The current SST service implementation does not allocate dynamic memory. So, all the memory needs be allocated at compile time. In the current design, there are 2 parameters that are defined based on the policy table and are used to dimension the amount of static memory required by the SST service. Those parameters are the maximum asset size and number of assets. As the policy table is not part of the new design, the maximum asset size and maximum number of assets, managed by the object system, need to be defined and exposed by the system integrator based on the board capabilities and/or system configuration. As a temporary solution, those parameters need to be exposed in the "flash_layout.h" located in “<TF-M PATH>/platform/ext/target/<target_name>/partition”. There is the place where other SST parameters are defined by the system integrators. It will be evaluated the fact of introduce a specific file for the SST configuration in the platforms folder.

As part of the re-design work, the following defines needs to be specified in the flash_layout.h:

• SST_MAX_ASSET_SIZE Defines the maximum asset size to be stored in the SST area.
• SST_NUM_ASSETS Defines the maximum number of assets to be stored in the SST area.

For the current platforms in the repository, the default values are 2048 for SST_MAX_ASSET_SIZE, and 10 for SST_NUM_ASSETS. Those are the values defined in sst_asset_defs.h.

SST tools

As the policy table is not required in the new design, the SST folder must be removed from tools in order to delete the Python script tool which generates the table based on the YAML file.

Validation tests

To validate the new SST service design and all changes in it, a set of new TF-M SST test suites will be implemented to validate the new interfaces.

The implementation of those test suites will be placed in “<TF-M REPO>/test/suites/sst/non_secure/” and “<TF-M REPO>/test/suites/sst/secure/”

To validate the modifications in the object system, it is required to update “sst_rollback_protection_testsuite” and “sst_reliability_testsuite” suites to use the new PSA PS APIs.

The following test suites are no longer required as tested functionalities have been removed from the service:

• SST referenced access test suite. The SST test service created to be used in combination with this test suite will be removed as well.
• SST policy test suite.

A more exhaustive validation of the new SST service must be performed with PSA Arch tests [4] in order to validate that SST service is compliant with PSA protected storage APIs.