From 5d6cfaa87e8912b99d05698ed9d693c92b83b277 Mon Sep 17 00:00:00 2001 From: Mia Koen Date: Thu, 10 Oct 2024 10:54:03 +0200 Subject: [PATCH] doc: Misc security and crypto doc updates A few updates to security and crypto doc for NCS 2.8.0 release. Among others: Security page nRF Security lib TF-M Trusted storage Access port protection HUK Signed-off-by: Mia Koen --- .../nrf_security/doc/driver_config.rst | 80 ++++++++++--------- .../security/nrf_security/doc/drivers.rst | 6 +- .../libraries/security/nrf_security/index.rst | 2 +- doc/nrf/security.rst | 5 +- doc/nrf/security/ap_protect.rst | 4 +- doc/nrf/security/tfm.rst | 20 ++--- doc/nrf/security/trusted_storage.rst | 12 +++ 7 files changed, 74 insertions(+), 55 deletions(-) diff --git a/doc/nrf/libraries/security/nrf_security/doc/driver_config.rst b/doc/nrf/libraries/security/nrf_security/doc/driver_config.rst index 686ba4876cfd..8495f3c0d862 100644 --- a/doc/nrf/libraries/security/nrf_security/doc/driver_config.rst +++ b/doc/nrf/libraries/security/nrf_security/doc/driver_config.rst @@ -209,25 +209,27 @@ Key derivation function configurations To enable key derivation function (KDF) support, set one or more of the Kconfig options in the following table: -+--------------------------+---------------------------------------------------------------+ -| KDF algorithm | Configuration option | -+==========================+===============================================================+ -| HKDF | :kconfig:option:`CONFIG_PSA_WANT_ALG_HKDF` | -+--------------------------+---------------------------------------------------------------+ -| HKDF-Extract | :kconfig:option:`CONFIG_PSA_WANT_ALG_HKDF_EXTRACT` | -+--------------------------+---------------------------------------------------------------+ -| HKDF-Expand | :kconfig:option:`CONFIG_PSA_WANT_ALG_HKDF_EXPAND` | -+--------------------------+---------------------------------------------------------------+ -| PBKDF2-HMAC | :kconfig:option:`CONFIG_PSA_WANT_ALG_PBKDF2_HMAC` | -+--------------------------+---------------------------------------------------------------+ -| PBKDF2-AES-CMAC-PRF-128 | :kconfig:option:`CONFIG_PSA_WANT_ALG_PBKDF2_AES_CMAC_PRF_128` | -+--------------------------+---------------------------------------------------------------+ -| TLS 1.2 PRF | :kconfig:option:`CONFIG_PSA_WANT_ALG_TLS12_PRF` | -+--------------------------+---------------------------------------------------------------+ -| TLS 1.2 PSK to MS | :kconfig:option:`CONFIG_PSA_WANT_ALG_TLS12_PSK_TO_MS` | -+--------------------------+---------------------------------------------------------------+ -| TLS 1.2 EC J-PAKE to PMS | :kconfig:option:`CONFIG_PSA_WANT_ALG_TLS12_ECJPAKE_TO_PMS` | -+--------------------------+---------------------------------------------------------------+ ++-----------------------------+---------------------------------------------------------------+ +| KDF algorithm | Configuration option | ++=============================+===============================================================+ +| HKDF | :kconfig:option:`CONFIG_PSA_WANT_ALG_HKDF` | ++-----------------------------+---------------------------------------------------------------+ +| HKDF-Extract | :kconfig:option:`CONFIG_PSA_WANT_ALG_HKDF_EXTRACT` | ++-----------------------------+---------------------------------------------------------------+ +| HKDF-Expand | :kconfig:option:`CONFIG_PSA_WANT_ALG_HKDF_EXPAND` | ++-----------------------------+---------------------------------------------------------------+ +| PBKDF2-HMAC | :kconfig:option:`CONFIG_PSA_WANT_ALG_PBKDF2_HMAC` | ++-----------------------------+---------------------------------------------------------------+ +| PBKDF2-AES-CMAC-PRF-128 | :kconfig:option:`CONFIG_PSA_WANT_ALG_PBKDF2_AES_CMAC_PRF_128` | ++-----------------------------+---------------------------------------------------------------+ +| TLS 1.2 PRF | :kconfig:option:`CONFIG_PSA_WANT_ALG_TLS12_PRF` | ++-----------------------------+---------------------------------------------------------------+ +| TLS 1.2 PSK to MS | :kconfig:option:`CONFIG_PSA_WANT_ALG_TLS12_PSK_TO_MS` | ++-----------------------------+---------------------------------------------------------------+ +| TLS 1.2 EC J-PAKE to PMS | :kconfig:option:`CONFIG_PSA_WANT_ALG_TLS12_ECJPAKE_TO_PMS` | ++-----------------------------+---------------------------------------------------------------+ +| SP 800-108r1 CMAC w/counter | :kconfig:option:`CONFIG_PSA_WANT_ALG_SP800_108_COUNTER_CMAC` | ++-----------------------------+---------------------------------------------------------------+ Key derivation function support @@ -235,25 +237,27 @@ Key derivation function support The following table shows key derivation function (KDF) support for each driver: -+--------------------------+--------------------------+----------------------------+---------------------------+ -| KDF algorithm | nrf_cc3xx driver support | nrf_oberon driver support | nrf_cracen driver support | -+==========================+==========================+============================+===========================+ -| HKDF | Not supported | Supported | Supported | -+--------------------------+--------------------------+----------------------------+---------------------------+ -| HKDF-Extract | Not supported | Supported | Not Supported | -+--------------------------+--------------------------+----------------------------+---------------------------+ -| HKDF-Expand | Not supported | Supported | Not Supported | -+--------------------------+--------------------------+----------------------------+---------------------------+ -| PBKDF2-HMAC | Not supported | Supported | Supported | -+--------------------------+--------------------------+----------------------------+---------------------------+ -| PBKDF2-AES-CMAC-PRF-128 | Not supported | Supported | Supported | -+--------------------------+--------------------------+----------------------------+---------------------------+ -| TLS 1.2 PRF | Not supported | Supported | Not Supported | -+--------------------------+--------------------------+----------------------------+---------------------------+ -| TLS 1.2 PSK to MS | Not supported | Supported | Not Supported | -+--------------------------+--------------------------+----------------------------+---------------------------+ -| TLS 1.2 EC J-PAKE to PMS | Not supported | Supported | Supported | -+--------------------------+--------------------------+----------------------------+---------------------------+ ++------------------------------+--------------------------+----------------------------+---------------------------+ +| KDF algorithm | nrf_cc3xx driver support | nrf_oberon driver support | nrf_cracen driver support | ++==============================+==========================+============================+===========================+ +| HKDF | Not supported | Supported | Supported | ++------------------------------+--------------------------+----------------------------+---------------------------+ +| HKDF-Extract | Not supported | Supported | Not Supported | ++------------------------------+--------------------------+----------------------------+---------------------------+ +| HKDF-Expand | Not supported | Supported | Not Supported | ++------------------------------+--------------------------+----------------------------+---------------------------+ +| PBKDF2-HMAC | Not supported | Supported | Supported | ++------------------------------+--------------------------+----------------------------+---------------------------+ +| PBKDF2-AES-CMAC-PRF-128 | Not supported | Supported | Supported | ++------------------------------+--------------------------+----------------------------+---------------------------+ +| TLS 1.2 PRF | Not supported | Supported | Not Supported | ++------------------------------+--------------------------+----------------------------+---------------------------+ +| TLS 1.2 PSK to MS | Not supported | Supported | Not Supported | ++------------------------------+--------------------------+----------------------------+---------------------------+ +| TLS 1.2 EC J-PAKE to PMS | Not supported | Supported | Supported | ++------------------------------+--------------------------+----------------------------+---------------------------+ +| SP 800-108r1 CMAC w/counter | Not supported | Not supported | Supported | ++------------------------------+--------------------------+----------------------------+---------------------------+ The configuration of the :ref:`nrf_security_drivers_oberon` is automatically generated based on the user-enabled algorithms in `Key derivation function configurations`_. diff --git a/doc/nrf/libraries/security/nrf_security/doc/drivers.rst b/doc/nrf/libraries/security/nrf_security/doc/drivers.rst index 42d9d59cc0cc..cac9d70a2814 100644 --- a/doc/nrf/libraries/security/nrf_security/doc/drivers.rst +++ b/doc/nrf/libraries/security/nrf_security/doc/drivers.rst @@ -83,7 +83,7 @@ To enable the :ref:`nrf_oberon_readme` PSA driver, set the :kconfig:option:`CONF CRACEN driver ************* -The CRACEN driver provides entropy and hardware-accelerated cryptography using the CRACEN (Crypto Accelerator Engine) peripheral. +The CRACEN driver provides entropy and hardware-accelerated cryptography using the Crypto Accelerator Engine (CRACEN) peripheral. This driver is only available on nRF54L Series devices. Enabling the CRACEN driver @@ -93,8 +93,10 @@ The CRACEN driver can be enabled by setting the :kconfig:option:`CONFIG_PSA_CRYP The nrf_oberon driver may then be disabled by using the Kconfig option :kconfig:option:`CONFIG_PSA_CRYPTO_DRIVER_OBERON` (``CONFIG_PSA_CRYPTO_DRIVER_OBERON=n``). +For more details on the nRF54L Series cryptography operations and the related configuration, see :ref:`ug_nrf54l_cryptography`. + .. note:: - On nRF54L Series devices, CRACEN is the only source of entropy. + On the nRF54L Series devices, CRACEN is the only source of entropy. Therefore, it is not possible to disable the :kconfig:option:`CONFIG_PSA_CRYPTO_DRIVER_CRACEN` option when the Zephyr entropy driver is enabled. Legacy Mbed TLS diff --git a/doc/nrf/libraries/security/nrf_security/index.rst b/doc/nrf/libraries/security/nrf_security/index.rst index e4f913496283..997ba32dde5d 100644 --- a/doc/nrf/libraries/security/nrf_security/index.rst +++ b/doc/nrf/libraries/security/nrf_security/index.rst @@ -5,7 +5,7 @@ nRF Security ############ The nRF Security subsystem (nrf_security) provides an integration between `Mbed TLS`_ and software libraries that provide hardware-accelerated cryptographic functionality on selected Nordic Semiconductor SoCs as well as alternate software-based implementations of the Mbed TLS APIs. -These libraries include the binary versions of accelerated cryptographic libraries listed in :ref:`nrfxlib:crypto`, and the open source Mbed TLS implementation in |NCS| located in `sdk-mbedtls`_. +These libraries include the binary versions of accelerated cryptographic libraries listed in :ref:`nrfxlib:crypto`, and the open source Mbed TLS implementation in the |NCS| located in `sdk-mbedtls`_. The subsystem includes a PSA driver abstraction layer to enable both hardware-accelerated and software-based implementation at the same time. The nRF Security subsystem can interface with the :ref:`nrf_cc3xx_mbedcrypto_readme`. diff --git a/doc/nrf/security.rst b/doc/nrf/security.rst index 1ddb71bf76b0..fbe1fdb7b955 100644 --- a/doc/nrf/security.rst +++ b/doc/nrf/security.rst @@ -36,16 +36,17 @@ Some of them are documented in detail in other parts of this documentation, whil - All samples and applications that support the ``*/ns`` :ref:`variant ` of the boards. * - Trusted Firmware-M (TF-M) - TF-M is the reference implementation of `Platform Security Architecture (PSA)`_. - On nRF5340 and nRF91 Series devices, TF-M is used to configure and boot an application with :ref:`CMSE enabled `. + On the nRF5340, nRF54L and nRF91 Series devices, TF-M is used to configure and boot an application with :ref:`CMSE enabled `. - See :ref:`ug_tfm`. - | - :ref:`tfm_samples` - | - :ref:`cryptography samples ` + | - :ref:`crypto_samples` | - :ref:`https_client` sample | - :ref:`openthread_samples` | - :ref:`TF-M integration samples ` in Zephyr * - Cryptographic operations (:ref:`nrf_security`) - The :ref:`nrf_security` library acts as an orchestrator for the different cryptographic libraries available in the system. HW accelerated libraries are prioritized over SW libraries when both are enabled. + | Find more information on nRF54L Series-specific cryptography operations and the related configuration in :ref:`ug_nrf54l_cryptography`. - :kconfig:option:`CONFIG_NRF_SECURITY` (:ref:`more info`) - | - :ref:`nrf_security` library with :ref:`nrf_security_drivers` | - :ref:`nrfxlib:crypto` diff --git a/doc/nrf/security/ap_protect.rst b/doc/nrf/security/ap_protect.rst index 85d399e75aa3..f85189e538c4 100644 --- a/doc/nrf/security/ap_protect.rst +++ b/doc/nrf/security/ap_protect.rst @@ -88,7 +88,7 @@ See the related hardware documentation for more information about which implemen - n/a - ✔ - *Documentation not yet available* - - Can also use the lifecycle state management mechanism as an alternative to AP-Protect + - Also supports Secure AP-Protect (see note below) * - nRF5340 - n/a - ✔ @@ -131,7 +131,7 @@ See the related hardware documentation for more information about which implemen - .. note:: - The SoCs or SiPs that support `ARM TrustZone`_ and different :ref:`app_boards_spe_nspe` (nRF5340 and nRF91 Series) implement two AP-Protect systems: AP-Protect and Secure AP-Protect. + The SoCs or SiPs that support `ARM TrustZone`_ and different :ref:`app_boards_spe_nspe` (nRF5340, nRF54L15 and nRF91 Series) implement two AP-Protect systems: AP-Protect and Secure AP-Protect. While AP-Protect blocks access to all CPU registers and memories, Secure AP-Protect limits access to the CPU to only non-secure accesses. This means that the CPU is entirely unavailable while it is running the code in the Secure Processing Environment, and only non-secure registers and address-mapped resources can be accessed. diff --git a/doc/nrf/security/tfm.rst b/doc/nrf/security/tfm.rst index e9185546ef61..2b1343a614ba 100644 --- a/doc/nrf/security/tfm.rst +++ b/doc/nrf/security/tfm.rst @@ -7,7 +7,7 @@ Running applications with Trusted Firmware-M :local: :depth: 2 -On nRF5340 and nRF91 Series devices, Trusted Firmware-M (TF-M) is used to configure and boot an application as non-secure. +On the nRF5340, nRF54L15 and nRF91 Series devices, Trusted Firmware-M (TF-M) is used to configure and boot an application as non-secure. Overview ******** @@ -19,17 +19,16 @@ This is achieved by a set of secure run time services such as Secure Storage, Cr Additionally, secure boot through MCUboot in TF-M ensures integrity of runtime software and supports firmware upgrade. .. note:: - Support for TF-M with :ref:`minimal version ` disabled in |NCS| is currently :ref:`experimental `. + Support for TF-M with :ref:`minimal version ` disabled in the |NCS| is currently :ref:`experimental `. For official documentation, see the `TF-M documentation`_. -The TF-M implementation in |NCS| is currently demonstrated in the following samples: +The TF-M implementation in |NCS| is demonstrated in the following samples: -- All :ref:`tfm_samples` in this SDK -- All :ref:`cryptography samples ` in this SDK -- A series of :ref:`TF-M integration samples ` available in Zephyr -- The :ref:`https_client` sample for nRF91 Series devices in this SDK -- The :ref:`openthread_samples` that support the ``nrf5340dk/nrf5340/cpuapp/ns`` board target in this SDK +* All :ref:`tfm_samples` in this SDK +* A series of :ref:`TF-M integration samples ` available in Zephyr + +In addition, the TF-M implementation is used in all samples and applications in this SDK that support the ``*/ns`` :ref:`variant ` of the boards (due to Cortex-M Security Extensions (CMSE) support, see :ref:`app_boards_spe_nspe` for more details). Building ******** @@ -48,6 +47,7 @@ To use the full TF-M, you must disable the :kconfig:option:`CONFIG_TFM_PROFILE_T You must build TF-M using a non-secure board target. The following platforms are currently supported: +* nRF54L15 * nRF5340 * nRF91 Series @@ -193,8 +193,8 @@ TF-M partition alignment requirements TF-M requires that secure and non-secure partition addresses must be aligned to the flash region size :kconfig:option:`CONFIG_NRF_TRUSTZONE_FLASH_REGION_SIZE`. |NCS| ensures that they in fact are aligned and comply with the TF-M requirements. -In nRF53 and nRF91 series TF-M uses the SPU to enforce the security policy between the partitions, so the :kconfig:option:`CONFIG_NRF_TRUSTZONE_FLASH_REGION_SIZE` is set to the SPU flash region size. -In nRF54L15 TF-M uses the MPC to enforce the security policy between the partitions, so the :kconfig:option:`CONFIG_NRF_TRUSTZONE_FLASH_REGION_SIZE` is set to the MPC region size. +On the nRF53 and nRF91 Series devices, TF-M uses the SPU to enforce the security policy between the partitions, so the :kconfig:option:`CONFIG_NRF_TRUSTZONE_FLASH_REGION_SIZE` is set to the SPU flash region size. +On the nRF54L15 devices, TF-M uses the MPC to enforce the security policy between the partitions, so the :kconfig:option:`CONFIG_NRF_TRUSTZONE_FLASH_REGION_SIZE` is set to the MPC region size. When the :ref:`partition_manager` is enabled, it will take into consideration the alignment requirements. But when the static partitions are used, the user is responsible for following the alignment requirements. diff --git a/doc/nrf/security/trusted_storage.rst b/doc/nrf/security/trusted_storage.rst index 3cdf2fd2b36f..ab842c4e982f 100644 --- a/doc/nrf/security/trusted_storage.rst +++ b/doc/nrf/security/trusted_storage.rst @@ -43,6 +43,18 @@ The table below gives an overview of the trusted storage support for the product - Yes - Yes - No + * - nRF54L15 with TF-M + - TF-M secure storage service + - Yes + - Yes + - Yes + - Yes + * - nRF54L15 without TF-M + - Trusted storage library + - Partial [1]_ + - Yes + - Yes + - Yes * - nRF5340 with TF-M - TF-M secure storage service - Yes