mirror of
https://github.com/espressif/esp-idf.git
synced 2026-10-02 03:00:34 +03:00
Merge branch 'feature/esp_tee_flash_prot_spi1' into 'master'
feat(esp_tee): Add support for flash memory isolation and protection (SPI1) Closes IDF-10481, IDF-10083, and IDF-8915 See merge request espressif/esp-idf!36454
This commit is contained in:
Mahavir Jain
@@ -100,10 +100,6 @@ External Memory (Flash)
|
||||
|
||||
Designated partitions in the external flash are reserved for the TEE, serving various purposes, including TEE code execution via XIP, secure storage, and OTA data. The PMS safeguards these partitions from unauthorized access, with the APM module protecting the MMU and SPI1 controller registers, and the PMP securing the cache.
|
||||
|
||||
.. note::
|
||||
|
||||
Flash memory protection is under development and will be introduced in the next revision of ESP-TEE.
|
||||
|
||||
.. figure:: ../../../_static/esp_tee/{IDF_TARGET_PATH_NAME}/esp_tee_flash_layout.png
|
||||
:align: center
|
||||
:scale: 80%
|
||||
@@ -112,6 +108,53 @@ Designated partitions in the external flash are reserved for the TEE, serving va
|
||||
|
||||
ESP-TEE: Flash Memory Map for {IDF_TARGET_NAME}
|
||||
|
||||
.. _tee-flash-prot-scope:
|
||||
|
||||
**Flash Protection - Virtual and Physical Access**
|
||||
|
||||
The key interfaces for flash memory protection are the cache connected to SPI0, which provides virtual access to flash memory, and the SPI1 controller, which provides physical access. By default, the cache and the MMU registers are secured by the PMS, preventing virtual access to the TEE-related flash partitions from the REE.
|
||||
|
||||
When :doc:`Flash Encryption <../flash-encryption>` is enabled, the REE can still access TEE flash regions via SPI1, but read operations will return encrypted data. Since neither the REE nor TEE has direct access to the flash encryption key, this prevents attackers from inferring TEE contents through direct reads.
|
||||
|
||||
Additionally with :ref:`Secure Boot <secure_boot-guide>` enabled, any unauthorized modifications to the TEE firmware will be detected during boot, causing signature verification to fail. Thus, the combination of Flash Encryption and Secure Boot provides a robust level of protection suitable for most applications.
|
||||
However, do note that while the TEE firmware integrity is protected, other TEE partitions (e.g., :doc:`Secure Storage <tee-sec-storage>`, :ref:`TEE OTA data <tee-ota-data-partition>`) can be modified through direct writes.
|
||||
|
||||
For stronger isolation, you can enable :ref:`CONFIG_SECURE_TEE_EXT_FLASH_MEMPROT_SPI1`, which completely blocks access to all TEE flash regions via SPI1 for the REE. With this setting, all SPI flash read, write, and erase operations are routed through service calls to the TEE. While this option provides enhanced security, it introduces some performance overhead.
|
||||
|
||||
The table below shows the rough time taken to read and write to a 1MB partition in 256B chunks with :doc:`../../api-reference/storage/partition`, highlighting the impact of ESP-TEE and the :ref:`CONFIG_SECURE_TEE_EXT_FLASH_MEMPROT_SPI1` configuration.
|
||||
|
||||
.. list-table:: Flash Protection: Performance Impact
|
||||
:header-rows: 1
|
||||
|
||||
* - Case
|
||||
- Read (ms)
|
||||
- Read Δ (ms)
|
||||
- Read Δ (%)
|
||||
- Write (ms)
|
||||
- Write Δ (ms)
|
||||
- Write Δ (%)
|
||||
* - ESP-TEE disabled
|
||||
- 262.01
|
||||
- -
|
||||
- -
|
||||
- 3394.23
|
||||
- -
|
||||
- -
|
||||
* - ESP-TEE enabled
|
||||
- 279.86
|
||||
- +17.85
|
||||
- +6.81%
|
||||
- 3415.64
|
||||
- +21.41
|
||||
- +0.63%
|
||||
* - ESP-TEE + SPI1 protected
|
||||
- 359.73
|
||||
- +97.72
|
||||
- +37.33%
|
||||
- 3778.65
|
||||
- +384.42
|
||||
- +11.32%
|
||||
|
||||
Peripherals
|
||||
~~~~~~~~~~~
|
||||
|
||||
@@ -286,31 +329,43 @@ To extend the ESP-TEE framework with custom service calls, follow the steps outl
|
||||
1. Create a Custom Service Call Table
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Define a component for defining custom service calls and create a ``.tbl`` file within the component.
|
||||
Define a component for defining custom service calls and create a ``.yml`` file within the component.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
touch <path/to/tbl/file>/custom_srvcall.tbl
|
||||
touch <path/to/yml/file>/custom_srvcall.yml
|
||||
|
||||
Add your custom service call entries to the ``.tbl`` file in the following format:
|
||||
Add your custom service call entries to the ``.yml`` file in the following format:
|
||||
|
||||
.. code-block:: none
|
||||
.. code-block:: yaml
|
||||
|
||||
<service_call_number> custom <function_name> <arguments_count>
|
||||
secure_services:
|
||||
- family: <api_family>
|
||||
entries:
|
||||
- id: <service_call_number>
|
||||
type: custom
|
||||
function: <function_name>
|
||||
args: <arguments_count>
|
||||
|
||||
**Example Entry**
|
||||
|
||||
.. code-block:: none
|
||||
.. code-block:: yaml
|
||||
|
||||
# SS no. API type Function Args
|
||||
201 custom custom_sec_srv_op 1
|
||||
secure_services:
|
||||
- family: example
|
||||
entries:
|
||||
- id: 300
|
||||
type: custom
|
||||
function: example_sec_serv_aes_op
|
||||
args: 5
|
||||
|
||||
- ``201``: Unique service call number
|
||||
|
||||
- ``300``: Unique service call number
|
||||
- ``custom``: Custom service call type
|
||||
- ``custom_sec_srv_op``: Function name
|
||||
- ``1``: Number of arguments
|
||||
- ``example_sec_serv_aes_op``: Function name
|
||||
- ``5``: Number of arguments
|
||||
|
||||
Ensure that the custom service call numbers does not conflict with the :component_file:`default service call table<esp_tee/scripts/{IDF_TARGET_PATH_NAME}/secure_service.tbl>`. The ESP-TEE framework parses the custom service call table along with the default table to generate relevant header files used in applications.
|
||||
Ensure that the custom service call numbers does not conflict with the :component_file:`default service call table<esp_tee/scripts/{IDF_TARGET_PATH_NAME}/sec_srv_tbl_default.yml>`. The ESP-TEE framework parses the custom service call table along with the default table to generate relevant header files used in applications.
|
||||
|
||||
2. Define the Service Call Implementation
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
@@ -327,7 +382,7 @@ Define the function corresponding to the custom service call in the TEE. This fu
|
||||
return 0;
|
||||
}
|
||||
|
||||
The function name should have the prefix ``_ss_`` before the name and must match the name specified in the ``.tbl`` file.
|
||||
The function name should have the prefix ``_ss_`` before the name and must match the name specified in the ``.yml`` file.
|
||||
|
||||
For reference, all default service call functions are defined in the :component_file:`file<esp_tee/subproject/main/core/esp_secure_services.c>`.
|
||||
|
||||
@@ -342,7 +397,7 @@ Define a CMake file (e.g., ``custom_sec_srv.cmake``) in the component that defin
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
idf_build_set_property(CUSTOM_SECURE_SERVICE_TBL ${CMAKE_CURRENT_LIST_DIR}/custom_srvcall.tbl APPEND)
|
||||
idf_build_set_property(CUSTOM_SECURE_SERVICE_YAML ${CMAKE_CURRENT_LIST_DIR}/custom_srvcall.yml APPEND)
|
||||
|
||||
#. Set the custom component directory and name so that the ``esp_tee`` subproject can use it
|
||||
|
||||
|
||||
@@ -255,8 +255,6 @@ API Reference
|
||||
|
||||
.. note::
|
||||
|
||||
- To use the TEE Attestation APIs into your project, ensure the :component:`tee_attestation <esp_tee/subproject/components/tee_attestation>` component is included by setting ``EXTRA_COMPONENT_DIRS`` in your project's ``CMakeLists.txt`` file, as shown in the :example:`tee_attestation <security/tee/tee_attestation>` example. For more information, refer to the :ref:`optional_project_variable` section from the :doc:`Build System </api-guides/build-system>` documentation.
|
||||
|
||||
- Additionally, the component-specific :component_file:`CMake <esp_tee/subproject/components/tee_attestation/esp_tee_att.cmake>` file needs to be included in the top-level ``CMakeLists.txt`` of your project before calling the ``project()`` command to integrate the corresponding service calls into the project.
|
||||
To use the TEE Attestation APIs in your project, ensure that the :component:`tee_attestation <esp_tee/subproject/components/tee_attestation>` component is listed as a local dependency in the component manager manifest file `idf_component.yml <https://docs.espressif.com/projects/idf-component-manager/en/latest/reference/manifest_file.html>`_. Refer to the :example:`tee_attestation <security/tee/tee_attestation>` example for guidance.
|
||||
|
||||
.. include-build-file:: inc/esp_tee_attestation.inc
|
||||
|
||||
@@ -74,6 +74,6 @@ API Reference
|
||||
|
||||
.. note::
|
||||
|
||||
To use the TEE OTA APIs into your project, ensure the :component:`tee_ota_ops <esp_tee/subproject/components/tee_ota_ops>` component is included by setting ``EXTRA_COMPONENT_DIRS`` in your project's ``CMakeLists.txt`` file, as shown in the :example:`tee_secure_ota <security/tee/tee_secure_ota>` example. For more information, refer to the :ref:`optional_project_variable` section from the :doc:`Build System </api-guides/build-system>` documentation.
|
||||
To use the TEE OTA APIs in your project, ensure that the :component:`tee_ota_ops <esp_tee/subproject/components/tee_ota_ops>` component is listed as a local dependency in the component manager manifest file `idf_component.yml <https://docs.espressif.com/projects/idf-component-manager/en/latest/reference/manifest_file.html>`_. Refer to the :example:`tee_secure_ota <security/tee/tee_secure_ota>` example for guidance.
|
||||
|
||||
.. include-build-file:: inc/esp_tee_ota_ops.inc
|
||||
|
||||
@@ -67,10 +67,6 @@ The TEE Secure Storage feature supports two modes (:ref:`CONFIG_SECURE_TEE_SEC_S
|
||||
|
||||
All the assets pertaining to the TEE secure storage are protected by the APM peripheral and thus, are inaccessible to the REE application. Any attempt to directly access them would result in a system fault.
|
||||
|
||||
.. note::
|
||||
|
||||
Flash memory protection is currently not implemented - it will be added soon in the next revision of the ESP-TEE framework.
|
||||
|
||||
.. note::
|
||||
|
||||
- Currently, the TEE secure storage supports the storage of two types of cryptographic keys:
|
||||
@@ -112,6 +108,6 @@ API Reference
|
||||
|
||||
.. note::
|
||||
|
||||
To use the TEE Secure Storage APIs into your project, ensure the :component:`tee_sec_storage <esp_tee/subproject/components/tee_sec_storage>` component is included by setting ``EXTRA_COMPONENT_DIRS`` in your project's ``CMakeLists.txt`` file, as shown in the :example:`tee_secure_storage <security/tee/tee_secure_storage>` example. For more information, refer to the :ref:`optional_project_variable` section from the :doc:`Build System </api-guides/build-system>` documentation.
|
||||
To use the TEE Secure Storage APIs in your project, ensure that the :component:`tee_sec_storage <esp_tee/subproject/components/tee_sec_storage>` component is listed as a local dependency in the component manager manifest file `idf_component.yml <https://docs.espressif.com/projects/idf-component-manager/en/latest/reference/manifest_file.html>`_. Refer to the :example:`tee_secure_storage <security/tee/tee_secure_storage>` example for guidance.
|
||||
|
||||
.. include-build-file:: inc/esp_tee_sec_storage.inc
|
||||
|
||||
@@ -71,10 +71,6 @@ Memory Allocation
|
||||
|
||||
ESP-TEE divides the memory into separate regions for the TEE and REE, allocating part of the internal SRAM and external flash memory to the TEE. This separation safeguards sensitive data and operations within the TEE, preventing unauthorized access from the REE.
|
||||
|
||||
.. note::
|
||||
|
||||
Flash memory protection is under development and will be introduced in the next revision of ESP-TEE.
|
||||
|
||||
.. _tee-internal-memory:
|
||||
|
||||
Internal Memory (SRAM)
|
||||
@@ -105,10 +101,14 @@ Example partition table is given below: ::
|
||||
nvs, data, nvs, 0x150000, 24K,
|
||||
phy_init, data, phy, 0x156000, 4K,
|
||||
|
||||
.. note::
|
||||
.. important::
|
||||
|
||||
The partition following the last TEE-related partition must be aligned to the configured MMU page size. This alignment is required to prevent secure boot verification failures when validating the user application (REE) image.
|
||||
|
||||
.. note::
|
||||
|
||||
For more details on the default policy and scope of flash memory protection with ESP-TEE, refer to the :ref:`Flash Protection - Virtual and Physical Access <tee-flash-prot-scope>` section from the advanced guide.
|
||||
|
||||
.. _tee-secure-services:
|
||||
|
||||
Secure Services
|
||||
@@ -120,7 +120,7 @@ All features that the TEE exposes to the REE are implemented as secure services.
|
||||
|
||||
Since multitasking is not currently supported in the TEE, secure service calls are serialized, and subsequent calls remain pending until the current service completes.
|
||||
|
||||
For {IDF_TARGET_NAME}, a list of secure services can be found at this :component_file:`table<esp_tee/scripts/{IDF_TARGET_PATH_NAME}/secure_service.tbl>`. Following are the types of secure services.
|
||||
For {IDF_TARGET_NAME}, a list of secure services can be found at this :component_file:`table<esp_tee/scripts/{IDF_TARGET_PATH_NAME}/sec_srv_tbl_default.yml>`. Following are the types of secure services.
|
||||
|
||||
- **Core secure services**: Built-in services within the TEE firmware that provide routine functionalities to the REE, such as interrupt configuration and eFuse access.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user