Mirrors/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2026-10-02 03:00:34 +03:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'feat/introduce_esp_rsa_ds_opaque_key_context_v6.0' into 'release/v6.0'

Browse Source 
Extend opaque driver context to add Key recovery info (v6.0)

See merge request espressif/esp-idf!46074
This commit is contained in:
Aditya Patwardhan
2026-03-19 19:45:02 +05:30
parent 305b04da81 1e05e719e1
commit 891ddca56e
55 changed files with 4031 additions and 615 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/en/api-reference/peripherals/ds.rst
+12 -2
View File
@@ -3,7 +3,13 @@ Digital Signature (DS)
:link_to_translation:`zh_CN:[中文]`
The Digital Signature (DS) module provides hardware acceleration of signing messages based on RSA. It uses pre-encrypted parameters to calculate a signature. The parameters are encrypted using HMAC as a key-derivation function. In turn, the HMAC uses eFuses as the input key. The whole process happens in hardware so that neither the decryption key for the RSA parameters nor the input key for the HMAC key derivation function can be seen by the software while calculating the signature.
The Digital Signature (DS) module provides hardware acceleration of signing messages based on RSA. It uses pre-encrypted parameters to calculate a signature. The parameters are encrypted using HMAC as a key-derivation function. In turn, the HMAC uses eFuses as the input key.
.. only:: SOC_KEY_MANAGER_SUPPORTED
On {IDF_TARGET_NAME}, the Digital Signature (DS) module can also use a key stored in the Key Manager instead of an eFuse key block. The AES encryption key can be directly deployed in the Key Manager with the type :cpp:enumerator:`ESP_KEY_MGR_DS_KEY`. Refer to :ref:`key-manager` for more details.
The whole process happens in hardware so that neither the decryption key for the RSA parameters nor the input key for the HMAC key derivation function can be seen by the software while calculating the signature.
For more detailed information on the hardware involved in the signature calculation and the registers used, see **{IDF_TARGET_NAME} Technical Reference Manual** > **Digital Signature (DS)** [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__].
@@ -112,7 +118,11 @@ Example for SSL Mutual Authentication Using DS
The SSL mutual authentication example that previously lived under ``examples/protocols/mqtt/ssl_ds`` is now shipped with the standalone `espressif/mqtt <https://components.espressif.com/components/espressif/mqtt>`__ component. Follow the component documentation to fetch the SSL DS example and build it together with ESP-MQTT. The example continues to use ``mqtt_client`` (implemented by ESP-MQTT) to connect to ``test.mosquitto.org`` over mutual-authenticated TLS, with the TLS portion handled by ESP-TLS.
.. only:: SOC_KEY_MANAGER_SUPPORTED
In case both the :cpp:member:`esp_ds_data_ctx_t::efuse_key_id` and :cpp:member:`esp_rsa_ds_opaque_key_t::key_recovery_info` are set, the ESP-DS PSA driver prefers using the Key Manager-based DS key over the eFuse-based DS key.
API Reference
-------------
.. include-build-file:: inc/esp_ds.inc
.. include-build-file:: inc/psa_crypto_driver_esp_rsa_ds_contexts.inc
docs/en/api-reference/peripherals/ecdsa.rst
+19 -1
View File
@@ -24,7 +24,14 @@ Supported Features
ECDSA on {IDF_TARGET_NAME}
--------------------------
On {IDF_TARGET_NAME}, the ECDSA module works with a secret key burnt into an eFuse block. This eFuse key is made completely inaccessible (default mode) for any resources outside the cryptographic modules, thus avoiding key leakage.
On {IDF_TARGET_NAME}, the ECDSA module works with a secret key burnt into an eFuse block.
.. only:: SOC_KEY_MANAGER_SUPPORTED
On {IDF_TARGET_NAME}, the ECDSA module also supports storing a secret key in the Key Manager. Refer to :ref:`key-manager` for more details.
This key is made completely inaccessible (default mode) for any resources outside the cryptographic modules, thus avoiding key leakage.
ECDSA Key Storage
^^^^^^^^^^^^^^^^^
@@ -53,6 +60,8 @@ ECDSA Key Storage
ECDSA key can be programmed externally through ``idf.py`` script. Here is an example of how to program the ECDSA key:
Using eFuses to store the ECDSA key:
.. code:: bash
idf.py efuse-burn-key <BLOCK_NUM> </path/to/ecdsa_private_key.pem> ECDSA_KEY
@@ -69,9 +78,18 @@ ECDSA key can be programmed externally through ``idf.py`` script. Here is an exa
Six physical eFuse blocks can be used as keys for the ECDSA module: block 4 ~ block 9. E.g., for block 4 (which is the first key block) , the argument should be ``BLOCK_KEY0``.
.. only:: SOC_KEY_MANAGER_SUPPORTED
Using the Key Manager to store the ECDSA key:
ECDSA private keys can be stored in the Key Manager. Refer to :ref:`key-manager` for more details.
Deploy an ECDSA key into the Key Manager and store the generated Key Recovery info in the flash memory for persistent keys.
Alternatively the ECDSA key can also be programmed through the application running on the target.
Using eFuses to store the ECDSA key:
Following code snippet uses :cpp:func:`esp_efuse_write_key` to set physical key block 0 in the eFuse with key purpose as :cpp:enumerator:`esp_efuse_purpose_t::ESP_EFUSE_KEY_PURPOSE_ECDSA_KEY`:
.. code-block:: c
docs/en/api-reference/peripherals/hmac.rst
+13 -4
View File
@@ -26,7 +26,13 @@ However, the HMAC itself is not bound to this use case. It can also be used for
HMAC on {IDF_TARGET_NAME}
-----------------------------
On {IDF_TARGET_NAME}, the HMAC module works with a secret key burnt into the eFuses. This eFuse key can be made completely inaccessible for any resources outside the cryptographic modules, thus avoiding key leakage.
On {IDF_TARGET_NAME}, the HMAC module works with a secret key burnt into the eFuses.
.. only:: SOC_KEY_MANAGER_SUPPORTED
On {IDF_TARGET_NAME}, the HMAC module also supports storing a secret key in the Key Manager. Refer to :ref:`key-manager` for more details.
This key can be made completely inaccessible for any resources outside the cryptographic modules, thus avoiding key leakage.
Furthermore, {IDF_TARGET_NAME} has three different application scenarios for its HMAC module:
@@ -142,6 +148,8 @@ Application Outline
The following code is an outline of how to set an eFuse key and then use it to calculate an HMAC for software usage.
Using eFuses to store the HMAC key:
We use ``esp_efuse_write_key`` to set physical key block 4 in the eFuse for the HMAC module together with its purpose. ``ESP_EFUSE_KEY_PURPOSE_HMAC_UP`` (8) means that this key can only be used for HMAC generation for software usage:
.. code-block:: c
@@ -162,6 +170,8 @@ We use ``esp_efuse_write_key`` to set physical key block 4 in the eFuse for the
Now we can calculate an HMAC for software usage with the saved key through the PSA Crypto API.
Using an eFuse-based HMAC key:
.. code-block:: c
#include "psa/crypto.h"
@@ -181,10 +191,9 @@ Now we can calculate an HMAC for software usage with the saved key through the P
psa_set_key_bits(&attributes, 256);
psa_set_key_lifetime(&attributes, PSA_KEY_LIFETIME_ESP_HMAC_VOLATILE);
// Create opaque key reference
// Create opaque key reference for eFuse-based key
esp_hmac_opaque_key_t opaque_key = {
.use_km_key = false,
.efuse_block = EFUSE_BLK_KEY4,
.efuse_key_id = HMAC_KEY4,
};
// Import the opaque key
docs/en/api-reference/peripherals/index.rst
+1
View File
@@ -23,6 +23,7 @@ Peripherals API
:SOC_I2S_SUPPORTED: i2s
:SOC_ISP_SUPPORTED: isp
:SOC_JPEG_CODEC_SUPPORTED: jpeg
:SOC_KEY_MANAGER_SUPPORTED: key_manager
lcd/index
:SOC_GP_LDO_SUPPORTED: ldo_regulator
ledc
docs/en/api-reference/peripherals/key_manager.rst
+171
View File
@@ -0,0 +1,171 @@
.. _key-manager:
Key Manager
===========
:link_to_translation:`zh_CN:[中文]`
The {IDF_TARGET_NAME}'s Key Manager peripheral provides hardware-assisted **key deployment and recovery** for cryptographic keys. It allows cryptographic keys to be provisioned and used without storing plaintext key material in flash, RAM, or eFuses.
The Key Manager is intended for applications that require secure handling of long-term cryptographic keys.
.. only:: esp32p4
.. note::
The Key Manager peripheral is only supported on ESP32-P4 chip revision >= v3.0.
.. only:: esp32c5
.. note::
The Key Manager peripheral is only supported on ESP32-C5 chip revision >= v1.2.
Key Manager provides the following properties:
- **Device uniqueness**
Keys are cryptographically bound to a Hardware Unique Key (HUK) that is unique to each chip.
- **No plaintext key storage**
Key material is never exposed to software accessible memory.
- **Flexible key lifecycle**
Keys can be deployed, recovered, or replaced by a newer key without reprogramming the eFuses for each key.
- **Resistance to physical extraction**
Reading flash or eFuses contents would not reveal usable key material.
Hardware Unique Key (HUK)
-------------------------
The Hardware Unique Key (HUK) is a device-specific unique key generated entirely in hardware HUK peripheral. It is generated using SRAM Physical Unclonable Function (PUF) and is reconstructed using the HUK recovery info stored in the key recovery info of a Key Manager deployed key. See **{IDF_TARGET_NAME} Technical Reference Manual** > **Chapter Key Manager** [`PDF <{IDF_TARGET_TRM_EN_URL}>`__] > **HUK Generator** for more details about the HUK peripheral.
The HUK acts as the root of trust for all keys deployed through the Key Manager.
Key Deployment and Key Recovery
-------------------------------
The Key Manager operates in two distinct phases:
- **Key deployment**
A cryptographic key is generated or securely introduced into the chip, and it gets bound to the HUK. This step is usually performed during manufacturing, first boot up or when generating transient or persistent keys during the application runtime.
- **Key recovery**
On subsequent boots, a Key Manager-deployed persistent key is restored using the previously generated key recovery information, without exposing the key value.
During deployment, the Key Manager generates a data structure referred to as :cpp:type:`esp_key_mgr_key_recovery_info_t`. In case of persistent keys, the applications must store this data in non-volatile storage (for example, flash) in order to recover the key on later boots.
Supported Key Types
-------------------
The Key Manager can manage keys for the following key types:
.. list::
:SOC_KEY_MANAGER_ECDSA_KEY_DEPLOY: - ECDSA
:SOC_KEY_MANAGER_FE_KEY_DEPLOY: - Flash Encryption (XTS-AES)
:SOC_KEY_MANAGER_HMAC_KEY_DEPLOY: - HMAC
:SOC_KEY_MANAGER_DS_KEY_DEPLOY: - Digital Signature peripherals
:SOC_KEY_MANAGER_FE_KEY_DEPLOY: - PSRAM Encryption
Each key is associated with a :cpp:type:`esp_key_mgr_key_purpose_t`, which defines how the key can be used by hardware peripherals.
Key Deployment Modes
--------------------
The Key Manager provides multiple key deployment modes to support different provisioning and security requirements.
Random Deploy Mode
^^^^^^^^^^^^^^^^^^
In this mode, the Key Manager generates a random private key internally.
- The key value is never known to the application software.
- No external key material is required.
- Intended for use cases where the key does not need to be backed up or exported.
AES Deploy Mode
^^^^^^^^^^^^^^^
In this mode, a user-specified private key is securely deployed.
- The key is encrypted before being transmitted to the chip.
- Auxiliary key material is used to protect the deployment process.
- Intended for factory provisioning scenarios where the key value must be predefined.
ECDH0 Deploy Mode
^^^^^^^^^^^^^^^^^
In this mode, a private key is negotiated using Elliptic Curve Diffie-Hellman (ECDH).
- The final private key is never transmitted.
- The deployment process can occur over an untrusted channel.
- Intended for high-security provisioning environments.
For detailed information various deployment modes, see **{IDF_TARGET_NAME} Technical Reference Manual** > **Chapter Key Manager** [`PDF <{IDF_TARGET_TRM_EN_URL}>`__] > **Section Key Manager**.
.. ECDH1 Deploy Mode
.. ~~~~~~~~~~~~~~~~~
..
.. This mode is similar to ECDH0 Deploy Mode, with additional flexibility for manufacturing workflows.
..
.. - Supports negotiated key deployment using auxiliary recovery data
.. - Allows updating deployed keys by replacing auxiliary information
.. - Intended for large-scale manufacturing with controlled trust assumptions
Typical Workflows
-----------------
First Boot or Manufacturing
^^^^^^^^^^^^^^^^^^^^^^^^^^^
A typical provisioning flow includes:
1. Generating the Hardware Unique Key (HUK)
2. Deploying required cryptographic keys using an appropriate deployment mode
3. Storing the generated ``key_recovery_info`` in non-volatile storage
4. Locking relevant security configuration eFuses, if required
This process is usually performed once per device.
Normal Boot
^^^^^^^^^^^
During a normal boot:
1. The application provides the previously generated and stored ``key_recovery_info`` of a Key Manager-deployed key.
2. The HUK is reconstructed automatically by hardware.
3. The Key Manager recovers the deployed key internally.
4. Cryptographic peripherals can use the recovered key.
Security Considerations
-----------------------
Applications using the Key Manager should consider the following:
- Protect the ``key_recovery_info`` of a Key Manager-deployed key against unauthorized modification or loss.
- Lock Key Manager's security-related eFuses after successful key deployment to prevent re-deployment of a key of the same type.
- Avoid deploying new XTS-AES keys when Flash Encryption is already enabled unless explicitly intended.
API Reference
-------------
.. include-build-file:: inc/esp_key_mgr.inc
.. include-build-file:: inc/key_mgr_types.inc
Examples
--------
See :example:`security/key_manager` for an example demonstrating key deployment using the Key Manager and using the deployed key to perform signing operations.
This example shows how to:
- Initialize the Key Manager
- Deploy keys using the AES deployment mode
- Use the PSA interface to perform signing operations using the Key Manager deployed key
docs/en/security/esp32c5_log.inc
+138 -58
View File
@@ -66,68 +66,72 @@
------
.. first_boot_enc_km
.. code-block:: none
ESP-ROM:esp32c5-eco3-20250704
Build:Jul 4 2025
rst:0x1 (POWERON),boot:0x18 (SPI_FAST_FLASH_BOOT)
SPI mode:DIO, clock div:1
load:0x40855820,len:0x3a60
load:0x4084bba0,len:0xdf4
load:0x4084e5a0,len:0x566c
entry 0x4084bbaa
I (23) boot: ESP-IDF v6.0-dev-3140-ge16a2fb13ad-dirt 2nd stage bootloader
I (24) boot: compile time Oct 27 2025 15:35:09
I (67) boot: chip revision: v1.1
I (70) boot: efuse block revision: v0.3
I (88) boot.esp32c5: SPI Speed : 80MHz
I (92) boot.esp32c5: SPI Mode : DIO
I (96) boot.esp32c5: SPI Flash Size : 2MB
I (103) boot: Enabling RNG early entropy source...
I (138) boot: Partition Table:
I (141) boot: ## Label Usage Type ST Offset Length
I (154) boot: 0 nvs WiFi data 01 02 0000e000 00006000
I (168) boot: 1 phy_init RF data 01 01 00014000 00001000
I (182) boot: 2 factory factory app 00 00 00020000 00100000
I (189) boot: End of partition table
I (283) esp_image: segment 0: paddr=00020020 vaddr=42070020 size=32f1ch (208668) map
I (377) esp_image: segment 1: paddr=00052f44 vaddr=40800000 size=0a2a4h ( 41636) load
I (445) esp_image: segment 2: paddr=0005d1f0 vaddr=4080a300 size=02ccch ( 11468) load
I (512) esp_image: segment 3: paddr=0005fec4 vaddr=00000000 size=00154h ( 340)
I (580) esp_image: segment 4: paddr=00060020 vaddr=42000020 size=63804h (407556) map
I (761) boot: Loaded app from partition at offset 0x20000
I (764) boot: Checking flash encryption...
I (788) efuse: Batch mode of writing fields is enabled
I (807) flash_encrypt: Deploying new flash encryption key using Key Manager
W (898) flash_encrypt: Not disabling UART bootloader encryption
I (904) flash_encrypt: Disable UART bootloader cache...
W (917) flash_encrypt: Not disabling JTAG - SECURITY COMPROMISED
I (930) efuse: BURN BLOCK0
I (935) efuse: BURN BLOCK0 - OK (all write block bits are set)
I (938) efuse: Batch mode. Prepared fields are committed
I (1028) esp_image: segment 0: paddr=00002020 vaddr=40855820 size=03a60h ( 14944)
I (1096) esp_image: segment 1: paddr=00005a88 vaddr=4084bba0 size=00df4h ( 3572)
I (1165) esp_image: segment 2: paddr=00006884 vaddr=4084e5a0 size=0566ch ( 22124)
I (1508) flash_encrypt: bootloader encrypted successfully
I (1535) flash_encrypt: partition table encrypted and loaded successfully
I (1616) esp_image: segment 0: paddr=00020020 vaddr=42070020 size=32f1ch (208668) map
I (1711) esp_image: segment 1: paddr=00052f44 vaddr=40800000 size=0a2a4h ( 41636)
I (1779) esp_image: segment 2: paddr=0005d1f0 vaddr=4080a300 size=02ccch ( 11468)
I (1847) esp_image: segment 3: paddr=0005fec4 vaddr=00000000 size=00154h ( 340)
I (1916) esp_image: segment 4: paddr=00060020 vaddr=42000020 size=63804h (407556) map
I (2096) flash_encrypt: Encrypting partition 2 at offset 0x20000 (length 0xa3850)...
I (5652) flash_encrypt: Done encrypting
I (5667) efuse: BURN BLOCK0
I (5671) efuse: BURN BLOCK0 - OK (all write block bits are set)
I (5675) flash_encrypt: Flash encryption completed
I (5679) boot: Resetting with flash encryption enabled...
------
.. already_en_enc
.. code-block:: none
rst:0x1 (POWERON),boot:0x3d (SPI_FAST_FLASH_BOOT)
SPI mode:DIO, clock div:2
load:0x40855c10,len:0x2be8
load:0x4084c7a0,len:0x6f8
load:0x4084e9a0,len:0x418c
entry 0x4084c804
I (32) boot: ESP-IDF v5.3-dev-3860-g5d36288649 2nd stage bootloader
I (33) boot: compile time May 7 2024 17:24:43
I (34) boot: chip revision: v0.0
I (37) boot.esp32c5: SPI Speed : 40MHz
I (42) boot.esp32c5: SPI Mode : DIO
I (46) boot.esp32c5: SPI Flash Size : 2MB
I (51) boot: Enabling RNG early entropy source...
I (64) boot: Partition Table:
I (67) boot: ## Label Usage Type ST Offset Length
I (74) boot: 0 nvs WiFi data 01 02 0000e000 00006000
I (82) boot: 1 storage Unknown data 01 ff 00014000 00001000
I (89) boot: 2 factory factory app 00 00 00020000 00100000
I (97) boot: 3 nvs_key NVS keys 01 04 00120000 00001000
I (104) boot: 4 custom_nvs WiFi data 01 02 00121000 00006000
I (113) boot: End of partition table
I (116) esp_image: segment 0: paddr=00020020 vaddr=42010020 size=095c4h ( 38340) map
I (169) esp_image: segment 1: paddr=000295ec vaddr=40800000 size=06a2ch ( 27180) load
I (197) esp_image: segment 2: paddr=00030020 vaddr=42000020 size=0f4d4h ( 62676) map
I (256) esp_image: segment 3: paddr=0003f4fc vaddr=40806a2c size=00b78h ( 2936) load
I (261) esp_image: segment 4: paddr=0004007c vaddr=408075b0 size=00d18h ( 3352) load
I (269) boot: Loaded app from partition at offset 0x20000
I (270) boot: Checking flash encryption...
I (273) efuse: Batch mode of writing fields is enabled
I (278) flash_encrypt: Generating new flash encryption key...
I (295) efuse: Writing EFUSE_BLK_KEY0 with purpose 4
W (300) flash_encrypt: Not disabling UART bootloader encryption
I (305) flash_encrypt: Disable JTAG...
I (312) efuse: BURN BLOCK4
I (317) efuse: BURN BLOCK4 - OK (write block == read block)
I (319) efuse: BURN BLOCK0
I (325) efuse: BURN BLOCK0 - OK (all write block bits are set)
I (330) efuse: Batch mode. Prepared fields are committed
I (335) esp_image: segment 0: paddr=00002020 vaddr=40855c10 size=02be8h ( 11240)
I (353) esp_image: segment 1: paddr=00004c10 vaddr=4084c7a0 size=006f8h ( 1784)
I (356) esp_image: segment 2: paddr=00005310 vaddr=4084e9a0 size=0418ch ( 16780)
I (1131) flash_encrypt: bootloader encrypted successfully
I (1229) flash_encrypt: partition table encrypted and loaded successfully
I (1230) flash_encrypt: Encrypting partition 1 at offset 0x14000 (length 0x1000)...
I (1325) flash_encrypt: Done encrypting
I (1325) esp_image: segment 0: paddr=00020020 vaddr=42010020 size=095c4h ( 38340) map
I (1362) esp_image: segment 1: paddr=000295ec vaddr=40800000 size=06a2ch ( 27180)
I (1389) esp_image: segment 2: paddr=00030020 vaddr=42000020 size=0f4d4h ( 62676) map
I (1448) esp_image: segment 3: paddr=0003f4fc vaddr=40806a2c size=00b78h ( 2936)
I (1453) esp_image: segment 4: paddr=0004007c vaddr=408075b0 size=00d18h ( 3352)
I (1458) flash_encrypt: Encrypting partition 2 at offset 0x20000 (length 0x100000)...
I (24332) flash_encrypt: Done encrypting
I (24332) flash_encrypt: Encrypting partition 3 at offset 0x120000 (length 0x1000)...
I (24422) flash_encrypt: Done encrypting
I (24423) efuse: BURN BLOCK0
I (24425) efuse: BURN BLOCK0 - OK (all write block bits are set)
I (24427) flash_encrypt: Flash encryption completed
I (24431) boot: Resetting with flash encryption enabled...
ESP-ROM:esp32c5-20240329
Build:Mar 29 2024
rst:0x3 (RTC_SW_HPSYS),boot:0x3d (SPI_FAST_FLASH_BOOT)
@@ -193,3 +197,79 @@
------
.. already_en_enc_km
.. code-block:: none
ESP-ROM:esp32c5-eco3-20250704
Build:Jul 4 2025
rst:0x1 (POWERON),boot:0x18 (SPI_FAST_FLASH_BOOT)
use sector0 for km info
use KM derived key
SPI mode:DIO, clock div:1
load:0x40855820,len:0x3a94
load:0x4084bba0,len:0xd84
load:0x4084e5a0,len:0x5670
entry 0x4084bbaa
I (27) boot: ESP-IDF v6.0-dev-3139-gb813f413096-dirt 2nd stage bootloader
I (28) boot: compile time Oct 27 2025 18:14:49
W (39) MMU: mmu_ll_write_entry mmu_id=0, entry_id=511, mmu_val=0x00000000, target=1
W (53) MMU: mmu_ll_write_entry mmu_id=0, entry_id=511, mmu_val=0x00000000, target=1
W (67) MMU: mmu_ll_write_entry mmu_id=0, entry_id=511, mmu_val=0x00000000, target=1
W (80) MMU: mmu_ll_write_entry mmu_id=0, entry_id=511, mmu_val=0x00000000, target=1
W (94) MMU: mmu_ll_write_entry mmu_id=0, entry_id=511, mmu_val=0x00000000, target=1
W (108) MMU: mmu_ll_write_entry mmu_id=0, entry_id=511, mmu_val=0x00000000, target=1
I (116) boot: chip revision: v1.1
I (119) boot: efuse block revision: v0.3
I (137) boot.esp32c5: SPI Speed : 80MHz
I (141) boot.esp32c5: SPI Mode : DIO
I (145) boot.esp32c5: SPI Flash Size : 2MB
I (149) boot: Enabling RNG early entropy source...
W (163) MMU: mmu_ll_write_entry mmu_id=0, entry_id=0, mmu_val=0x00000000, target=1
I (191) boot: Partition Table:
I (194) boot: ## Label Usage Type ST Offset Length
I (208) boot: 0 nvs WiFi data 01 02 0000e000 00006000
I (222) boot: 1 phy_init RF data 01 01 00014000 00001000
I (235) boot: 2 factory factory app 00 00 00020000 00100000
I (242) boot: End of partition table
I (396) esp_image: segment 0: paddr=00020020 vaddr=42070020 size=32f1ch (208668) map
I (539) esp_image: segment 1: paddr=00052f44 vaddr=40800000 size=0a2a4h ( 41636) load
I (629) esp_image: segment 2: paddr=0005d1f0 vaddr=4080a300 size=02ccch ( 11468) load
I (719) esp_image: segment 3: paddr=0005fec4 vaddr=00000000 size=00154h ( 340)
I (816) esp_image: segment 4: paddr=00060020 vaddr=42000020 size=6378ch (407436) map
I (1114) boot: Loaded app from partition at offset 0x20000
I (1116) boot: Checking flash encryption...
I (1133) flash_encrypt: flash encryption is enabled (1 plaintext flashes left)
I (1140) boot: Disabling RNG early entropy source...
I (1301) MSPI Timing: Enter flash timing tuning
I (1434) cpu_start: Unicore app
I (1468) cpu_start: GPIO 12 and 11 are used as console UART I/O pins
I (1479) cpu_start: Pro cpu start user code
I (1483) cpu_start: cpu freq: 240000000 Hz
I (1493) app_init: Application information:
I (1496) app_init: Project name: mbedtls_test
I (1501) app_init: App version: qa-test-esp32c61-master-2025070
I (1507) app_init: Compile time: Oct 27 2025 15:56:18
I (1512) app_init: ELF file SHA256: c5f7f520c...
I (1517) app_init: ESP-IDF: v6.0-dev-3140-ge16a2fb13ad-dirt
I (1528) efuse_init: Min chip rev: v1.0
I (1532) efuse_init: Max chip rev: v1.99
I (1536) efuse_init: Chip rev: v1.1
I (1669) heap_init: Initializing. RAM available for dynamic allocation:
I (1680) heap_init: At 4080FCB0 len 0004C8F0 (306 KiB): RAM
I (1685) heap_init: At 4085C5A0 len 00002F58 (11 KiB): RAM
I (1695) heap_init: At 50000000 len 00003FE8 (15 KiB): RTCRAM
I (1800) spi_flash: detected chip: generic
I (1804) spi_flash: flash io: dio
W (1807) spi_flash: Detected size(8192k) larger than the size in the binary image header(2048k). Using the size in the binary image header.
W (1833) flash_encrypt: Flash encryption mode is DEVELOPMENT (not secure)
I (1867) sleep_gpio: Configure to isolate all GPIO pins in sleep state
I (1873) sleep_gpio: Enable automatic switching of GPIO sleep configuration
I (1926) main_task: Started on CPU0
I (1926) main_task: Calling app_main()
I (1936) main_task: Returned from app_main()
------
docs/en/security/esp32p4_log.inc
+140
View File
@@ -70,6 +70,72 @@
------
.. first_boot_enc_km
.. code-block:: none
ESP-ROM:esp32p4-eco5-20250430
Build:Apr 30 2025
rst:0x17 (CHIP_USB_UART_RESET),boot:0xc (SPI_FAST_FLASH_BOOT)
Core0 Saved PC:0x4fc0130e
Core1 Saved PC:0x4fc05fa4
SPI mode:DIO, clock div:1
load:0x4ffb6240,len:0x3870
load:0x4ffac2c0,len:0x179c
load:0x4ffaefc0,len:0x4ed8
entry 0x4ffac2ca
I (38) boot: ESP-IDF v6.0-dev-2918-g6629f96afca-dirt 2nd stage bootloader
I (38) boot: compile time Oct 14 2025 08:50:07
I (39) boot: Multicore bootloader
I (85) boot: chip revision: v3.0
I (88) boot: efuse block revision: v1.0
I (106) boot.esp32p4: SPI Speed : 80MHz
I (110) boot.esp32p4: SPI Mode : DIO
I (114) boot.esp32p4: SPI Flash Size : 2MB
I (121) boot: Enabling RNG early entropy source...
I (156) boot: Partition Table:
I (159) boot: ## Label Usage Type ST Offset Length
I (173) boot: 0 factory factory app 00 00 00010000 00150000
I (187) boot: 1 storage Unknown data 01 81 00160000 00050000
I (194) boot: End of partition table
I (287) esp_image: segment 0: paddr=00010020 vaddr=40030020 size=0d1e8h ( 53736) map
I (355) esp_image: segment 1: paddr=0001d210 vaddr=30100000 size=00044h ( 68) load
I (423) esp_image: segment 2: paddr=0001d25c vaddr=4ff20000 size=02dbch ( 11708) load
I (491) esp_image: segment 3: paddr=00020020 vaddr=40000020 size=21834h (137268) map
I (567) esp_image: segment 4: paddr=0004185c vaddr=4ff22dbc size=094e8h ( 38120) load
I (635) esp_image: segment 5: paddr=0004ad4c vaddr=4ff2c300 size=044ech ( 17644) load
I (750) boot: Loaded app from partition at offset 0x10000
I (752) boot: Checking flash encryption...
I (777) efuse: Batch mode of writing fields is enabled
I (796) flash_encrypt: Deploying new flash encryption key using Key Manager
W (933) flash_encrypt: Not disabling UART bootloader encryption
I (939) flash_encrypt: Disable UART bootloader cache...
W (952) flash_encrypt: Not disabling JTAG - SECURITY COMPROMISED
I (965) efuse: BURN BLOCK0
I (970) efuse: BURN BLOCK0 - OK (write block == read block)
I (973) efuse: Batch mode. Prepared fields are committed
I (1063) esp_image: segment 0: paddr=00002020 vaddr=4ffb6240 size=03870h ( 14448)
I (1132) esp_image: segment 1: paddr=00005898 vaddr=4ffac2c0 size=0179ch ( 6044)
I (1200) esp_image: segment 2: paddr=0000703c vaddr=4ffaefc0 size=04ed8h ( 20184)
I (1725) flash_encrypt: bootloader encrypted successfully
I (1769) flash_encrypt: partition table encrypted and loaded successfully
I (1851) esp_image: segment 0: paddr=00010020 vaddr=40030020 size=0d1e8h ( 53736) map
I (1919) esp_image: segment 1: paddr=0001d210 vaddr=30100000 size=00044h ( 68)
I (1988) esp_image: segment 2: paddr=0001d25c vaddr=4ff20000 size=02dbch ( 11708)
I (2056) esp_image: segment 3: paddr=00020020 vaddr=40000020 size=21834h (137268) map
I (2133) esp_image: segment 4: paddr=0004185c vaddr=4ff22dbc size=094e8h ( 38120)
I (2202) esp_image: segment 5: paddr=0004ad4c vaddr=4ff2c300 size=044ech ( 17644)
I (2315) flash_encrypt: Encrypting partition 0 at offset 0x10000 (length 0x3f260)...
I (4978) flash_encrypt: Done encrypting
I (4992) efuse: BURN BLOCK0
I (4997) efuse: BURN BLOCK0 - OK (all write block bits are set)
I (5001) flash_encrypt: Flash encryption completed
I (5005) boot: Resetting with flash encryption enabled...
------
.. already_en_enc
.. code-block:: none
@@ -152,3 +218,77 @@
I (595) main_task: Returned from app_main()
------
.. already_en_enc_km
.. code-block:: none
ESP-ROM:esp32p4-eco5-20250430
Build:Apr 30 2025
rst:0x3 (SW_SYS_RESET),boot:0xc (SPI_FAST_FLASH_BOOT)
Core0 Saved PC:0x4ffb0910
Core1 Saved PC:0x4fc05fa4
SPI mode:DIO, clock div:1
load:0x4ffb6240,len:0x3870
load:0x4ffac2c0,len:0x179c
load:0x4ffaefc0,len:0x4ed8
entry 0x4ffac2ca
I (37) boot: ESP-IDF v6.0-dev-2918-g6629f96afca-dirt 2nd stage bootloader
I (38) boot: compile time Oct 14 2025 08:50:07
I (38) boot: Multicore bootloader
I (84) boot: chip revision: v3.0
I (87) boot: efuse block revision: v1.0
I (106) boot.esp32p4: SPI Speed : 80MHz
I (110) boot.esp32p4: SPI Mode : DIO
I (113) boot.esp32p4: SPI Flash Size : 2MB
I (121) boot: Enabling RNG early entropy source...
I (155) boot: Partition Table:
I (158) boot: ## Label Usage Type ST Offset Length
I (172) boot: 0 factory factory app 00 00 00010000 00150000
I (186) boot: 1 storage Unknown data 01 81 00160000 00050000
I (193) boot: End of partition table
I (287) esp_image: segment 0: paddr=00010020 vaddr=40030020 size=0d1e8h ( 53736) map
I (355) esp_image: segment 1: paddr=0001d210 vaddr=30100000 size=00044h ( 68) load
I (422) esp_image: segment 2: paddr=0001d25c vaddr=4ff20000 size=02dbch ( 11708) load
I (491) esp_image: segment 3: paddr=00020020 vaddr=40000020 size=21834h (137268) map
I (567) esp_image: segment 4: paddr=0004185c vaddr=4ff22dbc size=094e8h ( 38120) load
I (635) esp_image: segment 5: paddr=0004ad4c vaddr=4ff2c300 size=044ech ( 17644) load
I (750) boot: Loaded app from partition at offset 0x10000
I (752) boot: Checking flash encryption...
I (769) flash_encrypt: flash encryption is enabled (1 plaintext flashes left)
I (776) boot: Disabling RNG early entropy source...
W (847) pmu_pvt: blk_version is less than 2, pvt auto dbias init not supported in efuse.
I (855) cpu_start: Multicore app
I (890) cpu_start: GPIO 38 and 37 are used as console UART I/O pins
I (901) cpu_start: Pro cpu start user code
I (905) cpu_start: cpu freq: 400000000 Hz
I (914) app_init: Application information:
I (918) app_init: Project name: crypto_test
I (922) app_init: App version: qa-test-esp32c61-master-2025070
I (928) app_init: Compile time: Oct 14 2025 08:50:07
I (933) app_init: ELF file SHA256: 847005dd4...
I (938) app_init: ESP-IDF: v6.0-dev-2918-g6629f96afca-dirt
I (949) efuse_init: Min chip rev: v3.0
I (953) efuse_init: Max chip rev: v3.99
I (957) efuse_init: Chip rev: v3.0
I (1126) heap_init: Initializing. RAM available for dynamic allocation:
I (1137) heap_init: At 4FF33B20 len 000874A0 (541 KiB): RAM
I (1143) heap_init: At 4FFBAFC0 len 00004BF0 (18 KiB): RAM
I (1153) heap_init: At 50108080 len 00007F80 (31 KiB): RTCRAM
I (1163) heap_init: At 30100044 len 00001FBC (7 KiB): TCM
I (1261) spi_flash: detected chip: gd
I (1264) spi_flash: flash io: dio
W (1267) spi_flash: Detected size(16384k) larger than the size in the binary image header(2048k). Using the size in the binary image header.
W (1293) flash_encrypt: Flash encryption mode is DEVELOPMENT (not secure)
I (1357) main_task: Started on CPU0
I (1407) main_task: Calling app_main()
I (1407) main_task: Returned from app_main()
Example to check Flash Encryption status
This is esp32p4 chip with 2 CPU core(s), WiFi, silicon revision v0.0, 2MB external flash
FLASH_CRYPT_CNT eFuse value is 1
Flash encryption feature is enabled in DEVELOPMENT mode
------
docs/en/security/flash-encryption.rst
+303 -98
View File
@@ -13,7 +13,7 @@ This is a quick start guide to {IDF_TARGET_NAME}'s flash encryption feature. Usi
.. note::
In this guide, most used commands are in the form of ``idf.py secure-<command>``, which is a wrapper around corresponding ``espsecure <command>``. The ``idf.py`` based commands provides more user-friendly experience, although may lack some of the advanced functionality of their ``espsecure`` based counterparts.
In this guide, most used commands are in the form of ``idf.py secure-<command>``, which is a wrapper around corresponding ``espsecure <command>``. The ``idf.py`` based commands provide a more user-friendly experience, although may lack some of the advanced functionality of their ``espsecure`` based counterparts.
Introduction
------------
@@ -26,7 +26,7 @@ Flash encryption is intended for encrypting the contents of the {IDF_TARGET_NAME
.. important::
For production use, flash encryption should be enabled in the "Release" mode only.
For production use, flash encryption should be enabled in the release mode only.
.. important::
@@ -73,7 +73,7 @@ The flash encryption operation is controlled by various eFuses available on {IDF
- 2
* - ``flash_encryption`` (block1)
- AES key storage.
- 256 bit key block
- 256-bit key block
* - ``FLASH_CRYPT_CONFIG``
- Controls the AES encryption process.
- 4
@@ -84,7 +84,7 @@ The flash encryption operation is controlled by various eFuses available on {IDF
- If set, disables flash decryption while running in UART Firmware Download mode.
- 1
* - ``{IDF_TARGET_CRYPT_CNT}``
- A :math:`2^n` number that indicating whether the contents of flash have been encrypted.
- A :math:`2^n` number indicating whether the contents of flash have been encrypted.
* If an odd number of bits are set (e.g., ``0b0000001`` or ``0b0000111``), this indicates the contents of flash are encrypted. The contents will need to be transparently decrypted when read.
* If an even number of bits are set (e.g., ``0b0000000`` or ``0b0000011``), this indicates the contents of flash are unencrypted (i.e., plain text).
@@ -93,7 +93,35 @@ The flash encryption operation is controlled by various eFuses available on {IDF
- 7
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_256
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_256 and SOC_KEY_MANAGER_SUPPORTED
.. list-table:: eFuses Used in Flash Encryption
:widths: 25 40 10
:header-rows: 0
* - **eFuse**
- **Description**
- **Bit Depth**
* - ``BLOCK_KEYN``
- AES key storage. N is between 0 and 5. When using a Key Manager-based key, this eFuse is not used.
- One 256-bit key block for XTS_AES_128; two 256-bit key blocks for XTS_AES_256 (512-bit total).
* - ``KEY_PURPOSE_N``
- Controls the purpose of eFuse block ``BLOCK_KEYN``, where N is between 0 and 5. Possible values: ``2`` for ``XTS_AES_256_KEY_1``, ``3`` for ``XTS_AES_256_KEY_2``, and ``4`` for ``XTS_AES_128_KEY``. Final AES key is derived based on the value of one or two of these purpose eFuses. For a detailed description of the possible combinations, see **{IDF_TARGET_NAME} Technical Reference Manual** > **External Memory Encryption and Decryption (XTS_AES)** [`PDF <{IDF_TARGET_TRM_EN_URL}#extmemencr>`__]. When enabling Flash Encryption using a Key Manager-based key, this eFuse is not used.
- 4
* - ``KM_XTS_KEY_LENGTH_256``
- When enabling Flash Encryption using a Key Manager-based key, this eFuse is used to control the length of the XTS-AES key. Set this eFuse to 1 to use a 128-bit key, and to 0 to use a 256-bit key. This eFuse field is unused when enabling Flash Encryption using an eFuse-based key.
- 1
* - ``FORCE_USE_KEY_MANAGER_KEY``
- When enabling Flash Encryption using a Key Manager-based key, this eFuse is used to force the Key Manager to use the XTS-AES key. Set the bit 1 of this eFuse to use the Key Manager-based key. This eFuse field is unused when enabling Flash Encryption using an eFuse-based key.
- 1
* - ``DIS_DOWNLOAD_MANUAL_ENCRYPT``
- If set, disables Flash Encryption when in download bootmodes.
- 1
* - ``{IDF_TARGET_CRYPT_CNT}``
- Enables encryption and decryption, when an SPI boot mode is set. Feature is enabled if 1 or 3 bits are set in the eFuse, disabled otherwise.
- 3
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_256 and not SOC_KEY_MANAGER_SUPPORTED
.. list-table:: eFuses Used in Flash Encryption
:widths: 25 40 10
@@ -104,9 +132,9 @@ The flash encryption operation is controlled by various eFuses available on {IDF
- **Bit Depth**
* - ``BLOCK_KEYN``
- AES key storage. N is between 0 and 5.
- One 256 bit key block for XTS_AES_128, Two 256 bit key blocks for XTS_AES_256 (512 bit total)
- One 256-bit key block for XTS_AES_128, Two 256-bit key blocks for XTS_AES_256 (512 bit total)
* - ``KEY_PURPOSE_N``
- Controls the purpose of eFuse block ``BLOCK_KEYN``, where N is between 0 and 5. Possible values: ``2`` for ``XTS_AES_256_KEY_1`` , ``3`` for ``XTS_AES_256_KEY_2``, and ``4`` for ``XTS_AES_128_KEY``. Final AES key is derived based on the value of one or two of these purpose eFuses. For a detailed description of the possible combinations, see *{IDF_TARGET_NAME} Technical Reference Manual* > *External Memory Encryption and Decryption (XTS_AES)* [`PDF <{IDF_TARGET_TRM_EN_URL}#extmemencr>`__].
- Controls the purpose of eFuse block ``BLOCK_KEYN``, where N is between 0 and 5. Possible values: ``2`` for ``XTS_AES_256_KEY_1`` , ``3`` for ``XTS_AES_256_KEY_2``, and ``4`` for ``XTS_AES_128_KEY``. Final AES key is derived based on the value of one or two of these purpose eFuses. For a detailed description of the possible combinations, see **{IDF_TARGET_NAME} Technical Reference Manual** > **External Memory Encryption and Decryption (XTS_AES)** [`PDF <{IDF_TARGET_TRM_EN_URL}#extmemencr>`__].
- 4
* - ``DIS_DOWNLOAD_MANUAL_ENCRYPT``
- If set, disables flash encryption when in download bootmodes.
@@ -115,7 +143,35 @@ The flash encryption operation is controlled by various eFuses available on {IDF
- Enables encryption and decryption, when an SPI boot mode is set. Feature is enabled if 1 or 3 bits are set in the eFuse, disabled otherwise.
- 3
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_128 and not SOC_FLASH_ENCRYPTION_XTS_AES_256 and not SOC_EFUSE_CONSISTS_OF_ONE_KEY_BLOCK
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_128 and not SOC_FLASH_ENCRYPTION_XTS_AES_256 and not SOC_EFUSE_CONSISTS_OF_ONE_KEY_BLOCK and SOC_KEY_MANAGER_SUPPORTED
.. list-table:: eFuses Used in Flash Encryption
:widths: 25 40 10
:header-rows: 0
* - **eFuse**
- **Description**
- **Bit Depth**
* - ``BLOCK_KEYN``
- AES key storage. N is between 0 and 5. When using a Key Manager-based key, this eFuse is not used.
- 256-bit key block.
* - ``KEY_PURPOSE_N``
- Control the purpose of eFuse block ``BLOCK_KEYN``, where N is between 0 and 5. For flash encryption, the only valid value is ``4`` for ``XTS_AES_128_KEY``. When enabling Flash Encryption using a Key Manager-based key, this eFuse is not used.
- 4
* - ``KM_XTS_KEY_LENGTH_256``
- When enabling Flash Encryption using a Key Manager-based key, this eFuse is used to control the length of the XTS-AES key. Set this eFuse to 1 to use a 128-bit key, and to 0 to use a 256-bit key. This eFuse field is unused when enabling Flash Encryption using an eFuse-based key.
- 1
* - ``FORCE_USE_KEY_MANAGER_KEY``
- When enabling Flash Encryption using a Key Manager-based key, this eFuse is used to force the Key Manager to use the XTS-AES key. Set the bit 1 of this eFuse to use the Key Manager-based key. This eFuse field is unused when enabling Flash Encryption using an eFuse-based key.
- 1
* - ``DIS_DOWNLOAD_MANUAL_ENCRYPT``
- If set, disable flash encryption when in download bootmodes.
- 1
* - ``{IDF_TARGET_CRYPT_CNT}``
- Enable encryption and decryption, when an SPI boot mode is set. Feature is enabled if 1 or 3 bits are set in the eFuse, disabled otherwise.
- 3
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_128 and not SOC_FLASH_ENCRYPTION_XTS_AES_256 and not SOC_EFUSE_CONSISTS_OF_ONE_KEY_BLOCK and not SOC_KEY_MANAGER_SUPPORTED
.. list-table:: eFuses Used in Flash Encryption
:widths: 25 40 10
@@ -126,7 +182,7 @@ The flash encryption operation is controlled by various eFuses available on {IDF
- **Bit Depth**
* - ``BLOCK_KEYN``
- AES key storage. N is between 0 and 5.
- 256 bit key block
- 256-bit key block
* - ``KEY_PURPOSE_N``
- Control the purpose of eFuse block ``BLOCK_KEYN``, where N is between 0 and 5. For flash encryption, the only valid value is ``4`` for ``XTS_AES_128_KEY``.
- 4
@@ -181,7 +237,7 @@ Assuming that the eFuse values are in their default states and the second stage
1. On the first power-on reset, all data in flash is un-encrypted (plaintext). The first stage (ROM) bootloader loads the second stage bootloader.
2. Second stage bootloader reads the ``{IDF_TARGET_CRYPT_CNT}`` eFuse value (``0b0000000``). Since the value is ``0`` (even number of bits set), it configures and enables the flash encryption block. It also sets the ``FLASH_CRYPT_CONFIG`` eFuse to 0xF. For more information on the flash encryption block, see *{IDF_TARGET_NAME} Technical Reference Manual* > *eFuse Controller (eFuse)* > *Flash Encryption Block* [`PDF <{IDF_TARGET_TRM_EN_URL}#efuse>`__].
2. Second stage bootloader reads the ``{IDF_TARGET_CRYPT_CNT}`` eFuse value (``0b0000000``). Since the value is ``0`` (even number of bits set), it configures and enables the flash encryption block. It also sets the ``FLASH_CRYPT_CONFIG`` eFuse to 0xF. For more information on the flash encryption block, see **{IDF_TARGET_NAME} Technical Reference Manual** > **eFuse Controller (eFuse)** > **Flash Encryption Block** [`PDF <{IDF_TARGET_TRM_EN_URL}#efuse>`__].
3. Second stage bootloader first checks if a valid key is already present in the eFuse (e.g., burned using espefuse tool), then the process of key generation is skipped and the same key is used for flash encryption process. Otherwise, Second stage bootloader uses RNG (random) module to generate an AES-256 bit key and then writes it into the ``flash_encryption`` eFuse. The key cannot be accessed via software as the write and read protection bits for the ``flash_encryption`` eFuse are set. The flash encryption operations happen entirely by hardware, and the key cannot be accessed via software.
@@ -195,13 +251,46 @@ Assuming that the eFuse values are in their default states and the second stage
8. The device is then rebooted to start executing the encrypted image. The second stage bootloader calls the flash decryption block to decrypt the flash contents and then loads the decrypted contents into IRAM.
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_256
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_256 and SOC_KEY_MANAGER_SUPPORTED
1. On the first power-on reset, all data in flash is un-encrypted (plaintext). The first stage (ROM) bootloader loads the second stage bootloader.
2. Second stage bootloader reads the ``{IDF_TARGET_CRYPT_CNT}`` eFuse value (``0b000``). Since the value is ``0`` (even number of bits set), it configures and enables the flash encryption block. For more information on the flash encryption block, see *{IDF_TARGET_NAME} Technical Reference Manual* > *eFuse Controller (eFuse)* > *Auto Encryption Block* [`PDF <{IDF_TARGET_TRM_EN_URL}#efuse>`__].
2. Second stage bootloader reads the ``{IDF_TARGET_CRYPT_CNT}`` eFuse value (``0b000``). Since the value is ``0`` (even number of bits set), it configures and enables the flash encryption block. For more information on the flash encryption block, see **{IDF_TARGET_NAME} Technical Reference Manual** > **eFuse Controller (eFuse)** > **Manual Encryption Block** [`PDF <{IDF_TARGET_TRM_EN_URL}#efuse>`__].
3. Second stage bootloader first checks if a valid key is already present in the eFuse (e.g., burned using espefuse tool) then the process of key generation is skipped and the same key is used for flash encryption process. Otherwise, second stage bootloader uses RNG (random) module to generate an 256 bit or 512 bit key, depending on the value of :ref:`Size of generated XTS-AES key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>`, and then writes it into respectively one or two `BLOCK_KEYN` eFuses. The software also updates the ``KEY_PURPOSE_N`` for the blocks where the keys were stored. The key cannot be accessed via software as the write and read protection bits for one or two `BLOCK_KEYN` eFuses are set. ``KEY_PURPOSE_N`` field is write-protected as well. The flash encryption operations happen entirely by hardware, and the key cannot be accessed via software.
3. Second stage bootloader first checks if a valid key already exists, to decide whether to skip the key generation step:
- If Flash Encryption is intended to be enabled using an eFuse-based key, it checks if a valid key is already present in the eFuse (e.g., burned using espefuse tool).
- If Flash Encryption is intended to be enabled using a Key Manager-based key, it checks if there exists a valid key recovery info in the flash memory at the addresses: 0x0 and 0x1000.
If the check passes, the process of key generation is skipped and the same key is used for the flash encryption process.
4. Otherwise, if using an eFuse-based key, second stage bootloader uses RNG (random) module to generate an 256-bit or 512-bit key, depending on the value of :ref:`Size of generated XTS-AES key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>`, and then writes it into respectively one or two ``BLOCK_KEYN`` eFuses. The software also updates the ``KEY_PURPOSE_N`` for the blocks where the keys were stored. The key cannot be accessed via software as the write and read protection bits for one or two ``BLOCK_KEYN`` eFuses are set. ``KEY_PURPOSE_N`` field is write-protected as well. Whereas if using a Key Manager-based key, second stage bootloader writes the key recovery info to the flash memory at the address 0x0, followed by programming the ``KM_XTS_KEY_LENGTH_256`` and the ``FORCE_USE_KEY_MANAGER_KEY`` eFuses. The flash encryption operations happen entirely by hardware, and the key cannot be accessed via software.
5. Flash encryption block encrypts the flash contents – the second stage bootloader, applications and partitions marked as ``encrypted``. Encrypting in-place can take time, up to a minute for large partitions.
6. Second stage bootloader sets the first available bit in ``{IDF_TARGET_CRYPT_CNT}`` (0b001) to mark the flash contents as encrypted. Odd number of bits is set.
7. For :ref:`flash-enc-development-mode`, the second stage bootloader allows the UART bootloader to re-flash encrypted binaries. Also, the ``{IDF_TARGET_CRYPT_CNT}`` eFuse bits are NOT write-protected. In addition, the second stage bootloader by default sets the following eFuse bits:
.. list::
:esp32s2: - ``DIS_BOOT_REMAP``
- ``DIS_DOWNLOAD_ICACHE``
- ``DIS_DOWNLOAD_DCACHE``
- ``HARD_DIS_JTAG``
- ``DIS_LEGACY_SPI_BOOT``
8. For :ref:`flash-enc-release-mode`, the second stage bootloader sets all the eFuse bits set under development mode as well as ``DIS_DOWNLOAD_MANUAL_ENCRYPT``. It also write-protects the ``{IDF_TARGET_CRYPT_CNT}`` eFuse bits. To modify this behavior, see :ref:`uart-bootloader-encryption`.
9. The device is then rebooted to start executing the encrypted image. The second stage bootloader calls the flash decryption block to decrypt the flash contents and then loads the decrypted contents into IRAM.
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_256 and not SOC_KEY_MANAGER_SUPPORTED
1. On the first power-on reset, all data in flash is un-encrypted (plaintext). The first stage (ROM) bootloader loads the second stage bootloader.
2. Second stage bootloader reads the ``{IDF_TARGET_CRYPT_CNT}`` eFuse value (``0b000``). Since the value is ``0`` (even number of bits set), it configures and enables the flash encryption block. For more information on the flash encryption block, see **{IDF_TARGET_NAME} Technical Reference Manual** > **eFuse Controller (eFuse)** > **Auto Encryption Block** [`PDF <{IDF_TARGET_TRM_EN_URL}#efuse>`__].
3. Second stage bootloader first checks if a valid key is already present in the eFuse (e.g., burned using espefuse tool) then the process of key generation is skipped and the same key is used for flash encryption process. Otherwise, second stage bootloader uses RNG (random) module to generate a 256-bit or 512-bit key, depending on the value of :ref:`Size of generated XTS-AES key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>`, and then writes it into respectively one or two ``BLOCK_KEYN`` eFuses. The software also updates the ``KEY_PURPOSE_N`` for the blocks where the keys were stored. The key cannot be accessed via software as the write and read protection bits for one or two `BLOCK_KEYN` eFuses are set. ``KEY_PURPOSE_N`` field is write-protected as well. The flash encryption operations happen entirely by hardware, and the key cannot be accessed via software.
4. Flash encryption block encrypts the flash contents - the second stage bootloader, applications and partitions marked as ``encrypted``. Encrypting in-place can take time, up to a minute for large partitions.
@@ -221,31 +310,58 @@ Assuming that the eFuse values are in their default states and the second stage
8. The device is then rebooted to start executing the encrypted image. The second stage bootloader calls the flash decryption block to decrypt the flash contents and then loads the decrypted contents into IRAM.
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_128 and not SOC_FLASH_ENCRYPTION_XTS_AES_256 and not SOC_EFUSE_CONSISTS_OF_ONE_KEY_BLOCK and SOC_KEY_MANAGER_SUPPORTED
1. On the first power-on reset, all data in flash is un-encrypted (plaintext). The first stage (ROM) bootloader loads the second stage bootloader.
2. Second stage bootloader reads the ``{IDF_TARGET_CRYPT_CNT}`` eFuse value (``0b000``). Since the value is ``0`` (even number of bits set), it configures and enables the flash encryption block. For more information on the flash encryption block, see `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_.
3. Second stage bootloader first checks if a valid key already exists, to decide whether to skip the key generation step:
- If Flash Encryption is intended to be enabled using an eFuse-based key, it checks if a valid key is already present in the eFuse (e.g., burned using espefuse tool).
- If Flash Encryption is intended to be enabled using a Key Manager-based key, it checks if there exists a valid key recovery info in the flash memory at the addresses: 0x0 and 0x1000.
If the check passes, the process of key generation is skipped and the same key is used for the flash encryption process.
4. Otherwise, if using an eFuse-based key second stage bootloader uses RNG (random) module to generate a 256-bit key, and then writes it into respectively one ``BLOCK_KEYN`` eFuse block. The software also updates the ``KEY_PURPOSE_N`` for the block where the key were stored. The key cannot be accessed via software as the write and read protection bits for the ``BLOCK_KEYN`` eFuse block is set. ``KEY_PURPOSE_N`` field is write-protected as well. Whereas if using a Key Manager-based key, second stage bootloader writes the key recovery info to the flash memory at the address 0x0, followed by programming the ``KM_XTS_KEY_LENGTH_256`` and the ``FORCE_USE_KEY_MANAGER_KEY`` eFuses. The flash encryption operations happen entirely by hardware, and the key cannot be accessed via software.
5. Flash encryption block encrypts the flash contents - the second stage bootloader, applications and partitions marked as ``encrypted``. Encrypting in-place can take time, up to a minute for large partitions.
6. Second stage bootloader sets the first available bit in ``{IDF_TARGET_CRYPT_CNT}`` (0b001) to mark the flash contents as encrypted. Odd number of bits is set.
7. For :ref:`flash-enc-development-mode`, the second stage bootloader allows the UART bootloader to re-flash encrypted binaries. Also, the ``{IDF_TARGET_CRYPT_CNT}`` eFuse bits are NOT write-protected. In addition, the second stage bootloader by default sets the eFuse bits ``DIS_DOWNLOAD_ICACHE``, ``DIS_PAD_JTAG``, ``DIS_USB_JTAG`` and ``DIS_LEGACY_SPI_BOOT``.
8. For :ref:`flash-enc-release-mode`, the second stage bootloader sets all the eFuse bits set under development mode as well as ``DIS_DOWNLOAD_MANUAL_ENCRYPT``. It also write-protects the ``{IDF_TARGET_CRYPT_CNT}`` eFuse bits. To modify this behavior, see :ref:`uart-bootloader-encryption`.
9. The device is then rebooted to start executing the encrypted image. The second stage bootloader calls the flash decryption block to decrypt the flash contents and then loads the decrypted contents into IRAM.
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_128 and not SOC_FLASH_ENCRYPTION_XTS_AES_256 and not SOC_EFUSE_CONSISTS_OF_ONE_KEY_BLOCK
1. On the first power-on reset, all data in flash is un-encrypted (plaintext). The first stage (ROM) bootloader loads the second stage bootloader.
2. Second stage bootloader reads the ``{IDF_TARGET_CRYPT_CNT}`` eFuse value (``0b000``). Since the value is ``0`` (even number of bits set), it configures and enables the flash encryption block. For more information on the flash encryption block, see `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_.
3. Second stage bootloader uses RNG (random) module to generate an 256 bit key and then writes it into `BLOCK_KEYN` eFuse. The software also updates the ``KEY_PURPOSE_N`` for the block where the key is stored. The key cannot be accessed via software as the write and read protection bits for `BLOCK_KEYN` eFuse are set. ``KEY_PURPOSE_N`` field is write-protected as well. The flash encryption is completely conducted by hardware, and the key cannot be accessed via software. If a valid key is already present in the eFuse (e.g., burned using espefuse tool) then the process of key generation is skipped and the same key is used for flash encryption process.
3. Second stage bootloader first checks if a valid key is already present in the eFuse (e.g., burned using espefuse tool), then the process of key generation is skipped and the same key is used for flash encryption process.
4. Flash encryption block encrypts the flash contents - the second stage bootloader, applications and partitions marked as ``encrypted``. Encrypting in-place can take time, up to a minute for large partitions.
4. Otherwise, second stage bootloader uses RNG (random) module to generate a 256-bit key and then writes it into ``BLOCK_KEYN`` eFuse. The software also updates the ``KEY_PURPOSE_N`` for the block where the key is stored. The key cannot be accessed via software as the write and read protection bits for ``BLOCK_KEYN`` eFuse are set. ``KEY_PURPOSE_N`` field is write-protected as well. The flash encryption is completely conducted by hardware, and the key cannot be accessed via software.
5. Second stage bootloader sets the first available bit in ``{IDF_TARGET_CRYPT_CNT}`` (0b001) to mark the flash contents as encrypted. Odd number of bits is set.
5. Flash encryption block encrypts the flash contents - the second stage bootloader, applications and partitions marked as ``encrypted``. Encrypting in-place can take time, up to a minute for large partitions.
6. For :ref:`flash-enc-development-mode`, the second stage bootloader allows the UART bootloader to re-flash encrypted binaries. Also, the ``{IDF_TARGET_CRYPT_CNT}`` eFuse bits are NOT write-protected. In addition, the second stage bootloader by default sets the eFuse bits ``DIS_DOWNLOAD_ICACHE``, ``DIS_PAD_JTAG``, ``DIS_USB_JTAG`` and ``DIS_LEGACY_SPI_BOOT``.
6. Second stage bootloader sets the first available bit in ``{IDF_TARGET_CRYPT_CNT}`` (0b001) to mark the flash contents as encrypted. Odd number of bits is set.
7. For :ref:`flash-enc-release-mode`, the second stage bootloader sets all the eFuse bits set under development mode as well as ``DIS_DOWNLOAD_MANUAL_ENCRYPT``. It also write-protects the ``{IDF_TARGET_CRYPT_CNT}`` eFuse bits. To modify this behavior, see :ref:`uart-bootloader-encryption`.
7. For :ref:`flash-enc-development-mode`, the second stage bootloader allows the UART bootloader to re-flash encrypted binaries. Also, the ``{IDF_TARGET_CRYPT_CNT}`` eFuse bits are NOT write-protected. In addition, the second stage bootloader by default sets the eFuse bits ``DIS_DOWNLOAD_ICACHE``, ``DIS_PAD_JTAG``, ``DIS_USB_JTAG`` and ``DIS_LEGACY_SPI_BOOT``.
8. The device is then rebooted to start executing the encrypted image. The second stage bootloader calls the flash decryption block to decrypt the flash contents and then loads the decrypted contents into IRAM.
8. For :ref:`flash-enc-release-mode`, the second stage bootloader sets all the eFuse bits set under development mode as well as ``DIS_DOWNLOAD_MANUAL_ENCRYPT``. It also write-protects the ``{IDF_TARGET_CRYPT_CNT}`` eFuse bits. To modify this behavior, see :ref:`uart-bootloader-encryption`.
9. The device is then rebooted to start executing the encrypted image. The second stage bootloader calls the flash decryption block to decrypt the flash contents and then loads the decrypted contents into IRAM.
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_128 and SOC_EFUSE_CONSISTS_OF_ONE_KEY_BLOCK
1. On the first power-on reset, all data in flash is un-encrypted (plaintext). The first stage (ROM) bootloaders loads the second stage bootloader.
1. On the first power-on reset, all data in flash is un-encrypted (plaintext). The first stage (ROM) bootloader loads the second stage bootloader.
2. The second stage bootloader reads the ``{IDF_TARGET_CRYPT_CNT}`` eFuse value (``0b000``). Since the value is ``0`` (even number of bits set), it configures and enables the flash encryption block. For more information on the flash encryption block, see `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_.
3. The second stage bootloader uses RNG (random) module to generate an 256 or 128 bit key (depends on :ref:`Size of generated XTS-AES key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>`) and then writes it into `BLOCK_KEY0` eFuse. The software also updates the ``XTS_KEY_LENGTH_256`` according to the chosen option. The key cannot be accessed via software as the write and read protection bits for ``BLOCK_KEY0`` eFuse are set. The flash encryption operations happen entirely by hardware, and the key cannot be accessed via software. If 128-bit flash encryption key is used, then only the lower 128 bits of the eFuse key block are read-protected, the remaining 128 bits are readable, which is required for secure boot. The entire eFuse block is write-protected. If the FE key is 256 bits long, then ``XTS_KEY_LENGTH_256`` is 1, otherwise it is 0. To prevent this eFuse from being accidentally changed in the future (from 0 to 1), we set a write-protect bit for the RELEASE mode. If a valid key is already present in the eFuse (e.g., burned using espefuse tool) then the process of key generation is skipped and the same key is used for flash encryption process.
3. The second stage bootloader uses RNG (random) module to generate an 256 or 128 bit key (depends on :ref:`Size of generated XTS-AES key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>`) and then writes it into `BLOCK_KEY0` eFuse. The software also updates the ``XTS_KEY_LENGTH_256`` according to the chosen option. The key cannot be accessed via software as the write and read protection bits for ``BLOCK_KEY0`` eFuse are set. The flash encryption operations happen entirely by hardware, and the key cannot be accessed via software. If 128-bit flash encryption key is used, then only the lower 128 bits of the eFuse key block are read-protected, the remaining 128 bits are readable, which is required for secure boot. The entire eFuse block is write-protected. If the FE key is 256 bits long, then ``XTS_KEY_LENGTH_256`` is 1, otherwise it is 0. To prevent this eFuse from being accidentally changed in the future (from 0 to 1), we set a write-protect bit for the release mode. If a valid key is already present in the eFuse (e.g., burned using espefuse tool) then the process of key generation is skipped and the same key is used for flash encryption process.
4. Flash encryption block encrypts the flash contents - the second stage bootloader, applications and partitions marked as ``encrypted``. Encrypting in-place can take time, up to a minute for large partitions.
@@ -297,14 +413,15 @@ To test flash encryption process, take the following steps:
.. list::
- :ref:`Enable flash encryption on boot <CONFIG_SECURE_FLASH_ENC_ENABLED>`.
- :ref:`Select encryption mode <CONFIG_SECURE_FLASH_ENCRYPTION_MODE>` (**Development mode** by default).
- :ref:`Select encryption mode <CONFIG_SECURE_FLASH_ENCRYPTION_MODE>` (**development mode** by default).
:esp32: - :ref:`Select UART ROM download mode <CONFIG_SECURE_UART_ROM_DL_MODE>` (**enabled** by default). Note that for the ESP32 target, the choice is only available when :ref:`CONFIG_ESP32_REV_MIN` level is set to 3 (ESP32 V3).
:not esp32: - :ref:`Select UART ROM download mode <CONFIG_SECURE_UART_ROM_DL_MODE>` (**enabled** by default).
:SOC_FLASH_ENCRYPTION_XTS_AES_OPTIONS: - Set :ref:`Size of generated XTS-AES key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>`.
:SOC_KEY_MANAGER_SUPPORTED: - :ref:`Select the key source for the Flash Encryption key <CONFIG_SECURE_FLASH_ENCRYPTION_KEY_SOURCE>`.
- :ref:`Select the appropriate bootloader log verbosity <CONFIG_BOOTLOADER_LOG_LEVEL>`.
- Save the configuration and exit.
Enabling flash encryption will increase the size of bootloader, which might require updating partition table offset. See :ref:`bootloader-size`.
Enabling flash encryption will increase the size of bootloader, which might require updating partition table offset. See :ref:`bootloader-size`.
3. Run the command given below to build and flash the complete images.
@@ -318,13 +435,27 @@ Enabling flash encryption will increase the size of bootloader, which might requ
This command will write to flash memory unencrypted images: the second stage bootloader, the partition table and applications. Once the flashing is complete, {IDF_TARGET_NAME} will reset. On the next boot, the second stage bootloader encrypts: the second stage bootloader, application partitions and partitions marked as ``encrypted`` then resets. Encrypting in-place can take time, up to a minute for large partitions. After that, the application is decrypted at runtime and executed.
A sample output of the first {IDF_TARGET_NAME} boot after enabling flash encryption is given below:
.. only:: SOC_KEY_MANAGER_SUPPORTED
A sample output of the first {IDF_TARGET_NAME} boot after enabling flash encryption using a Key Manager-based key is given below:
.. include:: {IDF_TARGET_PATH_NAME}_log.inc
:start-after: first_boot_enc_km
:end-before: ------
A sample output of subsequent {IDF_TARGET_NAME} boot mentions that Flash Encryption is already enabled (ESP-ROM log mentions that the Key Manager-based key is being used):
.. include:: {IDF_TARGET_PATH_NAME}_log.inc
:start-after: already_en_enc_km
:end-before: ------
A sample output of the first {IDF_TARGET_NAME} boot after enabling flash encryption using an eFuse-based key is given below:
.. include:: {IDF_TARGET_PATH_NAME}_log.inc
:start-after: first_boot_enc
:end-before: ------
A sample output of subsequent {IDF_TARGET_NAME} boots just mentions that flash encryption is already enabled:
A sample output of subsequent {IDF_TARGET_NAME} boot mentions that Flash Encryption is already enabled:
.. include:: {IDF_TARGET_PATH_NAME}_log.inc
:start-after: already_en_enc
@@ -338,7 +469,7 @@ At this stage, if you need to update and re-flash binaries, see :ref:`encrypt-pa
Using Host Generated Key
""""""""""""""""""""""""
It is possible to pre-generate a flash encryption key on the host computer and burn it into the eFuse. This allows you to pre-encrypt data on the host and flash already encrypted data without needing a plaintext flash update. This feature can be used in both :ref:`flash-enc-development-mode` and :ref:`flash-enc-release-mode`. Without a pre-generated key, data is flashed in plaintext and then {IDF_TARGET_NAME} encrypts the data in-place.
It is possible to pre-generate a flash encryption key on the host computer and program it into the device. This allows you to pre-encrypt data on the host and flash already encrypted data without needing a plaintext flash update. This feature can be used in both :ref:`flash-enc-development-mode` and :ref:`flash-enc-release-mode`. Without a pre-generated key, data is flashed in plaintext and then {IDF_TARGET_NAME} encrypts the data in-place.
.. note::
@@ -350,7 +481,7 @@ It is possible to pre-generate a flash encryption key on the host computer and b
Note that {IDF_TARGET_NAME} only has one eFuse key block for both Secure Boot and Flash Encryption keys. Therefore, writing the host-generated Flash Encryption key must be done with Secure Boot key (if used), otherwise Secure Boot cannot be used.
To use a host generated key, take the following steps:
To use a host generated key and program it into the eFuses of the device, take the following steps:
1. Ensure that you have an {IDF_TARGET_NAME} device with default flash encryption eFuse settings as shown in :ref:`flash-encryption-efuse`.
@@ -421,13 +552,13 @@ To use a host generated key, take the following steps:
idf.py --port PORT efuse-burn-key BLOCK my_flash_encryption_key.bin XTS_AES_128_KEY
For AES-256 (512-bit key) - ``XTS_AES_256_KEY_1`` and ``XTS_AES_256_KEY_2``. ``idf.py`` supports burning both these two key purposes together with a 512 bit key to two separate key blocks via the virtual key purpose ``XTS_AES_256_KEY``. When this is used ``idf.py`` will burn the first 256 bit of the key to the specified ``BLOCK`` and burn the corresponding block key purpose to ``XTS_AES_256_KEY_1``. The last 256 bit of the key will be burned to the first free key block after ``BLOCK`` and the corresponding block key purpose to ``XTS_AES_256_KEY_2``
For AES-256 (512-bit key) - ``XTS_AES_256_KEY_1`` and ``XTS_AES_256_KEY_2``. ``idf.py`` supports burning both these two key purposes together with a 512 bit key to two separate key blocks via the virtual key purpose ``XTS_AES_256_KEY``. When this is used ``idf.py`` will burn the first 256 bits of the key to the specified ``BLOCK`` and burn the corresponding block key purpose to ``XTS_AES_256_KEY_1``. The last 256 bits of the key will be burned to the first free key block after ``BLOCK`` and the corresponding block key purpose to ``XTS_AES_256_KEY_2``
.. code-block:: bash
idf.py --port PORT efuse-burn-key BLOCK my_flash_encryption_key.bin XTS_AES_256_KEY
If you wish to specify exactly which two blocks are used then it is possible to divide key into two 256 bit keys, and manually burn each half with ``XTS_AES_256_KEY_1`` and ``XTS_AES_256_KEY_2`` as key purposes:
If you wish to specify exactly which two blocks are used then it is possible to divide key into two 256-bit keys, and manually burn each half with ``XTS_AES_256_KEY_1`` and ``XTS_AES_256_KEY_2`` as key purposes:
.. code-block:: bash
@@ -469,12 +600,12 @@ To use a host generated key, take the following steps:
4. In :ref:`project-configuration-menu`, do the following:
- :ref:`Enable flash encryption on boot <CONFIG_SECURE_FLASH_ENC_ENABLED>`
- :ref:`Select encryption mode <CONFIG_SECURE_FLASH_ENCRYPTION_MODE>` (**Development mode** by default)
- :ref:`Select the appropriate bootloader log verbosity <CONFIG_BOOTLOADER_LOG_LEVEL>`
- Save the configuration and exit.
- :ref:`Enable flash encryption on boot <CONFIG_SECURE_FLASH_ENC_ENABLED>`
- :ref:`Select encryption mode <CONFIG_SECURE_FLASH_ENCRYPTION_MODE>` (**development mode** by default)
- :ref:`Select the appropriate bootloader log verbosity <CONFIG_BOOTLOADER_LOG_LEVEL>`
- Save the configuration and exit.
Enabling flash encryption will increase the size of bootloader, which might require updating partition table offset. See :ref:`bootloader-size`.
Enabling flash encryption will increase the size of bootloader, which might require updating partition table offset. See :ref:`bootloader-size`.
5. Run the command given below to build and flash the complete images.
@@ -488,9 +619,75 @@ Enabling flash encryption will increase the size of bootloader, which might requ
This command will write to flash memory unencrypted images: the second stage bootloader, the partition table and applications. Once the flashing is complete, {IDF_TARGET_NAME} will reset. On the next boot, the second stage bootloader encrypts: the second stage bootloader, application partitions and partitions marked as ``encrypted`` then resets. Encrypting in-place can take time, up to a minute for large partitions. After that, the application is decrypted at runtime and executed.
If using Development Mode, then the easiest way to update and re-flash binaries is :ref:`encrypt-partitions`.
.. only:: SOC_KEY_MANAGER_SUPPORTED
If using Release Mode, then it is possible to pre-encrypt the binaries on the host and then flash them as ciphertext. See :ref:`manual-encryption`.
To use a host generated key and deploy it into the device's Key Manager of the device, take the following steps:
1. Ensure that you have an {IDF_TARGET_NAME} device with default flash encryption eFuse settings as shown in :ref:`flash-encryption-efuse`.
See how to check :ref:`flash-encryption-status`.
2. Generate a random key by running:
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_256
If :ref:`Size of generated XTS-AES key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>` is AES-128 (256-bit key):
.. code-block:: bash
idf.py secure-generate-flash-encryption-key my_flash_encryption_key.bin
else if :ref:`Size of generated XTS-AES key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>` is AES-256 (512-bit key):
.. code-block:: bash
idf.py secure-generate-flash-encryption-key --keylen 512 my_flash_encryption_key.bin
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_128 and not SOC_FLASH_ENCRYPTION_XTS_AES_256 and not SOC_EFUSE_CONSISTS_OF_ONE_KEY_BLOCK
.. code-block:: bash
idf.py secure-generate-flash-encryption-key my_flash_encryption_key.bin
3. **Before the first encrypted boot**, deploy the key into your device's Key Manager via its AES-deploy mode, using an init key and an auxiliary key.
4. The deployment process will generate key recovery information for the deployed key. Store the information at the flash address 0x0 using the following command:
.. code-block:: bash
esptool --port PORT --baud BAUD write-flash 0x0 key_recovery_info.bin
If the key is not deployed and the device is started after enabling Flash Encryption, the {IDF_TARGET_NAME} will generate and deploy a random key that software cannot access or modify.
.. note::
This command does not include any user files which should be written to the partitions on the flash memory. Please write them manually before running this command. Otherwise, the files should be encrypted separately before writing.
5. In :ref:`project-configuration-menu`, do the following:
- :ref:`Enable Flash Encryption on boot <CONFIG_SECURE_FLASH_ENC_ENABLED>`
- :ref:`Select encryption mode <CONFIG_SECURE_FLASH_ENCRYPTION_MODE>` (**development mode** by default)
- :ref:`Select Flash Encryption key source as the Key Manager <CONFIG_SECURE_FLASH_ENCRYPTION_KEY_SOURCE>`
- :ref:`Select the appropriate bootloader log verbosity <CONFIG_BOOTLOADER_LOG_LEVEL>`
- Save the configuration and exit.
Enabling flash encryption will increase the size of bootloader, which might require updating partition table offset. See :ref:`bootloader-size`.
6. Run the command given below to build and flash the complete images.
.. code-block:: bash
idf.py flash monitor
.. note::
This command does not include any user files which should be written to the partitions on the flash memory. Please write them manually before running this command. Otherwise, the files should be encrypted separately before writing.
If using development mode, then the easiest way to update and re-flash binaries is :ref:`encrypt-partitions`.
If using release mode, then it is possible to pre-encrypt the binaries on the host and then flash them as ciphertext. See :ref:`manual-encryption`.
.. _encrypt-partitions:
@@ -504,7 +701,7 @@ If you update your application code (done in plaintext) and want to re-flash it,
idf.py encrypted-app-flash monitor
If all partitions needs to be updated in encrypted format, run:
If all partitions need to be updated in encrypted format, run:
.. code-block:: bash
@@ -519,7 +716,7 @@ If all partitions needs to be updated in encrypted format, run:
Release Mode
^^^^^^^^^^^^
In Release mode, UART bootloader cannot perform flash encryption operations. New plaintext images can ONLY be downloaded using the over-the-air (OTA) scheme which will encrypt the plaintext image before writing to flash.
In release mode, UART bootloader cannot perform flash encryption operations. New plaintext images can ONLY be downloaded using the over-the-air (OTA) scheme which will encrypt the plaintext image before writing to flash.
To use this mode, take the following steps:
@@ -531,16 +728,16 @@ To use this mode, take the following steps:
.. list::
- :ref:`Enable flash encryption on boot <CONFIG_SECURE_FLASH_ENC_ENABLED>`.
:esp32: - :ref:`Select Release mode <CONFIG_SECURE_FLASH_ENCRYPTION_MODE>`. (Note that once Release mode is selected, the ``DISABLE_DL_ENCRYPT`` and ``DISABLE_DL_DECRYPT`` eFuse bits will be burned to disable flash encryption hardware in ROM Download Mode.)
- :ref:`Enable Flash Encryption on boot <CONFIG_SECURE_FLASH_ENC_ENABLED>`.
:esp32: - :ref:`Select release mode <CONFIG_SECURE_FLASH_ENCRYPTION_MODE>`. (Note that once release mode is selected, the ``DISABLE_DL_ENCRYPT`` and ``DISABLE_DL_DECRYPT`` eFuse bits will be burned to disable flash encryption hardware in ROM Download Mode.)
:esp32: - :ref:`Select UART ROM download mode (Permanently disabled (recommended)) <CONFIG_SECURE_UART_ROM_DL_MODE>` (Note that this option is only available when :ref:`CONFIG_ESP32_REV_MIN` is set to 3 (ESP32 V3).) The default choice is to keep UART ROM download mode enabled, however it is recommended to permanently disable this mode to reduce the options available to an attacker.
:not esp32: - :ref:`Select Release mode <CONFIG_SECURE_FLASH_ENCRYPTION_MODE>`. (Note that once Release mode is selected, the ``EFUSE_DIS_DOWNLOAD_MANUAL_ENCRYPT`` eFuse bit will be burned to disable flash encryption hardware in ROM Download Mode.)
:not esp32: - :ref:`Select release mode <CONFIG_SECURE_FLASH_ENCRYPTION_MODE>`. (Note that once release mode is selected, the ``EFUSE_DIS_DOWNLOAD_MANUAL_ENCRYPT`` eFuse bit will be burned to disable flash encryption hardware in ROM Download Mode.)
:not esp32: - :ref:`Select UART ROM download mode (Permanently switch to Secure mode (recommended)) <CONFIG_SECURE_UART_ROM_DL_MODE>`. This is the default option, and is recommended. It is also possible to change this configuration setting to permanently disable UART ROM download mode, if this mode is not needed.
:SOC_FLASH_ENCRYPTION_XTS_AES_SUPPORT_PSEUDO_ROUND: - :ref:`Select enable XTS-AES's pseudo rounds function <CONFIG_SECURE_FLASH_PSEUDO_ROUND_FUNC>`. This option is selected by default and its strength is configured to level low considering the performance impact on the flash encryption/decryption operations. Please refer to :ref:`xts-aes-pseudo-round-func` for more information regarding the performance impact per security level.
- :ref:`Select the appropriate bootloader log verbosity <CONFIG_BOOTLOADER_LOG_LEVEL>`.
- Save the configuration and exit.
Enabling flash encryption will increase the size of bootloader, which might require updating partition table offset. See :ref:`bootloader-size`.
Enabling flash encryption will increase the size of bootloader, which might require updating partition table offset. See :ref:`bootloader-size`.
3. Run the command given below to build and flash the complete images.
@@ -555,7 +752,7 @@ Enabling flash encryption will increase the size of bootloader, which might requ
This command will write to flash memory unencrypted images: the second stage bootloader, the partition table and applications. Once the flashing is complete, {IDF_TARGET_NAME} will reset. On the next boot, the second stage bootloader encrypts: the second stage bootloader, application partitions and partitions marked as ``encrypted`` then resets. Encrypting in-place can take time, up to a minute for large partitions. After that, the application is decrypted at runtime and executed.
Once the flash encryption is enabled in Release mode, the bootloader will write-protect the ``{IDF_TARGET_CRYPT_CNT}`` eFuse.
Once the flash encryption is enabled in release mode, the bootloader will write-protect the ``{IDF_TARGET_CRYPT_CNT}`` eFuse.
For subsequent plaintext field updates, use :ref:`OTA scheme <updating-encrypted-flash-ota>`.
@@ -574,7 +771,7 @@ When using Flash Encryption in production:
- Do not reuse the same flash encryption key between multiple devices. This means that an attacker who copies encrypted data from one device cannot transfer it to a second device.
:esp32: - When using ESP32 V3, if the UART ROM Download Mode is not needed for a production device then it should be disabled to provide an extra level of protection. Do this by calling :cpp:func:`esp_efuse_disable_rom_download_mode` during application startup. Alternatively, configure the project :ref:`CONFIG_ESP32_REV_MIN` level to 3 (targeting ESP32 V3 only) and select the :ref:`CONFIG_SECURE_UART_ROM_DL_MODE` to "Permanently disable ROM Download Mode (recommended)". The ability to disable ROM Download Mode is not available on earlier ESP32 versions.
:not esp32: - The UART ROM Download Mode should be disabled entirely if it is not needed, or permanently set to "Secure Download Mode" otherwise. Secure Download Mode permanently limits the available commands to updating SPI config, changing baud rate, basic flash write, and returning a summary of the currently enabled security features with the `get-security-info` command. The default behaviour is to set Secure Download Mode on first boot in Release mode. To disable Download Mode entirely, select :ref:`CONFIG_SECURE_UART_ROM_DL_MODE` to "Permanently disable ROM Download Mode (recommended)" or call :cpp:func:`esp_efuse_disable_rom_download_mode` at runtime.
:not esp32: - The UART ROM Download Mode should be disabled entirely if it is not needed, or permanently set to "Secure Download Mode" otherwise. Secure Download Mode permanently limits the available commands to updating SPI config, changing baud rate, basic flash write, and returning a summary of the currently enabled security features with the `get-security-info` command. The default behaviour is to set Secure Download Mode on first boot in release mode. To disable Download Mode entirely, select :ref:`CONFIG_SECURE_UART_ROM_DL_MODE` to "Permanently disable ROM Download Mode (recommended)" or call :cpp:func:`esp_efuse_disable_rom_download_mode` at runtime.
- Enable :doc:`Secure Boot <secure-boot-v2>` as an extra layer of protection, and to prevent an attacker from selectively corrupting any part of the flash before boot.
Enable Flash Encryption Externally
@@ -589,55 +786,55 @@ Once flash encryption is enabled, the ``{IDF_TARGET_CRYPT_CNT}`` eFuse value wil
1. If the bootloader partition is re-flashed with a **plaintext second stage bootloader image**, the first stage (ROM) bootloader will fail to load the second stage bootloader resulting in the following failure:
.. only:: esp32
.. only:: esp32
.. code-block:: bash
.. code-block:: bash
rst:0x3 (SW_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
flash read err, 1000
ets_main.c 371
ets Jun 8 2016 00:22:57
rst:0x3 (SW_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
flash read err, 1000
ets_main.c 371
ets Jun 8 2016 00:22:57
rst:0x7 (TG0WDT_SYS_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
flash read err, 1000
ets_main.c 371
ets Jun 8 2016 00:22:57
rst:0x7 (TG0WDT_SYS_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
flash read err, 1000
ets_main.c 371
ets Jun 8 2016 00:22:57
rst:0x7 (TG0WDT_SYS_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
flash read err, 1000
ets_main.c 371
ets Jun 8 2016 00:22:57
rst:0x7 (TG0WDT_SYS_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
flash read err, 1000
ets_main.c 371
ets Jun 8 2016 00:22:57
rst:0x7 (TG0WDT_SYS_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
flash read err, 1000
ets_main.c 371
ets Jun 8 2016 00:22:57
rst:0x7 (TG0WDT_SYS_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
flash read err, 1000
ets_main.c 371
ets Jun 8 2016 00:22:57
rst:0x7 (TG0WDT_SYS_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
flash read err, 1000
ets_main.c 371
ets Jun 8 2016 00:22:57
rst:0x7 (TG0WDT_SYS_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
flash read err, 1000
ets_main.c 371
ets Jun 8 2016 00:22:57
.. only:: not esp32
.. only:: not esp32
.. code-block:: bash
.. code-block:: bash
rst:0x3 (SW_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
invalid header: 0xb414f76b
invalid header: 0xb414f76b
invalid header: 0xb414f76b
invalid header: 0xb414f76b
invalid header: 0xb414f76b
invalid header: 0xb414f76b
invalid header: 0xb414f76b
rst:0x3 (SW_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
invalid header: 0xb414f76b
invalid header: 0xb414f76b
invalid header: 0xb414f76b
invalid header: 0xb414f76b
invalid header: 0xb414f76b
invalid header: 0xb414f76b
invalid header: 0xb414f76b
.. note::
.. note::
The value of invalid header will be different for every application.
The value of invalid header will be different for every application.
.. note::
.. note::
This error also appears if the flash contents are erased or corrupted.
This error also appears if the flash contents are erased or corrupted.
2. If the second stage bootloader is encrypted, but the partition table is re-flashed with a **plaintext partition table image**, the bootloader will fail to read the partition table resulting in the following failure:
@@ -700,7 +897,7 @@ Once flash encryption is enabled, the ``{IDF_TARGET_CRYPT_CNT}`` eFuse value wil
{IDF_TARGET_NAME} Flash Encryption Status
-----------------------------------------
1. Ensure that you have an {IDF_TARGET_NAME} device with default flash encryption eFuse settings as shown in :ref:`flash-encryption-efuse`.
Ensure that you have an {IDF_TARGET_NAME} device with default flash encryption eFuse settings as shown in :ref:`flash-encryption-efuse`.
To check if flash encryption on your {IDF_TARGET_NAME} device is enabled, do one of the following:
@@ -758,7 +955,7 @@ It is recommended to use the partition write function :cpp:func:`esp_partition_w
You can also pre-encrypt and write data using the function :cpp:func:`esp_flash_write_encrypted`
Also, the following ROM function exist but not supported in esp-idf applications:
Also, the following ROM functions exist but are not supported in ESP-IDF applications:
- ``esp_rom_spiflash_write_encrypted`` pre-encrypts and writes data to flash
- ``SPIWrite`` writes unencrypted data to flash
@@ -790,9 +987,9 @@ Updating Encrypted Flash via Serial
Flashing an encrypted device via serial bootloader requires that the serial bootloader download interface has not been permanently disabled via eFuse.
In Development Mode, the recommended method is :ref:`encrypt-partitions`.
In development mode, the recommended method is :ref:`encrypt-partitions`.
In Release Mode, if a copy of the same key stored in eFuse is available on the host then it is possible to pre-encrypt files on the host and then flash them. See :ref:`manual-encryption`.
In release mode, if a copy of the same key stored in eFuse is available on the host then it is possible to pre-encrypt files on the host and then flash them. See :ref:`manual-encryption`.
Disabling Flash Encryption
--------------------------
@@ -801,11 +998,11 @@ If flash encryption was enabled accidentally, flashing of plaintext data will so
.. only:: esp32
For flash encryption in Development mode, encryption can be disabled by burning the ``{IDF_TARGET_CRYPT_CNT}`` eFuse. It can only be done three times per chip by taking the following steps:
For flash encryption in development mode, encryption can be disabled by burning the ``{IDF_TARGET_CRYPT_CNT}`` eFuse. It can only be done three times per chip by taking the following steps:
.. only:: not esp32
For flash encryption in Development mode, encryption can be disabled by burning the ``{IDF_TARGET_CRYPT_CNT}`` eFuse. It can only be done one time per chip by taking the following steps:
For flash encryption in development mode, encryption can be disabled by burning the ``{IDF_TARGET_CRYPT_CNT}`` eFuse. It can only be done one time per chip by taking the following steps:
#. In :ref:`project-configuration-menu`, disable :ref:`Enable flash encryption on boot <CONFIG_SECURE_FLASH_ENC_ENABLED>`, then save and exit.
#. Open project configuration menu again and **double-check** that you have disabled this option! If this option is left enabled, the bootloader will immediately re-enable encryption when it boots.
@@ -828,7 +1025,9 @@ Key Points About Flash Encryption
:esp32: - The flash encryption algorithm is AES-256, where the key is "tweaked" with the offset address of each 32 byte block of flash. This means that every 32-byte block (two consecutive 16 byte AES blocks) is encrypted with a unique key derived from the flash encryption key.
:SOC_FLASH_ENCRYPTION_XTS_AES_256: - Flash memory contents is encrypted using XTS-AES-128 or XTS-AES-256. The flash encryption key is 256 bits and 512 bits respectively and stored in one or two ``BLOCK_KEYN`` eFuses internal to the chip and, by default, is protected from software access.
:SOC_FLASH_ENCRYPTION_XTS_AES_256 and SOC_KEY_MANAGER_SUPPORTED: - Flash memory contents are encrypted using XTS-AES-128 or XTS-AES-256. The flash encryption key is 256 bits and 512 bits respectively and stored in one or two ``BLOCK_KEYN`` eFuses internal to the chip and, by default, is protected from software access.
:SOC_FLASH_ENCRYPTION_XTS_AES_256 and not SOC_KEY_MANAGER_SUPPORTED: - Flash memory contents are encrypted using XTS-AES-128 or XTS-AES-256, with respective key sizes of 256 or 512 bits. If using an eFuse-based key, the key is stored in one or two internal ``BLOCK_KEYN`` eFuses. However, if using a Key Manager-based key, the key is stored within the Key Manager itself. In either case, the key is protected from software access by default.
:SOC_FLASH_ENCRYPTION_XTS_AES_128 and not SOC_FLASH_ENCRYPTION_XTS_AES_256 and not SOC_FLASH_ENCRYPTION_XTS_AES_128_DERIVED: - Flash memory contents is encrypted using XTS-AES-128. The flash encryption key is 256 bits and stored in one ``BLOCK_KEYN`` eFuse internal to the chip and, by default, is protected from software access.
@@ -844,9 +1043,9 @@ Key Points About Flash Encryption
Enabling flash encryption will increase the size of bootloader, which might require updating partition table offset. See :ref:`bootloader-size`.
.. important::
.. important::
Do not interrupt power to the {IDF_TARGET_NAME} while the first boot encryption pass is running. If power is interrupted, the flash contents will be corrupted and will require flashing with unencrypted data again. In this case, re-flashing will not count towards the flashing limit.
Do not interrupt power to the {IDF_TARGET_NAME} while the first boot encryption pass is running. If power is interrupted, the flash contents will be corrupted and will require flashing with unencrypted data again. In this case, re-flashing will not count towards the flashing limit.
.. _flash-encryption-limitations:
@@ -993,7 +1192,7 @@ However, before the first boot you can choose to keep any of these features enab
JTAG Debugging
^^^^^^^^^^^^^^
By default, when Flash Encryption is enabled (in either Development or Release mode) then JTAG debugging is disabled via eFuse. The bootloader does this on first boot, at the same time it enables flash encryption.
By default, when Flash Encryption is enabled (in either development or release mode) then JTAG debugging is disabled via eFuse. The bootloader does this on first boot, at the same time it enables flash encryption.
See :ref:`jtag-debugging-security-features` for more information about using JTAG Debugging with Flash Encryption.
@@ -1003,7 +1202,13 @@ See :ref:`jtag-debugging-security-features` for more information about using JTA
Manually Encrypting Files
^^^^^^^^^^^^^^^^^^^^^^^^^
Manually encrypting or decrypting files requires the flash encryption key to be pre-burned in eFuse (see :ref:`pregenerated-flash-encryption-key`) and a copy to be kept on the host. If the flash encryption is configured in Development Mode then it is not necessary to keep a copy of the key or follow these steps, the simpler :ref:`encrypt-partitions` steps can be used.
.. only:: SOC_KEY_MANAGER_SUPPORTED
Manually encrypting or decrypting files require the flash encryption key to be deployed in the Key Manager or pre-burned in eFuses (see :ref:`pregenerated-flash-encryption-key`) and a copy to be kept on the host. If the flash encryption is configured in development mode, then it is not necessary to keep a copy of the key or follow these steps. The simpler :ref:`encrypt-partitions` steps can be used.
.. only:: not SOC_KEY_MANAGER_SUPPORTED
Manually encrypting or decrypting files require the flash encryption key to be pre-burned in eFuse (see :ref:`pregenerated-flash-encryption-key`) and a copy to be kept on the host. If the flash encryption is configured in development mode, then it is not necessary to keep a copy of the key or follow these steps. The simpler :ref:`encrypt-partitions` steps can be used.
The key file should be a single raw binary file (example: ``key.bin``).
@@ -1025,11 +1230,11 @@ The file ``my-app-ciphertext.bin`` can then be flashed to offset 0x10000 using `
.. note::
If the flashed ciphertext file is not recognized by the {IDF_TARGET_NAME} when it boots, check that the keys match and that the command line arguments match exactly, including the correct offset.
If the flashed ciphertext file is not recognized by the {IDF_TARGET_NAME} when it boots, check that the keys match and that the command line arguments match exactly, including the correct offset.
.. only:: esp32
.. only:: esp32
If your ESP32 uses non-default :ref:`FLASH_CRYPT_CONFIG value in eFuse <setting-flash-crypt-config>` then you will need to pass the ``--flash-crypt-conf`` argument to ``idf.py`` command to set the matching value. This will not happen if the device configured flash encryption by itself, but may happen if burning eFuses manually to enable flash encryption.
If your ESP32 uses non-default :ref:`FLASH_CRYPT_CONFIG value in eFuse <setting-flash-crypt-config>` then you will need to pass the ``--flash-crypt-conf`` argument to ``idf.py`` command to set the matching value. This will not happen if the device configured flash encryption by itself, but may happen if burning eFuses manually to enable flash encryption.
The command ``idf.py decrypt-flash-data`` can be used with the same options (and different input/output files), to decrypt ciphertext flash contents or a previously encrypted file.
@@ -1089,13 +1294,13 @@ The following sections provide some reference information about the operation of
Flash Encryption Algorithm
^^^^^^^^^^^^^^^^^^^^^^^^^^
- {IDF_TARGET_NAME} use the XTS-AES block cipher mode with 256 bit or 512 bit key size for flash encryption.
- {IDF_TARGET_NAME} use the XTS-AES block cipher mode with 256-bit or 512-bit key size for flash encryption.
- XTS-AES is a block cipher mode specifically designed for disc encryption and addresses the weaknesses other potential modes (e.g., AES-CTR) have for this use case. A detailed description of the XTS-AES algorithm can be found in `IEEE Std 1619-2007 <https://ieeexplore.ieee.org/document/4493450>`_.
- The flash encryption key is stored in one or two ``BLOCK_KEYN`` eFuses and, by default, is protected from further writes or software readout.
- To see the full flash encryption algorithm implemented in Python, refer to the `_flash_encryption_operation()` function in the ``espsecure`` source code.
- To see the full flash encryption algorithm implemented in Python, refer to the ``_flash_encryption_operation()`` function in the ``espsecure`` source code.
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_128 and not SOC_FLASH_ENCRYPTION_XTS_AES_256 and not SOC_EFUSE_CONSISTS_OF_ONE_KEY_BLOCK
@@ -1105,7 +1310,7 @@ The following sections provide some reference information about the operation of
Flash Encryption Algorithm
^^^^^^^^^^^^^^^^^^^^^^^^^^
- {IDF_TARGET_NAME} use the XTS-AES block cipher mode with 256 bit size for flash encryption.
- {IDF_TARGET_NAME} use the XTS-AES block cipher mode with 256-bit size for flash encryption.
- XTS-AES is a block cipher mode specifically designed for disc encryption and addresses the weaknesses other potential modes (e.g., AES-CTR) have for this use case. A detailed description of the XTS-AES algorithm can be found in `IEEE Std 1619-2007 <https://ieeexplore.ieee.org/document/4493450>`_.
@@ -1120,7 +1325,7 @@ The following sections provide some reference information about the operation of
Flash Encryption Algorithm
^^^^^^^^^^^^^^^^^^^^^^^^^^
- {IDF_TARGET_NAME} use the XTS-AES block cipher mode with 256 bit size for flash encryption. In case the 128-bit key is stored in the eFuse key block, the final 256-bit AES key is obtained as SHA256(EFUSE_KEY0_FE_128BIT).
- {IDF_TARGET_NAME} use the XTS-AES block cipher mode with 256-bit size for flash encryption. In case the 128-bit key is stored in the eFuse key block, the final 256-bit AES key is obtained as SHA256(EFUSE_KEY0_FE_128BIT).
- XTS-AES is a block cipher mode specifically designed for disc encryption and addresses the weaknesses other potential modes (e.g., AES-CTR) have for this use case. A detailed description of the XTS-AES algorithm can be found in `IEEE Std 1619-2007 <https://ieeexplore.ieee.org/document/4493450>`_.
docs/en/security/security-features-enablement-workflows.rst
+50 -12
View File
@@ -61,19 +61,19 @@ Enable Flash Encryption and Secure Boot v2 Externally
It is recommended to enable both Flash Encryption and Secure Boot v2 for a production use case.
When enabling the Flash Encryption and Secure Boot v2 together, they need to enable them in the following order:
When enabling the Flash Encryption and Secure Boot v2 together, they must be enabled in the following order:
#. Enable the Flash Encryption feature by following the steps listed in :ref:`enable-flash-encryption-externally`.
#. Enable the Secure Boot v2 feature by following the steps listed in :ref:`enable-secure-boot-v2-externally`.
The reason this particular ordering is that when enabling Secure Boot (SB) v2, it is necessary to keep the SB v2 key readable. To protect the key's readability, the write protection for ``RD_DIS`` (``ESP_EFUSE_WR_DIS_RD_DIS``) is applied. However, this action poses a challenge when attempting to enable Flash Encryption, as the Flash Encryption (FE) key needs to remain unreadable. This conflict arises because the ``RD_DIS`` is already write-protected, making it impossible to read protect the FE key.
The reason for this particular ordering is that when enabling Secure Boot (SB) v2, it is necessary to keep the SB v2 key readable. To protect the key's readability, the write protection for ``RD_DIS`` (``ESP_EFUSE_WR_DIS_RD_DIS``) is applied. However, this action poses a challenge when attempting to enable Flash Encryption, as the Flash Encryption (FE) key needs to remain unreadable. This conflict arises because the ``RD_DIS`` is already write-protected, making it impossible to read protect the FE key.
.. _enable-flash-encryption-externally:
Enable Flash Encryption Externally
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In this case all the eFuses related to Flash Encryption are written with help of the espefuse tool. More details about Flash Encryption can process can be found in :doc:`/security/flash-encryption`.
In this case, all the eFuses related to Flash Encryption are written with help of the espefuse tool. More details about Flash Encryption process can be found in :doc:`/security/flash-encryption`.
1. Ensure that you have an {IDF_TARGET_NAME} device with default Flash Encryption eFuse settings as shown in :ref:`flash-encryption-efuse`
@@ -130,14 +130,52 @@ In this case all the eFuses related to Flash Encryption are written with help of
espsecure generate-flash-encryption-key --keylen 128 my_flash_encryption_key.bin
3. Burn the Flash Encryption key into eFuse
3. Program the generated Flash Encryption key into the device
.. only:: SOC_KEY_MANAGER_SUPPORTED
a. If you intend to use the Key Manager to store the Flash Encryption key, generate the Key Recovery Information for the Flash Encryption key and store it in the flash memory at the address 0x0 using the command:
.. code-block:: bash
esptool --port PORT write-flash 0x0 key_recovery_info.bin
After storing the Key Recovery Information in flash memory, you also need to program the ``KM_XTS_KEY_LENGTH_256`` and the ``FORCE_USE_KEY_MANAGER_KEY`` eFuses.
.. warning::
This action **cannot be reverted**.
Bit 1 of the ``FORCE_USE_KEY_MANAGER_KEY`` eFuse is used to force using a Key Manager-based XTS-AES key. Once this eFuse is burned, eFuse-based Flash Encryption keys can no longer be used; the device will exclusively use the Key Manager for Flash Encryption key management.
.. code-block:: bash
espefuse --port PORT burn-efuse FORCE_USE_KEY_MANAGER_KEY 2
The ``KM_XTS_KEY_LENGTH_256`` eFuse controls the length of the Key-Manager based XTS-AES key. Set this eFuse to 1 to use a 128-bit key, and to 0 to use a 256-bit key.
To use a 128-bit key, set the ``KM_XTS_KEY_LENGTH_256`` eFuse to 1.
.. code-block:: bash
espefuse --port PORT burn-efuse KM_XTS_KEY_LENGTH_256 1
Otherwise, to use a 256-bit key, set the ``KM_XTS_KEY_LENGTH_256`` eFuse to 0.
.. code-block:: bash
espefuse --port PORT burn-efuse KM_XTS_KEY_LENGTH_256 0
b. To store the Flash Encryption key in the eFuses, run the following commands:
.. only:: not SOC_KEY_MANAGER_SUPPORTED
To store the Flash Encryption key in the eFuses, run the following commands:
.. warning::
This action **cannot be reverted**.
It can be done by running:
.. only:: not SOC_FLASH_ENCRYPTION_XTS_AES
.. code-block:: bash
@@ -183,13 +221,13 @@ In this case all the eFuses related to Flash Encryption are written with help of
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_128 and SOC_EFUSE_CONSISTS_OF_ONE_KEY_BLOCK
For AES-128 (256-bit key) - ``XTS_AES_128_KEY`` (the ``XTS_KEY_LENGTH_256`` eFuse will be burn to 1):
For AES-128 (256-bit key) - ``XTS_AES_128_KEY`` (the ``XTS_KEY_LENGTH_256`` eFuse will be burned to 1):
.. code-block:: bash
espefuse --port PORT burn-key BLOCK_KEY0 flash_encryption_key256.bin XTS_AES_128_KEY
For AES-128 key derived from SHA256(128 eFuse bits) - ``XTS_AES_128_KEY_DERIVED_FROM_128_EFUSE_BITS``. The FE key will be written in the lower part of eFuse BLOCK_KEY0. The upper 128 bits are not used and will remain available for reading by software. Using the special mode of the espefuse tool, shown in the ``For burning both keys together`` section below, the user can write their data to it using any espefuse commands.
For AES-128 key derived from SHA256 (128 eFuse bits) - ``XTS_AES_128_KEY_DERIVED_FROM_128_EFUSE_BITS``. The FE key will be written in the lower part of eFuse BLOCK_KEY0. The upper 128 bits are not used and will remain available for reading by software. Using the special mode of the espefuse tool, shown in the ``For burning both keys together`` section below, the user can write their data to it using any espefuse commands.
.. code-block:: bash
@@ -244,7 +282,7 @@ In this case all the eFuses related to Flash Encryption are written with help of
:SOC_EFUSE_DIS_DOWNLOAD_ICACHE: - ``DIS_DOWNLOAD_ICACHE``: Disable UART cache
:SOC_EFUSE_DIS_DOWNLOAD_DCACHE: - ``DIS_DOWNLOAD_DCACHE``: Disable UART cache
:SOC_EFUSE_HARD_DIS_JTAG: - ``HARD_DIS_JTAG``: Hard disable JTAG peripheral
:SOC_EFUSE_DIS_DIRECT_BOOT:- ``DIS_DIRECT_BOOT``: Disable direct boot (legacy SPI boot mode)
:SOC_EFUSE_DIS_DIRECT_BOOT: - ``DIS_DIRECT_BOOT``: Disable direct boot (legacy SPI boot mode)
:SOC_EFUSE_DIS_LEGACY_SPI_BOOT: - ``DIS_LEGACY_SPI_BOOT``: Disable legacy SPI boot mode
:SOC_EFUSE_DIS_USB_JTAG: - ``DIS_USB_JTAG``: Disable USB switch to JTAG
:SOC_EFUSE_DIS_PAD_JTAG: - ``DIS_PAD_JTAG``: Disable JTAG permanently
@@ -266,7 +304,7 @@ In this case all the eFuses related to Flash Encryption are written with help of
B) Write protect security eFuses
After burning the respective eFuses we need to write_protect the security configurations. It can be done by burning following eFuse:
After burning the respective eFuses we need to write-protect the security configurations. It can be done by burning following eFuse:
.. code:: bash
@@ -499,12 +537,12 @@ In this workflow we shall use ``espsecure`` tool to generate signing keys and us
:SOC_EFUSE_DIS_BOOT_REMAP: - ``DIS_BOOT_REMAP``: Disable capability to remap ROM to RAM address space.
:SOC_EFUSE_HARD_DIS_JTAG: - ``HARD_DIS_JTAG``: Hard disable JTAG peripheral.
:SOC_EFUSE_SOFT_DIS_JTAG: - ``SOFT_DIS_JTAG``: Disable software access to JTAG peripheral.
:SOC_EFUSE_DIS_DIRECT_BOOT:- ``DIS_DIRECT_BOOT``: Disable direct boot (legacy SPI boot mode).
:SOC_EFUSE_DIS_DIRECT_BOOT: - ``DIS_DIRECT_BOOT``: Disable direct boot (legacy SPI boot mode).
:SOC_EFUSE_DIS_LEGACY_SPI_BOOT: - ``DIS_LEGACY_SPI_BOOT``: Disable legacy SPI boot mode.
:SOC_EFUSE_DIS_USB_JTAG: - ``DIS_USB_JTAG``: Disable USB switch to JTAG.
:SOC_EFUSE_DIS_PAD_JTAG: - ``DIS_PAD_JTAG``: Disable JTAG permanently.
:SOC_EFUSE_REVOKE_BOOT_KEY_DIGESTS: - ``SECURE_BOOT_AGGRESSIVE_REVOKE``: Aggressive revocation of key digests, see :ref:`secure-boot-v2-aggressive-key-revocation` for more details.
:SOC_ECDSA_P192_CURVE_DEFAULT_DISABLED: - ``WR_DIS_ECDSA_CURVE_MODE``: Disable writing to the ECDSA curve mode eFuse bit. As this write protection bit is shared with ``ECC_FORCE_CONST_TIME``, it is recommended to write protect this bit only after configuring the ``ECC_FORCE_CONST_TIME`` eFuse.
:SOC_ECDSA_P192_CURVE_DEFAULT_DISABLED: - ``WR_DIS_ECDSA_CURVE_MODE``: Disable writing to the ECDSA curve mode eFuse bit. As this write protection bit is shared with ``ECC_FORCE_CONST_TIME``, it is recommended to write-protect this bit only after configuring the ``ECC_FORCE_CONST_TIME`` eFuse.
:SOC_ECDSA_SUPPORT_CURVE_P384: - ``WR_DIS_SECURE_BOOT_SHA384_EN``: Disable writing to the SHA-384 Secure Boot eFuse bit. As this write protection bit is shared with ``XTS_DPA_PSEUDO_LEVEL`` and ``ECC_FORCE_CONST_TIME``, it is recommended to write protect this bit only after configuring all the other shared eFuses.
The respective eFuses can be burned by running:
docs/en/security/security.rst
+22 -4
View File
@@ -11,7 +11,7 @@ This guide provides an overview of the overall security features available in va
.. note::
In this guide, most used commands are in the form of ``idf.py secure-<command>``, which is a wrapper around corresponding ``espsecure <command>``. The ``idf.py`` based commands provides more user-friendly experience, although may lack some of the advanced functionality of their ``espsecure`` based counterparts.
In this guide, most used commands are in the form of ``idf.py secure-<command>``, which is a wrapper around corresponding ``espsecure <command>``. The ``idf.py`` based commands provides a more user-friendly experience, although may lack some of the advanced functionality of their ``espsecure`` based counterparts.
.. only:: TARGET_SUPPORT_QEMU
@@ -70,7 +70,7 @@ Please refer to :doc:`flash-encryption` for detailed information about this feat
.. only:: SOC_SPIRAM_SUPPORTED and not esp32
If {IDF_TARGET_NAME} is connected to an external SPI RAM, the contents written to or read from the SPI RAM will also be encrypted and decrypted respectively (via the MMU's flash cache, provided that FLash Encryption is enabled). This provides an additional safety layer for the data stored in SPI RAM, hence configurations like ``CONFIG_MBEDTLS_EXTERNAL_MEM_ALLOC`` can be safely enabled in this case.
If {IDF_TARGET_NAME} is connected to an external SPI RAM, the contents written to or read from the SPI RAM will also be encrypted and decrypted respectively (via the MMU's flash cache, provided that Flash Encryption is enabled). This provides an additional safety layer for the data stored in SPI RAM, hence configurations like ``CONFIG_MBEDTLS_EXTERNAL_MEM_ALLOC`` can be safely enabled in this case.
Flash Encryption Best Practices
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -101,6 +101,24 @@ Flash Encryption Best Practices
Please refer to the :doc:`../api-reference/peripherals/ecdsa` and :doc:`../api-reference/peripherals/ds` guides for detailed documentation.
.. only:: SOC_KEY_MANAGER_SUPPORTED
Key Manager
~~~~~~~~~~~
The Key Manager peripheral in {IDF_TARGET_NAME} provides hardware-assisted **key deployment and recovery** for cryptographic keys. Keys are cryptographically bound to a Hardware Unique Key (HUK) that is unique to each chip, ensuring that key material is never exposed to software-accessible memory.
The Key Manager supports key management for the following cryptographic peripherals: :doc:`ECDSA <../api-reference/peripherals/ecdsa>`, :doc:`HMAC <../api-reference/peripherals/hmac>`, :doc:`Digital Signature (DS) <../api-reference/peripherals/ds>`, and Flash Encryption.
Please refer to :doc:`../api-reference/peripherals/key_manager` for detailed documentation.
Key Manager Best Practices
^^^^^^^^^^^^^^^^^^^^^^^^^^
* Protect the ``key_recovery_info`` of a Key Manager-deployed key against unauthorized modification or loss.
* Lock Key Manager's security-related eFuses after successful key deployment to prevent re-deployment of a key of the same type.
* Avoid deploying new XTS-AES keys when Flash Encryption is already enabled unless explicitly intended.
.. only:: SOC_MEMPROT_SUPPORTED or SOC_CPU_IDRAM_SPLIT_USING_PMP
Memory Protection
@@ -124,7 +142,7 @@ Flash Encryption Best Practices
DPA (Differential Power Analysis) Protection
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
{IDF_TARGET_NAME} has support for protection mechanisms against the Differential Power Analysis related security attacks. DPA protection dynamically adjusts the clock frequency of the crypto peripherals, thereby blurring the power consumption trajectory during its operation. Based on the configured DPA security level, the clock variation range changes. Please refer to the *{IDF_TARGET_NAME} Technical Reference Manual* [`PDF <{IDF_TARGET_TRM_EN_URL}>`__]. for more details on this topic.
{IDF_TARGET_NAME} has support for protection mechanisms against the Differential Power Analysis related security attacks. DPA protection dynamically adjusts the clock frequency of the crypto peripherals, thereby blurring the power consumption trajectory during its operation. Based on the configured DPA security level, the clock variation range changes. Please refer to the **{IDF_TARGET_NAME} Technical Reference Manual** [`PDF <{IDF_TARGET_TRM_EN_URL}>`__] for more details on this topic.
:ref:`CONFIG_ESP_CRYPTO_DPA_PROTECTION_LEVEL` can help to select the DPA level. Higher level means better security, but it can also have an associated performance impact. By default, the lowest DPA level is kept enabled but it can be modified based on the security requirement.
@@ -140,7 +158,7 @@ Flash Encryption Best Practices
{IDF_TARGET_NAME} incorporates a pseudo-round function in the AES peripheral, thus enabling the peripheral to randomly insert pseudo-rounds before and after the original operation rounds and also generate a pseudo key to perform these dummy operations.
These operations do not alter the original result, but they increase the complexity to perform side channel analysis attacks by randomizing the power profile.
:ref:`CONFIG_MBEDTLS_AES_USE_PSEUDO_ROUND_FUNC_STRENGTH` can be used to select the strength of the pseudo-round function. Increasing the strength improves the security provided, but would slow down the encrryption/decryption operations.
:ref:`CONFIG_MBEDTLS_AES_USE_PSEUDO_ROUND_FUNC_STRENGTH` can be used to select the strength of the pseudo-round function. Increasing the strength improves the security provided, but would slow down the encryption/decryption operations.
.. list-table:: Performance impact on AES operations per strength level