From dc41adb95a82ce90f5be532d10a2a04b5b1dc0b9 Mon Sep 17 00:00:00 2001 From: Seppo Takalo Date: Wed, 22 Jan 2025 09:42:54 +0200 Subject: [PATCH] doc: tfm: Documentation review fixes Fixes from documentation review Signed-off-by: Seppo Takalo Co-authored-by: Pekka Niskanen <73991005+peknis@users.noreply.github.com> --- .../migration/migration_guide_spm_to_tf-m.rst | 4 +- doc/nrf/security/tfm.rst | 203 ++++++++++-------- 2 files changed, 114 insertions(+), 93 deletions(-) diff --git a/doc/nrf/releases_and_maturity/migration/migration_guide_spm_to_tf-m.rst b/doc/nrf/releases_and_maturity/migration/migration_guide_spm_to_tf-m.rst index 4f50001dd4c4..6988fb219319 100644 --- a/doc/nrf/releases_and_maturity/migration/migration_guide_spm_to_tf-m.rst +++ b/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. diff --git a/doc/nrf/security/tfm.rst b/doc/nrf/security/tfm.rst index cda244dc7f8f..8823d84adfbc 100644 --- a/doc/nrf/security/tfm.rst +++ b/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,13 +343,14 @@ 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. @@ -350,7 +358,7 @@ As long as each file has a unique file ID, the key used for encryption and authe 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: @@ -358,11 +366,11 @@ The random seed is generated once in the boot process and stays the same until r 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 ` when the PSA Crypto key derivation APIs are used, and ``psa_key_derivation_setup`` is called with the algorithm ``TFM_CRYPTO_ALG_HUK_DERIVATION``. @@ -413,26 +424,31 @@ For more information about the general features of the Crypto partition, see `TF .. _tfm_partition_ps: -CONFIG_TFM_PARTITION_PROTECTED_STORAGE --------------------------------------- +Protect Storage partition +------------------------- -Protect Storage (PS) partition implements the PSA Protected Storage APIs (`PSA Certified Secure Storage API 1.0`_). -PS partition utilizes ITS partition to achieve confidentiality and authenticity. In addition, PS provides encryption in rest, authentication and rollback protection. +To enable Protect Storage (PS) partition, set the :kconfig:option:`CONFIG_TFM_PARTITION_PROTECTED_STORAGE`. -The non-secure application should use the PS for storing sensitive data. +It implements the PSA Protected Storage APIs (`PSA Certified Secure Storage API 1.0`_). +PS partition uses ITS partition to achieve confidentiality and authenticity. +In addition, PS provides encryption in rest, authentication and rollback protection. + +A non-secure application should use the PS for storing sensitive data. For more information about the general features of the TF-M PS partition, see `TF-M PS`_. Sizing the Protected Storage ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The RAM and Flash usage of the PS partition are included in the ``tfm_secure`` partition. -The storage itself is a separate ``tfm_ps`` partition. Additionally, the PS partition requires non-volatile counters for rollback protection. Those are stored in the ``tfm_otp_nv_counters`` partition. +The RAM and flash usage of the PS partition are included in the ``tfm_secure`` partition. +The storage itself is a separate ``tfm_ps`` partition. +Additionally, the PS partition requires non-volatile counters for rollback protection. +Those are stored in the ``tfm_otp_nv_counters`` partition. -When using the Partition Manager, the size of the ``tfm_ps`` is configured by the :kconfig:option:`CONFIG_PM_PARTITION_SIZE_TFM_PROTECTED_STORAGE` Kconfig option. -And the size of the ``tfm_otp_nv_counters`` is configured by the :kconfig:option:`CONFIG_PM_PARTITION_SIZE_TFM_OTP_NV_COUNTERS` Kconfig option. +When using the Partition Manager, the size of the ``tfm_ps`` is configured with the :kconfig:option:`CONFIG_PM_PARTITION_SIZE_TFM_PROTECTED_STORAGE` Kconfig option. +The size of the ``tfm_otp_nv_counters`` is configured with the :kconfig:option:`CONFIG_PM_PARTITION_SIZE_TFM_OTP_NV_COUNTERS` Kconfig option. -Resulting partitions are visible in the ``partitions.yml`` in the build directory: +Resulting partitions are visible in the :file:`partitions.yml` file in the build directory: .. code-block:: console @@ -477,14 +493,17 @@ Resulting partitions are visible in the ``partitions.yml`` in the build director region: flash_primary size: 0x4000 -Similarly to :ref:`tfm_partition_its_sizing` the Partition Manager can only align the start addresses of the partitions with the flash region size. -Partition Manager allocates an additional empty partition to fill the gaps. +Similarly to :ref:`tfm_partition_its_sizing`, the Partition Manager can only align the start addresses of the partitions with the flash region size. +The Partition Manager allocates an additional empty partition to fill the gaps. -See the :ref:`tfm_ps_static_partition` for an example on how to optimize by manually configuring the size of the partitions. +See :ref:`tfm_ps_static_partition` for an example on how to optimize the size of the partitions by manual configuration. TF-M does not guarantee in build time that the ``tfm_ps`` partition can hold the assets that are configured with the :kconfig:option:`CONFIG_TFM_PS_NUM_ASSETS` and :kconfig:option:`CONFIG_TFM_PS_MAX_ASSET_SIZE` options. -PS uses ITS internally to store the assets in ``tfm_ps``. This means that some of the flash space is reserved for ITS functionality. Additionally PS stores the file metadata in object tables, which also consumes flash space. Object table size scales with the number of configured assets and two object tables (old and new) are required when performing PS operations. -This can leave a surprisingly small amount of space for the actual assets. +PS uses ITS internally to store the assets in ``tfm_ps``. +This means that some of the flash space is reserved for the ITS functionality. +Additionally, PS stores the file metadata in object tables, which also consumes flash space. +Object table size scales with the number of configured assets and two object tables (old and new) are required when performing PS operations. +This can leave a very small amount of space for the actual assets. It is highly recommended to test the PS with the intended assets to ensure that the assets fit in the available space. @@ -493,10 +512,10 @@ It is highly recommended to test the PS with the intended assets to ensure that Example of PS sizing with static partitions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -With devices where ROM granularity is higher than the flash page size (nRF53 Series and nRF91 Series), it can make sense to configure the ``tfm_its``, ``tfm_ps`` and ``tfm_otp_nv_counters`` partitions as static partitions. +With devices where ROM granularity is higher than the flash page size (nRF53 Series and nRF91 Series), it might be useful to configure the ``tfm_its``, ``tfm_ps`` and ``tfm_otp_nv_counters`` partitions as static partitions. -You can start by copying the default configuration from the ``partitions.yml`` file in the build directory as the ``pm_static.yml`` file in the application directory. -The following snippet shows the meaningful parts of the default configuration for the ``tfm_its``, ``tfm_ps`` and ``tfm_otp_nv_counters`` partitions for the nRF9151: +You can start by copying the default configuration from the :file:`partitions.yml` file in the build directory as the :file:`pm_static.yml` file in the application directory. +The following snippet shows the meaningful parts of the default configuration for the ``tfm_its``, ``tfm_ps`` and ``tfm_otp_nv_counters`` partitions in the nRF9151 SoC: .. code-block:: console @@ -584,8 +603,8 @@ The following snippet shows the meaningful parts of the default configuration fo size: 0x14000 span: *id006 -The requirement is that the ``tfm_storage`` partition, which holds the ``tfm_its``, ``tfm_ps`` and ``tfm_otp_nv_counters`` partitions, must be aligned with the flash region size, so that we can configure it as secure. -After removing the empty partitions, unnecessary alignments and adjusting the sizes of the partitions, the same information in ``pm_static.yml`` file should look like this: +The ``tfm_storage`` partition that holds the ``tfm_its``, ``tfm_ps`` and ``tfm_otp_nv_counters`` partitions must be aligned with the flash region size, so that you can configure it as secure. +After removing the empty partitions, unnecessary alignments and adjusting the sizes of the partitions, the same information in the :file:`pm_static.yml` file should look like this: .. code-block:: console @@ -638,13 +657,15 @@ The available space for the non-secure application has increased by 0x10000 byte .. note:: - With the devices that are intended to production and meant to be updated in the field, you should always use static partitions to ensure that the partitions are not moved around in the flash memory. + With devices that are intended for production and meant to be updated in the field, you should always use static partitions to ensure that the partitions are not moved around in the flash memory. -CONFIG_TFM_PARTITION_INITIAL_ATTESTATION ----------------------------------------- +Initial Attestation partition +----------------------------- -Initial Attestation partition implements the PSA Initial Attestation APIs (`PSA Certified Attestation API 1.0`_). -It allows the device to prove its identity to a remote entity. The :ref:`tfm_psa_template` sample demonstrates how to use the Initial Attestation partition. +To enable Initial Attestation partition, set the :kconfig:option:`CONFIG_TFM_PARTITION_INITIAL_ATTESTATION` Kconfig option. +It implements the PSA Initial Attestation APIs (`PSA Certified Attestation API 1.0`_). +It allows the device to prove its identity to a remote entity. +The :ref:`tfm_psa_template` sample demonstrates how to use the Initial Attestation partition. The Initial Attestation partition is not enabled by default. Unless you need attestation, it is recommended to keep it disabled. @@ -653,17 +674,17 @@ For more information about the general features of the TF-M Initial Attestation Provisioning ************ -For the devices that need provisioning, TF-M implements the following Platform Root of Trust (PRoT) Security Lifecycle states that conform to the `ARM Platform Security Model 1.1`_: +For devices that need provisioning, TF-M implements the following Platform Root of Trust (PRoT) Security Lifecycle states that conform to the `ARM Platform Security Model 1.1`_: * Device Assembly and Test * PRoT Provisioning * Secured The device starts in the **Device Assembly and Test** state. -The :ref:`provisioning_image` sample shows how to move the device from the **Device Assembly and Test** state to the **PRoT Provisioning** state, and how to provision the device with hardware unique keys (HUKs) and an identity key. +The :ref:`provisioning_image` sample shows how to switch the device from the **Device Assembly and Test** state to the **PRoT Provisioning** state, and how to provision the device with hardware unique keys (HUKs) and an identity key. -To move the device from the **PRoT Provisioning** state to the **Secured** state, set the :kconfig:option:`CONFIG_TFM_NRF_PROVISIONING` Kconfig option for your application. -In the first boot, TF-M will ensure that the keys are stored in the Key Management Unit (KMU) and move the device to the **Secured** state. +To switch the device from the **PRoT Provisioning** state to the **Secured** state, set the :kconfig:option:`CONFIG_TFM_NRF_PROVISIONING` Kconfig option for your application. +In the first boot, TF-M ensures that the keys are stored in the Key Management Unit (KMU) and switches the device to the **Secured** state. The :ref:`tfm_psa_template` sample shows how to achieve this. .. _ug_tfm_manual_VCOM_connection: @@ -673,40 +694,40 @@ Logging TF-M employs two UART interfaces for logging: one for the secure part (MCUboot and TF-M), and one for the non-secure application. By default, the logs arrive on different COM ports on the host PC. -See the :ref:`ug_tfm_manual_VCOM_connection` for more details. +See :ref:`ug_tfm_manual_VCOM_connection` for more details. -Alternatively, you can configure the TF-M to connect to the same UART as the application by using the :kconfig:option:`CONFIG_TFM_SECURE_UART0` Kconfig option. +Alternatively, you can configure the TF-M to connect to the same UART as the application with the :kconfig:option:`CONFIG_TFM_SECURE_UART0` Kconfig option. Setting this Kconfig option makes TF-M logs visible on the application's VCOM, without manual connection. The UART instance used by the application is ``0`` by default, and the TF-M UART instance is ``1``. -By using the :kconfig:option:`CONFIG_TFM_SECURE_UART0`. the TF-M UART instance becomes the same as that of the application's. +To change the TF-M UART instance to the same as that of the application's, use the :kconfig:option:`CONFIG_TFM_SECURE_UART0` Kconfig option. .. note:: - When the TF-M and application use the same UART, the TF-M will disable logging after it has booted and it will only re-enable it again to log a fatal error. + When the TF-M and application use the same UART, the TF-M disables logging after it has booted and it re-enables it again only to log a fatal error. Manual connection to Virtual COM ports on the nRF5340 DK ========================================================= By default, the nRF5340 DK v1.0.0 requires that you connect specific wires on the kit to receive secure logs on the host PC. Specifically, wire the pins **P0.25** and **P0.26** of the **P2** connector to **RxD** and **TxD** of the **P24** connector respectively. -See :ref:`logging_cpunet` on the Working with nRF5340 DK page for more information. +See :ref:`logging_cpunet` for more information. -On the nRF5340 DK v2.0.0, there are only two virtual COM ports available. +On the nRF5340 DK v2.0.0, only two virtual COM ports are available. By default, one of the ports is used by the non-secure UART0 peripheral from the application and the other by the UART1 peripheral from the network core. There are several options to get UART output from the secure TF-M: * Disable the output for the network core and change the pins used by TF-M. - The network core will usually have an |NCS| child image. - To configure a child image, see Configuration of the child image section described in :ref:`ug_nrf5340_multi_image`. + The network core usually has a child image. + For instructions on how to configure a child image, see :ref:`ug_nrf5340_multi_image`. To configure logging in an |NCS| image, see :ref:`ug_logging`. - To change the pins used by TF-M, the RXD (:kconfig:option:`CONFIG_TFM_UART1_RXD_PIN`) and TXD (:kconfig:option:`CONFIG_TFM_UART1_TXD_PIN`) Kconfig options in the application image can be set to **P1.00** (32) and **P1.01** (33). + To change the pins used by TF-M, set the RXD (:kconfig:option:`CONFIG_TFM_UART1_RXD_PIN`) and TXD (:kconfig:option:`CONFIG_TFM_UART1_TXD_PIN`) Kconfig options in the application image to **P1.00** (32) and **P1.01** (33). -* The secure and non-secure UART peripherals can be wired to the same pins. +* You can wire the secure and non-secure UART peripherals to the same pins. Specifically, physically wire together the pins **P0.25** and **P0.26** to **P0.20** and **P0.22**, respectively. -* If the non-secure application, network core and TF-M outputs are all needed simultaneously, additional UART <-> USB hardware is needed. - A second nRF DK can be used if available. - Pin **P0.25** needs to be wired to the TXD pin, and **P0.26** to the RXD pin of the external hardware. - These pins will provide the secure TF-M output, while the two native COM ports of the DK will be used for the non-secure application and the network core output. +* If the non-secure application, network core, and TF-M outputs are all needed simultaneously, additional UART <-> USB hardware is needed. + You can use a second DK if available. + Connect the **P0.25** pin to the TXD pin, and **P0.26** to the RXD pin of the external hardware. + These pins provide the secure TF-M output, while the two native COM ports of the DK are used for the non-secure application and the network core output.