doc: security: move configuring PSA Crypto API

greg-fer · greg-fer · commit 74133e800452 · 2025-06-23T10:37:30.000+02:00
Moved the page about configuring PSA Crypto API
under security/crypto from the nRF Security lib docs.
NCSDK-33433 and NCSDK-33436.

Signed-off-by: Grzegorz Ferenc &lt;Grzegorz.Ferenc@nordicsemi.no&gt;
diff --git a/doc/_utils/redirects.py b/doc/_utils/redirects.py
@@ -549,7 +549,8 @@
     ("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/driver_config", "libraries/security/nrf_security/doc/driver_config"), # Feature configurations and driver support
+    ("libraries/nrf_security/doc/driver_config", "security/crypto/driver_config"), # Feature configurations and driver support (moved to security/crypto for v3.1.0)
+    ("libraries/security/nrf_security/doc/driver_config", "security/crypto/driver_config"),
     ("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
     ("libraries/tfm/index", "libraries/security/tfm/index"), # TF-M libraries (landing)
diff --git a/doc/nrf/app_dev/device_guides/nrf54l/cryptography.rst b/doc/nrf/app_dev/device_guides/nrf54l/cryptography.rst
@@ -369,7 +369,7 @@ Enabling support for the Encrypted key usage scheme looks as shown in the follow
    CONFIG_PSA_WANT_ALG_SP800_108_COUNTER_CMAC=y
    CONFIG_PSA_WANT_ALG_GCM=y
 
-The configuration is enabling the key type (AES) and the key size (256 bits) supported by the Encrypted usage scheme as explained in the :ref:`ug_nrf54l_crypto_kmu_supported_key_types` section, and in addition enabling the following :ref:`cryptographic features <nrf_security_driver_config>` supported by the CRACEN driver:
+The configuration is enabling the key type (AES) and the key size (256 bits) supported by the Encrypted usage scheme as explained in the :ref:`ug_nrf54l_crypto_kmu_supported_key_types` section, and in addition enabling the following :ref:`cryptographic features <ug_crypto_supported_features>` supported by the CRACEN driver:
 
 * Cipher mode: AES ECB (Electronic CodeBook) mode, no padding
 * Message Authentication Code (MAC) cipher: cipher-based MAC (CMAC) cipher
diff --git a/doc/nrf/libraries/security/nrf_security/doc/configuration.rst b/doc/nrf/libraries/security/nrf_security/doc/configuration.rst
@@ -12,25 +12,23 @@ To enable nRF Security, set the :kconfig:option:`CONFIG_NRF_SECURITY` Kconfig op
 You can use nRF Security with the PSA Crypto APIs or the Legacy crypto APIs.
 
 PSA Crypto APIs
-   .. ncs-include:: driver_config.rst
+   .. ncs-include:: ../../../../security/crypto/driver_config.rst
       :start-after: psa_crypto_support_def_start
       :end-before: psa_crypto_support_def_end
 
-   For more configuration options, see :ref:`psa_crypto_support`.
+   The PSA Crypto API is enabled by default when you enable nRF Security.
+   For more information, see :ref:`psa_crypto_support`.
+   For the list of supported crypto features, see :ref:`ug_crypto_supported_features`.
+
+   Depending on the implementation you are using, the |NCS| builds nRF Security using different versions of the PSA Crypto API.
+
+   .. ncs-include:: ../../../../security/psa_certified_api_overview.rst
+      :start-after: psa_crypto_support_tfm_build_start
+      :end-before: psa_crypto_support_tfm_build_end
 
 Legacy crypto APIs
    .. ncs-include:: backend_config.rst
       :start-after: legacy_crypto_support_def_start
       :end-before: legacy_crypto_support_def_end
 
    For more configuration options, see :ref:`nrf_security_legacy_config`.
-
-Building with TF-M
-******************
-
-If :kconfig:option:`CONFIG_BUILD_WITH_TFM` is enabled together with :kconfig:option:`CONFIG_NRF_SECURITY`, the TF-M secure image will enable the use of the hardware acceleration of Arm CryptoCell.
-In this case, the Kconfig configurations in the nRF Security subsystem control the features enabled in TF-M.
-
-.. ncs-include:: driver_config.rst
-   :start-after: psa_crypto_support_tfm_build_start
-   :end-before: psa_crypto_support_tfm_build_end
diff --git a/doc/nrf/libraries/security/nrf_security/index.rst b/doc/nrf/libraries/security/nrf_security/index.rst
@@ -25,6 +25,5 @@ This library conforms to the specific revision of Mbed TLS that is supplied thro
    :caption: Subpages:
 
    doc/configuration
-   doc/driver_config
    doc/backend_config
    doc/mbed_tls_header
diff --git a/doc/nrf/protocols/matter/getting_started/kconfig.rst b/doc/nrf/protocols/matter/getting_started/kconfig.rst
@@ -28,5 +28,5 @@ Configuration options for other modules
 ***************************************
 
 Because Matter is an application layer protocol on top of the other IPv6-based transport protocols (see :ref:`ug_matter_architecture`), it uses multiple software modules with their own configuration options to provide the communication between the devices and the necessary functionalities.
-It uses modules such as Bluetooth® LE, the IPv6 stack (for example :ref:`Thread <ug_thread_configuring>`), :ref:`nRF Security <nrf_security_config>`, or :ref:`MCUboot <mcuboot:mcuboot_ncs>`.
+It uses modules such as Bluetooth® LE, the IPv6 stack (for example :ref:`Thread <ug_thread_configuring>`), :ref:`PSA Crypto API <psa_crypto_support>`, or :ref:`MCUboot <mcuboot:mcuboot_ncs>`.
 Make sure to review the configuration options of these modules when configuring Matter.
diff --git a/doc/nrf/protocols/thread/configuring.rst b/doc/nrf/protocols/thread/configuring.rst
@@ -211,14 +211,14 @@ At the end of the configuration process, you can check the EUI-64 value using Op
 
 .. _ug_thread_configuring_crypto:
 
-Cryptography options
-====================
+Cryptographic support
+=====================
 
-By default, the OpenThread stack uses the :ref:`nrf_security` (nrf_security) for cryptographic operations.
-The module provides hardware-accelerated cryptographic functionality on selected Nordic Semiconductor SoCs as well as alternate software-based implementations of the Mbed TLS APIs
+By default, the OpenThread stack uses the Mbed TLS crypto toolbox API for cryptographic operations.
+The support is implemented through the :ref:`nrf_security` library, which provides hardware-accelerated cryptographic functionality on selected Nordic Semiconductor SoCs as well as alternate software-based implementations of the Mbed TLS APIs.
 To use `Mbed TLS`_, modify  the :kconfig:option:`OPENTHREAD_MBEDTLS_CHOICE` Kconfig option.
 
-For more information about the configuration and usage of the :ref:`nrf_security`, see the :ref:`nrf_security_config` page.
+For more information, see the :ref:`legacy_crypto_support` page.
 For more information about the open source Mbed TLS implementation in the |NCS|, see the `sdk-mbedtls`_ repository.
 
 .. _ug_thread_configure_commission:
diff --git a/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst b/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst
@@ -119,7 +119,7 @@ Security
 ========
 
 * 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).
+  The new section includes pages about :ref:`ug_crypto_architecture` (new page), :ref:`crypto_drivers` and :ref:`psa_crypto_support` (both moved from the :ref:`nrf_security` library documentation).
 
 * Updated:
 
diff --git a/doc/nrf/security/crypto/crypto_architecture.rst b/doc/nrf/security/crypto/crypto_architecture.rst
@@ -64,6 +64,13 @@ Both are based on the `sdk-oberon-psa-crypto`_ library, which offers a lightweig
 
    PSA Crypto API implementations in the |NCS|
 
+.. note::
+   Depending on the implementation you are using, the |NCS| build system uses different versions of the PSA Crypto API.
+
+   .. ncs-include:: ../psa_certified_api_overview.rst
+      :start-after: psa_crypto_support_tfm_build_start
+      :end-before: psa_crypto_support_tfm_build_end
+
 .. _ug_crypto_architecture_implementation_standards_oberon:
 
 Oberon PSA Crypto implementation
diff --git a/doc/nrf/security/crypto/driver_config.rst b/doc/nrf/security/crypto/driver_config.rst
@@ -1,8 +1,8 @@
 .. _psa_crypto_support:
 .. _nrf_security_driver_config:
 
-Configuring nRF Security with PSA Crypto APIs
-#############################################
+Configuring PSA Crypto APIs
+###########################
 
 .. contents::
    :local:
@@ -11,23 +11,25 @@ Configuring nRF Security with PSA Crypto APIs
 .. psa_crypto_support_def_start
 
 The PSA Crypto in the |NCS| provides secure crypto operations through standardized :ref:`Platform Security Architecture <ug_psa_certified_api_overview>`.
-It implements the cryptographic features either in software, or using hardware accelerators.
-
-The PSA Crypto API is enabled by default when you enable nRF Security with the :kconfig:option:`CONFIG_NRF_SECURITY` Kconfig option.
+Using :ref:`one of the two available implementations of the PSA Crypto API <ug_crypto_architecture_implementation_standards>`, the SDK implements the cryptographic features in software or using hardware accelerators, or both.
 
 .. psa_crypto_support_def_end
 
-.. psa_crypto_support_tfm_build_start
+.. note::
+   If you work with the Mbed TLS legacy crypto toolbox, see :ref:`legacy_crypto_support`.
+
+.. _psa_crypto_support_enable:
 
-When you :ref:`build with TF-M<ug_tfm>`, `PSA Certified Crypto API`_ v1.0 is implemented.
-Otherwise, when you build without TF-M, v1.2 of the API is used.
+Enabling PSA Crypto API
+***********************
 
-.. psa_crypto_support_tfm_build_end
+To enable the use of PSA Crypto API in your application, enable the following Kconfig options depending on the implementation you want to use:
 
-This page covers the configurations available when using the :ref:`nrf_security_drivers` compatible with the PSA Crypto API.
-If you work with the legacy crypto toolbox, see :ref:`legacy_crypto_support`.
+* For the :ref:`Oberon PSA Crypto implementation <ug_crypto_architecture_implementation_standards_oberon>`, enable the :kconfig:option:`CONFIG_NRF_SECURITY` Kconfig option.
+* For the :ref:`TF-M Crypto Service implementation <ug_crypto_architecture_implementation_standards_tfm>`, enable the :kconfig:option:`CONFIG_NRF_SECURITY` Kconfig option together with the :kconfig:option:`CONFIG_BUILD_WITH_TFM` Kconfig option.
+  For more information, see :ref:`ug_tfm_building_secure_services`.
 
-.. _nrf_security_drivers_config_single:
+.. _psa_crypto_support_single_driver:
 
 Configuring single drivers
 **************************
@@ -64,7 +66,7 @@ The nrf_oberon driver may then be disabled by using the Kconfig option :kconfig:
    On 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` Kconfig option when the Zephyr entropy driver is enabled.
 
-.. _nrf_security_drivers_config_multiple:
+.. _psa_crypto_support_multiple_drivers:
 
 Configuring multiple drivers
 ****************************
@@ -106,3 +108,12 @@ You can enable a cryptographic feature or algorithm using `CONFIG_PSA_WANT_*`_ K
 For example, to enable the AES algorithm, set the :kconfig:option:`CONFIG_PSA_WANT_ALG_AES` Kconfig option.
 
 For a list of supported cryptographic features and algorithms and the Kconfig options to enable them, see :ref:`ug_crypto_supported_features`.
+
+Building PSA Crypto API
+***********************
+
+Depending on the implementation you are using, the |NCS| build system uses different versions of the PSA Crypto API.
+
+.. ncs-include:: ../psa_certified_api_overview.rst
+   :start-after: psa_crypto_support_tfm_build_start
+   :end-before: psa_crypto_support_tfm_build_end
diff --git a/doc/nrf/security/crypto/drivers.rst b/doc/nrf/security/crypto/drivers.rst
@@ -40,8 +40,8 @@ The following figure shows the Oberon PSA Crypto implementation with the cryptog
 
 .. psa_crypto_driver_table_start
 
-The PSA Crypto implementations in the |NCS| use different driver libraries depending on hardware capabilities and user configuration.
-They are organized into hardware and software drivers, with hardware drivers taking precedence over software drivers, which provide fallback options.
+The cryptographic drivers are organized into hardware and software drivers.
+Hardware drivers take precedence over software drivers, which provide fallback options in case the hardware drivers are not available for a given cryptographic operation for a given hardware platform.
 
 .. list-table:: PSA Crypto drivers in the |NCS|
    :widths: auto
@@ -173,7 +173,7 @@ The following table provides an overview of the available directives and their c
 
 .. note::
 
-   For the complete overview of the available configuration options, see the :ref:`psa_crypto_support` page.
+   For the complete overview of the available configuration options, see the :ref:`ug_crypto_supported_features` page.
 
 The nRF Security subsystem checks the directives (set through the Kconfig options) to make the optimal driver selection.
 The subsystem combines the ``PSA_WANT_*`` and ``PSA_USE_*`` settings in Kconfig to make the appropriate driver selection for the cryptographic operation:
@@ -216,7 +216,7 @@ At the same time, it ensures all cryptographic operations are supported across d
 Driver chaining in the |NCS|
 ----------------------------
 
-Driver chaining is handled in the |NCS| in runtime when you :ref:`enable multiple drivers at the same time <nrf_security_drivers_config_multiple>` and then enable specific :ref:`nrf_oberon driver features in combination with driver features for hardware acceleration <nrf_security_drivers_config_features>`.
+Driver chaining is handled in the |NCS| in runtime when you :ref:`enable multiple drivers at the same time <psa_crypto_support_multiple_drivers>` and then enable specific :ref:`nrf_oberon driver features in combination with driver features for hardware acceleration <nrf_security_drivers_config_features>`.
 
 Common driver chains supported in the nrf_oberon driver include the following cases:
 
@@ -292,7 +292,7 @@ nrf_cc3xx driver configuration
 
 For configuration details, see the following pages:
 
-* :ref:`nrf_security_driver_config` (both drivers)
+* :ref:`psa_crypto_support` (both drivers)
 * :ref:`nrf_security_legacy_backend_config` (:ref:`nrf_cc3xx_mbedcrypto_readme` used as legacy backend)
 
 .. note::
@@ -324,7 +324,7 @@ For more information about both the driver and the hardware peripheral, see :ref
 CRACEN driver configuration
 ---------------------------
 
-For configuration details, see :ref:`nrf_security_driver_config`.
+For configuration details, see :ref:`psa_crypto_support`.
 
 .. _crypto_drivers_oberon:
 .. _nrf_security_drivers_oberon:
@@ -381,7 +381,7 @@ nrf_oberon driver configuration
 
 For configuration details, see the following pages:
 
-* :ref:`nrf_security_driver_config`
+* :ref:`psa_crypto_support`
 * :ref:`nrf_security_legacy_backend_config` (nrf_oberon used as legacy backend)
 
 API documentation
diff --git a/doc/nrf/security/crypto/index.rst b/doc/nrf/security/crypto/index.rst
@@ -24,4 +24,5 @@ For more information about PSA Crypto within the broader context of the PSA Cert
 
    crypto_architecture
    drivers
+   driver_config
    crypto_supported_features
diff --git a/doc/nrf/security/psa_certified_api_overview.rst b/doc/nrf/security/psa_certified_api_overview.rst
@@ -85,7 +85,7 @@ For definitions of the PSA Crypto API functions, see `crypto.h`_.
 Among the advantages of the PSA Crypto API are the following:
 
 * The PSA Crypto API is a single API for all cryptographic drivers, which means that you can use the same functions for the nRF52840, nRF5340, nRF54L15, and nRF9160 devices, as well as future ones.
-  The API will work for applications with and without Trusted Firmware-M.
+  The API will work for applications with and without Trusted Firmware-M (TF-M).
 
 * The PSA Crypto API will automatically select cryptographic libraries based on project configurations.
   This way, the codebase for cryptography can easily be reused across multiple projects.
@@ -94,10 +94,12 @@ The PSA Crypto API is designed to be safe, lowering developers' possibility of i
 For example, the functions in the PSA Crypto API use opaque `Key Identifiers`_ to handle keys, so developers do not have to handle keys manually.
 See `Keystore Interface`_ for an overview.
 
+.. _ug_psa_certified_api_overview_crypto_ncs:
+
 PSA Crypto API in the |NCS|
 ===========================
 
-The Crypto API is used to request cryptographic operations in the |NCS|.
+The PSA Crypto API is used to request cryptographic operations in the |NCS|.
 It is mandatory for use in the |NCS|.
 
 Supported operations include the following:
@@ -107,14 +109,36 @@ Supported operations include the following:
 * Authenticated encryption
 * Signature generation and verification
 
+The PSA Crypto API has two implementations in the |NCS|:
+
+* :ref:`Oberon PSA Crypto <ug_crypto_architecture_implementation_standards_oberon>` - which provides a direct PSA Crypto API interface for applications that do not require TF-M.
+* :ref:`TF-M Crypto Service <ug_crypto_architecture_implementation_standards_tfm>`- which provides PSA Crypto API access through TF-M for applications that require enhanced security.
+
+Depending on the implementation you are using, the |NCS| build system uses different versions of the PSA Crypto API.
+
+.. psa_crypto_support_tfm_build_start
+
+.. list-table:: PSA Crypto API versions by implementation
+   :header-rows: 1
+   :widths: auto
+
+   * - Implementation
+     - PSA Crypto API version
+   * - :ref:`Oberon PSA Crypto <ug_crypto_architecture_implementation_standards_oberon>`
+     - `PSA Certified Crypto API`_ v1.2
+   * - :ref:`TF-M Crypto Service <ug_crypto_architecture_implementation_standards_tfm>`
+     - `PSA Certified Crypto API`_ v1.0
+
+.. psa_crypto_support_tfm_build_end
+
+Both implementations in the |NCS| can use different driver libraries, depending on hardware capabilities and user configuration.
+
 .. ncs-include:: crypto/drivers.rst
    :start-after: psa_crypto_driver_table_start
    :end-before: psa_crypto_driver_table_end
 
-See :ref:`nrf_security_drivers` for a list of supported functionalities.
-For specific cryptographic operations, the PSA Crypto API uses :ref:`the library configured <nrf_security_drivers>` for the given operation.
-
-See :ref:`crypto_samples` for usage examples.
+For specific cryptographic operations, the PSA Crypto API uses :ref:`the driver configured <psa_crypto_support>` for the given operation.
+See :ref:`ug_crypto_supported_features` for a list of supported functionalities for each driver and :ref:`crypto_samples` for usage examples.
 
 .. _ug_psa_certified_api_overview_attestation:
 
diff --git a/doc/nrf/security/tfm/tfm_building.rst b/doc/nrf/security/tfm/tfm_building.rst
@@ -7,7 +7,7 @@ Building and configuring TF-M
    :local:
    :depth: 2
 
-TF-M is one of the images that are built as part of a multi-image application.
+TF-M is one of the images that are built as part of a :ref:`multi-image application <ug_tfm_building_secure_services>`.
 
 To add TF-M to your build, enable the :kconfig:option:`CONFIG_BUILD_WITH_TFM` configuration option by adding it to your :file:`prj.conf` file.
 
@@ -29,14 +29,31 @@ The following platforms are currently supported:
 * nRF5340
 * nRF91 Series
 
+.. _ug_tfm_building_secure_services:
+
 Enabling secure services
 ************************
 
-When using the :ref:`nrf_security`, if :kconfig:option:`CONFIG_BUILD_WITH_TFM` is enabled together with :kconfig:option:`CONFIG_NORDIC_SECURITY_BACKEND`, the TF-M secure image will enable the use of the hardware acceleration of Arm CryptoCell.
-In such case, the Kconfig configurations in the Nordic Security Backend control the features enabled through TF-M.
+To enable the secure services in TF-M, you must use the :ref:`TF-M Crypto Service PSA Crypto API implementation <ug_crypto_architecture_implementation_standards_tfm>`.
+
+Complete the following steps to enable the secure services in TF-M:
+
+1. Enable :kconfig:option:`CONFIG_NRF_SECURITY` to enable PSA Crypto APIs through :ref:`nRF Security <nrf_security>`.
+#. Enable the :kconfig:option:`CONFIG_BUILD_WITH_TFM` configuration option by adding it to your :file:`prj.conf` file.
+#. :ref:`Configure PSA Crypto API <psa_crypto_support>` Kconfig options.
+#. Build the application with :ref:`tfm_minimal_build` or :ref:`tfm_configurable_build`.
+
+After building the application, the TF-M secure image enables the use of the hardware acceleration and the Kconfig configurations in the nRF Security subsystem control the features enabled in TF-M.
 
 See :ref:`tfm_partition_crypto` for more information about the TF-M Crypto partition.
 
+.. note::
+   Depending on the implementation you are using, the |NCS| build system uses different versions of the PSA Crypto API.
+
+   .. ncs-include:: ../psa_certified_api_overview.rst
+      :start-after: psa_crypto_support_tfm_build_start
+      :end-before: psa_crypto_support_tfm_build_end
+
 .. _tfm_minimal_build:
 
 Minimal build
diff --git a/doc/nrf/shortcuts.txt b/doc/nrf/shortcuts.txt
