diff --git a/MAINTAINERS.yml b/MAINTAINERS.yml index 422d849ea79..0eebdfa7406 100644 --- a/MAINTAINERS.yml +++ b/MAINTAINERS.yml @@ -4114,6 +4114,7 @@ Secure storage: files: - subsys/secure_storage/ - samples/psa/ + - doc/services/secure_storage.rst - tests/subsys/secure_storage/ labels: - "area: Secure storage" diff --git a/doc/releases/release-notes-4.0.rst b/doc/releases/release-notes-4.0.rst index b5bcacdb9e5..6e1b0726ab0 100644 --- a/doc/releases/release-notes-4.0.rst +++ b/doc/releases/release-notes-4.0.rst @@ -9,6 +9,10 @@ We are pleased to announce the release of Zephyr version 4.0.0. Major enhancements with this release include: +* The introduction of the :ref:`secure storage` subsystem. It allows the use of the + PSA Secure Storage API and of persistent keys in the PSA Crypto API on all board targets. It + is now the standard way to provide device-specific protection to data at rest. (:github:`76222`) + An overview of the changes required or recommended when migrating your application from Zephyr v3.7.0 to Zephyr v4.0.0 can be found in the separate :ref:`migration guide`. diff --git a/doc/services/index.rst b/doc/services/index.rst index 57e6e2d71b2..d1c456151a2 100644 --- a/doc/services/index.rst +++ b/doc/services/index.rst @@ -6,7 +6,6 @@ OS Services .. toctree:: :maxdepth: 1 - binary_descriptors/index.rst console.rst crypto/index @@ -30,6 +29,7 @@ OS Services portability/index.rst poweroff.rst profiling/index.rst + secure_storage.rst shell/index.rst serialization/index.rst settings/index.rst diff --git a/doc/services/secure_storage.rst b/doc/services/secure_storage.rst new file mode 100644 index 00000000000..5f7b90943b6 --- /dev/null +++ b/doc/services/secure_storage.rst @@ -0,0 +1,119 @@ +.. _secure_storage: + +Secure storage +############## + +| The secure storage subsystem provides an implementation of the functions defined in the + `Platform Security Architecture (PSA) Secure Storage API `_. +| It can be enabled on :term:`board targets` + 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 `_.) + + | The specification considers the storage underlying the ITS to be + ``implicitly confidential and protected from replay`` + (`2.4. 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 `_). + | 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 `_.) + + 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 diff --git a/doc/services/tfm/index.rst b/doc/services/tfm/index.rst index e957ae0d5da..9417648e688 100644 --- a/doc/services/tfm/index.rst +++ b/doc/services/tfm/index.rst @@ -1,7 +1,7 @@ .. _tfm: -Trusted Firmware-M -################## +Trusted Firmware-M (TF-M) +######################### .. toctree:: :maxdepth: 1 diff --git a/doc/zephyr.doxyfile.in b/doc/zephyr.doxyfile.in index 05b541c517d..38b55ad6aeb 100644 --- a/doc/zephyr.doxyfile.in +++ b/doc/zephyr.doxyfile.in @@ -980,7 +980,8 @@ INPUT = @ZEPHYR_BASE@/doc/_doxygen/mainpage.md \ @ZEPHYR_BASE@/include/ \ @ZEPHYR_BASE@/lib/libc/minimal/include/ \ @ZEPHYR_BASE@/subsys/testsuite/include/ \ - @ZEPHYR_BASE@/subsys/testsuite/ztest/include/ + @ZEPHYR_BASE@/subsys/testsuite/ztest/include/ \ + @ZEPHYR_BASE@/subsys/secure_storage/include/ \ # This tag can be used to specify the character encoding of the source files # that Doxygen parses. Internally Doxygen uses the UTF-8 encoding. Doxygen uses