doc: tfm: Documentation review fixes

Fixes from documentation review

Signed-off-by: Seppo Takalo <[email protected]>

Co-authored-by: Pekka Niskanen <[email protected]>

doc/nrf/releases_and_maturity/migration/migration_guide_spm_to_tf-m.rst

@@ -3,8 +3,8 @@
 Migrating from Secure Partition Manager to Trusted Firmware-M
 #############################################################
 
-The Nordic Secure Partition Manager (SPM) was replaced with Trusted Firmware-M (TF-M) as the default trusted execution solution in the nRF Connect SDK 2.1.0.
-This change was made to enhance the security features of the SDK by integrating the more widely adopted TF-M, which aligns with the Arm Platform Security Architecture (PSA).
+The Nordic Secure Partition Manager (SPM) was replaced with Trusted Firmware-M (TF-M) as the default trusted execution solution in the |NCS| v2.1.0.
+This change was made to enhance the security features of the SDK by integrating the more widely adopted TF-M that aligns with the Arm Platform Security Architecture (PSA).
 
 The migration from SPM to TF-M requires changes in the application code and the partition configuration.
 The interface to TF-M is different from the interface to SPM.

doc/nrf/security/tfm.rst

@@ -99,18 +99,20 @@ Instead, the default configuration must be used as a starting point.
 Configurable build
 ==================
 
-The minimal version of TF-M is disabled by setting the :kconfig:option:`CONFIG_TFM_PROFILE_TYPE_NOT_SET` option or one of the other build profiles.
-For description of the build profiles, see Trusted Firmware M documentation regarding :ref:`tf-m_profiles`.
+To disable the minimal version of TF-M, set the :kconfig:option:`CONFIG_TFM_PROFILE_TYPE_NOT_SET` Kconfig option or one of the other build profiles.
+For description of the build profiles, see :ref:`tf-m_profiles`.
 It is not recommended to use predefined TF-M profiles as they might result in a larger memory footprint than necessary.
 
-When :kconfig:option:`CONFIG_TFM_PROFILE_TYPE_NOT_SET` is enabled, the build process will not set a specific
-TF-M profile type. This allows for a more flexible configuration where individual TF-M features can be
-enabled or disabled as needed. This provides more control over the build process and allows for a more
-fine-grained configuration of the TF-M secure image.
+When the :kconfig:option:`CONFIG_TFM_PROFILE_TYPE_NOT_SET` Kconfig option is enabled, the build process will not set a specific TF-M profile type.
+This allows for a more flexible configuration where individual TF-M features can be enabled or disabled as needed.
+It also provides more control over the build process and allows for a more fine-grained configuration of the TF-M secure image.
 
-In order to configure the features of the TF-M secure image, you must choose which TF-M partitions and which secure services to include in the build.
-A "TF-M partition" in this context refers to a secure partition within the Trusted Firmware-M architecture. These partitions are isolated from each other and from the non-secure application code.
-A service running inside TF-M would typically be implemented within one of these secure partitions. Each service can be a separate partition, or multiple related services might be grouped into a single partition. The partition provides the execution environment for the service, handling secure function calls and ensuring that the service's code and data are protected from unauthorized access.
+To configure the features of the TF-M secure image, you must choose which TF-M partitions and which secure services to include in the build.
+A "TF-M partition" in this context refers to a secure partition within the Trusted Firmware-M architecture.
+These partitions are isolated from each other and from the non-secure application code.
+A service running inside TF-M would typically be implemented within one of these secure partitions.
+Each service can be a separate partition, or multiple related services might be grouped into a single partition.
+The partition provides the execution environment for the service, handling secure function calls and ensuring that the service's code and data are protected from unauthorized access.
 
 Following are the available Kconfig options for TF-M partitions:
 
@@ -157,16 +159,17 @@ Security Partition Manager (SPM) backend may also be configured, depending on th
      - With IPC each Secure Partition processes signals in any order, and can defer responding to a message while continuing to process other signals.
      - Levels 1, 2 and 3
 
-Amount of logging messages can be controlled by setting the :kconfig:option:`CONFIG_TFM_LOG_LEVEL` option or by setting the :kconfig:option:`CONFIG_TFM_LOG_LEVEL_SILENCE` option to disable logging.
+To control the number of logging messages, set the :kconfig:option:`CONFIG_TFM_LOG_LEVEL` Kconfig option.
+To disable logging, set the :kconfig:option:`CONFIG_TFM_LOG_LEVEL_SILENCE` option.
 
-Size of TF-M partitions are affected by multiple configuration option and hardware related options.
-Code and memory size of TF-M increases as more services are enabled but also selected hardware places limitations on how separation of secure and non-secure are made.
+The size of TF-M partitions is affected by multiple configuration options and hardware-related options.
+The code and memory size of TF-M increases when more services are enabled but also the selected hardware places limitations on how the separation of secure and non-secure is made.
 
-TF-M is linked as a separate partition in the final binary image. The reserved sizes of its RAM and Flash partitions are configured by the :kconfig:option:`CONFIG_PM_PARTITION_SIZE_TFM` and :kconfig:option:`CONFIG_PM_PARTITION_SIZE_TFM_SRAM` options.
-These configuration option allows you to specify the size allocated for the TF-M partition in the final binary image. Default partition sizes vary between device families and are not optimized to any specific use case.
+TF-M is linked as a separate partition in the final binary image.
+The reserved sizes of its RAM and Flash partitions are configured by the :kconfig:option:`CONFIG_PM_PARTITION_SIZE_TFM` and :kconfig:option:`CONFIG_PM_PARTITION_SIZE_TFM_SRAM` options.
+These configuration options allow you to specify the size allocated for the TF-M partition in the final binary image. Default partition sizes vary between device families and are not optimized to any specific use case.
 
-Process to optimize the TF-M size is to first find the minimal set of features to satisfy the application needs and then minimize the allocated partition sizes while still conforming to the alignment and granularity requirements of given hardware.
-See next section for more information about the alignment requirements.
+To optimize the TF-M size, find the minimal set of features to satisfy the application needs and then minimize the allocated partition sizes while still conforming to the alignment and granularity requirements of given hardware.
 
 .. _ug_tfm_partition_alignment_requirements:
 
@@ -214,7 +217,7 @@ But when the static partitions are used, the user is responsible for following t
 
 If you are experiencing any partition alignment issues when using the Partition Manager, check the :ref:`known_issues` page on the main branch.
 
-The partitions which need to be aligned with the TrustZone flash region size are partitions ``tfm_nonsecure``, ``tfm_storage`` and ``nonsecure_storage``.
+You need to align the ``tfm_nonsecure``, ``tfm_storage``, and ``nonsecure_storage`` partitions with the TrustZone flash region size.
 Both the partition start address and the partition size need to be aligned with the flash region size :kconfig:option:`CONFIG_NRF_TRUSTZONE_FLASH_REGION_SIZE`.
 
 Note that the ``tfm_nonsecure`` partition is placed after the ``tfm_secure`` partition, thus the end address of the ``tfm_secure`` partition is the same as the start address of the ``tfm_nonsecure`` partition.
@@ -269,7 +272,7 @@ We will decrease the size of the (optional) ``mcuboot_pad`` partition and thus t
 Analyzing ``tfm_secure`` partition size
 =======================================
 
-The size of the ``tfm_secure`` partition can be analyzed from the build output.
+You can analyze the size of the ``tfm_secure`` partition from the build output:
 
   .. code-block:: console
 
@@ -278,34 +281,35 @@ The size of the ``tfm_secure`` partition can be analyzed from the build output.
         FLASH:       31972 B       256 KB     12.20%
         RAM:         4804 B        88 KB      5.33%
 
-The example above shows that the ``tfm_secure`` partition :kconfig:option:`CONFIG_PM_PARTITION_SIZE_TFM` is set to 256 kB and the TF-M binary uses 32 kB of the available space.
-Similarly the ``tfm_secure`` partition :kconfig:option:`CONFIG_PM_PARTITION_SIZE_TFM_SRAM` is set to 88 kB and the TF-M binary uses 5 kB of the available space.
-This information can be used to optimize the size of the TF-M, as long as it is within the alignment requirements explained in the previous section.
+The example shows that the :kconfig:option:`CONFIG_PM_PARTITION_SIZE_TFM` Kconfig option for the ``tfm_secure`` partition is set to 256 kB and the TF-M binary uses 32 kB of the available space.
+Similarly the :kconfig:option:`CONFIG_PM_PARTITION_SIZE_TFM_SRAM` option for the ``tfm_secure`` partition  is set to 88 kB and the TF-M binary uses 5 kB of the available space.
+You can use this information to optimize the size of the TF-M, as long as it is within the alignment requirements explained in the previous section.
 
 Tools for analyzing the ``tfm_secure`` partition size
 -----------------------------------------------------
 
-TF-M build system provides ``tfm_ram_report`` and ``tfm_rom_report`` targets for analyzing the memory usage of the TF-M partitions inside ``tfm_secure`` partition.
+The TF-M build system provides the ``tfm_ram_report`` and ``tfm_rom_report`` targets for analyzing the memory usage of the TF-M partitions inside the ``tfm_secure`` partition.
 
-With |NCS|, the following commands can be used to generate the reports:
+In the |NCS|, you can use the following commands to generate the reports:
 
-  .. code-block:: console
+.. code-block:: console
 
     west build -p -b nrf9151dk/nrf9151/ns samples/tfm/tfm_hello_world
     cd build/tfm_hello_world
     ninja tfm_ram_report
     ninja tfm_rom_report
 
-Reports can be used to analyze the memory usage of the different TF-M partitions and how changing the Kconfig options affects the memory usage.
+You can use the reports to analyze the memory usage of the different TF-M partitions and see how changing the Kconfig options affects the memory usage.
 For more information about the ``tfm_ram_report`` and ``tfm_rom_report`` targets, refer to the :ref:`tfm_build_system` documentation.
 
 TF-M Partitions
 ===============
 
-CONFIG_TFM_PARTITION_PLATFORM
------------------------------
+Platform partition
+------------------
 
-Platform partition provides platform-specific services to other TF-M partitions and to non-secure application.
+To enable platform partition, set the :kconfig:option:`CONFIG_TFM_PARTITION_PLATFORM` Kconfig option.
+It provides platform-specific services to other TF-M partitions and to a non-secure application.
 
 For the non-secure application, setting the :kconfig:option:`CONFIG_TFM_ALLOW_NON_SECURE_FAULT_HANDLING` Kconfig option enables more detailed error descriptions of faults from the non-secure application with the Zephyr fault handler.
 
@@ -319,15 +323,18 @@ Platform partition also exposes the following |NCS| specific APIs for the non-se
     /* Check if S0 is the active B1 slot. */
     int tfm_platform_s0_active(uint32_t s0_address, uint32_t s1_address, bool *s0_active);
 
-See :ref:`lib_tfm_ioctl_api`: for more information about what APIs are available for the non-secure application.
+See :ref:`lib_tfm_ioctl_api` for more information about APIs available for the non-secure application.
 
 For more information about the general features of the TF-M Platform partition, see `TF-M Platform`_.
 
-CONFIG_TFM_PARTITION_INTERNAL_TRUSTED_STORAGE
----------------------------------------------
+Internal Trusted Storage partition
+----------------------------------
 
-Internal Trusted Storage (ITS) partition implements the PSA Internal Trusted Storage APIs (`PSA Certified Secure Storage API 1.0`_) to achieve confidentiality, authenticity and encryption in rest (optional).
-ITS is meant to be used by the other TF-M partitions. It must not be accessed directly by the non-secure application, instead the :ref:`tfm_partition_ps` should be used.
+To enable Internal Trusted Storage (ITS) partition, set the :kconfig:option:`CONFIG_TFM_PARTITION_INTERNAL_TRUSTED_STORAGE` Kconfig option.
+It implements the PSA Internal Trusted Storage APIs (`PSA Certified Secure Storage API 1.0`_) to achieve confidentiality, authenticity and encryption in rest (optional).
+ITS is meant to be used by the other TF-M partitions.
+It must not be accessed directly by the non-secure application.
+Instead, use the :ref:`tfm_partition_ps`.
 
 For more information about the general features of the TF-M ITS service, see `TF-M ITS`_.
 
@@ -336,33 +343,34 @@ For more information about the general features of the TF-M ITS service, see `TF
 Encrypted ITS
 ~~~~~~~~~~~~~
 
-To enable TF-M ITS encryption, use the Kconfig option :kconfig:option:`CONFIG_TFM_ITS_ENCRYPTED`.
+To enable TF-M ITS encryption, set the :kconfig:option:`CONFIG_TFM_ITS_ENCRYPTED` Kconfig option.
 The ITS encryption is transparent to the user as long as the Master Key Encryption Key (MKEK) is populated before use.
 
-On Nordic Semiconductor devices, the hardware-accelerated AEAD scheme ChaChaPoly1305 is used with a 256 bits key.
+On Nordic Semiconductor devices, the hardware-accelerated AEAD scheme ChaChaPoly1305 is used with a 256-bit key.
 This key is derived with a key derivation function (KDF) based on NIST SP 800-108 CMAC.
 The input key of the KDF is the MKEK, a symmetric key stored in the Key Management Unit (KMU) of Nordic Semiconductor devices.
-The MKEK is protected by the KMU peripheral and its key material cannot be read by software. It can only be used by reference.
+The MKEK is protected by the KMU peripheral and its key material cannot be read by the software.
+It can only be used by reference.
 
 The file ID is used as a derivation label for the KDF.
 This means that each file ID uses a different AEAD key.
 As long as each file has a unique file ID, the key used for encryption and authentication is unique.
 
 To strengthen data integrity, the metadata of the ITS file (creation flags/size) is used as authenticated data in the encryption process.
 
-The nonce for the AEAD operation is generated by concatenating a random 8-byte seed and an increasing 4-byte counter.
+The nonce for the AEAD operation is generated by concatenating a random 8-byte seed and an increasing the 4-byte counter.
 The random seed is generated once in the boot process and stays the same until reset.
 
 .. _tfm_partition_its_sizing:
 
 Sizing the Internal Trusted Storage
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The RAM and Flash usage of the ITS partition are included in the ``tfm_secure`` partition.
+The RAM and flash usage of the ITS partition are included in the ``tfm_secure`` partition.
 The storage itself is a separate ``tfm_its`` partition.
 
-When using the Partition Manager, the size of the ``tfm_its`` is configured by the :kconfig:option:`CONFIG_PM_PARTITION_SIZE_TFM_INTERNAL_TRUSTED_STORAGE` Kconfig option.
-The resulting partition is visible in ``partitions.yml`` in the build directory:
+When using the Partition Manager, you can configure the size of the ``tfm_its`` with the :kconfig:option:`CONFIG_PM_PARTITION_SIZE_TFM_INTERNAL_TRUSTED_STORAGE` Kconfig option.
+The resulting partition is visible in the :file:`partitions.yml` file in the build directory:
 
 .. code-block:: console
 
@@ -389,23 +397,26 @@ The resulting partition is visible in ``partitions.yml`` in the build directory:
 
 The Partition Manager can only align the start address of the ``tfm_its`` partition with the flash region size (see :ref:`ug_tfm_partition_alignment_requirements`).
 If the size of the ``tfm_its`` does not equal the flash region size, the Partition Manager allocates an additional empty partition to fill the gap.
-See the :ref:`tfm_ps_static_partition` for an example on how to optimize by manually configuring the size of the ``tfm_its`` partition.
+See the :ref:`tfm_ps_static_partition` for an example on how to optimize the size of the ``tfm_its`` partition by manual configuration.
 
 TF-M does not guarantee in build time that the ``tfm_its`` partition can hold the assets that are configured with the :kconfig:option:`CONFIG_TFM_ITS_NUM_ASSETS` and :kconfig:option:`CONFIG_TFM_ITS_MAX_ASSET_SIZE` options.
-Depending on the available flash size, ITS can use one or two flash pages (4KB) for ensuring power failure safe operations.
-In addition, ITS stores the bookkeeping information for the assets in the flash and the bookkeeping size scales with the configured number of assets. This can leave a surprisingly small amount of space for the actual assets.
+Depending on the available flash size, ITS can use one or two flash pages (4 KB) for ensuring power failure safe operations.
+In addition, ITS stores the bookkeeping information for the assets in the flash memory and the bookkeeping size scales with the configured number of assets.
+This can leave a very small amount of space for the actual assets.
 
 It is recommended to test the ITS with the intended assets to ensure that the assets fit in the available space.
 
 .. _tfm_partition_crypto:
 
-CONFIG_TFM_PARTITION_CRYPTO
----------------------------
+Crypto partition
+----------------
 
-Crypto partition implements the PSA Crypto APIs (`PSA Certified Crypto API`_). It provides cryptographic services to other TF-M partitions and to the non-secure application.
+To enable crypto partition, set the :kconfig:option:`CONFIG_TFM_PARTITION_CRYPTO` Kconfig option.
+It implements the PSA Crypto APIs (`PSA Certified Crypto API`_) and provides cryptographic services to other TF-M partitions and to the non-secure application.
 
-Partition can be directly configured by using the ``CONFIG_TFM_CRYPTO_*`` Kconfig options found in file :file:`zephyr/modules/trusted-firmware-m/Kconfig.tfm.crypto_modules`.
-However, it is recommended to use the ``CONFIG_PSA_WANT_*`` Kconfig options to enable the required algorithms and key types. These will enable the required ``CONFIG_TFM_CRYPTO_*`` Kconfig options.
+You can configure the partition directly using the ``CONFIG_TFM_CRYPTO_*`` Kconfig options found in the :file:`zephyr/modules/trusted-firmware-m/Kconfig.tfm.crypto_modules` file.
+However, it is recommended to use the ``CONFIG_PSA_WANT_*`` Kconfig options to enable the required algorithms and key types.
+These will enable the required ``CONFIG_TFM_CRYPTO_*`` Kconfig options.
 
 TF-M utilizes :ref:`hardware unique keys <lib_hw_unique_key>` when the PSA Crypto key derivation APIs are used, and ``psa_key_derivation_setup`` is called with the algorithm ``TFM_CRYPTO_ALG_HUK_DERIVATION``.