forked from espressif/esp-idf
docs(esp_tee): Revise TEE secure storage and related documentation
This commit is contained in:
Laukik Hase
@ -15,18 +15,21 @@ This example can be executed on any development board with a Espressif SOC chip
|
||||
|
||||
- Open the project configuration menu (`idf.py menuconfig`).
|
||||
|
||||
- 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.
|
||||
- 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`.
|
||||
|
||||
- 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`.
|
||||
- **Development** Mode: The encryption key is statically embedded in the TEE firmware.
|
||||
- **Release** Mode: The encryption key is stored in eFuse BLK4 - BLK9, depending on the `SECURE_TEE_SEC_STG_KEY_EFUSE_BLK` Kconfig option.
|
||||
- Set the eFuse block ID to store the encryption key in `Security features → Trusted Execution Environment → TEE: Secure Storage encryption key eFuse block`.
|
||||
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`
|
||||
|
||||
- **Development** Mode: Encryption keys are embedded in the ESP-TEE firmware (identical across all instances).
|
||||
- **Release** Mode: Encryption keys are derived via the HMAC peripheral using a key stored in eFuse.
|
||||
- Set the eFuse key ID storing the HMAC key at `ESP-TEE (Trusted Execution Environment) → Secure Services → Secure Storage: eFuse HMAC key ID`.
|
||||
- Snippet for burning the secure storage key in eFuse is given below.
|
||||
|
||||
```shell
|
||||
# Programming user key (256-bit) in eFuse
|
||||
# Generate a random 32-byte HMAC key
|
||||
openssl rand -out hmac_key_file.bin 32
|
||||
# Programming the HMAC key (256-bit) in eFuse
|
||||
# Here, BLOCK_KEYx is a free eFuse key-block between BLOCK_KEY0 and BLOCK_KEY5
|
||||
espefuse.py -p PORT burn_key BLOCK_KEYx user_key.bin USER
|
||||
espefuse.py -p PORT burn_key BLOCK_KEYx hmac_key_file.bin HMAC_UP
|
||||
```
|
||||
|
||||
### Build and Flash
|
||||
@ -121,7 +124,7 @@ help [<string>] [-v <0|1>]
|
||||
esp32c6> tee_att_info
|
||||
I (8180) tee_attest: Attestation token - Length: 1455
|
||||
I (8180) tee_attest: Attestation token - Data:
|
||||
'{"header":{"magic":"44fef7cc","encr_alg":"","sign_alg":"ecdsa_secp256r1_sha256","key_id":0},"eat":{"nonce":-1582119980,"client_id":262974944,"device_ver":0,"device_id":"cd9c173cb3675c7adfae243f0cd9841e4bce003237cb5321927a85a86cb4b32e","instance_id":"9616ef0ecf02cdc89a3749f8fc16b3103d5100bd42d9312fcd04593baa7bac64","psa_cert_ref":"0716053550477-10100","device_status":165,"sw_claims":{"tee":{"type":1,"ver":"v0.3.0","idf_ver":"v5.1.4-241-g7ff01fd46f-dirty","secure_ver":0,"part_chip_rev":{"min":0,"max":99},"part_digest":{"type":0,"calc_digest":"94536998e1dcb2a036477cb2feb01ed4fff67ba6208f30482346c62bca64b280","digest_validated":true,"sign_verified":true}},"app":{"type":2,"ver":"v0.1.0","idf_ver":"v5.1.4-241-g7ff01fd46f-dirty","secure_ver":0,"part_chip_rev":{"min":0,"max":99},"part_digest":{"type":0,"calc_digest":"3d4c038fcec76852b4d07acb9e94afaf5fca69fc2eb212a32032d09ce5b4f2b3","digest_validated":true,"sign_verified":true,"secure_padding":true}},"bootloader":{"type":0,"ver":"","idf_ver":"","secure_ver":-1,"part_chip_rev":{"min":0,"max":99},"part_digest":{"type":0,"calc_digest":"1bef421beb1a4642c6fcefb3e37fd4afad60cb4074e538f42605b012c482b946","digest_validated":true,"sign_verified":true}}}},"public_key":{"compressed":"02039c4bfab0762af1aff2fe5596b037f629cf839da8c4a9c0018afedfccf519a6"},"sign":{"r":"915e749f5a780bc21a2b21821cfeb54286dc742e9f12f2387e3de9b8b1a70bc9","s":"1e583236f2630b0fe8e291645ffa35d429f14035182e19868508d4dac0e1a441"}}'
|
||||
'{"header":{"magic":"44fef7cc","encr_alg":"","sign_alg":"ecdsa_secp256r1_sha256","key_id":"tee_att_key0"},"eat":{"nonce":-1582119980,"client_id":262974944,"device_ver":0,"device_id":"cd9c173cb3675c7adfae243f0cd9841e4bce003237cb5321927a85a86cb4b32e","instance_id":"9616ef0ecf02cdc89a3749f8fc16b3103d5100bd42d9312fcd04593baa7bac64","psa_cert_ref":"0716053550477-10100","device_status":165,"sw_claims":{"tee":{"type":1,"ver":"v0.3.0","idf_ver":"v5.1.4-241-g7ff01fd46f-dirty","secure_ver":0,"part_chip_rev":{"min":0,"max":99},"part_digest":{"type":0,"calc_digest":"94536998e1dcb2a036477cb2feb01ed4fff67ba6208f30482346c62bca64b280","digest_validated":true,"sign_verified":true}},"app":{"type":2,"ver":"v0.1.0","idf_ver":"v5.1.4-241-g7ff01fd46f-dirty","secure_ver":0,"part_chip_rev":{"min":0,"max":99},"part_digest":{"type":0,"calc_digest":"3d4c038fcec76852b4d07acb9e94afaf5fca69fc2eb212a32032d09ce5b4f2b3","digest_validated":true,"sign_verified":true,"secure_padding":true}},"bootloader":{"type":0,"ver":"","idf_ver":"","secure_ver":-1,"part_chip_rev":{"min":0,"max":99},"part_digest":{"type":0,"calc_digest":"1bef421beb1a4642c6fcefb3e37fd4afad60cb4074e538f42605b012c482b946","digest_validated":true,"sign_verified":true}}}},"public_key":{"compressed":"02039c4bfab0762af1aff2fe5596b037f629cf839da8c4a9c0018afedfccf519a6"},"sign":{"r":"915e749f5a780bc21a2b21821cfeb54286dc742e9f12f2387e3de9b8b1a70bc9","s":"1e583236f2630b0fe8e291645ffa35d429f14035182e19868508d4dac0e1a441"}}'
|
||||
|
||||
```
|
||||
|
||||
|
||||
BIN
docs/_static/esp_tee/tee_sec_stg_metadata.png
vendored
BIN
docs/_static/esp_tee/tee_sec_stg_metadata.png
vendored
Binary file not shown.
|
Before Width: | Height: | Size: 31 KiB |
BIN
docs/_static/esp_tee/tee_sec_stg_part.png
vendored
BIN
docs/_static/esp_tee/tee_sec_stg_part.png
vendored
Binary file not shown.
|
Before Width: | Height: | Size: 28 KiB |
@ -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:
|
||||
|
||||
|
||||
@ -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
|
||||
--------------------------------------------
|
||||
|
||||
|
||||
@ -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,
|
||||
|
||||
@ -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
|
||||
-------------
|
||||
|
||||
@ -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,
|
||||
|
||||
@ -185,7 +185,6 @@ SubType 字段长度为 8 bit，内容与具体分区 Type 有关。目前，ESP
|
||||
.. only:: esp32c6
|
||||
|
||||
- ``tee-ota`` (0x90) 是 :ref:`TEE OTA 数据分区 <tee-ota-data-partition>`，用于存储所选 TEE OTA 应用分区的信息。此分区大小应为 0x2000 字节。详情请参阅 :doc:`TEE OTA <../security/tee/tee-ota>`。
|
||||
- ``tee_sec_stg`` (0x91) 是 TEE 安全存储分区，用于存储仅能被 TEE 应用程序访问的加密数据。:doc:`TEE 安全存储 <../security/tee/tee-sec-storage>` 将使用此分区存储包括加密密钥在内的敏感数据。此分区大小取决于具体的应用需求。
|
||||
|
||||
- ESP-IDF 还支持其他用于数据存储的预定义子类型，包括：
|
||||
|
||||
|
||||
@ -14,6 +14,7 @@ NVS 加密
|
||||
|
||||
根据要使用的具体方案，可以选择启用 :ref:`CONFIG_NVS_ENCRYPTION` 和 :ref:`CONFIG_NVS_SEC_KEY_PROTECTION_SCHEME` > ``CONFIG_NVS_SEC_KEY_PROTECT_USING_FLASH_ENC`` 或 ``CONFIG_NVS_SEC_KEY_PROTECT_USING_HMAC`` 实现 NVS 加密。
|
||||
|
||||
.. _nvs_encr_flash_enc_scheme:
|
||||
|
||||
NVS 加密：基于 flash 加密的方案
|
||||
-------------------------------------
|
||||
@ -104,6 +105,8 @@ NVS 密钥分区
|
||||
|
||||
.. only:: SOC_HMAC_SUPPORTED
|
||||
|
||||
.. _nvs_encr_hmac_scheme:
|
||||
|
||||
NVS 加密：基于 HMAC 外设的方案
|
||||
--------------------------------------------
|
||||
|
||||
|
||||
@ -12,7 +12,7 @@
|
||||
- Digest (SHA256)
|
||||
- Public key corresponding to the private key used for signing (in compressed format)
|
||||
- Signature (`r` and `s` components)
|
||||
- The token is signed using the ECDSA key stored in the designated slot ID of the TEE's Secure Storage. Subsequently, the resulting token is handed back to the REE in the output buffer specified in the secure service call.
|
||||
- The token is signed using the ECDSA key stored with the configured ID of the TEE's Secure Storage. Subsequently, the resulting token is handed back to the REE in the output buffer specified in the secure service call.
|
||||
|
||||
<details>
|
||||
<summary><b>Attestation: Sample Token</b></summary>
|
||||
@ -23,7 +23,7 @@
|
||||
"magic": "44fef7cc",
|
||||
"encr_alg": "",
|
||||
"sign_alg": "ecdsa_secp256r1_sha256",
|
||||
"key_id": 0
|
||||
"key_id": "tee_att_key0",
|
||||
},
|
||||
"eat": {
|
||||
"nonce": -1582119980,
|
||||
@ -109,7 +109,7 @@ Before the project configuration and build, be sure to set the correct chip targ
|
||||
|
||||
Open the project configuration menu (`idf.py menuconfig`).
|
||||
|
||||
- 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`.
|
||||
- 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`.
|
||||
|
||||
### Build and Flash
|
||||
|
||||
@ -123,10 +123,17 @@ idf.py -p PORT flash monitor
|
||||
|
||||
See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
|
||||
|
||||
### Usage
|
||||
### Example Output
|
||||
|
||||
- Use console commands to dump the attestation info: `tee_att_info`
|
||||
- The generated token's signature can be verified using the script given below.
|
||||
```log
|
||||
I (438) example_tee_attest: TEE Attestation Service
|
||||
I (1008) example_tee_attest: Attestation token - Length: 1538
|
||||
I (1018) example_tee_attest: Attestation token - Data:
|
||||
'{"header":{"magic":"44fef7cc","encr_alg":"","sign_alg":"ecdsa_secp256r1_sha256","key_id":"tee_att_key0"},"eat":{"nonce":-1582119980,"client_id":262974944,"device_ver":1,"device_id":"4ecc458ef4290329552b4dcdccb99d55e5ea7624f24c87b27b71515e1666f39c","instance_id":"66571b78918f4bb7ae2723f235a9e4fe1c7070ae6261ce5df7049b44b1f8a318","psa_cert_ref":"0716053550477-10100","device_status":165,"sw_claims":{"tee":{"type":1,"ver":"1.0.0","idf_ver":"v5.5-dev-2978-gd75a0105dac-dirt","secure_ver":0,"part_chip_rev":{"min":0,"max":99},"part_digest":{"type":0,"calc_digest":"5213904fd8ca7538776bdf372c08c13138f20b2fac3503bc878f19c6e36a710d","digest_validated":true,"sign_verified":false,"secure_padding":false}},"app":{"type":2,"ver":"v0.1.0","idf_ver":"v5.5-dev-2978-gd75a0105dac-dirt","secure_ver":0,"part_chip_rev":{"min":0,"max":99},"part_digest":{"type":0,"calc_digest":"65c905fc0fc135fdfa8def210d1c186627cb3a17ecb2e7f020b56411b2d2fc76","digest_validated":true,"sign_verified":false,"secure_padding":false}},"bootloader":{"type":0,"ver":"01000000","idf_ver":"v5.5-dev-2978-gd75a0105dac-dirt","secure_ver":0,"part_chip_rev":{"min":0,"max":99},"part_digest":{"type":0,"calc_digest":"9efd37d29266f3239f7c6a095df880f1e85e41505f154cfd3bbfad4b8a2b18dd","digest_validated":true,"sign_verified":false}}}},"public_key":{"compressed":"02ce0188c61b0118c86ca20af7e01185dd687c6698b2265a288fee845d083e9066"},"sign":{"r":"362e2053bab26c779559793b2eae89e96c1a058e5fffc49d544d07b934ce3b32","s":"fc5f0e4d329fc6e031cbf425ef62d4756b728392b2a77282baa1f15b554d2716"}}'
|
||||
I (1148) main_task: Returned from app_main()
|
||||
```
|
||||
|
||||
**Note:** The generated token's signature can be verified using the script given below.
|
||||
|
||||
<details>
|
||||
<summary><b>Attestation: Verifying the generated token</b></summary>
|
||||
@ -181,19 +188,3 @@ assert vk.verify_digest(signature, digest, sigdecode=sigdecode_der)
|
||||
print('Token signature verified!')
|
||||
```
|
||||
</details>
|
||||
|
||||
### Example Output
|
||||
|
||||
```log
|
||||
I (416) main_task: Calling app_main()
|
||||
I (416) example_tee_attest: TEE Attestation Service
|
||||
|
||||
Type 'help' to get the list of commands.
|
||||
Use UP/DOWN arrows to navigate through command history.
|
||||
Press TAB when typing command name to auto-complete.
|
||||
I (476) main_task: Returned from app_main()
|
||||
esp32c6> tee_att_info
|
||||
I (6206) cmd_tee_attest: Attestation token - Length: 1525
|
||||
I (6206) cmd_tee_attest: Attestation token - Data:
|
||||
'{"header":{"magic":"44fef7cc","encr_alg":"","sign_alg":"ecdsa_secp256r1_sha256","key_id":0},"eat":{"nonce":-1582119980,"client_id":262974944,"device_ver":1,"device_id":"4ecc458ef4290329552b4dcdccb99d55e5ea7624f24c87b27b71515e1666f39c","instance_id":"77eb3dfec7633302fe4bcf04ffe3be5e83c0513057aa070d387f1e8350271329","psa_cert_ref":"0716053550477-10100","device_status":165,"sw_claims":{"tee":{"type":1,"ver":"1.0.0","idf_ver":"v5.5-dev-727-g624f640f61d-dirty","secure_ver":0,"part_chip_rev":{"min":0,"max":99},"part_digest":{"type":0,"calc_digest":"6e6548a5d64cd3d6e2e6dc166384f32f73558fbd9c0c0985c6095d643f053eb5","digest_validated":true,"sign_verified":false,"secure_padding":false}},"app":{"type":2,"ver":"v0.1.0","idf_ver":"v5.5-dev-727-g624f640f61d-dirty","secure_ver":0,"part_chip_rev":{"min":0,"max":99},"part_digest":{"type":0,"calc_digest":"7f10992d4bb32c497184fd2da0e3a593b235d82bde24de868c8eb4636d4b7bdc","digest_validated":true,"sign_verified":false,"secure_padding":false}},"bootloader":{"type":0,"ver":"01000000","idf_ver":"v5.5-dev-727-g624f640f61d-dirty","secure_ver":0,"part_chip_rev":{"min":0,"max":99},"part_digest":{"type":0,"calc_digest":"2cdf1bac1792df04ad10d67287ef3ab7024e183dc32899a190668cbb7d21a5a8","digest_validated":true,"sign_verified":false}}}},"public_key":{"compressed":"030df5c5fd9a4096a58ba16dfc4f1d53781bab555fc307d71367f0afc663005174"},"sign":{"r":"c3a0fc8ce3cd1dec2a0e38c4a63c03bd1e044febd5847178fe304b06d48b3eaf","s":"c8e34bc5d854e728cffdfd701ea09deabc9a9a22c4b06f312a61a1448a56b8b1"}}'
|
||||
```
|
||||
@ -8,19 +8,15 @@
|
||||
- This example demonstrates the ESP-TEE framework's Secure Storage with two workflows:
|
||||
- Signing and verification
|
||||
- Create and securely store an ECDSA `secp256r1` keypair in a protected memory space i.e. the secure storage partition
|
||||
- Sign a message in the TEE (given its digest) using the ECDSA keypair stored in the given slot ID
|
||||
- Retrieve the ECDSA public key associated with the private key for the given slot ID
|
||||
- Sign a message in the TEE (given its digest) using the ECDSA keypair stored with the given ID
|
||||
- Retrieve the ECDSA public key associated with the private key with the given ID
|
||||
- Verify the generated signature in the REE
|
||||
- Encryption and decryption
|
||||
- Generate and securely store an AES-256 key in the secure storage partition
|
||||
- Encrypt a message in the TEE using the AES key stored in the given slot ID with the `aes-256-gcm` algorithm and generate an authentication tag
|
||||
- Encrypt a message in the TEE using the AES key stored with the given ID with the `aes-256-gcm` algorithm and generate an authentication tag
|
||||
- Decrypt the ciphertext using the same AES key and validate the authentication tag
|
||||
- Verify that the decrypted message matches the original
|
||||
|
||||
### Notes
|
||||
|
||||
- Secure Storage currently supports only the `ecdsa-secp256r1-sha256` algorithm for signing and the `aes-256-gcm` algorithm for encryption.
|
||||
|
||||
## How to use the example
|
||||
|
||||
### Hardware Required
|
||||
@ -33,24 +29,26 @@ Before the project configuration and build, be sure to set the correct chip targ
|
||||
|
||||
Open the project configuration menu (`idf.py menuconfig`).
|
||||
|
||||
- Configure the secure storage slot ID for storing the ECDSA keypair at `Example Configuration → TEE: Secure Storage keypair slot ID`.
|
||||
- Configure the secure storage example key ID at `Example Configuration → TEE: Secure Storage Key ID`.
|
||||
|
||||
The TEE Secure Storage feature supports two modes for determining which eFuse block stores the encryption key:
|
||||
TEE Secure Storage follows the NVS partition format and uses an AES-XTS encryption scheme derived via the HMAC peripheral. It supports two key derivation modes, configurable via `CONFIG_SECURE_TEE_SEC_STG_MODE`:
|
||||
|
||||
- **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 `SECURE_TEE_SEC_STG_KEY_EFUSE_BLK` Kconfig option.
|
||||
- **Development** Mode: Encryption keys are embedded in the ESP-TEE firmware (identical across all instances).
|
||||
- **Release** Mode: Encryption keys are derived via the HMAC peripheral using a key stored in eFuse, specified by `CONFIG_SECURE_TEE_SEC_STG_EFUSE_HMAC_KEY_ID`.
|
||||
|
||||
#### Configure the eFuse Block ID for Encryption Key Storage
|
||||
#### Configure the eFuse key ID storing the HMAC key
|
||||
|
||||
- Navigate to `Security features → Trusted Execution Environment → TEE: Secure Storage Mode` and enable the Release mode configuration.
|
||||
- Set the eFuse block ID to store the encryption key in `Security features → Trusted Execution Environment → TEE: Secure Storage encryption key eFuse block`.
|
||||
- Navigate to `ESP-TEE (Trusted Execution Environment) → Secure Services → Secure Storage: Mode` and enable the `Release` mode configuration.
|
||||
- Set the eFuse key ID storing the HMAC key at `ESP-TEE (Trusted Execution Environment) → Secure Services → Secure Storage: eFuse HMAC key ID`.
|
||||
|
||||
**Note:** Before running the example, users must program the encryption key into the configured eFuse block - refer to the snippet below. The TEE checks whether the specified eFuse block is empty or already programmed with a key. If the block is empty, an error will be returned; otherwise, the pre-programmed key will be used.
|
||||
**Note:** Before running the example, users must program the HMAC key into the configured eFuse block - refer to the snippet below. The TEE checks whether the specified eFuse block is empty or already programmed with a key. If the block is empty, an error will be returned; otherwise, the pre-programmed key will be used.
|
||||
|
||||
```shell
|
||||
# Programming the user key (256-bit) in eFuse
|
||||
# Generate a random 32-byte HMAC key
|
||||
openssl rand -out hmac_key_file.bin 32
|
||||
# Programming the HMAC key (256-bit) in eFuse
|
||||
# Here, BLOCK_KEYx is a free eFuse key-block between BLOCK_KEY0 and BLOCK_KEY5
|
||||
espefuse.py -p PORT burn_key BLOCK_KEYx user_key.bin USER
|
||||
espefuse.py -p PORT burn_key BLOCK_KEYx hmac_key_file.bin HMAC_UP
|
||||
```
|
||||
|
||||
### Build and Flash
|
||||
|
||||
Reference in New Issue
Block a user