diff --git a/doc/nrf/links.txt b/doc/nrf/links.txt index 6f71ee44abae..a74a3d5ae4ee 100644 --- a/doc/nrf/links.txt +++ b/doc/nrf/links.txt @@ -221,6 +221,8 @@ .. _`PSA Certified Crypto API 1.2.1`: https://arm-software.github.io/psa-api/crypto/1.2/ .. _`PSA Certified Crypto API 1.2 PAKE Extension Final 1`: https://arm-software.github.io/psa-api/crypto/1.2/ext-pake/ .. _`PSA functions for key management`: https://arm-software.github.io/psa-api/crypto/1.1/api/keys/management.html +.. _`PSA Certified Secure Storage API 1.0`: https://arm-software.github.io/psa-api/storage/1.0/ +.. _`PSA Certified Attestation API 1.0`: https://arm-software.github.io/psa-api/attestation/1.0/ .. _`Memfault WebBluetooth Client`: https://memfault.github.io/web-ble-example/ @@ -472,7 +474,11 @@ .. _`TF-M documentation`: https://docs.nordicsemi.com/bundle/ncs-latest/page/tfm/index.html .. _`TF-M secure partition integration guide`: https://docs.nordicsemi.com/bundle/ncs-latest/page/tfm/integration_guide/services/tfm_secure_partition_addition.html +.. _`TF-M Platform`: https://docs.nordicsemi.com/bundle/ncs-latest/page/tfm/integration_guide/services/tfm_platform_integration_guide.html .. _`TF-M ITS`: https://docs.nordicsemi.com/bundle/ncs-latest/page/tfm/integration_guide/services/tfm_its_integration_guide.html +.. _`TF-M Crypto`: https://docs.nordicsemi.com/bundle/ncs-latest/page/tfm/integration_guide/services/tfm_crypto_integration_guide.html +.. _`TF-M PS`: https://docs.nordicsemi.com/bundle/ncs-latest/page/tfm/integration_guide/services/tfm_ps_integration_guide.html +.. _`TF-M Attestation`: https://docs.nordicsemi.com/bundle/ncs-latest/page/tfm/integration_guide/services/tfm_attestation_integration_guide.html .. _`HCI Events`: https://docs.nordicsemi.com/bundle/ncs-latest/page/nrfxlib/softdevice_controller/doc/api.html#hci_events diff --git a/doc/nrf/security/tfm.rst b/doc/nrf/security/tfm.rst index ea58f088f8b2..7eaed969f63f 100644 --- a/doc/nrf/security/tfm.rst +++ b/doc/nrf/security/tfm.rst @@ -78,10 +78,7 @@ 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. -You can configure what crypto modules to include in TF-M by using the ``CONFIG_TFM_CRYPTO_*`` Kconfig options found in file :file:`zephyr/modules/trusted-firmware-m/Kconfig.tfm.crypto_modules`. - -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``. -For more information about the PSA cryptography and the API, see `PSA Certified Crypto API`_. +See :ref:`tfm_partition_crypto` for more information about the TF-M Crypto partition. .. _tfm_minimal_build: @@ -145,8 +142,6 @@ Following are the available Kconfig options for TF-M partitions: - Disabled - CRYPTO -When cryptographic services are enabled, you can configure what crypto modules to include in TF-M by using the ``CONFIG_TFM_CRYPTO_*`` Kconfig options as explained above. - Security Partition Manager (SPM) backend may also be configured, depending on the isolation requirements of the application. .. list-table:: SPM backends @@ -296,22 +291,47 @@ With |NCS|, the following commands can be used to generate the reports: .. 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 + 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. For more information about the ``tfm_ram_report`` and ``tfm_rom_report`` targets, refer to the :ref:`tfm_build_system` documentation. -.. _tfm_encrypted_its: +TF-M Partitions +=============== -Encrypted ITS -************* +CONFIG_TFM_PARTITION_PLATFORM +----------------------------- + +Platform partition provides platform-specific services to other TF-M partitions and to 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. + +Platform partition also exposes the following |NCS| specific APIs for the non-secure application: + + .. code-block:: c + + /* Search for the fw_info structure in firmware image located at address. */ + int tfm_platform_firmware_info(uint32_t fw_address, struct fw_info *info); + + /* Check if S0 is the active B1 slot. */ + int tfm_platform_s0_active(uint32_t s0_address, uint32_t s1_address, bool *s0_active); + +CONFIG_TFM_PARTITION_INTERNAL_TRUSTED_STORAGE +--------------------------------------------- + +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. -TF-M implements a PSA internal trusted storage (ITS) with encryption and authentication. For more information about the general features of the TF-M ITS service, see `TF-M ITS`_. +.. _tfm_encrypted_its: + +Encrypted ITS +~~~~~~~~~~~~~ + To enable TF-M ITS encryption, use the Kconfig option :kconfig:option:`CONFIG_TFM_ITS_ENCRYPTED`. The ITS encryption is transparent to the user as long as the Master Key Encryption Key (MKEK) is populated before use. @@ -329,6 +349,303 @@ To strengthen data integrity, the metadata of the ITS file (creation flags/size) The nonce for the AEAD operation is generated by concatenating a random 8-byte seed and an increasing 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 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: + +.. code-block:: console + + EMPTY_2: + address: 0xea000 + end_address: 0xf0000 + placement: + after: + - tfm_its + region: flash_primary + size: 0x6000 + tfm_its: + address: 0xe8000 + end_address: 0xea000 + inside: + - tfm_storage + placement: + align: + start: 0x8000 + before: + - tfm_otp_nv_counters + region: flash_primary + size: 0x2000 + +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. + +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 uses can use one or two flash pages (4096 bytes) for ensuring power failure safe operations. +In addition, ITS stores the bookkeeping information for the assets in the flash. Bookkeeping size scales with the configured number of assets. This can leave a surprisingly 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 implements the PSA Crypto APIs (`PSA Certified Crypto API`_). It 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. + +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``. + +For more information about the general features of the Crypto partition, see `TF-M Crypto`_. + +.. _tfm_partition_ps: + +CONFIG_TFM_PARTITION_PROTECTED_STORAGE +-------------------------------------- + +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. + +The 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. + +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. + +Resulting partitions are visible in ``partitions.yml`` in the build directory: + +.. code-block:: console + + EMPTY_0: + address: 0xfc000 + end_address: 0x100000 + placement: + after: + - tfm_ps + region: flash_primary + size: 0x4000 + EMPTY_1: + address: 0xf2000 + end_address: 0xf8000 + placement: + after: + - tfm_otp_nv_counters + region: flash_primary + size: 0x6000 + tfm_otp_nv_counters: + address: 0xf0000 + end_address: 0xf2000 + inside: + - tfm_storage + placement: + align: + start: 0x8000 + before: + - tfm_ps + region: flash_primary + size: 0x2000 + tfm_ps: + address: 0xf8000 + end_address: 0xfc000 + inside: + - tfm_storage + placement: + align: + start: 0x8000 + before: + - end + 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. + +See the :ref:`tfm_ps_static_partition` for an example on how to optimize by manually configuring the size of the partitions. + +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. + +It is highly recommended to test the PS with the intended assets to ensure that the assets fit in the available space. + +.. _tfm_ps_static_partition: + +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. + +You can start by copying the default configuration from the ``partitions.yml`` file in the build directory to 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: + +.. code-block:: console + + EMPTY_0: + address: 0xfc000 + end_address: 0x100000 + placement: + after: + - tfm_ps + region: flash_primary + size: 0x4000 + EMPTY_1: + address: 0xf2000 + end_address: 0xf8000 + placement: + after: + - tfm_otp_nv_counters + region: flash_primary + size: 0x6000 + EMPTY_2: + address: 0xea000 + end_address: 0xf0000 + placement: + after: + - tfm_its + region: flash_primary + size: 0x6000 + app: + address: 0x40000 + end_address: 0xe8000 + region: flash_primary + size: 0xa8000 + tfm_nonsecure: + address: 0x40000 + end_address: 0xe8000 + orig_span: &id004 + - app + region: flash_primary + size: 0xa8000 + span: *id004 + tfm_its: + address: 0xe8000 + end_address: 0xea000 + inside: + - tfm_storage + placement: + align: + start: 0x8000 + before: + - tfm_otp_nv_counters + region: flash_primary + size: 0x2000 + tfm_otp_nv_counters: + address: 0xf0000 + end_address: 0xf2000 + inside: + - tfm_storage + placement: + align: + start: 0x8000 + before: + - tfm_ps + region: flash_primary + size: 0x2000 + tfm_ps: + address: 0xf8000 + end_address: 0xfc000 + inside: + - tfm_storage + placement: + align: + start: 0x8000 + before: + - end + region: flash_primary + size: 0x4000 + tfm_storage: + address: 0xe8000 + end_address: 0xfc000 + orig_span: &id006 + - tfm_ps + - tfm_its + - tfm_otp_nv_counters + region: flash_primary + 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: + +.. code-block:: console + + app: + address: 0x40000 + end_address: 0xf8000 + region: flash_primary + size: 0xb8000 + tfm_nonsecure: + address: 0x40000 + end_address: 0xf8000 + orig_span: &id004 + - app + region: flash_primary + size: 0xb8000 + span: *id004 + tfm_its: + address: 0xf8000 + end_address: 0xfa000 + inside: + - tfm_storage + placement: + before: + - tfm_otp_nv_counters + region: flash_primary + size: 0x2000 + tfm_otp_nv_counters: + address: 0xfa000 + end_address: 0xfc000 + inside: + - tfm_storage + placement: + before: + - tfm_ps + region: flash_primary + size: 0x2000 + tfm_storage: + address: 0xf8000 + end_address: 0x100000 + orig_span: &id006 + - tfm_ps + - tfm_its + - tfm_otp_nv_counters + region: flash_primary + size: 0x8000 + span: *id006 + +The ``tfm_storage`` partition is still aligned with the flash region size and the ``tfm_its``, ``tfm_ps`` and ``tfm_otp_nv_counters`` partitions are placed inside it. +The available space for the non-secure application has increased by 0x10000 bytes. + +.. 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. + +CONFIG_TFM_PARTITION_INITIAL_ATTESTATION +---------------------------------------- + +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. + +The Initial Attestation partition is not enabled by default. Unless you need attestation, it is recommended to keep it disabled. + +For more information about the general features of the TF-M Initial Attestation partition, see `TF-M Attestation`_. + Provisioning ************