feedc0de/esp-idf
1
0
Fork 0
forked from espressif/esp-idf
Code Pull Requests Activity

docs(esp_tee): Enable ESP-TEE documentation for ESP32-C61

Browse Source
This commit is contained in:
Laukik Hase
2025-11-11 14:37:00 +05:30
parent b6a51f0ff6
commit 7a1ab62cf7
5 changed files with 46 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/conf_common.py
+1 -1
View File
@@ -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',
docs/doxygen/Doxyfile_esp32c61
+4
View File
@@ -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 \
docs/en/security/index.rst
+1 -1
View File
@@ -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
docs/en/security/tee/tee-sec-storage.rst
+39 -8
View File
@@ -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 <nvs_encr_hmac_scheme>`. 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 <nvs_encr_flash_enc_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 <nvs_encr_hmac_scheme>`. 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 <nvs_encr_flash_enc_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 <nvs_encr_flash_enc_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 <BLOCK_KEY0-5> hmac_key_file.bin HMAC_UP
espefuse -p PORT burn-key <BLOCK_KEY0-5> 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 <BLOCK_KEY0-5> 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
-----
docs/zh_CN/security/index.rst
+1 -1
View File
@@ -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