|
|
|
|
@@ -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
|
|
|
|
|
-----
|
|
|
|
|
|
Mahavir Jain