You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: components/esp_tee/test_apps/tee_cli_app/README.md
+11-8Lines changed: 11 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -15,18 +15,21 @@ This example can be executed on any development board with a Espressif SOC chip
15
15
16
16
- Open the project configuration menu (`idf.py menuconfig`).
17
17
18
-
- Configure the secure storage slot ID for generating/fetching the ECDSA keypair for attestation token signing at `(Top) → Security features → TEE: Secure Storage slot ID for EAT signing`. If this configuration is not set, the slot with ID **0** will be used as default.
18
+
- Configure the secure storage key ID for generating/fetching the ECDSA keypair for attestation token signing at `ESP-TEE (Trusted Execution Environment) → Secure Services → Attestation: Secure Storage key ID for EAT signing`.
19
19
20
-
- Configure the Secure Storage mode for determining which eFuse block stores the encryption key at `(Top) → Security features → Trusted Execution Environment → TEE: Secure Storage Mode`.
21
-
-**Development** Mode: The encryption key is statically embedded in the TEE firmware.
22
-
-**Release** Mode: The encryption key is stored in eFuse BLK4 - BLK9, depending on the `SECURE_TEE_SEC_STG_KEY_EFUSE_BLK` Kconfig option.
23
-
- Set the eFuse block ID to store the encryption key in `Security features → Trusted Execution Environment → TEE: Secure Storage encryption key eFuse block`.
20
+
Configure the Secure Storage mode for determining how the NVS XTS encryption keys are derived at `ESP-TEE (Trusted Execution Environment) → Secure Services → Secure Storage: Mode`
21
+
22
+
-**Development** Mode: Encryption keys are embedded in the ESP-TEE firmware (identical across all instances).
23
+
-**Release** Mode: Encryption keys are derived via the HMAC peripheral using a key stored in eFuse.
24
+
- Set the eFuse key ID storing the HMAC key at `ESP-TEE (Trusted Execution Environment) → Secure Services → Secure Storage: eFuse HMAC key ID`.
24
25
- Snippet for burning the secure storage key in eFuse is given below.
25
26
26
27
```shell
27
-
# Programming user key (256-bit) in eFuse
28
+
# Generate a random 32-byte HMAC key
29
+
openssl rand -out hmac_key_file.bin 32
30
+
# Programming the HMAC key (256-bit) in eFuse
28
31
# Here, BLOCK_KEYx is a free eFuse key-block between BLOCK_KEY0 and BLOCK_KEY5
29
-
espefuse.py -p PORT burn_key BLOCK_KEYx user_key.bin USER
32
+
espefuse.py -p PORT burn_key BLOCK_KEYx hmac_key_file.bin HMAC_UP
30
33
```
31
34
32
35
### Build and Flash
@@ -121,7 +124,7 @@ help [<string>] [-v <0|1>]
121
124
esp32c6> tee_att_info
122
125
I (8180) tee_attest: Attestation token - Length: 1455
Copy file name to clipboardExpand all lines: docs/en/api-guides/partition-tables.rst
-1Lines changed: 0 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -185,7 +185,6 @@ See enum :cpp:type:`esp_partition_subtype_t` for the full list of subtypes defin
185
185
.. only:: esp32c6
186
186
187
187
- ``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.
188
-
- ``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.
189
188
190
189
- There are other predefined data subtypes for data storage supported by ESP-IDF. These include:
Copy file name to clipboardExpand all lines: docs/en/api-reference/storage/nvs_encryption.rst
+3Lines changed: 3 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,6 +14,7 @@ Data stored in NVS partitions can be encrypted using XTS-AES in the manner simil
14
14
15
15
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.
16
16
17
+
.. _nvs_encr_flash_enc_scheme:
17
18
18
19
NVS Encryption: Flash Encryption-Based Scheme
19
20
---------------------------------------------
@@ -104,6 +105,8 @@ It is possible for an application to use different keys for different NVS partit
Copy file name to clipboardExpand all lines: docs/en/security/tee/tee-sec-storage.rst
+36-69Lines changed: 36 additions & 69 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,105 +3,72 @@ Secure Storage
3
3
4
4
Overview
5
5
--------
6
+
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.
6
7
7
-
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.
8
+
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>`.
8
9
9
-
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:
10
+
.. important::
10
11
11
-
#. Message signing and public key retrieval with the ``ecdsa_secp256r1`` algorithm
12
-
#. Authenticated encryption and decryption using the ``aes256_gcm`` algorithm
12
+
- 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.
13
+
- 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.
13
14
14
-
Internals
15
-
---------
15
+
Additionally, the secure storage provides interfaces for performing the following cryptographic services from the TEE using securely stored key material:
16
16
17
-
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.
17
+
#. Message signing and public key retrieval using the ``ecdsa_secp256r1`` and ``ecdsa_secp192r1`` algorithms
18
+
#. Authenticated encryption and decryption using the ``aes256_gcm`` algorithm
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.
22
+
As per the current implementation, the TEE Secure Storage partition **must** have the label ``secure_storage``.
28
23
29
-
.. list-table::
30
-
:header-rows: 1
31
-
:widths: 35 65
32
-
:align: center
24
+
Internals
25
+
---------
33
26
34
-
* - **Element**
35
-
- **Description**
36
-
* - Owner ID
37
-
- Application ID defining the data ownership
38
-
* - Slot ID
39
-
- Slot ID for corresponding owner ID
40
-
* - Encryption: Initialization Vector (IV)
41
-
- IV for the encryption algorithm
42
-
* - Encryption: Tag
43
-
- Tag for the encryption algorithm
44
-
* - Data Type
45
-
- Type of data stored in this slot
46
-
* - Data Length
47
-
- Actual data length
27
+
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.
As per the current implementation, all data objects in the TEE Secure Storage are to be stored in the ``tee_sec_stg_ns`` namespace.
56
32
57
-
.. warning::
33
+
Currently, TEE secure storage supports storing the following cryptographic keys:
58
34
59
-
Future ESP-TEE framework releases may modify the internal data structure of the TEE secure storage, which could introduce breaking changes in existing applications.
35
+
#. ``ecdsa_secp256r1`` and ``ecdsa_secp192r1`` curve key-pairs, including private and public key components
36
+
#. ``aes256`` keys, including the key and initialization vector (IV)
60
37
61
-
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.
38
+
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.
62
39
63
-
The TEE Secure Storage feature supports two modes (:ref:`CONFIG_SECURE_TEE_SEC_STG_MODE`) for determining which eFuse block stores the encryption key:
40
+
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`):
64
41
65
-
- **Development** Mode: The encryption key is embedded (constant for all instances) in the ESP-TEE firmware.
66
-
- **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.
42
+
- **Development** Mode: Encryption keys are embedded (constant for all instances) in the ESP-TEE firmware.
43
+
- **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`.
67
44
68
-
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.
45
+
.. note::
69
46
70
-
.. note::
47
+
- 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.
71
48
72
-
- Currently, the TEE secure storage supports the storage of two types of cryptographic keys:
49
+
- The following commands can be used to generate and program the HMAC key into the required eFuse block:
73
50
74
-
#. ``ecdsa_secp256r1`` curve key-pairs, including the private and public key components
75
-
#. ``aes256_gcm`` keys, including the key and initialization vector (IV)
51
+
::
76
52
77
-
The internal structures for these key types are as follows:
53
+
# Generate a random 32-byte HMAC key
54
+
openssl rand -out hmac_key_file.bin 32
78
55
79
-
.. code-block:: c
56
+
# Program the HMAC key into the eFuse block
57
+
idf.py -p PORT efuse-burn-key <BLOCK_KEY0-5> hmac_key_file.bin HMAC_UP
80
58
81
-
#define ECDSA_SECP256R1_KEY_LEN 32
82
-
#define AES256_GCM_KEY_LEN 32
83
-
#define AES256_GCM_IV_LEN 12
59
+
Tools
60
+
-----
84
61
85
-
typedef struct {
86
-
/* Private key */
87
-
uint8_t priv_key[ECDSA_SECP256R1_KEY_LEN];
88
-
/* Public key - X and Y components */
89
-
uint8_t pub_key[2 * ECDSA_SECP256R1_KEY_LEN];
90
-
} sec_stg_ecdsa_secp256r1_t;
62
+
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.
91
63
92
-
typedef struct {
93
-
/* Key */
94
-
uint8_t key[AES256_GCM_KEY_LEN];
95
-
/* Initialization Vector */
96
-
uint8_t iv[AES256_GCM_IV_LEN];
97
-
} sec_stg_aes256_gcm_t;
64
+
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.
98
65
99
-
- Future updates may include support for additional key types and general-purpose data storage.
66
+
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.
100
67
101
68
Application Example
102
69
-------------------
103
70
104
-
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.
71
+
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.
Copy file name to clipboardExpand all lines: docs/zh_CN/api-guides/partition-tables.rst
-1Lines changed: 0 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -185,7 +185,6 @@ SubType 字段长度为 8 bit，内容与具体分区 Type 有关。目前，ESP
185
185
.. only:: esp32c6
186
186
187
187
- ``tee-ota`` (0x90) 是 :ref:`TEE OTA 数据分区 <tee-ota-data-partition>`，用于存储所选 TEE OTA 应用分区的信息。此分区大小应为 0x2000 字节。详情请参阅 :doc:`TEE OTA <../security/tee/tee-ota>`。
188
-
- ``tee_sec_stg`` (0x91) 是 TEE 安全存储分区，用于存储仅能被 TEE 应用程序访问的加密数据。:doc:`TEE 安全存储 <../security/tee/tee-sec-storage>` 将使用此分区存储包括加密密钥在内的敏感数据。此分区大小取决于具体的应用需求。
0 commit comments