From 7a1ab62cf72b137e1c561951c320fe5eb46e5bd7 Mon Sep 17 00:00:00 2001 From: Laukik Hase Date: Tue, 11 Nov 2025 14:37:00 +0530 Subject: [PATCH] docs(esp_tee): Enable ESP-TEE documentation for ESP32-C61 --- docs/conf_common.py | 2 +- docs/doxygen/Doxyfile_esp32c61 | 4 ++ docs/en/security/index.rst | 2 +- docs/en/security/tee/tee-sec-storage.rst | 47 ++++++++++++++++++++---- docs/zh_CN/security/index.rst | 2 +- 5 files changed, 46 insertions(+), 11 deletions(-) diff --git a/docs/conf_common.py b/docs/conf_common.py index b6feb4a241..48f608f56f 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -309,7 +309,7 @@ ESP32C61_DOCS = [ 'api-guides/phy.rst', 'api-reference/peripherals/sd_pullup_requirements.rst', 'api-guides/RF_calibration.rst', -] +] + ESP_TEE_DOCS ESP32C6_DOCS = [ 'api-guides/RF_calibration.rst', diff --git a/docs/doxygen/Doxyfile_esp32c61 b/docs/doxygen/Doxyfile_esp32c61 index 74f603a122..674784e580 100644 --- a/docs/doxygen/Doxyfile_esp32c61 +++ b/docs/doxygen/Doxyfile_esp32c61 @@ -5,3 +5,7 @@ INPUT += \ $(PROJECT_PATH)/components/bt/include/esp32c6/include/esp_bt_vs.h \ $(PROJECT_PATH)/components/esp_phy/include/esp_phy_init.h \ $(PROJECT_PATH)/components/esp_phy/include/esp_phy_cert_test.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 \ diff --git a/docs/en/security/index.rst b/docs/en/security/index.rst index 9a108e9302..96529124c1 100644 --- a/docs/en/security/index.rst +++ b/docs/en/security/index.rst @@ -10,6 +10,6 @@ Security Guides flash-encryption :esp32: secure-boot-v1 secure-boot-v2 - :esp32c6 or esp32c5: tee/index + :esp32c6 or esp32c5 or esp32c61: tee/index security-features-enablement-workflows vulnerabilities diff --git a/docs/en/security/tee/tee-sec-storage.rst b/docs/en/security/tee/tee-sec-storage.rst index 22c37b11f8..c3c0e88055 100644 --- a/docs/en/security/tee/tee-sec-storage.rst +++ b/docs/en/security/tee/tee-sec-storage.rst @@ -5,12 +5,18 @@ Overview -------- The TEE Secure Storage service provides persistent storage for securely storing sensitive data, such as cryptographic keys, cloud credentials, or other general-purpose information. It uses a dedicated flash partition of type ``data`` and subtype ``nvs``. The TEE ensures both confidentiality and integrity of the stored data. -TEE Secure Storage adopts the :doc:`../../api-reference/storage/nvs_flash` partition format and uses the HMAC peripheral-based XTS-AES encryption scheme, as detailed :ref:`here `. The AES encryption keys are derived from an HMAC key programmed in eFuse with the purpose :cpp:enumerator:`esp_efuse_purpose_t::ESP_EFUSE_KEY_PURPOSE_HMAC_UP`. Please note that the TEE Secure storage does not support the :ref:`NVS Flash Encryption-based scheme `. +.. only:: SOC_HMAC_SUPPORTED + + TEE Secure Storage adopts the :doc:`../../api-reference/storage/nvs_flash` partition format and uses the HMAC peripheral-based XTS-AES encryption scheme, as detailed :ref:`here `. The AES encryption keys are derived from an HMAC key programmed in eFuse with the purpose :cpp:enumerator:`esp_efuse_purpose_t::ESP_EFUSE_KEY_PURPOSE_HMAC_UP`. Please note that the TEE Secure storage does not support the :ref:`NVS Flash Encryption-based scheme `. + +.. only:: not SOC_HMAC_SUPPORTED + + TEE Secure Storage adopts the :doc:`../../api-reference/storage/nvs_flash` partition format and uses the HMAC-based XTS-AES encryption scheme. There is, however, an important difference in how the HMAC step is handled. Since {IDF_TARGET_NAME} lacks a hardware HMAC peripheral, the HMAC computation is carried out in software with assistance from the SHA peripheral.The AES encryption keys are derived from an eFuse key with the purpose :cpp:enumerator:`esp_efuse_purpose_t::ESP_EFUSE_KEY_PURPOSE_USER`. Please note that the TEE Secure storage does not support the :ref:`NVS Flash Encryption-based scheme `. .. important:: - One eFuse block is required to store the HMAC key used for deriving the NVS encryption keys. This key is exclusive to the TEE and **CANNOT** be used by the REE for any purpose. - - The HMAC key must be programmed into eFuse before firmware execution, as TEE Secure Storage does not support generating it on-device. If no valid key with the required purpose is found in the configured eFuse block, an error will be raised at runtime. + - The required key must be programmed into eFuse before firmware execution, as TEE Secure Storage does not support generating it on-device. If no valid key with the required purpose is found in the configured eFuse block, an error will be raised at runtime. Additionally, the secure storage provides interfaces for performing the following cryptographic services from the TEE using securely stored key material: @@ -21,12 +27,14 @@ Additionally, the secure storage provides interfaces for performing the followin As per the current implementation, the TEE Secure Storage partition **must** have the label ``secure_storage``. -TEE secure storage also supports ECDSA signing with keys derived via PBKDF2 (Password-Based Key Derivation Function 2), using an HMAC key programmed in eFuse along with a user-provided salt. This mechanism enables ECDSA signing on both P-256 and P-192 curves without requiring storage of the actual private keys. The eFuse HMAC key ID for the PBKDF2 operations is specified via the :ref:`CONFIG_SECURE_TEE_PBKDF2_EFUSE_HMAC_KEY_ID` option. +.. only:: SOC_HMAC_SUPPORTED -.. important:: + TEE secure storage also supports ECDSA signing with keys derived via PBKDF2 (Password-Based Key Derivation Function 2), using an HMAC key programmed in eFuse along with a user-provided salt. This mechanism enables ECDSA signing on both P-256 and P-192 curves without requiring storage of the actual private keys. The eFuse HMAC key ID for the PBKDF2 operations is specified via the :ref:`CONFIG_SECURE_TEE_PBKDF2_EFUSE_HMAC_KEY_ID` option. - - The eFuse HMAC key ID used for PBKDF2-based signing **CANNOT** be the same as the one used for deriving TEE secure storage encryption keys (i.e., :ref:`CONFIG_SECURE_TEE_SEC_STG_EFUSE_HMAC_KEY_ID`). - - This eFuse ID is also exclusive to the TEE and **CANNOT** be used by the REE for any purpose. + .. important:: + + - The eFuse HMAC key ID used for PBKDF2-based signing **CANNOT** be the same as the one used for deriving TEE secure storage encryption keys (i.e., :ref:`CONFIG_SECURE_TEE_SEC_STG_EFUSE_HMAC_KEY_ID`). + - This eFuse ID is also exclusive to the TEE and **CANNOT** be used by the REE for any purpose. Internals --------- @@ -47,7 +55,9 @@ All assets related to TEE secure storage are protected by the APM peripheral and The TEE Secure Storage feature supports two modes for determining how the NVS encryption keys are derived (see :ref:`CONFIG_SECURE_TEE_SEC_STG_MODE`): - **Development** Mode: Encryption keys are embedded (constant for all instances) in the ESP-TEE firmware. - - **Release** Mode: Encryption keys are derived via the HMAC peripheral using a key stored in eFuse, specified by :ref:`CONFIG_SECURE_TEE_SEC_STG_EFUSE_HMAC_KEY_ID`. + - **Release** Mode: Encryption keys are derived via the HMAC peripheral (or software-based HMAC implementation) using a key stored in eFuse, specified by :ref:`CONFIG_SECURE_TEE_SEC_STG_EFUSE_HMAC_KEY_ID`. + +.. only:: SOC_HMAC_SUPPORTED .. note:: @@ -61,7 +71,28 @@ The TEE Secure Storage feature supports two modes for determining how the NVS en openssl rand -out hmac_key_file.bin 32 # Program the HMAC key into the eFuse block - idf.py -p PORT efuse-burn-key hmac_key_file.bin HMAC_UP + espefuse -p PORT burn-key hmac_key_file.bin HMAC_UP + +.. only:: not SOC_HMAC_SUPPORTED + + .. note:: + + - The valid range for :ref:`CONFIG_SECURE_TEE_SEC_STG_EFUSE_HMAC_KEY_ID` is from ``0`` (:cpp:enumerator:`esp_efuse_block_t::EFUSE_BLK_KEY0`) to ``5`` (:cpp:enumerator:`esp_efuse_block_t::EFUSE_BLK_KEY5`). By default, this config is set to ``-1`` and must be configured before building the TEE application. + + - The following commands can be used to generate and program the USER purpose key into the required eFuse block: + + :: + + # Generate a random 32-byte key + openssl rand -out hmac_key_file.bin 32 + + # Program the USER purpose key into the eFuse block + espefuse -p PORT burn-key --no-read-protect hmac_key_file.bin USER + + .. warning:: + + - When programming the key into eFuse, ensure that it is **NOT** marked as read-protected (use the ``--no-read-protect`` flag). If the key is read-protected, the TEE will be unable to access it. + - However, this does not weaken security: the APM peripheral already blocks software access to the key, and any illegal read or write attempt from the REE triggers a fault. Tools ----- diff --git a/docs/zh_CN/security/index.rst b/docs/zh_CN/security/index.rst index da5da3dd41..556270dc27 100644 --- a/docs/zh_CN/security/index.rst +++ b/docs/zh_CN/security/index.rst @@ -10,6 +10,6 @@ flash-encryption :esp32: secure-boot-v1 secure-boot-v2 - :esp32c6 or esp32c5: tee/index + :esp32c6 or esp32c5 or esp32c61: tee/index security-features-enablement-workflows vulnerabilities