120 lines
5.4 KiB
ReStructuredText
120 lines
5.4 KiB
ReStructuredText
.. _secure_storage:
|
|
|
|
Secure storage
|
|
##############
|
|
|
|
| The secure storage subsystem provides an implementation of the functions defined in the
|
|
`Platform Security Architecture (PSA) Secure Storage API <https://arm-software.github.io/psa-api/storage/>`_.
|
|
| It can be enabled on :term:`board targets<board target>`
|
|
that don't already have an implementation of the API.
|
|
|
|
Overview
|
|
********
|
|
|
|
The secure storage subsystem makes the PSA Secure Storage API available on all board targets with
|
|
non-volatile memory support.
|
|
As such, it provides an implementation of the API on those that don't already have one, ensuring
|
|
functional support for the API.
|
|
Board targets with :ref:`tfm` enabled (ending in ``/ns``), for instance,
|
|
cannot enable the subsystem because TF-M already provides an implementation of the API.
|
|
|
|
| In addition to providing functional support for the API, depending on
|
|
device-specific security features and the configuration, the subsystem
|
|
may secure the data stored via the PSA Secure Storage API at rest.
|
|
| Keep in mind, however, that it's preferable to use a secure processing environment like TF-M when
|
|
possible because it's able to provide more security due to isolation guarantees.
|
|
|
|
Limitations
|
|
***********
|
|
|
|
The secure storage subsystem's implementation of the PSA Secure Storage API:
|
|
|
|
* does not aim at full compliance with the specification.
|
|
|
|
| Its foremost goal is functional support for the API on all board targets.
|
|
| See below for important ways the implementation deviates from the specification.
|
|
|
|
* does not guarantee that the data it stores will be secure at rest in all cases.
|
|
|
|
This depends on device-specific security features and the configuration.
|
|
|
|
* does not yet provide an implementation of the Protected Storage (PS) API as of this writing.
|
|
|
|
Instead, the PS API directly calls into the Internal Trusted Storage (ITS) API
|
|
(unless a `custom implementation <#whole-api>`_ of the PS API is provided).
|
|
|
|
Below are some ways the implementation deviates from the specification
|
|
and an explanation why. This is not an exhaustive list.
|
|
|
|
* The data stored in the ITS is by default encrypted and authenticated (Against ``1.`` in
|
|
`3.2. Internal Trusted Storage requirements <https://arm-software.github.io/psa-api/storage/1.0/overview/requirements.html#internal-trusted-storage-requirements>`_.)
|
|
|
|
| The specification considers the storage underlying the ITS to be
|
|
``implicitly confidential and protected from replay``
|
|
(`2.4. The Internal Trusted Storage API <https://arm-software.github.io/psa-api/storage/1.0/overview/architecture.html#the-internal-trusted-storage-api>`_)
|
|
because ``most embedded microprocessors (MCU) have on-chip flash storage that can be made
|
|
inaccessible except to software running on the MCU``
|
|
(`2.2. Technical Background <https://arm-software.github.io/psa-api/storage/1.0/overview/architecture.html#technical-background>`_).
|
|
| This is not the case on all MCUs. Thus, additional protection is provided to the stored data.
|
|
|
|
However, this does not guarantee that the data stored will be secure at rest in all cases,
|
|
because this depends on device-specific security features and the configuration.
|
|
It requires a random entropy source and especially a secure encryption key provider
|
|
(:kconfig:option:`CONFIG_SECURE_STORAGE_ITS_TRANSFORM_AEAD_KEY_PROVIDER`).
|
|
|
|
In addition, the data stored in the ITS is not protected against replay attacks,
|
|
because this requires storage that is protected by hardware.
|
|
|
|
* The data stored via the PSA Secure Storage API is not protected from direct
|
|
read/write by software or debugging. (Against ``2.`` and ``10.`` in
|
|
`3.2. Internal Trusted Storage requirements <https://arm-software.github.io/psa-api/storage/1.0/overview/requirements.html#internal-trusted-storage-requirements>`_.)
|
|
|
|
It is only secured at rest. Protecting it at runtime as well
|
|
requires specific hardware mechanisms to support this.
|
|
|
|
Configuration
|
|
*************
|
|
|
|
To configure the implementation of the PSA Secure Storage API provided by Zephyr, have a look at the
|
|
``CONFIG_SECURE_STORAGE_.*`` Kconfig options. They are defined in the various Kconfig files found
|
|
under ``subsys/secure_storage/``.
|
|
|
|
Customization
|
|
*************
|
|
|
|
Custom implementations can also replace those of Zephyr at different levels
|
|
if the functionality provided by the existing implementations isn't enough.
|
|
|
|
Whole API
|
|
=========
|
|
|
|
If you already have an implementation of the whole ITS or PS API and want to make use of it, you
|
|
can do so by enabling the following Kconfig option and implementing the relevant functions:
|
|
|
|
* :kconfig:option:`CONFIG_SECURE_STORAGE_ITS_IMPLEMENTATION_CUSTOM`, for the ITS API.
|
|
* :kconfig:option:`CONFIG_SECURE_STORAGE_PS_IMPLEMENTATION_CUSTOM`, for the PS API.
|
|
|
|
ITS API
|
|
=======
|
|
|
|
Zephyr's implementation of the ITS API
|
|
(:kconfig:option:`CONFIG_SECURE_STORAGE_ITS_IMPLEMENTATION_ZEPHYR`)
|
|
makes use of the ITS transform and store modules, which can be configured and customized separately.
|
|
Have a look at the ``CONFIG_SECURE_STORAGE_ITS_(STORE|TRANSFORM)_.*_CUSTOM``
|
|
Kconfig options to see the different customization possibilities.
|
|
|
|
It's especially recommended to implement a custom encryption key provider
|
|
(:kconfig:option:`CONFIG_SECURE_STORAGE_ITS_TRANSFORM_AEAD_KEY_PROVIDER_CUSTOM`)
|
|
that is more secure than the available options, if possible.
|
|
|
|
Samples
|
|
*******
|
|
|
|
* :zephyr:code-sample:`persistent_key`
|
|
* :zephyr:code-sample:`psa_its`
|
|
|
|
PSA Secure Storage API reference
|
|
********************************
|
|
|
|
.. doxygengroup:: psa_secure_storage
|