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

Merge branch 'refactor/esp_tee_sec_stg' into 'master'

Browse Source 
refactor(esp_tee): Revamp the TEE Secure Storage format

Closes IDF-9180

See merge request espressif/esp-idf!36878
This commit is contained in:
Laukik Hase
2025-05-07 13:40:06 +08:00
parent e0da61caea c16fc04c2d
commit 7411eafb2e
69 changed files with 1968 additions and 1197 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/en/api-guides/partition-tables.rst
-1
View File
@@ -185,7 +185,6 @@ See enum :cpp:type:`esp_partition_subtype_t` for the full list of subtypes defin
.. 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:
docs/en/api-reference/storage/nvs_encryption.rst
+3
View File
@@ -14,6 +14,7 @@ Data stored in NVS partitions can be encrypted using XTS-AES in the manner simil
NVS encryption can be facilitated by enabling :ref:`CONFIG_NVS_ENCRYPTION` and :ref:`CONFIG_NVS_SEC_KEY_PROTECTION_SCHEME` > ``CONFIG_NVS_SEC_KEY_PROTECT_USING_FLASH_ENC`` or ``CONFIG_NVS_SEC_KEY_PROTECT_USING_HMAC`` depending on the scheme to be used.
.. _nvs_encr_flash_enc_scheme:
NVS Encryption: Flash Encryption-Based Scheme
---------------------------------------------
@@ -104,6 +105,8 @@ It is possible for an application to use different keys for different NVS partit
.. only:: SOC_HMAC_SUPPORTED
.. _nvs_encr_hmac_scheme:
NVS Encryption: HMAC Peripheral-Based Scheme
--------------------------------------------
docs/en/security/tee/tee-attestation.rst
+2 -2
View File
@@ -88,7 +88,7 @@ EAT: Header
- 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
- TEE secure storage key ID (string)
EAT: Claim Table
^^^^^^^^^^^^^^^^
@@ -173,7 +173,7 @@ Sample EAT in JSON format
"magic": "44fef7cc",
"encr_alg": "",
"sign_alg": "ecdsa_secp256r1_sha256",
"key_id": 0
"key_id": "tee_att_key0"
},
"eat": {
"nonce": -1582119980,
docs/en/security/tee/tee-sec-storage.rst
+45 -78
View File
@@ -3,105 +3,72 @@ Secure Storage
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.
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.
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>`.
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:
.. important::
#. Message signing and public key retrieval with the ``ecdsa_secp256r1`` algorithm
#. Authenticated encryption and decryption using the ``aes256_gcm`` algorithm
- 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.
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 using the ``ecdsa_secp256r1`` and ``ecdsa_secp192r1`` algorithms
#. Authenticated encryption and decryption using the ``aes256_gcm`` algorithm
.. note::
As per the current implementation, the TEE Secure Storage partition **must** have the label ``secure_storage``.
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.
Each data object consisting of the type, associated metadata flags (e.g., ``WRITE_ONCE``), and the actual payload is encapsulated in a structured format and stored as a variable-length NVS blob in the secure storage partition.
.. note::
- Currently, the TEE secure storage supports the storage of two types of cryptographic keys:
As per the current implementation, all data objects in the TEE Secure Storage are to be stored in the ``tee_sec_stg_ns`` namespace.
#. ``ecdsa_secp256r1`` curve key-pairs, including the private and public key components
#. ``aes256_gcm`` keys, including the key and initialization vector (IV)
Currently, TEE secure storage supports storing the following cryptographic keys:
The internal structures for these key types are as follows:
#. ``ecdsa_secp256r1`` and ``ecdsa_secp192r1`` curve key-pairs, including private and public key components
#. ``aes256`` keys, including the key and initialization vector (IV)
.. code-block:: c
All assets related to TEE secure storage are protected by the APM peripheral and are inaccessible to the REE application. Any direct access attempts will result in a system fault. Future updates are planned to add support for additional key types and general-purpose data storage.
#define ECDSA_SECP256R1_KEY_LEN 32
#define AES256_GCM_KEY_LEN 32
#define AES256_GCM_IV_LEN 12
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`):
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;
- **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`.
typedef struct {
/* Key */
uint8_t key[AES256_GCM_KEY_LEN];
/* Initialization Vector */
uint8_t iv[AES256_GCM_IV_LEN];
} sec_stg_aes256_gcm_t;
.. note::
- Future updates may include support for additional key types and general-purpose data storage.
- The valid range for :ref:`CONFIG_SECURE_TEE_SEC_STG_EFUSE_HMAC_KEY_ID` is from ``0`` (:cpp:enumerator:`hmac_key_id_t::HMAC_KEY0`) to ``5`` (:cpp:enumerator:`hmac_key_id_t::HMAC_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 HMAC key into the required eFuse block:
::
# Generate a random 32-byte HMAC key
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
Tools
-----
The :doc:`../../api-reference/storage/nvs_partition_gen` tool can be used to generate binary images compatible with the NVS format for use with TEE Secure Storage. Since TEE Secure Storage stores data objects using a custom structured format, an additional step is required to convert input data into this format prior to image generation and encryption.
To support this process, the :component_file:`esp_tee_sec_stg_keygen.py<esp_tee/scripts/esp_tee_sec_stg_keygen/esp_tee_sec_stg_keygen.py>` script is provided for generating secure key blobs corresponding to the various supported cryptographic algorithms. These key blobs are then referenced in the input CSV file (format described :ref:`here <nvs-csv-file-format>`) and passed to the NVS Partition Generator utility to produce an encrypted images suitable for TEE Secure Storage.
Refer the detailed steps given :component_file:`here<esp_tee/scripts/esp_tee_sec_stg_keygen/README.md>` on generating key blobs and encrypted NVS partition images for TEE Secure 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.
The :example:`tee_secure_storage <security/tee/tee_secure_storage>` example demonstrates how to generate ECDSA key pairs and AES-256 keys in the TEE secure storage and use them for signing messages and encrypting/decrypting data.
API Reference
-------------
docs/en/security/tee/tee.rst
+1 -1
View File
@@ -96,7 +96,7 @@ 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,
secure_storage, data, nvs, 0x40000, 64K,
factory, app, factory, 0x50000, 1M,
nvs, data, nvs, 0x150000, 24K,
phy_init, data, phy, 0x156000, 4K,