doc: secure_storage: add documentation for the secure storage subsystem

It includes both the high-level documentation of the subsystem and
that of APIs defined in code (PSA Secure Storage and internal APIs of
the subsystem).

Signed-off-by: Tomi Fontanilles <[email protected]>

Author: tomi-font

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"

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<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<migration_4.0>`.
 

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

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 <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

doc/services/tfm/index.rst

@@ -1,7 +1,7 @@
 .. _tfm:
 
-Trusted Firmware-M
-##################
+Trusted Firmware-M (TF-M)
+#########################
 
 .. toctree::
    :maxdepth: 1

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