secure_storage: introduce the secure storage subsystem

Implements RFC zephyrproject-rtos#75275.

See also the added documentation and the PR
(zephyrproject-rtos#76222)
for more information.

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

MAINTAINERS.yml

@@ -4115,6 +4115,20 @@ RTIO:
   tests:
     - rtio
 
+Secure storage:
+  status: maintained
+  maintainers:
+    - tomi-font
+  files:
+    - subsys/secure_storage/
+    - samples/psa/
+    - doc/services/secure_storage.rst
+    - tests/subsys/secure_storage/
+  labels:
+    - "area: Secure storage"
+  tests:
+    - psa.secure_storage
+
 Storage:
   status: odd fixes
   files:
@@ -4916,6 +4930,7 @@ West:
   tests:
     - benchmark.crypto.mbedtls
     - crypto.mbedtls
+    - psa.secure_storage
 
 "West project: mcuboot":
   status: maintained
@@ -5089,6 +5104,7 @@ West:
     - "area: TF-M"
   tests:
     - trusted-firmware-m
+    - psa.secure_storage
 
 "West project: tf-m-tests":
   status: maintained

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
@@ -29,6 +28,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

@@ -977,7 +977,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

modules/mbedtls/CMakeLists.txt

@@ -136,7 +136,7 @@ zephyr_interface_library_named(mbedTLS)
 
     zephyr_library_named(mbedTLSCrypto)
 
-    if (CONFIG_MBEDTLS_PSA_CRYPTO_C AND NOT CONFIG_BUILD_WITH_TFM)
+    if (CONFIG_MBEDTLS_PSA_CRYPTO_C)
       list(APPEND crypto_source
         ${ZEPHYR_CURRENT_MODULE_DIR}/library/psa_crypto_aead.c
         ${ZEPHYR_CURRENT_MODULE_DIR}/library/psa_crypto_cipher.c
@@ -176,6 +176,9 @@ zephyr_interface_library_named(mbedTLS)
 
     zephyr_library_sources(${crypto_source})
 
+    # Custom macro to tell that an mbedTLSCrypto source file is being compiled.
+    zephyr_library_compile_definitions(BUILDING_MBEDTLS_CRYPTO)
+
     zephyr_library_link_libraries(mbedTLS)
 
     zephyr_library_link_libraries_ifdef(CONFIG_BUILD_WITH_TFM tfm_api)

modules/mbedtls/configs/config-tls-generic.h

@@ -453,11 +453,12 @@
 #define MBEDTLS_PSA_P256M_DRIVER_ENABLED
 #endif
 
-#if defined(CONFIG_ARCH_POSIX) && !defined(CONFIG_PICOLIBC)
-#define MBEDTLS_PSA_KEY_SLOT_COUNT     64
+#if defined(CONFIG_ARCH_POSIX)
+#define MBEDTLS_PSA_KEY_SLOT_COUNT 64 /* for BLE Mesh tests */
+#endif
+
+#if defined(CONFIG_SECURE_STORAGE)
 #define MBEDTLS_PSA_CRYPTO_STORAGE_C
-#define MBEDTLS_PSA_ITS_FILE_C
-#define MBEDTLS_FS_IO
 #endif
 
 #endif /* CONFIG_MBEDTLS_PSA_CRYPTO_C */
@@ -470,7 +471,6 @@
 #define MBEDTLS_PSA_CRYPTO_CLIENT
 #define MBEDTLS_PSA_CRYPTO_CONFIG
 #define MBEDTLS_PSA_CRYPTO_CONFIG_FILE   "config-psa.h"
-
 #endif
 
 #if defined(CONFIG_MBEDTLS_TLS_VERSION_1_2) && defined(CONFIG_MBEDTLS_PSA_CRYPTO_C)

samples/index.rst

@@ -26,6 +26,7 @@ Samples and Demos
    cpp/*
    posix/*
    kernel/*
+   psa/*
    tfm_integration/tfm_integration.rst
    modules/*
    fuel_gauge/*

samples/psa/index.rst

@@ -0,0 +1,10 @@
+PSA samples
+###########
+
+The following samples demonstrate various uses of several of the `Platform Security Architecture (PSA) Certified APIs <https://arm-software.github.io/psa-api/>`_.
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   **/*

samples/psa/its/CMakeLists.txt

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: Apache-2.0
+cmake_minimum_required(VERSION 3.20.0)
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+
+project(psa_its)
+
+target_sources(app PRIVATE src/main.c)

samples/psa/its/README.rst

@@ -0,0 +1,67 @@
+.. zephyr:code-sample:: psa_its
+   :name: PSA Internal Trusted Storage API
+   :relevant-api: psa_secure_storage
+
+   Use the PSA ITS API.
+
+Overview
+********
+
+This sample demonstrates usage of the
+`PSA Internal Trusted Storage (ITS) API <https://arm-software.github.io/psa-api/storage/1.0/overview/architecture.html#the-internal-trusted-storage-api>`_,
+which is part of the `PSA Secure Storage API <https://arm-software.github.io/psa-api/storage/>`_,
+for storing and retrieving persistent data.
+
+Requirements
+************
+
+An implementation of the PSA ITS API must be present for this sample to build.
+It can be provided by:
+
+* :ref:`tfm`, for ``*/ns`` :term:`board targets<board target>`.
+* The :ref:`secure storage subsystem <secure_storage>`, for the other board targets.
+
+Building
+********
+
+This sample is located in :zephyr_file:`samples/psa/its`.
+
+Different configurations are defined in the :file:`sample.yaml` file.
+You can use them to build the sample, depending on the PSA ITS provider, as follows:
+
+.. tabs::
+
+   .. tab:: TF-M
+
+     For board targets with TF-M:
+
+      .. zephyr-app-commands::
+         :zephyr-app: samples/psa/its
+         :tool: west
+         :goals: build
+         :board: <ns_board_target>
+         :west-args: -T sample.psa.its.tfm
+
+   .. tab:: secure storage subsystem
+
+      For board targets without TF-M.
+
+      If the board target to compile for has an entropy driver (preferable):
+
+      .. zephyr-app-commands::
+         :zephyr-app: samples/psa/its
+         :tool: west
+         :goals: build
+         :board: <board_target>
+         :west-args: -T sample.psa.its.secure_storage.entropy_driver
+
+      Or, to use an insecure entropy source (only for testing):
+
+      .. zephyr-app-commands::
+         :zephyr-app: samples/psa/its
+         :tool: west
+         :goals: build
+         :board: <board_target>
+         :west-args: -T sample.psa.its.secure_storage.entropy_not_secure
+
+To flash it, see :ref:`west-flashing`.

samples/psa/its/overlay-entropy_driver.conf

@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: Apache-2.0
+
+CONFIG_ENTROPY_GENERATOR=y
+CONFIG_MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG=y

samples/psa/its/overlay-entropy_not_secure.conf

@@ -0,0 +1,5 @@
+# SPDX-License-Identifier: Apache-2.0
+
+CONFIG_TEST_RANDOM_GENERATOR=y
+CONFIG_TIMER_RANDOM_GENERATOR=y
+CONFIG_MBEDTLS_ENTROPY_POLL_ZEPHYR=y

samples/psa/its/overlay-secure_storage.conf

@@ -0,0 +1,10 @@
+# SPDX-License-Identifier: Apache-2.0
+
+CONFIG_MBEDTLS=y
+CONFIG_MBEDTLS_PSA_CRYPTO_C=y
+
+# The default stack size (1024) is not enough for the PSA Crypto core.
+# On top of that, the ITS implementation uses the stack for buffers.
+CONFIG_MAIN_STACK_SIZE=3072
+
+CONFIG_SECURE_STORAGE=y

samples/psa/its/prj.conf

@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: Apache-2.0
+
+CONFIG_LOG=y
+CONFIG_LOG_DEFAULT_LEVEL=3