doc: security: add crypto overview page

Added crypto overview page to the documentation.
Added a new crypto section under Security.
Moved the page listing crypto drivers to the new section.
NCSDK-33436, NCSDK-33433, NCSDK-30041.

Signed-off-by: Grzegorz Ferenc <[email protected]>

Author: greg-fer

doc/_utils/redirects.py

@@ -292,6 +292,8 @@
     ("app_dev/optimizing/power", "test_and_optimize/optimizing/power"),
     ("security_chapter", "security"), # Security (landing)
     ("security/security", "security"), # Security (subpage -- removed in v2.8.0)
+    ("libraries/nrf_security/doc/drivers", "security/crypto/drivers"), # Cryptographic drivers ("nRF Security drivers" before v3.1.0)
+    ("libraries/security/nrf_security/doc/drivers", "security/crypto/drivers"),
     ("ug_tfm", "security/tfm/index"), # Running applications with Trusted Firmware-M (split into multiple files in v3.0.0)
     ("app_dev/tfm/index", "security/tfm/index"),
     ("security/tfm", "security/tfm/index"),
@@ -547,7 +549,6 @@
     ("libraries/others/fw_info", "libraries/security/bootloader/fw_info"), # Firmware information
     ("libraries/nrf_security/index", "libraries/security/nrf_security/index"), # nRF Security (landing page in Security libraries)
     ("libraries/nrf_security/doc/configuration", "libraries/security/nrf_security/doc/configuration"), # Configuration
-    ("libraries/nrf_security/doc/drivers", "libraries/security/nrf_security/doc/drivers"), # nRF Security drivers
     ("libraries/nrf_security/doc/driver_config", "libraries/security/nrf_security/doc/driver_config"), # Feature configurations and driver support
     ("libraries/nrf_security/doc/mbed_tls_header", "libraries/security/nrf_security/doc/mbed_tls_header"), # User-provided Mbed TLS configuration header
     ("libraries/nrf_security/doc/backend_config", "libraries/security/nrf_security/doc/backend_config"), # Legacy configurations and supported features

doc/nrf/libraries/security/nrf_security/index.rst

@@ -24,7 +24,6 @@ This library conforms to the specific revision of Mbed TLS that is supplied thro
    :maxdepth: 2
    :caption: Subpages:
 
-   doc/drivers
    doc/configuration
    doc/driver_config
    doc/backend_config

doc/nrf/links.txt

@@ -1561,6 +1561,7 @@
 
 .. _`Platform Security Architecture (PSA)`: https://www.psacertified.org/what-is-psa-certified/
 .. _`PSA Certified IoT Security Framework`: https://www.psacertified.org/what-is-psa-certified/using-psa-certified/
+.. _`Embedded and IoT Security Specifications and Implementations`: https://www.psacertified.org/development-resources/building-in-security/specifications-implementations/
 .. _`What is a Root of Trust?`: https://www.psacertified.org/blog/what-is-a-root-of-trust/
 .. _`Device Attestation and Entity Attestation Tokens Explained`: https://www.psacertified.org/blog/what-is-an-entity-attestation-token/
 .. _`PSA Certified development resources`: https://www.psacertified.org/development-resources/

doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst

@@ -117,7 +117,8 @@ Developing with custom boards
 Security
 ========
 
-|no_changes_yet_note|
+* Added the new section about :ref:`ug_crypto_index`.
+  The new section includes pages about :ref:`ug_crypto_architecture` (new page) and :ref:`crypto_drivers` (moved from :ref:`nrf_security` library).
 
 Protocols
 =========
@@ -494,9 +495,14 @@ Gazell libraries
 Security libraries
 ------------------
 
-* :ref:`nrf_security_readme` library:
+* :ref:`nrf_security` library:
+
+  * Updated:
+
+    * The name of the Kconfig option ``CONFIG_PSA_USE_CRACEN_ASYMMETRIC_DRIVER`` to :kconfig:option:`CONFIG_PSA_USE_CRACEN_ASYMMETRIC_ENCRYPTION_DRIVER`, which is more descriptive and more consistent with the options of the other drivers.
+    * The placement of the page about nRF Security drivers.
+      The page was moved to :ref:`ug_crypto_index` and renamed to :ref:`crypto_drivers`.
 
-  * Renamed the ``CONFIG_PSA_USE_CRACEN_ASYMMETRIC_DRIVER`` Kconfig option to :kconfig:option:`CONFIG_PSA_USE_CRACEN_ASYMMETRIC_ENCRYPTION_DRIVER`, which is more descriptive and more consistent with the options of the other drivers.
 
 Modem libraries
 ---------------

doc/nrf/samples/crypto.rst

@@ -1,9 +1,10 @@
 .. _crypto_samples:
 
-Cryptography samples
-####################
+Cryptographic samples
+#####################
 
-This section lists the available |NCS| samples and tests for the :ref:`nrf_security` and the :ref:`nrfxlib:crypto`, two of the :ref:`security` features of the |NCS|.
+This section lists the available |NCS| samples and tests for the :ref:`cryptographic features in the nRF Connect SDK <ug_crypto_index>`.
+The samples use :ref:`nrf_security` and the :ref:`nrfxlib:crypto`.
 
 .. include:: ../samples.rst
     :start-after: samples_general_info_start

doc/nrf/security.rst

@@ -28,27 +28,28 @@ Some of them are documented in detail in other parts of this documentation, whil
       | - :ref:`DFU libraries <lib_dfu>`
       | - :ref:`Software Updates for Internet of Things (SUIT) <ug_nrf54h20_suit_dfu>`
       | - :doc:`MCUboot <mcuboot:design>`
-  * - Processing environments (CMSE)
-    - The :ref:`boards supported by the SDK <app_boards_names>` distinguish entries according to which CPU is to be targeted (for multi-core SoCs) and whether Cortex-M Security Extensions (CMSE) are used or not.
-      When CMSE is used, the firmware is split in accordance with the security by separation architecture principle to better protect sensitive assets and code.
-      In the |NCS|, the CMSE support is implemented using Trusted Firmware-M (TF-M).
-    - See :ref:`app_boards_spe_nspe`.
-    - All samples and applications that support the ``*/ns`` :ref:`variant <app_boards_names>` of the boards.
+  * - Cryptographic operations
+    - The |NCS| follows the :ref:`PSA Crypto standard <ug_psa_certified_api_overview_crypto>` and provides :ref:`two different implementations <ug_crypto_architecture_implementation_standards>`, Oberon PSA Crypto and TF-M Crypto Service.
+      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.
+    - :kconfig:option:`CONFIG_NRF_SECURITY` (:ref:`more info<psa_crypto_support>`)
+    - | - :ref:`nrf_security` library
+      | - :ref:`nrfxlib:crypto`
+      | - :ref:`crypto_samples`
+      | - :ref:`ug_nrf54l_cryptography`
   * - Trusted Firmware-M (TF-M)
     - TF-M is the reference implementation of `Platform Security Architecture (PSA)`_.
-      On nRF5340, nRF54L and nRF91 Series devices, TF-M is used to configure and boot an application with :ref:`CMSE enabled <app_boards_spe_nspe_cpuapp_ns>`.
+      On nRF5340, nRF54L and nRF91 Series devices, TF-M is used to configure and boot an application with :ref:`security by separation <app_boards_spe_nspe_cpuapp_ns>`.
     - See :ref:`ug_tfm`.
     - | - :ref:`tfm_samples`
       | - :ref:`crypto_samples`
       | - :zephyr:code-sample-category:`tfm_integration` 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<nrf_security_config>`)
-    - | - :ref:`nrf_security` library with :ref:`nrf_security_drivers`
-      | - :ref:`nrfxlib:crypto`
-      | - :ref:`crypto_samples`
+  * - Processing environments (CMSE)
+    - The :ref:`boards supported by the SDK <app_boards_names>` distinguish entries according to which CPU is to be targeted (for multi-core SoCs) and whether Cortex-M Security Extensions (CMSE) are used or not.
+      When CMSE is used, the firmware is split in accordance with the security by separation architecture principle to better protect sensitive assets and code.
+      In the |NCS|, the CMSE support is implemented using Trusted Firmware-M (TF-M).
+    - See :ref:`app_boards_spe_nspe`.
+    - All samples and applications that support the ``*/ns`` :ref:`variant <app_boards_names>` of the boards.
   * - Trusted storage
     - The trusted storage library enables you to provide features like integrity, confidentiality and authenticity of the stored data, without using the TF-M Platform Root of Trust (PRoT).
     - See :ref:`trusted_storage_in_ncs` and :ref:`trusted storage library configuration <trusted_storage_configuration>`.
@@ -65,6 +66,7 @@ Some of them are documented in detail in other parts of this documentation, whil
    :caption: Subpages:
 
    security/psa_certified_api_overview
-   security/ap_protect
+   security/crypto/index
    security/tfm/index
+   security/ap_protect
    security/trusted_storage

doc/nrf/security/crypto/crypto_architecture.rst

@@ -0,0 +1,143 @@
+.. _ug_crypto_architecture:
+
+Cryptographic architecture overview
+###################################
+
+.. contents::
+   :local:
+   :depth: 2
+
+The cryptographic subsystem in the |NCS| is based on the `PSA Certified Crypto API`_ standard (PSA Crypto API), which is one of the `PSA Certified APIs <Embedded and IoT Security Specifications and Implementations_>`_.
+The PSA Crypto API is a cryptographic standard that offers a unified interface for cryptographic operations across different hardware platforms.
+
+PSA Crypto API architecture
+***************************
+
+The following figure shows the general architecture of PSA Crypto:
+
+.. figure:: ../images/psa_crypto_api_arch.svg
+   :alt: PSA Crypto standard architecture
+   :align: center
+
+   PSA Crypto standard architecture
+
+In this figure:
+
+* Application calls the PSA Crypto implementation through the PSA Crypto API.
+* The PSA Crypto API implementation is an abstraction layer that manages cryptographic operations, key handling, and driver coordination.
+  The implementations can be different, but they should all conform to the PSA Crypto specification.
+* Crypto driver is a specialized component that implements specific cryptographic algorithms or provides access to hardware accelerators.
+* Storage integration provides persistent and secure storage capabilities through standardized PSA Secure Storage APIs.
+  It implements storage interfaces that allow the PSA Crypto implementation to securely store and retrieve keys, ensuring proper protection of sensitive material throughout its lifecycle.
+
+.. _ug_crypto_architecture_interaction_flow:
+
+Component interaction flow
+==========================
+
+When an application makes a call to the PSA Crypto API, the following interaction flow occurs between the architecture components:
+
+1. The application or protocol stack initiates a cryptographic operation by calling a function in the PSA Crypto API, such as ``psa_cipher_encrypt()`` or ``psa_sign_message()``.
+2. The PSA Crypto implementation receives the request and performs initial parameter validation to ensure the request is properly formatted and contains valid parameters.
+3. Based on the specific operation requested, the implementation selects the most appropriate crypto driver.
+   Hardware drivers are typically prioritized when available, with software drivers serving as fallbacks.
+4. If the operation involves cryptographic keys, the implementation coordinates with the storage integration to securely retrieve the necessary key material.
+   Keys are handled using `Key Identifiers`_ to maintain security and prevent direct exposure of key material to the application.
+5. The implementation delegates the actual cryptographic processing to the selected crypto driver.
+   The driver performs the requested operation using either hardware acceleration or software algorithms.
+6. The driver returns the operation result to the PSA Crypto implementation, which performs any necessary post-processing and validation.
+7. The implementation returns the final result to the application through the PSA Crypto API, completing the cryptographic operation.
+
+.. _ug_crypto_architecture_implementation_standards:
+
+Implementations in the |NCS|
+****************************
+
+The |NCS| follows the PSA Crypto standard through two major API implementations: Oberon PSA Crypto and TF-M Crypto Service.
+They are designed for use without and with Trusted Firmware-M (TF-M), respectively, and have different security requirements.
+Both are based on the `sdk-oberon-psa-crypto`_ library, which offers a lightweight PSA Crypto API implementation optimized for resource-constrained microcontrollers.
+
+.. figure:: ../images/psa_crypto_api_overview.svg
+   :alt: PSA Crypto API implementations in the |NCS|
+   :align: center
+
+   PSA Crypto API implementations in the |NCS|
+
+.. _ug_crypto_architecture_implementation_standards_oberon:
+
+Oberon PSA Crypto implementation
+================================
+
+The Oberon PSA Crypto implementation provides a direct PSA Crypto API interface for applications that do not require Trusted Firmware-M (TF-M).
+The Oberon PSA Crypto is a library that serves as the central component managing cryptographic operations and driver selection.
+
+.. figure:: ../images/psa_crypto_api_oberon.svg
+   :alt: Oberon PSA Crypto implementation
+   :align: center
+
+   Oberon PSA Crypto implementation
+
+The Oberon PSA Crypto acts as the implementation provider, directly exposing the PSA Crypto API to applications.
+Each driver can implement support for different subsets of cryptographic algorithms, providing software support for algorithms that hardware cannot support.
+
+The following figure shows the driver library selection through the driver wrapper, one of the internal modules of Oberon PSA Crypto:
+
+.. figure:: ../images/psa_certified_api_lib_selection.svg
+   :alt: Oberon PSA Crypto driver library selection
+   :align: center
+
+   Oberon PSA Crypto driver library selection
+
+This implementation standard is suitable for applications that prioritize simplicity and do not require the additional security isolation provided by TF-M.
+It offers direct access to cryptographic functionality with minimal overhead, making it ideal for resource-constrained applications.
+
+Storage integration for the Oberon PSA Crypto implementation
+------------------------------------------------------------
+
+When using the Oberon PSA Crypto implementation, persistent keys from the PSA Crypto API can be stored in the |NCS| using one of the following storage mechanisms:
+
+* Zephyr's :ref:`Secure storage <zephyr:secure_storage>` subsystem - Zephyr-specific implementation of the functions defined in the `PSA Certified Secure Storage API`_.
+* |NCS|'s :ref:`trusted_storage_readme` library - which provides features like integrity, confidentiality, and authenticity of the stored data without using the TF-M Platform Root of Trust (PRoT).
+
+For more information about the storage integration for the Oberon PSA Crypto implementation, see :ref:`trusted_storage_in_ncs`.
+
+.. _ug_crypto_architecture_implementation_standards_tfm:
+
+TF-M Crypto Service implementation
+==================================
+
+The TF-M Crypto Service implementation provides PSA Crypto API access through Trusted Firmware-M for applications that require enhanced security through hardware-enforced separation.
+
+.. figure:: ../images/psa_crypto_api_tfm.svg
+   :alt: TF-M Crypto Service implementation
+   :align: center
+
+   TF-M Crypto Service implementation
+
+This implementation leverages TF-M's Secure Processing Environment (SPE) to isolate cryptographic operations from the Non-Secure Processing Environment (NSPE).
+TF-M is built on top of TrustZone technology and isolates the PSA Crypto API as non-secure callable calls into a secure processing environment.
+
+.. figure:: ../images/tfm_psa_crypto_api_nspe_spe.svg
+   :alt: TF-M Crypto Service implementation in the NSPE and SPE
+   :align: center
+
+   TF-M Crypto Service implementation in the NSPE and SPE
+
+In this architecture, TF-M implements the secure cryptographic service using the existing Oberon PSA Core and its associated drivers within the secure environment.
+Cryptographic keys are stored and isolated in the SPE, ensuring they are not accessible by the application running in the NSPE.
+The same cryptographic drivers (nrf_cc3xx, nrf_oberon, and CRACEN) are available within the secure environment, providing consistent cryptographic capabilities.
+Additionally, TF-M integrates key storage using its internal mechanisms, offering secure key management through :ref:`Internal Trusted Storage <ug_tfm_services_its>` and :ref:`Protected Storage <tfm_partition_ps>`.
+
+This implementation standard is mandatory for applications requiring PSA Certified security levels and provides the highest level of security through hardware-enforced isolation.
+It ensures that cryptographic operations and key material remain protected even if the non-secure application is compromised.
+
+Storage integration for the TF-M Crypto Service implementation
+--------------------------------------------------------------
+
+When using the TF-M Crypto Service implementation, keys from the PSA Crypto API are stored in the |NCS| using both of the following storage mechanisms:
+
+* Internal Trusted Storage (ITS) - One of :ref:`ug_tfm_architecture_rot_services_platform` that provides secure storage within the Trusted Firmware-M environment.
+  ITS is the only storage for persistent keys in the TF-M Crypto Service implementation.
+* Protected Storage (PS) - One of :ref:`ug_tfm_architecture_rot_services_application` that provides secure storage within the Trusted Firmware-M environment.
+
+For more information about the storage integration for the TF-M Crypto Service implementation, see :ref:`ug_psa_certified_api_overview_secstorage` and :ref:`ug_tfm_services`.