Merge branch 'feature/esp_tee_examples_and_docs' into 'master'

docs(esp_tee): Added documentation for ESP-TEE

Closes IDF-10483

See merge request espressif/esp-idf!34852

docs/component_info_ignore_file.txt

@@ -12,3 +12,7 @@ components/ulp/lp_core/lp_core/include/ulp_lp_core_spi.h
 components/driver/test_apps/components/esp_serial_slave_link/include/esp_serial_slave_link/essl_sdio.h
 components/driver/test_apps/components/esp_serial_slave_link/include/esp_serial_slave_link/essl_spi.h
 components/driver/test_apps/components/esp_serial_slave_link/include/esp_serial_slave_link/essl.h
+# ESP-TEE header files
+components/esp_tee/subproject/components/tee_sec_storage/include/esp_tee_sec_storage.h
+components/esp_tee/subproject/components/tee_attestation/esp_tee_attestation.h
+components/esp_tee/subproject/components/tee_ota_ops/include/esp_tee_ota_ops.h

docs/conf_common.py

@@ -199,6 +199,13 @@ PPA_DOCS = ['api-reference/peripherals/ppa.rst']
 
 QEMU_DOCS = ['api-guides/tools/qemu.rst']
 
+ESP_TEE_DOCS = ['security/tee/index.rst',
+                'security/tee/tee.rst',
+                'security/tee/tee-advanced.rst',
+                'security/tee/tee-attestation.rst',
+                'security/tee/tee-ota.rst',
+                'security/tee/tee-sec-storage.rst']
+
 ESP32_DOCS = ['api-reference/system/himem.rst',
               'api-guides/romconsole.rst',
               'api-reference/system/ipc.rst',
@@ -242,7 +249,7 @@ ESP32C61_DOCS = ['api-guides/phy.rst']
 
 ESP32C6_DOCS = ['api-guides/RF_calibration.rst',
                 'api-reference/peripherals/sd_pullup_requirements.rst',
-                'api-guides/phy.rst']
+                'api-guides/phy.rst'] + ESP_TEE_DOCS
 
 ESP32H2_DOCS = ['api-guides/RF_calibration.rst',
                 'api-guides/phy.rst']

docs/doxygen/Doxyfile_esp32c6

@@ -15,3 +15,7 @@ INPUT += \
     $(PROJECT_PATH)/components/ulp/ulp_common/include/ulp_common.h \
     $(PROJECT_PATH)/components/esp_wifi/include/esp_wifi_he_types.h \
     $(PROJECT_PATH)/components/esp_wifi/include/esp_wifi_he.h \
+    $(PROJECT_PATH)/components/esp_tee/include/esp_tee.h \
+    $(PROJECT_PATH)/components/esp_tee/subproject/components/tee_sec_storage/include/esp_tee_sec_storage.h \
+    $(PROJECT_PATH)/components/esp_tee/subproject/components/tee_attestation/esp_tee_attestation.h \
+    $(PROJECT_PATH)/components/esp_tee/subproject/components/tee_ota_ops/include/esp_tee_ota_ops.h \

docs/en/api-guides/partition-tables.rst

@@ -123,7 +123,13 @@ The 8-bit SubType field is specific to a given partition type. ESP-IDF currently
 
 See enum :cpp:type:`esp_partition_subtype_t` for the full list of subtypes defined by ESP-IDF, including the following:
 
-* When type is ``app``, the SubType field can be specified as ``factory`` (0x00), ``ota_0`` (0x10) ... ``ota_15`` (0x1F) or ``test`` (0x20).
+.. only:: not esp32c6
+
+  * When type is ``app``, the SubType field can be specified as ``factory`` (0x00), ``ota_0`` (0x10) ... ``ota_15`` (0x1F) or ``test`` (0x20).
+
+.. only:: esp32c6
+
+  * When type is ``app``, the SubType field can be specified as ``factory`` (0x00), ``ota_0`` (0x10) through ``ota_15`` (0x1F), or ``test`` (0x20). Additionally, if :doc:`ESP-TEE <../security/tee/tee>` functionality is enabled, two TEE-specific subtypes become available: ``tee_0`` (0x30) and ``tee_1`` (0x31).
 
     - ``factory`` (0x00) is the default app partition. The bootloader will execute the factory app unless there it sees a partition of type data/ota, in which case it reads this partition to determine which OTA image to boot.
 
@@ -133,6 +139,10 @@ See enum :cpp:type:`esp_partition_subtype_t` for the full list of subtypes defin
     - ``ota_0`` (0x10) ... ``ota_15`` (0x1F) are the OTA app slots. When :doc:`OTA <../api-reference/system/ota>` is in use, the OTA data partition configures which app slot the bootloader should boot. When using OTA, an application should have at least two OTA application slots (``ota_0`` & ``ota_1``). Refer to the :doc:`OTA documentation <../api-reference/system/ota>` for more details.
     - ``test`` (0x20) is a reserved subtype for factory test procedures. It will be used as the fallback boot partition if no other valid app partition is found. It is also possible to configure the bootloader to read a GPIO input during each boot, and boot this partition if the GPIO is held low, see :ref:`bootloader_boot_from_test_firmware`.
 
+    .. only:: esp32c6
+
+      - ``tee_0`` (0x30) and ``tee_1`` (0x31) are the TEE app slots. When :doc:`TEE OTA <../security/tee/tee-ota>` is in use, the TEE OTA data partition configures which TEE app slot the bootloader should boot. When using TEE OTA, the partition table should have these two TEE app slots. Refer to the :doc:`TEE OTA documentation <../security/tee/tee-ota>` for more details.
+
 * When type is ``bootloader``, the SubType field can be specified as:
 
     - ``primary`` (0x00). This is the 2nd stage bootloader, located at the {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH} address in flash memory. The tool automatically determines the appropriate size and offset for this subtype, so any size or offset specified for this subtype will be ignored. You can either leave these fields blank or use ``N/A`` as a placeholder.
@@ -171,6 +181,11 @@ See enum :cpp:type:`esp_partition_subtype_t` for the full list of subtypes defin
         - It is used to store NVS encryption keys when `NVS Encryption` feature is enabled.
         - The size of this partition should be 4096 bytes (minimum partition size).
 
+    .. only:: esp32c6
+
+            - ``tee_ota`` (0x90) is the :ref:`TEE OTA data partition <tee-ota-data-partition>` which stores information about the currently selected TEE OTA app slot. This partition should be 0x2000 bytes in size. Refer to the :doc:`TEE OTA documentation <../security/tee/tee-ota>` for more details.
+            - ``tee_sec_stg`` (0x91) is the TEE secure storage partition which stores encrypted data that can only be accessed by the TEE application. This partition is used by the :doc:`TEE Secure Storage <../security/tee/tee-sec-storage>` to store sensitive data like cryptographic keys. The size of this partition depends on the application requirements.
+
     - There are other predefined data subtypes for data storage supported by ESP-IDF. These include:
 
         - ``coredump`` (0x03) is for storing core dumps while using a custom partition table CSV file. See :doc:`/api-guides/core_dump` for more details.

docs/en/contribute/esp-idf-tests-with-pytest.rst

@@ -481,6 +481,8 @@ In CI, all generated target test jobs are named according to the pattern "<targe
 
 The binaries in the target test jobs are downloaded from our internal MinIO servers. For most of the test cases, only the files that are required by flash (like .bin files, flash_args files, etc) would be downloaded. For some test cases, like jtag test cases, .elf files are also downloaded.
 
+.. _run_the_tests_locally:
+
 Running Tests Locally
 =====================
 

docs/en/security/index.rst

@@ -18,6 +18,7 @@ Features
    flash-encryption
    :esp32: secure-boot-v1
    secure-boot-v2
+   :esp32c6: tee/index
 
 Workflows
 ---------

docs/en/security/tee/index.rst

@@ -0,0 +1,24 @@
+###################################
+Trusted Execution Environment (TEE)
+###################################
+
+*********************
+The ESP-TEE Framework
+*********************
+
+.. toctree::
+   :maxdepth: 1
+
+   tee
+   tee-advanced
+
+****************
+Salient Features
+****************
+
+.. toctree::
+   :maxdepth: 1
+
+   tee-sec-storage
+   tee-ota
+   tee-attestation

docs/en/security/tee/tee-advanced.rst

@@ -0,0 +1,404 @@
+Advanced Topics
+===============
+
+.. _tee-detailed-architecture:
+
+Detailed Architecture
+---------------------
+
+The ESP-TEE framework on {IDF_TARGET_NAME} utilizes the inherent features of the RISC-V architecture, along with Espressif's proprietary hardware peripherals (given below), to ensure system isolation and enable a secure execution environment.
+
+- Inherent RISC-V CPU features
+
+  * Machine (M) and User (U) privilege levels
+  * PMP (Physical Memory Protection)
+  * PMA (Physical Memory Attributes)
+
+- Espressif proprietary hardware
+
+  * APM (Access Permission Management) peripheral
+
+Together, these components enable the {IDF_TARGET_NAME} SoC to allocate the chip's hardware resources (internal memory, external memory, and peripherals) and software resources into two modes - Machine (M) mode and User (U) mode. The CPU can switch between these modes, with the TEE running in the higher privilege M-mode and the REE running in the lower privilege U-mode.
+
+    .. figure:: ../../../_static/esp_tee/{IDF_TARGET_PATH_NAME}/esp_tee_arch.png
+        :align: center
+        :scale: 90%
+        :alt: ESP TEE Architecture for {IDF_TARGET_NAME}
+        :figclass: align-center
+
+        ESP-TEE: Architecture for {IDF_TARGET_NAME}
+
+Boot-up Flow
+^^^^^^^^^^^^
+
+The :doc:`Application Startup Flow <../../api-guides/startup>` is slightly modified when ESP-TEE is enabled. After a reset, the second stage bootloader loads both the TEE image and the application image from the boot device. Control is then handed over to the TEE, which configures memory, interrupts, and peripheral access settings before switching to the REE in U-mode to execute the application image.
+
+
+    .. figure:: ../../../_static/esp_tee/esp_tee_boot_seq.png
+        :align: center
+        :scale: 65%
+        :alt: ESP TEE Boot sequence for {IDF_TARGET_NAME}
+        :figclass: align-center
+
+        ESP-TEE: Boot Sequence for {IDF_TARGET_NAME}
+
+Isolation: Hardware
+^^^^^^^^^^^^^^^^^^^
+
+RISC-V: Privilege Levels
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+In RISC-V architecture, each hardware thread (hart) operates at a specific privilege level, defined as a mode within one or more Control Status Registers (CSRs). These privilege levels serve as a protective measure, segregating different components within the software stack. Any attempts to execute operations or access assets that are not permitted by the current privilege mode will trigger an exception. The M-mode has the highest privileges and code running in M-mode is usually inherently trusted, as it has low-level access to the machine implementation.
+
+For more information, please refer to the *RISC-V Instruction Set Manual Volume II: Privileged Architecture, Version 1.10*.
+
+Physical Memory Protection (PMP) and Physical Memory Attributes (PMA) Checker
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ESP-TEE framework for {IDF_TARGET_NAME} leverages the RISC-V architecture's features, such as Physical Memory Protection (PMP) and Physical Memory Attributes (PMA) Checker, to manage access to system memory (internal SRAM and external Flash) within the TEE and REE contexts.
+
+The PMP unit allows M-mode software to configure access privileges (read, write, execute) for required memory regions. This mechanism enforces resource isolation between the TEE and REE, adhering to the system's predefined policies and ensuring secure access control.
+
+The PMAC unit enhances security by providing additional permission checks, including configurable memory types and customizable attributes for required memory regions.
+
+For more details, see *{IDF_TARGET_NAME} Technical Reference Manual* > *Physical Memory Protection* [`PDF <{IDF_TARGET_TRM_EN_URL}#subsection.1.8>`__] and *Physical Memory Attribute (PMA) Checker* [`PDF <{IDF_TARGET_TRM_EN_URL}#subsection.1.9>`__].
+
+Access Permission Management (APM)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Access Permission Management (APM) module is a {IDF_TARGET_NAME}-hardware peripheral designed to enforce isolation between the TEE and REE, both for the system memory and peripherals. It is composed of two primary components: the TEE controller and the APM controller, each with its dedicated registers. The TEE-related registers are used to configure the security mode of each master (e.g., HP CPU or DMA acting as a master accessing memory), and the APM-related registers are used to specify the access permission and access address range of each security mode.
+
+APM enhances system isolation in areas where the PMP and PMA mechanisms fall short. The number of entries for PMP/PMA are limited, and these mechanisms cannot govern accesses by the low-power core or other masters, such as the GDMA.
+
+For more details, see *{IDF_TARGET_NAME} Technical Reference Manual* > *Permission Control (PMS)* [`PDF <{IDF_TARGET_TRM_EN_URL}#permctrl>`__].
+
+.. note::
+
+  For {IDF_TARGET_NAME}, the Access Permission Management (APM) and the Physical Memory Protection (PMP) together play the role of Permission Control (PMS).
+
+Isolation: Entities
+^^^^^^^^^^^^^^^^^^^
+
+Internal Memory (SRAM)
+~~~~~~~~~~~~~~~~~~~~~~
+
+A region at the top of the HP SRAM is reserved for the TEE, allocated for TEE code execution and runtime data storage, including stack and heap. Permissions for all memory regions within the SRAM are managed by the PMP and configured by the TEE.
+
+The REE memory is partitioned into IRAM (text: Read/Execute) and DRAM (data: Read/Write) sections, with the division controlled by the PMP.
+However, the TEE memory is divided into IRAM and DRAM sections, with division enforced by the PMA.
+
+    .. figure:: ../../../_static/esp_tee/{IDF_TARGET_PATH_NAME}/esp_tee_memory_layout.png
+        :align: center
+        :scale: 80%
+        :alt: ESP TEE Memory Map for {IDF_TARGET_NAME}
+        :figclass: align-center
+
+        ESP-TEE: Memory Map for {IDF_TARGET_NAME}
+
+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%
+    :alt: ESP TEE Flash Memory Map for {IDF_TARGET_NAME}
+    :figclass: align-center
+
+    ESP-TEE: Flash Memory Map for {IDF_TARGET_NAME}
+
+Peripherals
+~~~~~~~~~~~
+
+The following peripherals are protected using the APM module and accessible only by the TEE. Any direct access to these peripherals from the REE will trigger an exception. These peripherals are chosen for protection because access from the REE could compromise system security or interfere with secure services like secure storage and attestation.
+
+.. list::
+
+    - Access Permission Management (APM) peripheral
+    - AES, SHA accelerators
+    - eFuse Controller
+    - Interrupt Controller
+    - Brownout Detector
+    - Super Watchdog Timer (SWDT)
+
+.. note::
+
+  -  The following peripherals will be secured in future releases -
+
+     - MPI accelerator (RSA)
+     - ECC accelerator
+     - Digital Signature module
+     - Hash-Based Message Authentication Code (HMAC) module
+
+Firmware
+^^^^^^^^
+
+The TEE firmware is primarily loaded and executed from the internal secure SRAM. However, due to SRAM's limited capacity, some portions of the TEE firmware are stored and executed from a dedicated external flash partition, which is protected from access by the REE. This firmware is responsible for securely configuring the system, ensuring isolation and protection of both internal and external memory, as well as peripherals.
+
+System Initialization
+~~~~~~~~~~~~~~~~~~~~~
+
+The TEE handles the secure initialization of the SoC's resources, including:
+
+    * Setting the TEE vector table, the designated secure interrupt and the interrupts to be delegated to the REE
+    * Configuring the isolation boundaries between TEE and REE by setting up -
+
+        - RISC-V PMP/PMA for internal memory (I/DRAM) and external memory (Flash)
+        - APM for peripherals (AES, SHA, eFuse, MMU, etc.)
+
+    * Registering the TEE heap
+
+Interrupts
+~~~~~~~~~~
+
+The TEE and REE each have their own vector tables, with one interrupt pin dedicated to secure interrupts. TEE interrupts are always given higher priority over REE interrupts. The TEE firmware provides APIs for registering secure, peripheral-specific interrupt handlers.
+
+Depending on the interrupt state, an interrupt may either be handled within the current execution environment's vector table or trigger a privilege switch, transferring the handling to the other environment's vector table. There are four possible scenarios for interrupt handling, as outlined in the table below.
+
+Once the interrupt is handled in the other execution environment, execution returns to the environment where the interrupt was initially triggered.
+
++-------------------------------------------+---------------------------------------------------------+
+| Scenario                                  | Description                                             |
++===========================================+=========================================================+
+| TEE interrupts while operating in TEE     | Trapped in the TEE at the M-mode exception handler      |
++-------------------------------------------+---------------------------------------------------------+
+| REE interrupts while operating in REE     | Trapped in the REE at the U-mode exception handler      |
++-------------------------------------------+---------------------------------------------------------+
+| TEE interrupts while operating in REE     | Trapped in the TEE at the M-mode exception handler and  |
+|                                           | return to the REE after processing                      |
++-------------------------------------------+---------------------------------------------------------+
+| REE interrupts while operating in TEE     | Trapped in the TEE at the M-mode exception handler,     |
+|                                           | jump to the U-mode exception handler in the REE and     |
+|                                           | return to the TEE after processing                      |
++-------------------------------------------+---------------------------------------------------------+
+
+.. seqdiag::
+    :caption: ESP-TEE: Handling TEE interrupts occurring in REE
+    :align: center
+
+    seqdiag esp_tee_m_u_intr {
+        activation = none;
+        node_width = 120;
+        node_height = 80;
+        edge_length = 500;
+        default_shape = roundedbox;
+        default_fontsize = 12;
+
+        REE  [label = "REE\n(User mode)"];
+        TEE  [label = "TEE\n(Machine mode)"];
+
+        === TEE interrupts in REE ===
+        REE -> REE[label = "REE software\nexecution"];
+        REE -> TEE [label = "TEE interrupt", rightnote = "Jump to the M-mode\nexception handler"];
+        TEE -> TEE [rightnote = "Save the U-mode context\nSwitch to the M-mode\ninterrupt stack"];
+        TEE -> TEE [label = "Service Routine"];
+        TEE -> REE [label = "Return to REE", rightnote = "Restore the U-mode context\n(mret instruction)"];
+        REE -> REE[label = "REE software\nexecution"];
+    }
+
+
+.. figure:: ../../../_static/esp_tee/{IDF_TARGET_PATH_NAME}/esp_tee_intr_handling.png
+    :align: center
+    :alt: ESP-TEE: Interrupt Handling
+    :figclass: align-center
+
+    ESP-TEE: Handling REE interrupts occurring in TEE
+
+
+Secure Services
+---------------
+
+Execution Flow
+^^^^^^^^^^^^^^
+
+The secure service call interface allows the REE application to request trusted (TEE) operations, triggering the secure service dispatcher function. The dispatcher parses the input parameters, identifies the correct service to invoke, and forwards the request to the appropriate service handler.
+
+Serving as the entry point to the TEE, the dispatcher manages the secure service call. Upon receiving a request, it processes the input arguments and executes the requested service.
+
+After the secure service completes, the dispatcher handles the return process and initiates a privilege switch, restoring control to the REE at the point of the original call. Note that the privilege levels are switched as a part of the pre and post processing routines of the secure service dispatcher.
+
+.. seqdiag::
+    :caption: ESP-TEE: Secure Service Call Trace
+    :align: center
+
+    seqdiag esp_tee_ss_call_trace {
+        activation = none;
+        node_width = 120;
+        node_height = 80;
+        edge_length = 500;
+        default_shape = roundedbox;
+        default_fontsize = 12;
+
+
+        REE  [label = "REE\n(User mode)"];
+        TEE  [label = "TEE\n(Machine mode)"];
+
+        === Secure Service Call Interface ===
+        REE -> REE[label = "REE software\nexecution"];
+        REE -> TEE [label = "Secure service call", rightnote = "(ecall instruction)\nJump to M-mode exception handler"];
+        TEE -> TEE [leftnote = "Save the U-mode context\nSwitch to the M-mode stack\nDisable U-mode interrupt delegation"];
+        TEE -> TEE [label = "Secure service\nexecution"];
+        TEE -> REE [label = "Return to REE", rightnote = "Restore the U-mode context\nEnable U-mode interrupt delegation\n(mret instruction)"];
+        REE -> REE[label = "REE software\nexecution"];
+    }
+
+The convention for the secure service call interface API :cpp:func:`esp_tee_service_call` is defined as follows.
+
+.. list-table:: Secure Service calling convention
+         :widths: 15 20 40
+         :header-rows: 1
+
+         * - **Argument**
+           - **Type**
+           - **Description**
+         * - ``arg0``
+           - ``uint8_t``
+           - Input: Number of input arguments to the secure service
+         * - ``arg1``
+           - ``tee_secure_service_t``
+           - Input: Secure Service ID
+         * - ``arg2`` - ``arg9``
+           - ``uint32_t``
+           - Input: Arguments to the secure service
+         * - ``val``
+           - ``uint32_t``
+           - Output: Return value from the secure service
+
+.. note::
+
+    - An IRAM-safe variant of the API, :cpp:func:`esp_tee_service_call_with_noniram_intr_disabled`, suspends the scheduler and disables all non-IRAM resident interrupts before switching execution environments.
+
+    - This is essential during operations like flash access through the SPI1 bus, where the flash cache may be disabled, to prevent concurrent access to flash from multiple entities.
+
+
+.. _custom-secure-services:
+
+Adding Custom Secure Services
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To extend the ESP-TEE framework with custom service calls, follow the steps outlined below.
+
+1. Create a Custom Service Call Table
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Define a component for defining custom service calls and create a ``.tbl`` file within the component.
+
+.. code-block:: bash
+
+   touch <path/to/tbl/file>/custom_srvcall.tbl
+
+Add your custom service call entries to the ``.tbl`` file in the following format:
+
+.. code-block:: none
+
+  <service_call_number>    custom    <function_name>    <arguments_count>
+
+**Example Entry**
+
+.. code-block:: none
+
+  # SS no.    API type    Function              Args
+  201         custom      custom_sec_srv_op    1
+
+- ``201``: Unique service call number
+- ``custom``: Custom service call type
+- ``custom_sec_srv_op``: Function name
+- ``1``: 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.
+
+2. Define the Service Call Implementation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Define the function corresponding to the custom service call in the TEE. This function will execute whenever the REE invokes the service with the associated number.
+
+**Example Implementation**
+
+.. code-block:: c
+
+   int _ss_custom_sec_srv_op(void *arg)
+   {
+       // Perform the intended task
+       return 0;
+   }
+
+The function name should have the prefix ``_ss_`` before the name and must match the name specified in the ``.tbl`` file.
+
+For reference, all default service call functions are defined in the :component_file:`file<esp_tee/subproject/main/core/esp_secure_services.c>`.
+
+3. Build-system changes
+~~~~~~~~~~~~~~~~~~~~~~~
+
+**Custom component-level**
+
+Define a CMake file (e.g., ``custom_sec_srv.cmake``) in the component that defines the custom service calls. Add the following configurations.
+
+#. Append the service call table to the default table
+
+   .. code-block:: cmake
+
+     idf_build_set_property(CUSTOM_SECURE_SERVICE_TBL ${CMAKE_CURRENT_LIST_DIR}/custom_srvcall.tbl APPEND)
+
+#. Set the custom component directory and name so that the ``esp_tee`` subproject can use it
+
+   .. code-block:: cmake
+
+     get_filename_component(directory "${CMAKE_CURRENT_LIST_DIR}/.." ABSOLUTE DIRECTORY)
+     idf_build_set_property(CUSTOM_SECURE_SERVICE_COMPONENT_DIR ${directory} APPEND)
+
+     get_filename_component(name ${CMAKE_CURRENT_LIST_DIR} NAME)
+     idf_build_set_property(CUSTOM_SECURE_SERVICE_COMPONENT ${name} APPEND)
+
+#. Define the ``CMakeLists.txt`` for the custom component
+
+   .. code-block:: cmake
+
+      idf_build_get_property(esp_tee_build ESP_TEE_BUILD)
+
+      if(esp_tee_build)
+      ## Headers, sources and dependent components for the TEE-build
+      else()
+      ## Headers, sources and dependent components for the REE-build
+      endif()
+
+      idf_component_register(...)
+
+**Project-level**
+
+Modify the top-level ``CMakeLists.txt`` of your project to include the ``custom_sec_srv.cmake`` file before calling the ``project()`` command.
+
+.. code-block:: cmake
+
+  include(<path/to/component>/custom_sec_srv.cmake)
+
+  project(your_project_name)
+
+.. note::
+
+  For more details, refer to the :example:`tee_basic <security/tee/tee_basic>` example.
+
+Unit Testing
+------------
+
+The ESP-TEE framework utilizes the :doc:`pytest in ESP-IDF <../../contribute/esp-idf-tests-with-pytest>` framework for executing the dedicated unit tests on the target. The test application includes cases spanning the modules listed below and can be located in the ``components`` directory at :component:`esp_tee/test_apps`.
+
+- Secure service call interface
+- Interrupts and exception handling
+- Privilege violation
+- Cryptographic operations
+- TEE OTA updates
+- Secure storage
+- Attestation
+
+Please follow the steps given :ref:`here <run_the_tests_locally>` for running the tests locally. For example, if you want to execute the TEE test suite for {IDF_TARGET_NAME} with all the available ``sdkconfig`` files (assuming you have ESP-IDF setup), run the following steps.
+
+.. code-block:: bash
+
+  $ cd components/esp_tee/test_apps/tee_test_fw
+  $ idf.py build
+  $ pytest --target <target>

docs/en/security/tee/tee-attestation.rst

@@ -0,0 +1,256 @@
+Attestation
+===========
+
+Overview
+--------
+
+Attestation is the process of securely providing information about a device to external parties through a cryptographically secured token. It enables IoT devices, especially those without user interfaces or in remote locations, to introduce themselves securely to networks and IoT platforms by offering attestation information.
+
+Thus, the attestation service is employed by the device to communicate evidence regarding its credentials and operational state to a remote relying party. The collected information is structured into the Entity Attestation Token (EAT) format.
+
+To ensure security, the EAT is cryptographically protected. The remote relying party can then verify the authenticity of the EAT and make decisions about engaging with the device based on its contents.
+
+Attestation Flow
+----------------
+
+.. seqdiag::
+    :caption: ESP-TEE Attestation Flow
+    :align: center
+
+    seqdiag tee_attestation {
+        activation = none;
+        node_width = 125;
+        node_height = 60;
+        edge_length = 275;
+        default_shape = roundedbox;
+        default_fontsize = 13;
+
+        ET  [label = "Entity"];
+        RP  [label = "Relying Party"];
+        AS  [label = "Attestation Service"];
+
+        === Attestation ===
+        RP -> ET [label = "Attestation Request"];
+        ET -> ET [label = "EAT Generation\nand Signature", rightnote = "Attestor"];
+        ET -> RP [label = "Attestation Evidence"];
+        RP -> AS [label = "Attestation Evidence"];
+        AS -> AS [label = "Evidence\nVerification", rightnote = "Verifier"];
+        AS -> RP [label = "Attestation Result"];
+        RP -> ET [label = "Relying Party Decision"];
+    }
+
+#. The Relying Party sends an Attestation Request (AR) to the device REE with some challenge or nonce (usually a random number).
+#. The device REE forwards the request to the device TEE attestation service through the secure service call interface.
+#. The TEE assembles the Entity Attestation Token (EAT) (the attestation evidence) by gathering all the relevant claim information as outlined in the EAT claim table. It then generates a signature on the claim data, appending it to the token.
+#. The evidence is transmitted back to the remote attestation service (verifier) through the device REE and the relying party. In certain cases, the Relying Party itself may act as the attestation service.
+#. The attestation service assesses the received evidence and, upon successful verification, compares the EAT claim data with the available reference values.
+#. The relying party determines the trustworthiness of the device based on the attestation result and its predefined policy. Subsequently, it communicates this determination to the device.
+
+
+Entity Attestation Token
+------------------------
+
+The Entity Attestation Token (EAT) is a small blob of data that contains claims and is cryptographically signed. The cryptographic signing secures the token, so the means to convey the token does not need to provide any security.
+
+When an attestation request is sent to the device, it generates the EAT in the predefined JSON format as given below. The token contains all the necessary information about the hardware and software entities on device. Here, an ECDSA key-pair from the TEE secure storage is used for signing the EAT, utilizing the slot ID mentioned in the attestation request. The EAT contains the **compressed** ECDSA public key as well as the ``R`` and ``S`` components of the signature.
+
+    .. figure:: ../../../_static/esp_tee/tee_attestation_evidence.png
+        :align: center
+        :scale: 75%
+        :alt: ESP TEE Attestation Evidence
+        :figclass: align-center
+
+        ESP-TEE: Attestation Evidence
+
+EAT: Header
+^^^^^^^^^^^
+
+.. list-table::
+    :header-rows: 1
+    :widths: 25 65 65
+    :align: center
+
+    * - **Claim**
+      - **Description**
+      - **Comments**
+    * - Magic
+      - Identifies the commencement of the EAT
+      -
+    * - Encryption Algorithm
+      - Specifies encryption algorithm details if the EAT is encrypted
+      -
+    * - Signing Algorithm
+      - Specifies signing algorithm details if the EAT is signed
+      - Currently, only ``ecdsa_secp256r1_sha256`` is supported
+    * - Key ID
+      - Identifies the key to be utilized by the device for encryption and signing
+      - TEE secure storage slot ID
+
+EAT: Claim Table
+^^^^^^^^^^^^^^^^
+
+.. list-table::
+    :header-rows: 1
+    :widths: 25 65 65
+    :align: center
+
+    * - **Claim**
+      - **Description**
+      - **Comments**
+    * - Nonce
+      - For protection from Reply Attack. If attestation is initiated by the device, it provides the nonce as part of the attestation request to the Relying Party.
+      -
+    * - Client ID
+      - Relying Party identification
+      -
+    * - Device ID
+      - Device identification (should be unique)
+      - SHA256 digest of the device MAC address
+    * - Device Version
+      - SoC H/W revision from eFuse
+      -
+    * - Instance ID
+      - Instance identification
+      - Public-key hash (SHA256) from the current secure storage slot for the active session
+    * - Certification Reference
+      - PSA certification ID
+      -
+    * - Device State
+      - Development/Production Mode
+      -
+    * - Software Measurement
+      - Details of the active firmware components - for e.g. app version, ESP-IDF version, digest, etc. There will be one entry of this type in the EAT for each firmware in the device.
+      -
+
+EAT: Software Measurement
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. list-table::
+    :header-rows: 1
+    :widths: 30 60 60
+    :align: center
+
+    * - **Key**
+      - **Description**
+      - **Comments**
+    * - Version
+      - Entity image version
+      - Not applicable to the bootloader
+    * - ESP-IDF Version
+      -
+      - Not applicable to the bootloader
+    * - Secure Version
+      - For firmware anti-rollback support
+      - Applicable only to the REE application
+    * - Digest: Type
+      -
+      - Currently, only ``SHA256`` is supported
+    * - Digest: Calculated Value
+      -
+      -
+    * - Digest: Validation
+      - Whether the calculated digest matches the one embedded in the firmware image
+      -
+    * - Secure Boot signature verification status
+      -
+      -
+    * - Secure Padding status
+      -
+      - For more details, refer :ref:`here <secure_padding>`.
+
+
+Sample EAT in JSON format
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: JSON
+
+  {
+    "header": {
+      "magic": "44fef7cc",
+      "encr_alg": "",
+      "sign_alg": "ecdsa_secp256r1_sha256",
+      "key_id": 0
+    },
+    "eat": {
+      "nonce": -1582119980,
+      "client_id": 262974944,
+      "device_ver": 1,
+      "device_id": "e8cddb2a7f9a5a7c61735d6dda26e4bd153c6d772a9be6f26bd321dfe25e0ac8",
+      "instance_id": "1adba85e0df997fd961f25a9e312430cef162b5c69466cd5b172f1e65ac7360c",
+      "psa_cert_ref": "0716053550477-10100",
+      "device_status": 255,
+      "sw_claims": {
+        "tee": {
+          "type": 1,
+          "ver": "v0.3.0",
+          "idf_ver": "v5.1.2-139-g07d83a7ced",
+          "secure_ver": 0,
+          "part_chip_rev": {
+            "min": 0,
+            "max": 99
+          },
+          "part_digest": {
+            "type": 0,
+            "calc_digest": "f732e7f285b7de7ac3167a867711eddbf17a2a05513d35e41cd1ebf2e0958b2e",
+            "digest_validated": true,
+            "sign_verified": true,
+            "secure_padding": true
+          }
+        },
+        "app": {
+          "type": 2,
+          "ver": "v0.1.0",
+          "idf_ver": "v5.1.2-139-g07d83a7ced",
+          "secure_ver": 0,
+          "part_chip_rev": {
+            "min": 0,
+            "max": 99
+          },
+          "part_digest": {
+            "type": 0,
+            "calc_digest": "21e114fd30b9234c501525990dfab71d00348c531bb64224feff9deb32e66f9f",
+            "digest_validated": true,
+            "sign_verified": true,
+            "secure_padding": true
+          }
+        },
+        "bootloader": {
+          "type": 0,
+          "ver": "",
+          "idf_ver": "",
+          "secure_ver": -1,
+          "part_chip_rev": {
+            "min": 0,
+            "max": 99
+          },
+          "part_digest": {
+            "type": 0,
+            "calc_digest": "516148649a7f670b894391ded9d64a0e8604c5cec9a1eeb0014d2549cdaa4725",
+            "digest_validated": true,
+            "sign_verified": true
+          }
+        }
+      }
+    },
+    "public_key": {
+      "compressed": "02a45c6c94c4be7722bd2513f4ccbc4daa369747e6e96e0f9f7a2eba055dee6d46"
+    },
+    "sign": {
+      "r": "37bcc8ed9c15a4712c18fe20b257992e5d9ec273b6261675f247667b4575495b",
+      "s": "28ce15da73880f7d5ee303948769b197077208f1f242aaee448e9ed23f9085fa"
+    }
+  }
+
+Application Example
+-------------------
+
+The :example:`tee_attestation <security/tee/tee_attestation>` example demonstrates how to generate an entity attestation token containing validation details for all active firmware components (bootloader, TEE, and REE app).
+
+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.
+
+.. include-build-file:: inc/esp_tee_attestation.inc

docs/en/security/tee/tee-ota.rst

@@ -0,0 +1,79 @@
+TEE Over-the-Air Updates (OTA)
+==============================
+
+Overview
+--------
+
+The OTA update mechanism allows a device to update itself based on data received while the normal firmware is running (for example, over Wi-Fi or Bluetooth). While OTA updates for application images are extensively documented :doc:`here <../../api-reference/system/ota>`, this section specifically details how OTA updates for the TEE image are securely managed.
+
+TEE OTA requires configuring the partition table of the device with at least two TEE OTA app slot partitions (i.e., ``tee_0`` and ``tee_1``) and a TEE OTA Data Partition (type ``data`` and subtype ``tee_ota``).
+
+    .. figure:: ../../../_static/esp_tee/{IDF_TARGET_PATH_NAME}/esp_tee_ota_flash_partitions.png
+        :align: center
+        :scale: 75%
+        :alt: ESP TEE OTA Flash Partition
+        :figclass: align-center
+
+        Sample flash partition layout with TEE and application OTA support
+
+.. _tee-ota-data-partition:
+
+TEE OTA Data Partition
+^^^^^^^^^^^^^^^^^^^^^^
+
+An OTA data partition (type ``data``, subtype ``tee_ota``) for the TEE image must be included in the partition table of any project which uses the OTA functions. Note that the TEE app has its own OTA data partition, separate from that of the REE app.
+
+For factory boot settings, the TEE OTA data partition should contain no data (all bytes erased to 0xFF). In this case, the second stage bootloader will boot the first available TEE OTA slot (usually ``tee_0``). After the first OTA update, the TEE OTA data partition is updated to specify which OTA app slot partition should be booted next.
+
+The TEE OTA data partition is two flash sectors (0x2000 bytes) in size, to prevent problems if there is a power failure while it is being written. Sectors are independently erased and written with matching data, and if they disagree a counter field is used to determine which sector was written more recently.
+
+    .. figure:: ../../../_static/esp_tee/tee_ota_data_entry.png
+        :align: center
+        :scale: 80%
+        :alt: ESP TEE OTA Data Entry
+        :figclass: align-center
+
+        ESP-TEE: OTA Data partition entry
+
+
+OTA Process: Boot-up Flow and Image Rollback
+--------------------------------------------
+
+#. The new TEE application is successfully downloaded over the appropriate interface (Wi-Fi, Bluetooth, Ethernet, etc.). The REE app will download the TEE OTA update. Since it does not have permission to write to the TEE flash region directly, it will issue the appropriate service calls to write the new firmware to the flash.
+#. The new firmware is written to the passive TEE partition and set as the bootable partition with the state ``NEW``. This means that the application is new and should be monitored during its first boot. The system is then rebooted.
+#. The bootloader will verify the magic and the CRC of the first sector in the ``tee_otadata`` partition. If invalid, the second sector will be used.
+#. If the application state is ``PENDING_VERIFY``, it will be overwritten to ``INVALID``. The bootloader will not select any image marked as ``INVALID`` for booting.
+#. If the application state is ``NEW``, it will be overwritten to ``PENDING_VERIFY``. This means that the application requires a confirmation to be considered as operable. If this does not happen and a reboot occurs, the state will be overwritten to ``INVALID`` and this application will no longer be able to boot, i.e., there will be a rollback to the previous working application.
+#. The new TEE application starts executing, but it needs a self-test to confirm its operability. As we reach the point of entry of the non-secure app, we consider the rollback self-test to be successful. The application is then marked as valid (state ``VALID``) and selected across further reboots if there are no updates to the device.
+#. If the self-test fails - the device did not reach the non-secure app entry point as there was some issue with the TEE image. This is considered as a critical exception and the device will reboot.
+
+  .. note::
+
+    - Any partition flashed serially will be automatically marked as valid during its first boot.
+
+    - If the first ``tee_otadata`` sector is valid but does not match with a valid second ``tee_otadata`` sector (or vice versa), it is the responsibility of the bootloader to make the ``tee_otadata`` sectors the same before handing control to TEE.
+
+    - If :ref:`Secure Boot <secure_boot-guide>` is enabled, the bootloader will verify the TEE and the non-secure app.
+
+
+.. figure:: ../../../_static/esp_tee/esp_tee_ota_flow.png
+    :align: center
+    :scale: 75%
+    :alt: ESP TEE OTA Flow
+    :figclass: align-center
+
+    TEE OTA process flow
+
+Application Example
+-------------------
+
+The :example:`tee_secure_ota <security/tee/tee_secure_ota>` example demonstrates how to perform an Over-the-Air updates with HTTP/S for the TEE.
+
+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.
+
+.. include-build-file:: inc/esp_tee_ota_ops.inc

docs/en/security/tee/tee-sec-storage.rst

@@ -0,0 +1,117 @@
+Secure Storage
+==============
+
+Overview
+--------
+
+The TEE Secure Storage service offers a persistent storage for securely holding sensitive data, such as cryptographic keys, cloud credentials or any other general-purpose information. It utilizes a dedicated flash partition of type ``data`` and subtype ``tee_sec_stg``. The confidentiality and integrity of the data is ensured by the TEE.
+
+For enhanced security, data stored in the secure storage is encrypted using a device-specific encryption key with ``AES-256-GCM`` algorithm. Additionally, the secure storage provides interfaces for performing the following cryptographic services from the TEE using securely stored key material:
+
+    #. Message signing and public key retrieval with the ``ecdsa_secp256r1`` algorithm
+    #. Authenticated encryption and decryption using the ``aes256_gcm`` algorithm
+
+Internals
+---------
+
+The secure storage partition is 4 KB in size, of which only the first half is used for storing data. The partition is divided into slots which hold data objects. Each data object within the TEE secure storage is encapsulated in a structured format, comprising the metadata and actual data.
+
+.. figure:: ../../../_static/esp_tee/tee_sec_stg_part.png
+    :align: center
+    :scale: 80%
+    :alt: TEE Secure storage partition
+    :figclass: align-center
+
+    ESP-TEE: Secure Storage partition
+
+Metadata is represented by the :cpp:type:`sec_stg_metadata_t` structure, which contains details related to the data stored in a specific slot of the storage. These details include information such as the owner, slot ID, data length, encryption parameters, etc.
+
+.. list-table::
+    :header-rows: 1
+    :widths: 35 65
+    :align: center
+
+    * - **Element**
+      - **Description**
+    * - Owner ID
+      - Application ID defining the data ownership
+    * - Slot ID
+      - Slot ID for corresponding owner ID
+    * - Encryption: Initialization Vector (IV)
+      - IV for the encryption algorithm
+    * - Encryption: Tag
+      - Tag for the encryption algorithm
+    * - Data Type
+      - Type of data stored in this slot
+    * - Data Length
+      - Actual data length
+
+.. figure:: ../../../_static/esp_tee/tee_sec_stg_metadata.png
+    :align: center
+    :scale: 80%
+    :alt: TEE Secure storage metadata
+    :figclass: align-center
+
+    ESP-TEE: Secure Storage Metadata
+
+.. warning::
+
+    Future ESP-TEE framework releases may modify the internal data structure of the TEE secure storage, which could introduce breaking changes in existing applications.
+
+Each data object in the secure storage is encrypted as specified in the **AES-GCM based AEAD** encryption policy with a platform instance unique key of length **256 bits**, stored in the eFuse.
+
+The TEE Secure Storage feature supports two modes (:ref:`CONFIG_SECURE_TEE_SEC_STG_MODE`) for determining which eFuse block stores the encryption key:
+
+  - **Development** Mode: The encryption key is embedded (constant for all instances) in the ESP-TEE firmware.
+  - **Release** Mode: The encryption key is stored in eFuse BLK4 - BLK9, depending on the :ref:`CONFIG_SECURE_TEE_SEC_STG_KEY_EFUSE_BLK` Kconfig option.
+
+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:
+
+    #. ``ecdsa_secp256r1`` curve key-pairs, including the private and public key components
+    #. ``aes256_gcm`` keys, including the key and initialization vector (IV)
+
+  The internal structures for these key types are as follows:
+
+  .. code-block:: c
+
+    #define ECDSA_SECP256R1_KEY_LEN  32
+    #define AES256_GCM_KEY_LEN       32
+    #define AES256_GCM_IV_LEN        12
+
+    typedef struct {
+        /* Private key */
+        uint8_t priv_key[ECDSA_SECP256R1_KEY_LEN];
+        /* Public key - X and Y components */
+        uint8_t pub_key[2 * ECDSA_SECP256R1_KEY_LEN];
+    } sec_stg_ecdsa_secp256r1_t;
+
+    typedef struct {
+        /* Key */
+        uint8_t key[AES256_GCM_KEY_LEN];
+        /* Initialization Vector */
+        uint8_t iv[AES256_GCM_IV_LEN];
+    } sec_stg_aes256_gcm_t;
+
+  - Future updates may include support for additional key types and general-purpose data storage.
+
+Application Example
+-------------------
+
+The :example:`tee_secure_storage <security/tee/tee_secure_storage>` example demonstrates how to generate ECDSA key pairs and AES-256-GCM keys in the TEE secure storage and use them for signing messages and encrypting/decrypting data.
+
+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.
+
+.. include-build-file:: inc/esp_tee_sec_storage.inc

docs/en/security/tee/tee.rst

@@ -0,0 +1,164 @@
+User Guide
+==========
+
+The ESP-TEE (Espressif Trusted Execution Environment) is a security framework built on top of dedicated hardware that ensures only authorized parties or applications can access protected information or services.
+When enabled, ESP-TEE runs in parallel with a FreeRTOS-based ESP-IDF application. In this case, the execution environment is split into the following:
+
+- **TEE**: the protected or trusted execution environment, managed by ESP-TEE.
+
+- **REE**: the unprotected or rich execution environment, where the ESP-IDF user application runs.
+
+An example use case for ESP-TEE is securely storing a cryptographic key in the TEE for authentication in a challenge-response protocol with external entities and enabling secure communication to protect data.
+
+ESP-TEE offers several key secure services, including:
+
+- :doc:`Secure Storage <tee-sec-storage>`
+
+  ESP-TEE provides secure storage to ensure that sensitive data is stored in an encrypted external flash partition, completely inaccessible to the REE. It also supports secure key management and operations for signing and encryption.
+
+- :doc:`Attestation <tee-attestation>`
+
+  Attestation is a mechanism enabling a device to make claims about its identity and security status, through a cryptographically secured token. ESP-TEE generates this token in a predefined JSON format, signed using the ECDSA scheme.
+
+- :doc:`Over-the-Air Updates (OTA) <tee-ota>`
+
+  ESP-TEE supports a secure TEE OTA update mechanism, allowing the device to update the TEE firmware using data received during normal operation, such as over Wi-Fi or Bluetooth. The mechanism also includes support for update rollback.
+
+For more information, see the :ref:`Secure Services <tee-secure-services>` section.
+
+Scope of Protection
+-------------------
+
+The :doc:`Secure Boot <../secure-boot-v2>` feature ensures that only authenticated software can execute on the device. When enabled, a signed TEE image is generated during the build process alongside the signed REE image. The signing scheme and key are the same for both applications.
+
+Secure Boot establishes a robust chain of trust by verifying all mutable software entities involved in the :doc:`Application Startup Flow <../../api-guides/startup>` i.e. the second stage bootloader, TEE, and REE applications. Signature verification is performed both during boot-up and OTA updates. While Secure Boot ensures boot-time security, ESP-TEE provides runtime security by safeguarding the security assets within the TEE.
+
+In addition, the attestation service verifies the signature and firmware hash for all active software upon request, ensuring ongoing protection against unauthorized modifications.
+
+The :doc:`Flash Encryption <../flash-encryption>` feature encrypts the contents of the {IDF_TARGET_NAME}'s off-chip flash memory, preventing physical readout from recovering its contents. The flash encryption key is securely stored in hardware and remains inaccessible to both TEE and REE.
+
+.. figure:: ../../../_static/esp_tee/esp_tee_secure_boot.png
+    :align: center
+    :alt: ESP-TEE: Boot-up Flow with Secure Boot for {IDF_TARGET_NAME}
+    :figclass: align-center
+
+    ESP-TEE: Boot-up Flow with Secure Boot for {IDF_TARGET_NAME}
+
+.. important::
+
+    It is highly recommended to enable both Secure Boot and Flash Encryption with ESP-TEE on all production devices.
+
+Architecture: Simplified Overview
+---------------------------------
+
+ESP-TEE offers a secure execution environment centered around a Root-of-Trust (RoT), which is a set of implicitly trusted functions on which the system or device relies on for security.
+
+The **Immutable RoT** consists of the following components:
+
+- First stage bootloader (BootROM)
+- Isolation hardware
+- Cryptographic hardware (AES, SHA)
+- eFuse
+
+The **Updatable RoT** comprises the second stage bootloader and the TEE firmware, which is responsible for secure configuration, initialization, interrupt handling, exception management, and providing secure services for cryptographic operations as well as features like secure storage and attestation.
+
+For more details about the individual components and the architecture, refer to the :ref:`Detailed Architecture <tee-detailed-architecture>` section.
+
+.. _tee-memory-allocation:
+
+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)
+^^^^^^^^^^^^^^^^^^^^^^
+
+Internal memory is allocated to the the TEE based on the Kconfig options that are available under the :ref:`Memory Configuration <esp-tee-trusted-execution-environment--enable-the-esp-tee-framework-memory-configuration>` section in the :ref:`esp-tee-trusted-execution-environment-` menu. All remaining memory is allocated to the REE.
+
+.. warning::
+
+  Modify the above values at your own risk as it may cause build or runtime failures.
+
+Both the TEE and REE have independent heap allocators, each operating within the memory allocated to its respective application.
+
+.. _tee-external-memory:
+
+External Memory (Flash)
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Designated partitions in the external flash are reserved for the TEE to support functions such as code XIP (eXecute-In-Place), secure storage, and OTA data. The partition table must include at least one TEE app slot (type ``app`` and subtype ``tee_0``) with a minimum size of 192 KB.
+
+Example partition table is given below: ::
+
+  # ESP-IDF Partition Table
+  # Name,         Type, SubType,     Offset,   Size, Flags
+  tee_0,          app,  tee_0,       0x10000,  192K,
+  secure_storage, data, tee_sec_stg, 0x40000,  64K,
+  factory,        app,  factory,     0x50000,  1M,
+  nvs,            data, nvs,         0x150000, 24K,
+  phy_init,       data, phy,         0x156000, 4K,
+
+.. note::
+
+  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.
+
+.. _tee-secure-services:
+
+Secure Services
+---------------
+
+All features that the TEE exposes to the REE are implemented as secure services. The REE can invoke such secure services through the interface APIs :cpp:func:`esp_tee_service_call` and :cpp:func:`esp_tee_service_call_with_noniram_intr_disabled`. Secure services can be preempted by TEE or REE interrupts.
+
+.. note::
+
+  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.
+
+- **Core secure services**: Built-in services within the TEE firmware that provide routine functionalities to the REE, such as interrupt configuration and eFuse access.
+
+- **Optional secure Services**: Configurable services that extend the capabilities of the TEE and can be enabled or disabled as needed, such as attestation.
+
+- **Custom secure services**: User-defined secure services as required by the user application. For more details, refer to the :ref:`Adding Custom Secure Services <custom-secure-services>` section and the :example:`tee_basic <security/tee/tee_basic>` example.
+
+Usage
+-----
+
+#. **Enable ESP-TEE**: In the :ref:`Project Configuration <project-configuration-guide>` menu, go to :ref:`esp-tee-trusted-execution-environment-` and set the option :ref:`CONFIG_SECURE_ENABLE_TEE`.
+
+#. **Configure the TEE logging**:
+
+   - Set :ref:`CONFIG_SECURE_TEE_DEBUG_MODE` to enable logging for TEE.
+
+   - Set :ref:`CONFIG_SECURE_TEE_LOG_LEVEL` to select the logging verbosity level.
+
+#. **Configure the TEE memory regions**:
+
+   - Set :ref:`CONFIG_SECURE_TEE_IRAM_SIZE` to configure the TEE IRAM size
+
+   - Set :ref:`CONFIG_SECURE_TEE_DRAM_SIZE` to configure the TEE DRAM size
+
+   - Set :ref:`CONFIG_SECURE_TEE_STACK_SIZE` and :ref:`CONFIG_SECURE_TEE_INTR_STACK_SIZE` to configure the TEE task and interrupt stack from the reserved DRAM
+
+#. **Configure the partition table**:
+
+   - Select one of the simple predefined partition tables under :ref:`CONFIG_PARTITION_TABLE_TYPE` - *Single factory app, no OTA, TEE* or *Two OTA definitions, TEE*
+
+   - Alternatively, select the *Custom partition table CSV* option and define your own layout as per the guidelines provided in the :ref:`tee-external-memory` section.
+
+Application Examples
+--------------------
+
+Examples are available in the :example:`security/tee` directory, showcasing the various ESP-TEE secure services. For more detailed information, please refer to the ``README.md`` file within each specific example.
+
+API Reference
+-------------
+
+.. include-build-file:: inc/esp_tee.inc

docs/zh_CN/api-guides/partition-tables.rst

@@ -123,7 +123,13 @@ SubType 字段长度为 8 bit，内容与具体分区 Type 有关。目前，ESP
 
 参考 :cpp:type:`esp_partition_subtype_t`，以了解 ESP-IDF 定义的全部子类型列表，包括：
 
-* 当 Type 定义为 ``app`` 时，SubType 字段可以指定为 ``factory`` (0x00)、 ``ota_0`` (0x10) … ``ota_15`` (0x1F) 或者 ``test`` (0x20)。
+.. only:: not esp32c6
+
+    * 当 Type 定义为 ``app`` 时，SubType 字段可以指定为 ``factory`` (0x00)、``ota_0`` (0x10) … ``ota_15`` (0x1F) 或 ``test`` (0x20)。
+
+.. only:: esp32c6
+
+    * 当 Type 定义为 ``app`` 时，SubType 字段可以指定为 ``factory`` (0x00)、 ``ota_0`` (0x10) … ``ota_15`` (0x1F) 或 ``test`` (0x20)。此外，如果启用了 :doc:`ESP-TEE <../security/tee/tee>` 功能，则可以使用两个 TEE 特定子类型：``tee_0`` (0x30) 和 ``tee_1`` (0x31)。
 
     -  ``factory`` (0x00) 是默认的 app 分区。引导加载程序将默认加载该应用程序。但如果存在类型为 data/ota 的分区，则引导加载程序将加载 data/ota 分区中的数据，进而判断启动哪个 OTA 镜像文件。
 
@@ -133,6 +139,10 @@ SubType 字段长度为 8 bit，内容与具体分区 Type 有关。目前，ESP
     -  ``ota_0`` (0x10) … ``ota_15`` (0x1F) 为 OTA 应用程序分区，引导加载程序将根据 OTA 数据分区中的数据来决定加载哪个 OTA 应用程序分区中的程序。在使用 OTA 功能时，应用程序应至少拥有 2 个 OTA 应用程序分区（``ota_0`` 和 ``ota_1``）。更多详细信息，请参考 :doc:`OTA 文档 </api-reference/system/ota>`。
     -  ``test`` (0x20) 为预留的子类型，用于工厂测试流程。如果没有其他有效 app 分区，test 将作为备选启动分区使用。也可以配置引导加载程序在每次启动时读取 GPIO，如果 GPIO 被拉低则启动该分区。详细信息请查阅 :ref:`bootloader_boot_from_test_firmware`。
 
+    .. only:: esp32c6
+
+        - ``tee_0`` (0x30) 和 ``tee_1`` (0x31) 是 TEE 应用分区。使用 :doc:`TEE OTA <../security/tee/tee-ota>` 时，分区表应包含 ``tee_0`` 和 ``tee_1``，通过 TEE OTA 数据分区，可以配置引导加载程序应启动的 TEE 应用分区。详情请参阅 :doc:`TEE OTA <../security/tee/tee-ota>`。
+
 * 当 Type 定义为 ``bootloader`` 时，可以将 SubType 字段指定为：
 
     - ``primary`` (0x00)，即二级引导加载程序，位于 flash 的 {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH} 地址处。工具会自动确定此子类型的适当大小和偏移量，因此为此子类型指定的任何大小或偏移量将被忽略。你可以将这些字段留空或使用 ``N/A`` 作为占位符。
@@ -171,6 +181,11 @@ SubType 字段长度为 8 bit，内容与具体分区 Type 有关。目前，ESP
         -  用于存储加密密钥（如果启用了 `NVS 加密` 功能）。
         -  此分区应至少设定为 4096 字节。
 
+.. only:: esp32c6
+
+    - ``tee-ota`` (0x90) 是 :ref:`TEE OTA 数据分区 <tee-ota-data-partition>`，用于存储所选 TEE OTA 应用分区的信息。此分区大小应为 0x2000 字节。详情请参阅 :doc:`TEE OTA <../security/tee/tee-ota>`。
+    - ``tee_sec_stg`` (0x91) 是 TEE 安全存储分区，用于存储仅能被 TEE 应用程序访问的加密数据。:doc:`TEE 安全存储 <../security/tee/tee-sec-storage>` 将使用此分区存储包括加密密钥在内的敏感数据。此分区大小取决于具体的应用需求。
+
     - ESP-IDF 还支持其他用于数据存储的预定义子类型，包括：
 
         - ``coredump`` (0x03) 用于在使用自定义分区表 CSV 文件时存储核心转储，详情请参阅 :doc:`/api-guides/core_dump`。

docs/zh_CN/contribute/esp-idf-tests-with-pytest.rst

@@ -481,6 +481,8 @@ CI 的工作流程如下所示：
 
 板载测试任务中的二进制文件是从内部 MinIO 服务器下载的。对于大多数测试用例，仅下载烧录所需的文件（如 .bin 文件、flash_args 文件等）。对于某些测试用例，如 jtag 测试用例，还会下载 .elf 文件。
 
+.. _run_the_tests_locally:
+
 本地测试
 ==========
 

docs/zh_CN/security/index.rst

@@ -18,6 +18,7 @@
    flash-encryption
    :esp32: secure-boot-v1
    secure-boot-v2
+   :esp32c6: tee/index
 
 流程
 ---------

docs/zh_CN/security/tee/index.rst

@@ -0,0 +1 @@
+.. include:: ../../../en/security/tee/index.rst

docs/zh_CN/security/tee/tee-advanced.rst

@@ -0,0 +1 @@
+.. include:: ../../../en/security/tee/tee-advanced.rst

docs/zh_CN/security/tee/tee-attestation.rst

@@ -0,0 +1 @@
+.. include:: ../../../en/security/tee/tee-attestation.rst

docs/zh_CN/security/tee/tee-ota.rst

@@ -0,0 +1 @@
+.. include:: ../../../en/security/tee/tee-ota.rst

docs/zh_CN/security/tee/tee-sec-storage.rst

@@ -0,0 +1 @@
+.. include:: ../../../en/security/tee/tee-sec-storage.rst

docs/zh_CN/security/tee/tee.rst

@@ -0,0 +1 @@
+.. include:: ../../../en/security/tee/tee.rst