doc: tfm: Add documentation regarding configurable build #19562

SeppoTakalo · 2024-12-16T14:13:58Z

Add documentation regarding CONFIG_TFM_PROFILE_TYPE_NOT_SET and various TF-M partitions that user need to configure.

NOTE: This is very early phase. This work is still in progress, but I'm just starting the review process very early.

NordicBuilder · 2024-12-16T14:18:25Z

CI Information

^{To view the history of this post, clich the 'edited' button above}
Build number: 16

Inputs:

Sources:

sdk-nrf: PR head: e06cb9f1bc53dae4852f3b9dad58d9f4c340eab6

more details

sdk-nrf:

PR head: e06cb9f1bc53dae4852f3b9dad58d9f4c340eab6
merge base: 47c18832e293d6f3e11b91c753ce436e62a46265
target head (main): 47c18832e293d6f3e11b91c753ce436e62a46265
Diff

Github labels

Enabled	Name	Description
	ci-disabled	Disable the ci execution
	ci-all-test	Run all of ci, no test spec filtering will be done
	ci-force-downstream	Force execution of downstream even if twister fails
	ci-run-twister	Force run twister
	ci-run-zephyr-twister	Force run zephyr twister

List of changed files detected by CI (6)

doc
│  ├── nrf
│  │  ├── images
│  │  │  ├── nrf-secure-rom-granularity.svg
│  │  │  │ secure-flash-regions.svg
│  │  ├── links.txt
│  │  ├── releases_and_maturity
│  │  │  ├── migration
│  │  │  │  ├── migration_guide_1.x_to_2.x.rst
│  │  │  │  │ migration_guide_spm_to_tf-m.rst
│  │  ├── security
│  │  │  │ tfm.rst

Outputs:

Toolchain

Version:
Build docker image:

Test Spec & Results: ✅ Success; ❌ Failure; 🟠 Queued; 🟡 Progress; ◻️ Skipped; ⚠️ Quarantine

◻️ Toolchain
◻️ Build twister
◻️ Integration tests

Disabled integration tests

- desktop52_verification
- doc-internal
- test_ble_nrf_config
- test-fw-nrfconnect-apps
- test-fw-nrfconnect-ble_mesh
- test-fw-nrfconnect-ble_samples
- test-fw-nrfconnect-boot
- test-fw-nrfconnect-chip
- test-fw-nrfconnect-fem
- test-fw-nrfconnect-nfc
- test-fw-nrfconnect-nrf-iot_libmodem-nrf
- test-fw-nrfconnect-nrf-iot_lwm2m
- test-fw-nrfconnect-nrf-iot_mosh
- test-fw-nrfconnect-nrf-iot_positioning
- test-fw-nrfconnect-nrf-iot_samples
- test-fw-nrfconnect-nrf-iot_serial_lte_modem
- test-fw-nrfconnect-nrf-iot_thingy91
- test-fw-nrfconnect-nrf-iot_zephyr_lwm2m
- test-fw-nrfconnect-nrf_crypto
- test-fw-nrfconnect-ps
- test-fw-nrfconnect-rpc
- test-fw-nrfconnect-rs
- test-fw-nrfconnect-tfm
- test-fw-nrfconnect-thread
- test-fw-nrfconnect-zigbee
- test-low-level
- test-sdk-audio
- test-sdk-dfu
- test-sdk-find-my
- test-sdk-mcuboot
- test-sdk-pmic-samples
- test-sdk-sidewalk
- test-sdk-wifi
- test-secdom-samples-public

Note: This message is automatically posted and updated by the CI

NordicBuilder · 2024-12-16T14:32:36Z

You can find the documentation preview for this PR at this link. It will be updated about 10 minutes after the documentation build succeeds.

Note: This comment is automatically posted by the Documentation Publish GitHub Action.

MarkusLassila

Some comments. Moving to right direction.

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

doc/nrf/security/tfm.rst

MarkusLassila · 2024-12-27T08:03:28Z

doc/nrf/security/tfm.rst

+   :align: center
+
+   Partition alignment granularity on different nRF devices.
+
 When the :ref:`partition_manager` is enabled, it will take into consideration the alignment requirements.


Partition manager likely warrants its own chapter in here. I would like to at least give the flow of working with partition manager in here:

Minimize your partitions

Copy the partitions.yaml from build directory as static partitions.yaml.

Modify static partitions.yaml (if necessary) (PS and ITS storage can be set more efficiently, reserve enough space for future updates).

MarkusLassila · 2024-12-27T08:10:40Z

doc/nrf/security/tfm.rst

+   :align: center
+
+   Example of aligning partitions with flash regions.
+
 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`` and ``nonsecure_storage``.


tfm_storage also needs to be aligned with this, if it is set after non-secure partition.

doc/nrf/security/tfm.rst

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

doc/nrf/security/tfm.rst

peknis · 2025-01-21T14:43:59Z

More comments/suggestions coming later this week.

doc/nrf/security/tfm.rst

Add documentation regarding CONFIG_TFM_PROFILE_TYPE_NOT_SET and various TF-M partitions that user need to configure. Signed-off-by: Seppo Takalo <[email protected]>

Current user guide does not need this information anymore. It should be moved to a separate migration guide. Signed-off-by: Seppo Takalo <[email protected]>

Move building, configuring and limitations to appear before background information on TF-M user guide. Signed-off-by: Seppo Takalo <[email protected]>

Unfortunately TF-M rst file in Zephyr does not have cross-reference labels. Signed-off-by: Seppo Takalo <[email protected]>

Add diagram to show the granularity differences between each HW. Signed-off-by: Seppo Takalo <[email protected]>

Add usage examples from tfm_ram_report and tfm_rom_report. Signed-off-by: Markus Lassila <[email protected]>

Add information from TF-M partitions: - CONFIG_TFM_PARTITION_PLATFORM - CONFIG_TFM_PARTITION_INTERNAL_TRUSTED_STORAGE - CONFIG_TFM_PARTITION_CRYPTO - CONFIG_TFM_PARTITION_PROTECTED_STORAGE - CONFIG_TFM_PARTITION_INITIAL_ATTESTATION Signed-off-by: Markus Lassila <[email protected]>

Fixes from documentation review Signed-off-by: Seppo Takalo <[email protected]> Co-authored-by: Pekka Niskanen <[email protected]>

melwee01 · 2025-01-24T08:43:08Z

doc/nrf/images/nrf-secure-rom-granularity.svg

These images need to be converted to the unified style in Visio. https://nordicsemi.atlassian.net/wiki/spaces/TECHDOC/pages/120293046/Figure+guide If you prefer, I can do it.

Yes, please.
I don't have a Visio, as it does not exist on Linux.

melwee01 · 2025-01-24T08:45:31Z

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

+#############################################################
+
+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).


Suggested change

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).

This change enhances the security features of the SDK by integrating the more widely adopted TF-M that aligns with the Arm Platform Security Architecture (PSA).

melwee01 · 2025-01-24T08:45:42Z

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

+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.


Suggested change

The migration from SPM to TF-M requires changes in the application code and the partition configuration.

Migration from SPM to TF-M requires changes in the application code and the partition configuration.

melwee01 · 2025-01-24T11:47:03Z

doc/nrf/security/tfm.rst

+Internal Trusted Storage partition
+----------------------------------
+
+To enable Internal Trusted Storage (ITS) partition, set the :kconfig:option:`CONFIG_TFM_PARTITION_INTERNAL_TRUSTED_STORAGE` Kconfig option.


Suggested change

To enable Internal Trusted Storage (ITS) partition, set the :kconfig:option:`CONFIG_TFM_PARTITION_INTERNAL_TRUSTED_STORAGE` Kconfig option.

To enable the Internal Trusted Storage (ITS) partition, set the :kconfig:option:`CONFIG_TFM_PARTITION_INTERNAL_TRUSTED_STORAGE` Kconfig option.

melwee01 · 2025-01-24T11:49:35Z

doc/nrf/security/tfm.rst

+
+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 the 4-byte counter.


Suggested change

The nonce for the AEAD operation is generated by concatenating a random 8-byte seed and an increasing the 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.

Either 'an' or 'the' need to go, but I'm not sure which. It depends. Is the 4-byte counter concatenated?

melwee01 · 2025-01-24T11:56:14Z

doc/nrf/security/tfm.rst

+Protect Storage partition
+-------------------------
+
+To enable Protect Storage (PS) partition, set the :kconfig:option:`CONFIG_TFM_PARTITION_PROTECTED_STORAGE`.


I think 'the' partition for all of these reads better.

melwee01 · 2025-01-24T11:59:20Z

doc/nrf/security/tfm.rst

+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 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.


Suggested change

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.

On 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.

SeppoTakalo added the DNM label Dec 16, 2024

SeppoTakalo requested review from juhaylinen and MarkusLassila December 16, 2024 14:13

github-actions bot added doc-required PR must not be merged without tech writer approval. changelog-entry-required Update changelog before merge. Remove label if entry is not needed or already added. labels Dec 16, 2024

SeppoTakalo force-pushed the tfm_partition_docs branch 3 times, most recently from 426dd6c to 536d653 Compare December 23, 2024 14:04

MarkusLassila reviewed Dec 27, 2024

View reviewed changes

SeppoTakalo force-pushed the tfm_partition_docs branch from 536d653 to e15f633 Compare December 27, 2024 14:08

SeppoTakalo requested a review from melwee01 December 30, 2024 12:40

MarkusLassila force-pushed the tfm_partition_docs branch 2 times, most recently from 82f0ec3 to de44e9e Compare January 20, 2025 11:45

SeppoTakalo marked this pull request as ready for review January 21, 2025 13:03

SeppoTakalo requested review from a team as code owners January 21, 2025 13:03

peknis requested changes Jan 21, 2025

View reviewed changes

SeppoTakalo changed the title ~~WIP: doc: tfm: Add documentation regarding configurable build~~ doc: tfm: Add documentation regarding configurable build Jan 22, 2025

peknis requested changes Jan 22, 2025

View reviewed changes

SeppoTakalo removed the DNM label Jan 22, 2025

SeppoTakalo force-pushed the tfm_partition_docs branch from fd7f2f4 to dc41adb Compare January 22, 2025 08:32

SeppoTakalo added 4 commits January 22, 2025 15:49

doc: tfm: Add documentation regarding configurable build

26dc8f9

Add documentation regarding CONFIG_TFM_PROFILE_TYPE_NOT_SET and various TF-M partitions that user need to configure. Signed-off-by: Seppo Takalo <[email protected]>

doc: tfm: Move SPM migration guide to own page

dd50191

Current user guide does not need this information anymore. It should be moved to a separate migration guide. Signed-off-by: Seppo Takalo <[email protected]>

doc: tfm: Restructure sections

06e450e

Move building, configuring and limitations to appear before background information on TF-M user guide. Signed-off-by: Seppo Takalo <[email protected]>

doc: tfm: Add section about analyzing the size

945e9a7

Unfortunately TF-M rst file in Zephyr does not have cross-reference labels. Signed-off-by: Seppo Takalo <[email protected]>

SeppoTakalo and others added 4 commits January 22, 2025 15:49

doc: tfm: Add diagram to describe granularity

bcba319

Add diagram to show the granularity differences between each HW. Signed-off-by: Seppo Takalo <[email protected]>

doc: tfm: Add tfm_ram_report and tfm_rom_report

fc677a6

Add usage examples from tfm_ram_report and tfm_rom_report. Signed-off-by: Markus Lassila <[email protected]>

doc: tfm: Documentation review fixes

e06cb9f

Fixes from documentation review Signed-off-by: Seppo Takalo <[email protected]> Co-authored-by: Pekka Niskanen <[email protected]>

SeppoTakalo force-pushed the tfm_partition_docs branch from dc41adb to e06cb9f Compare January 22, 2025 13:50

melwee01 reviewed Jan 24, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: tfm: Add documentation regarding configurable build #19562

doc: tfm: Add documentation regarding configurable build #19562

SeppoTakalo commented Dec 16, 2024

NordicBuilder commented Dec 16, 2024 •

edited

Loading

NordicBuilder commented Dec 16, 2024

MarkusLassila left a comment

MarkusLassila Dec 27, 2024

MarkusLassila Dec 27, 2024

peknis commented Jan 21, 2025

melwee01 Jan 24, 2025

SeppoTakalo Jan 24, 2025

melwee01 Jan 24, 2025

melwee01 Jan 24, 2025

melwee01 Jan 24, 2025

melwee01 Jan 24, 2025

melwee01 Jan 24, 2025

melwee01 Jan 24, 2025

	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).
	This change enhances 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.
	Migration from SPM to TF-M requires changes in the application code and the partition configuration.

	To enable Internal Trusted Storage (ITS) partition, set the :kconfig:option:`CONFIG_TFM_PARTITION_INTERNAL_TRUSTED_STORAGE` Kconfig option.
	To enable the Internal Trusted Storage (ITS) partition, set the :kconfig:option:`CONFIG_TFM_PARTITION_INTERNAL_TRUSTED_STORAGE` Kconfig option.


		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 the 4-byte counter.

	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.
	On 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.

doc: tfm: Add documentation regarding configurable build #19562

Are you sure you want to change the base?

doc: tfm: Add documentation regarding configurable build #19562

Conversation

SeppoTakalo commented Dec 16, 2024

NordicBuilder commented Dec 16, 2024 • edited Loading

CI Information

Inputs:

Sources:

Github labels

Outputs:

Toolchain

Test Spec & Results: ✅ Success; ❌ Failure; 🟠 Queued; 🟡 Progress; ◻️ Skipped; ⚠️ Quarantine

NordicBuilder commented Dec 16, 2024

MarkusLassila left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

peknis commented Jan 21, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

NordicBuilder commented Dec 16, 2024 •

edited

Loading