TF-M Internal Trusted Storage Service Integration Guide¶
Introduction¶
TF-M Internal Trusted Storage (ITS) service implements PSA Internal Trusted Storage APIs.
The service is backed by hardware isolation of the flash access domain and relies on hardware to isolate the flash area from access by the Non-secure Processing Environment, as well as the Application Root of Trust at higher levels of isolation.
The current ITS service design relies on hardware abstraction provided by TF-M. The ITS service provides a non-hierarchical storage model, as a filesystem, where all the assets are managed by a linearly indexed list of metadata.
The design addresses the following high level requirements as well:
Confidentiality - Resistance to unauthorised accesses through hardware/software attacks. Assumed to be provided by the internal flash device, backed by hardware isolation.
Access Authentication - Mechanism to establish requester’s identity (a non-secure entity, secure entity, or a remote server).
Integrity - Resistance to tampering by attackers with physical access is assumed to be provided by the internal flash device itself, while resistance to tampering by Non-secure or App RoT attackers also requires hardware isolation.
Reliability - Resistance to power failure scenarios and incomplete write cycles.
Configurability - High level of configurability to scale up/down memory footprint to cater for a variety of devices with varying requirements.
Performance - Optimized to be used for resource constrained devices with very small silicon footprint, the PPA (power, performance, area) should be optimal.
Current ITS Service Limitations¶
Fragmentation - The current design does not support fragmentation, as an asset is stored in a contiguous space in a block. This means that the maximum asset size can only be up-to a block size. Each block can potentially store multiple assets. A delete operation implicitly moves all the assets towards the top of the block to avoid fragmentation within block. However, this may also result in unutilized space at the end of each block.
Non-hierarchical storage model - The current design uses a non-hierarchical storage model, as a filesystem, where all the assets are managed by a linearly indexed list of metadata. This model locates the metadata in blocks which are always stored in the same flash location. That increases the number of writes in a specific flash location as every change in the storage area requires a metadata update.
Protection against physical storage medium failure - Complete handling of inherent failures of storage mediums (e.g. bad blocks in a NAND based device) is not supported by the current design.
Lifecycle management - Currently, it does not support any subscription based keys and certificates required in a secure lifecycle management. Hence, an asset’s validity time-stamp can not be invalidated based on the system time.
Provisioning vs user/device data - In the current design, all assets are treated in the same manner. In an alternative design, it may be required to create separate partitions for provisioning content and user/device generated content. This is to allow safe update of provisioning data during firmware updates without the need to wipe out the user/device generated data.
Code Structure¶
TF-M Internal Trusted Storage service code is located in
secure_fw/partitions/internal_trusted_storage/
and is divided as follows:
Core files
Flash filesystem interfaces
Flash interfaces
The PSA ITS interfaces for the TF-M ITS service are located in
interface/include/psa
.
PSA Internal Trusted Storage Interfaces¶
The TF-M ITS service exposes the following mandatory PSA ITS interfaces version 1.0:
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);
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);
psa_status_t psa_its_get_info(psa_storage_uid_t uid, struct psa_storage_info_t *p_info);
psa_status_t psa_its_remove(psa_storage_uid_t uid);
These PSA ITS interfaces and TF-M ITS types are defined and documented in
interface/include/psa/storage_common.h
,
interface/include/psa/internal_trusted_storage.h
, and
interface/include/tfm_its_defs.h
Core Files¶
tfm_its_req_mngr.c
- Contains the ITS request manager implementation which handles all requests which arrive to the service. This layer extracts the arguments from the input and output vectors, and it calls the internal trusted storage layer with the provided parameters.tfm_internal_trusted_storage.c
- Contains the TF-M internal trusted storage API implementations which are the entry points to the ITS service. Allocates a filesystem context for ITS and makes appropriate fs calls. Also handles requests from the PS partition with a separate fs context.its_utils.c
- Contains common and basic functionalities used across the ITS service code.
Flash Filesystem Interface¶
flash_fs/its_flash_fs.h
- Abstracts the flash filesystem operations used by the internal trusted storage service. The purpose of this abstraction is to have the ability to plug-in other filesystems or filesystem proxies (supplicant).flash_fs/its_flash_fs.c
- Contains theits_flash_fs
implementation for the required interfaces.flash_fs/its_flash_fs_mbloc.c
- Contains the metadata block manipulation functions required to implement theits_flash_fs
interfaces inflash_fs/its_flash_fs.c
.flash_fs/its_flash_fs_dbloc.c
- Contains the data block manipulation functions required to implement theits_flash_fs
interfaces inflash_fs/its_flash_fs.c
.
The system integrator may replace this implementation with its own flash filesystem implementation or filesystem proxy (supplicant).
Flash Interface¶
flash/its_flash.h
- Abstracts the flash operations for the internal trusted storage service. Defines thestruct its_flash_info_t
type, which is used as a parameter to the filesystem to provide information about the flash device in use, such as the block size and number of blocks available.flash/its_flash.c
- Contains theits_flash
implementations common to all flash types.flash/its_flash_nand.c
- Implements the ITS flash interface for a NAND flash device, on top of the CMSIS flash interface implemented by the target. This implementation writes entire block updates in one-shot, so the CMSIS flash implementation must be able to detect incomplete writes and return an error the next time the block is read.flash/its_flash_nor.c
- Implements the ITS flash interface for a NOR flash device, on top of the CMSIS flash interface implemented by the target.flash/its_flash_ram.c
- Implements the ITS flash interface for an emulated flash device using RAM, on top of the CMSIS flash interface implemented by the target.flash/its_flash_info_internal.c
- Defines an instance of thestruct its_flash_info_t
type for the internal flash device based on target-specific definitions.flash/its_flash_info_external.c
- Defines an instance of thestruct its_flash_info_t
type for the external flash device, used only to handle requests from the PS partition.
The CMSIS flash interface must be implemented for each target based on its flash controller.
The ITS flash interface depends on target-specific definitions from
platform/ext/target/<TARGET_NAME>/partition/flash_layout.h
.
Please see the Internal Trusted Storage Service Definitions section for
details.
ITS Service Integration Guide¶
This section describes mandatory (i.e. must implement) or optional (i.e. may implement) interfaces which the system integrator has to take in to account in order to integrate the internal trusted storage service in a new platform.
Maximum Asset Size¶
An asset is stored in a contiguous space in a block/sector. The maximum size of an asset can be up-to the size of the data block/sector.
Internal Trusted Storage Service Platform Definitions¶
The ITS service requires the following platform definitions:
ITS_SECTOR_SIZE
- Defines the size of the flash sectors (the smallest erasable unit) in bytes.ITS_SECTORS_PER_BLOCK
- Defines the number of contiguous ITS_SECTOR_SIZE to form a logical block in the filesystem.ITS_FLASH_DEV_NAME
- Specifies the flash device used by ITS to store the data.ITS_FLASH_PROGRAM_UNIT
- Defines the smallest flash programmable unit in bytes. Valid values are powers of two between 1 andITS_SECTOR_SIZE
inclusive.
The sectors reserved to be used as internal trusted storage must be
contiguous sectors starting at ITS_FLASH_AREA_ADDR
.
Target must provide a header file, called flash_layout.h
, which defines the
information explained above. The defines must be named as they are specified
above.
More information about the flash_layout.h
content, not ITS related, is
available in platform readme along with other
platform information.
The following optional platform definitions may also be defined in
flash_layout.h
or set at build time in platform/ext/<TARGET_NAME>.cmake
:
ITS_FLASH_AREA_ADDR
- Defines the flash address where the internal trusted storage area starts. If not defined, the platform must implementtfm_hal_its_fs_info()
.ITS_FLASH_AREA_SIZE
- Defines the size of the dedicated flash area for internal trusted storage in bytes. If not defined, the platform must implementtfm_hal_its_fs_info()
.ITS_MAX_BLOCK_DATA_COPY
- Defines the buffer size used when copying data between blocks, in bytes. If not provided, defaults to 256. Increasing this value will increase the memory footprint of the service.
Flash Interface¶
For ITS service operations, a contiguous set of blocks must be earmarked for the internal trusted storage area. The design requires either 2 blocks, or any number of blocks greater than or equal to 4. Total number of blocks can not be 0, 1 or 3. This is a design choice limitation to provide power failure safe update operations.
For API specification, please check:
secure_fw/partitions/internal_trusted_storage/flash/its_flash.h
ITS Service Build Definitions¶
The ITS service uses a set of C definitions to compile in/out certain features,
as well as to configure certain service parameters. When using the TF-M build
system, these definitions are controlled by build flags of the same name. The
config/config_default.cmake
file sets the default values of those flags, but
they can be overwritten based on platform capabilities by setting them in
platform/ext/target/<TARGET_NAME>/config.cmake
. The list of ITS service
build definitions is:
ITS_CREATE_FLASH_LAYOUT
- this flag indicates that it is required to create an ITS flash layout. If this flag is set, ITS service will generate an empty and valid ITS flash layout to store assets. It will erase all data located in the assigned ITS memory area before generating the ITS layout. This flag is required to be set if the ITS memory area is located in a non-persistent memory. This flag can be set if the ITS memory area is located in a persistent memory without a valid ITS flash layout in it. That is the case when it is the first time in the device life that the ITS service is executed.ITS_VALIDATE_METADATA_FROM_FLASH
- this flag allows to enable/disable the validation mechanism to check the metadata store in flash every time the flash data is read from flash. This validation is required if the flash is not hardware protected against data corruption.ITS_RAM_FS
- setting this flag toON
enables the use of RAM instead of the persistent storage device to store the FS in the Internal Trusted Storage service. This flag isOFF
by default. The ITS regression tests write/erase storage multiple time, so enabling this flag can increase the life of flash memory when testing. If this flag is set toON
, ITS_RAM_FS_SIZE must also be provided. This specifies the size of the block of RAM to be used to simulate the flash.Note
If this flag is disabled when running the regression tests, then it is recommended that the persistent storage area is erased before running the tests to ensure that all tests can run to completion. The type of persistent storage area is platform specific (eFlash, MRAM, etc.) and it is described in corresponding flash_layout.h
ITS_MAX_ASSET_SIZE
- Defines the maximum asset size to be stored in the ITS area. This size is used to define the temporary buffers used by ITS to read/write the asset content from/to flash. The memory used by the temporary buffers is allocated statically as ITS does not use dynamic memory allocation.ITS_NUM_ASSETS
- Defines the maximum number of assets to be stored in the ITS area. This number is used to dimension statically the filesystem metadata tables in RAM (fast access) and flash (persistent storage). The memory used by the filesystem metadata tables is allocated statically as ITS does not use dynamic memory allocation.ITS_BUF_SIZE
- Defines the size of the partition’s internal data transfer buffer. If not provided, thenITS_MAX_ASSET_SIZE
is used to allow asset data to be copied between the client and the filesystem in one iteration. Reducing the buffer size will decrease the RAM usage of the partition at the expense of latency, as data will be copied in multiple iterations. Note: when data is copied in multiple iterations, the atomicity property of the filesystem is lost in the case of an asynchronous power failure.
Copyright (c) 2019-2020, Arm Limited. All rights reserved. Copyright (c) 2020, Cypress Semiconductor Corporation. All rights reserved.