Host-Based Security Workflows

Introduction

It is recommended to have an uninterrupted power supply while enabling security features on ESP32 SoCs. Power failures during the secure manufacturing process could cause issues that are hard to debug and, in some cases, may cause permanent boot-up failures.

This guide highlights an approach where security features are enabled with the assistance of an external host machine. Security workflows are broken down into various stages and key material is generated on the host machine; thus, allowing greater recovery chances in case of power or other failures. It also offers better timings for secure manufacturing, e.g., in the case of encryption of firmware on the host machine vs. on the device.

Goals

Simplify the traditional workflow with stepwise instructions.
Design a more flexible workflow as compared to the traditional firmware-based workflow.
Improve reliability by dividing the workflow into small operations.
Eliminate dependency on 二级引导程序 (firmware bootloader).

Pre-requisite

esptool: Please make sure the esptool has been installed. It can be installed by running:

pip install esptool

Scope

Enable Flash Encryption and Secure Boot V2 Externally
Enable Flash Encryption Externally
Enable Secure Boot V2 Externally
Enable NVS Encryption Externally

Security Workflows

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 we need to enable them in the following order:

Enable the Flash Encryption feature by following the steps listed in Enable Flash Encryption Externally.
Enable the Secure Boot V2 feature by following the steps listed in Enable Secure Boot V2 Externally.

The reason for this order is as follows:

备注

To enable the 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

In this case, all the eFuses related to Flash Encryption are written with help of the espefuse tool. More details about flash encryption can be found in the Flash Encryption Guide

Check device status

Ensure that you have an ESP32-S2 device with default Flash Encryption eFuse settings as shown in 相关 eFuses.

See how to check ESP32-S2 flash 加密状态.

At this point, the Flash Encryption must not be already enabled on the chip. Additionally, the flash on the chip needs to be erased, which can be done by running:
esptool.py --port PORT erase_flash

Generate a Flash Encryption key

A random Flash Encryption key can be generated by running:

If Size of generated AES-XTS key is AES-128 (256-bit key):
espsecure.py generate_flash_encryption_key my_flash_encryption_key.bin
else if Size of generated AES-XTS key is AES-256 (512-bit key):
espsecure.py generate_flash_encryption_key --keylen 512 my_flash_encryption_key.bin

Burn the Flash Encryption key into eFuse

This action cannot be reverted. It can be done by running:
espefuse.py --port PORT burn_key BLOCK my_flash_encryption_key.bin KEYPURPOSE
where BLOCK is a free keyblock between BLOCK_KEY0 and BLOCK_KEY5. And KEYPURPOSE is either XTS_AES_256_KEY_1, XTS_AES_256_KEY_2, XTS_AES_128_KEY. See ESP32-S2 Technical Reference Manual for a description of the key purposes.

For AES-128 (256-bit key) - XTS_AES_128_KEY:
espefuse.py --port PORT 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. espefuse.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 espefuse.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
espefuse.py --port PORT 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 the 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:
split -b 32 my_flash_encryption_key.bin my_flash_encryption_key.bin
espefuse.py --port PORT burn_key BLOCK my_flash_encryption_key.bin.aa XTS_AES_256_KEY_1
espefuse.py --port PORT burn_key BLOCK+1 my_flash_encryption_key.bin.ab XTS_AES_256_KEY_2

Burn the SPI_BOOT_CRYPT_CNT eFuse

If you only want to enable Flash Encryption in Development mode and want to keep the ability to disable it in the future, Update the SPI_BOOT_CRYPT_CNT value in the below command from 7 to 0x1 (not recommended for production).
espefuse.py --port PORT --chip esp32s2 burn_efuse SPI_BOOT_CRYPT_CNT 7

Burn Flash Encryption-related security eFuses as listed below

Burn security eFuses
重要

For production use cases, it is highly recommended to burn all the eFuses listed below.

DIS_BOOT_REMAP: Disable capability to Remap ROM to RAM address space

DIS_DOWNLOAD_ICACHE: Disable UART cache

DIS_DOWNLOAD_DCACHE: Disable UART cache

HARD_DIS_JTAG: Hard disable JTAG peripheral

DIS_LEGACY_SPI_BOOT: Disable legacy SPI boot mode

DIS_DOWNLOAD_MANUAL_ENCRYPT: Disable UART bootloader encryption access

The respective eFuses can be burned by running:
espefuse.py burn_efuse --port PORT EFUSE_NAME 0x1
备注

Please update the EFUSE_NAME with the eFuse that you need to burn. Multiple eFuses can be burned at the same time by appending them to the above command (e.g., EFUSE_NAME VAL EFUSE_NAME2 VAL2). More documentation about espefuse.py can be found here.
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
espefuse.py --port PORT write_protect_efuse DIS_ICACHE
备注

The write protection of above eFuse also write protects multiple other eFuses, Please refer to the ESP32-S2 eFuse table for more details.

Configure the project

The bootloader and the application binaries for the project must be built with Flash Encryption Release mode with default configurations.

Flash encryption Release mode can be set in the menuconfig as follows:

Enable Flash Encryption on boot

Select Release 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)

Select UART ROM download mode (Permanently switch to Secure mode (recommended)). 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

Select the appropriate bootloader log verbosity

Save the configuration and exit

Build, Encrypt and Flash the binaries

The binaries can be encrypted on the host machine by running:
espsecure.py encrypt_flash_data --aes_xts --keyfile my_flash_encryption_key.bin --address 0x1000 --output bootloader-enc.bin build/bootloader/bootloader.bin

espsecure.py encrypt_flash_data --aes_xts --keyfile my_flash_encryption_key.bin --address 0x8000 --output partition-table-enc.bin build/partition_table/partition-table.bin

espsecure.py encrypt_flash_data --aes_xts --keyfile my_flash_encryption_key.bin --address 0x10000 --output my-app-enc.bin build/my-app.bin
In the above command the offsets are used for a sample firmware, the actual offset for your firmware can be obtained by checking the partition table entry or by running idf.py partition-table. Please note that not all the binaries need to be encrypted, the encryption applies only to those generated from the partitions which are marked as encrypted in the partition table definition file. Other binaries are flashed unencrypted, i.e., as a plain output of the build process.

The above files can then be flashed to their respective offset using esptool.py. To see all of the command line options recommended for esptool.py, see the output printed when idf.py build succeeds.

When the application contains the following partition: otadata, nvs_encryption_keys they need to be encrypted as well. Please refer to 加密分区 for more details about encrypted partitions.

备注

If the flashed ciphertext file is not recognized by the ESP32-S2 when it boots, check that the keys match and that the command line arguments match exactly, including the correct offset. It is important to provide the correct offset as the ciphertext changes when the offset changes.

The command espsecure.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.

Secure the ROM Download mode

警告

Please perform the following step at the very end. After this eFuse is burned, the espefuse tool can no longer be used to burn additional eFuses.

Disable UART ROM DL mode:

UART_DOWNLOAD_DIS : Disable the UART ROM Download mode

The eFuse can be burned by running:
espefuse.py --port PORT burn_efuse UART_DOWNLOAD_DIS

Enable Security Download mode:

ENABLE_SECURITY_DOWNLOAD: Enable Secure ROM download mode

The eFuse can be burned by running:
espefuse.py --port PORT burn_efuse ENABLE_SECURITY_DOWNLOAD

重要

Delete Flash Encryption key on host

Once the Flash Encryption has been enabled for the device, the key must be deleted immediately. This ensures that the host cannot produce encrypted binaries for the same device going forward. This step is important to reduce the vulnerability of the flash encryption key.

Flash Encryption Guidelines

It is recommended to generate a unique Flash Encryption key for each device for production use-cases.
It is recommended to ensure that the RNG used by host machine to generate the Flash Encryption key has good entropy.
See flash 加密的局限性 for more details.

Enable Secure Boot V2 Externally

In this workflow, we shall use espsecure tool to generate signing keys and use the espefuse tool to burn the relevant eFuses. The details about the Secure Boot V2 process can be found at Secure Boot V2 Guide

Generate Secure Boot V2 Signing Private Key

The Secure Boot V2 signing key for the RSA3072 scheme can be generated by running:
espsecure.py generate_signing_key --version 2 --scheme rsa3072 secure_boot_signing_key.pem
A total of 3 keys can be used for Secure Boot V2 at once. These should be computed independently and stored separately. The same command with different key file names can be used to generate multiple Secure Boot V2 signing keys. It is recommended to use multiple keys in order to reduce dependency on a single key.

Generate Public Key Digest

The public key digest for the private key generated in the previous step can be generated by running:
espsecure.py digest_sbv2_public_key --keyfile secure_boot_signing_key.pem --output digest.bin
In case of multiple digests, each digest should be kept in a separate file.

Burn the key digest in eFuse

The public key digest can be burned in the eFuse by running:
espefuse.py --port PORT --chip esp32s2 burn_key BLOCK digest.bin SECURE_BOOT_DIGEST0
where BLOCK is a free keyblock between BLOCK_KEY0 and BLOCK_KEY5.

In case of multiple digests, the other digests can be burned sequentially by changing the key purpose to SECURE_BOOT_DIGEST1 and SECURE_BOOT_DIGEST2 respectively.

Enable Secure Boot V2

Secure Boot V2 eFuse can be enabled by running:
espefuse.py --port PORT --chip esp32s2 burn_efuse SECURE_BOOT_EN

Burn relevant eFuses

Burn security eFuses
重要

For production use cases, it is highly recommended to burn all the eFuses listed below.

DIS_BOOT_REMAP: Disable capability to Remap ROM to RAM address space

HARD_DIS_JTAG: Hard disable JTAG peripheral

SOFT_DIS_JTAG: Disable software access to JTAG peripheral

DIS_LEGACY_SPI_BOOT: Disable legacy SPI boot mode

SECURE_BOOT_AGGRESSIVE_REVOKE: Aggressive revocation of key digests, see Aggressive Approach: for more details.

The respective eFuses can be burned by running:
espefuse.py burn_efuse --port PORT EFUSE_NAME 0x1
备注

Please update the EFUSE_NAME with the eFuse that you need to burn. Multiple eFuses can be burned at the same time by appending them to the above command (e.g., EFUSE_NAME VAL EFUSE_NAME2 VAL2). More documentation about espefuse.py can be found here
Secure Boot V2-related eFuses
Disable the read-protection option:

The Secure Boot digest burned in the eFuse must be kept readable otherwise the Secure Boot operation would result in a failure. To prevent the accidental enabling of read protection for this key block, the following eFuse needs to be burned:

重要

After burning above-mentioned eFuse, the read protection cannot be enabled for any key. E.g., if Flash Encryption which requires read protection for its key is not enabled at this point, then it cannot be enabled afterwards. Please ensure that no eFuse keys are going to need read protection after completing this step.
espefuse.py -p $ESPPORT write_protect_efuse RD_DIS
Revoke key digests:

The unused digest slots need to be revoked when we are burning the Secure Boot key. The respective slots can be revoked by running
espefuse.py --port PORT --chip esp32s2 burn_efuse EFUSE_REVOKE_BIT
The EFUSE_REVOKE_BIT in the above command can be SECURE_BOOT_KEY_REVOKE0 or SECURE_BOOT_KEY_REVOKE1 or SECURE_BOOT_KEY_REVOKE2. Please note that only the unused key digests must be revoked. Once revoked, the respective digest cannot be used again.

Configure the project

By default, the ROM bootloader would only verify the 二级引导程序 (firmware bootloader). The firmware bootloader would verify the app partition only when the CONFIG_SECURE_BOOT option is enabled (and CONFIG_SECURE_BOOT_VERSION is set to SECURE_BOOT_V2_ENABLED) while building the bootloader.

Open the 项目配置菜单, in "Security features" set "Enable hardware Secure Boot in bootloader" to enable Secure Boot.

The "Secure Boot V2" option will be selected and the "App Signing Scheme" will be set to RSA by default.

Disable the option CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES for the project in the 项目配置菜单. This shall make sure that all the generated binaries are secure padded and unsigned. This step is done to avoid generating signed binaries as we are going to manually sign the binaries using espsecure tool.

Build, Sign and Flash the binaries

After the above configurations, the bootloader and application binaries can be built with idf.py build command.

The Secure Boot V2 workflow only verifies the bootloader and application binaries, hence only those binaries need to be signed. The other binaries (e.g., partition-table.bin) can be flashed as they are generated in the build stage.

The bootloader.bin and app.bin binaries can be signed by running:
espsecure.py sign_data --version 2 --keyfile secure_boot_signing_key.pem --output bootloader-signed.bin build/bootloader/bootloader.bin

espsecure.py sign_data --version 2 --keyfile secure_boot_signing_key.pem --output my-app-signed.bin build/my-app.bin
If multiple keys Secure Boot keys are to be used then the same signed binary can be appended with a signature block signed with the new key as follows:
espsecure.py sign_data --keyfile secure_boot_signing_key2.pem --version 2 --append_signatures -o bootloader-signed2.bin bootloader-signed.bin

espsecure.py sign_data --keyfile secure_boot_signing_key2.pem --version 2 --append_signatures -o my-app-signed2.bin my-app-signed.bin
The same process can be repeated for the third key. Note that the names of the input and output files must not be the same.

The signatures attached to a binary can be checked by running:
espsecure.py signature_info_v2 bootloader-signed.bin
The above files along with other binaries (e.g., partition table) can then be flashed to their respective offset using esptool.py. To see all of the command line options recommended for esptool.py, see the output printed when idf.py build succeeds. The flash offset for your firmware can be obtained by checking the partition table entry or by running idf.py partition-table.

Secure the ROM Download mode:

警告

Please perform the following step at the very end. After this eFuse is burned, the espefuse tool can no longer be used to burn additional eFuses.

Disable UART ROM DL mode:

UART_DOWNLOAD_DIS : Disable the UART ROM Download mode

The eFuse can be burned by running:
espefuse.py --port PORT burn_efuse UART_DOWNLOAD_DIS

Enable Security Download mode:

ENABLE_SECURITY_DOWNLOAD: Enable Secure ROM download mode

The eFuse can be burned by running:
espefuse.py --port PORT burn_efuse ENABLE_SECURITY_DOWNLOAD

Secure Boot V2 Guidelines

It is recommended to store the Secure Boot key in a highly secure place. A physical or a cloud HSM may be used for secure storage of the Secure Boot private key. Please take a look at Remote Signing of Images for more details.

It is recommended to use all the available digest slots to reduce dependency on a single private key.

Enable NVS Encryption Externally

The details about NVS Encryption and related schemes can be found at NVS Encryption.

Enable NVS Encryption based on HMAC

Generate the HMAC key and NVS Encryption key

In the HMAC based NVS scheme, there are two keys:

HMAC key - this is a 256 bit HMAC key that shall be stored in the eFuse

NVS Encryption key - This is the NVS Encryption key that is used to encrypt the NVS partition. This key is derived at run-time using the HMAC key.

The above keys can be generated with the nvs_flash/nvs_partition_generator/nvs_partition_gen.py script with help of the following command:
python3 nvs_partition_gen.py generate-key --key_protect_hmac --kp_hmac_keygen --kp_hmac_keyfile hmac_key.bin --keyfile nvs_encr_key.bin
This shall generate the respective keys in the keys folder.

Burn the HMAC key in the eFuse

The NVS key can be burned in the eFuse of ESP32-S2 with help of following command:
espefuse.py --port PORT burn_key BLOCK hmac_key.bin HMAC_UP
where BLOCK is a free keyblock between BLOCK_KEY0 and BLOCK_KEY5.

Generate the encrypted NVS partition

We shall generate the actual encrypted NVS partition on host. More details about generating the encryption NVS partition can be found at 生成 NVS 加密分区. For this purpose, the contents of the NVS file shall be available in a CSV file. Please check out CSV 文件格式 for more details.

The encrypted NVS partition can be generated with following command:
python3 nvs_partition_gen.py encrypt sample_singlepage_blob.csv nvs_encr_partition.bin 0x3000 --inputkey keys/nvs_encr_key.bin
Some command arguments are explained below:

CSV file name - In this case sample_singlepage_blob.csv is the CSV file which contains the NVS data, Replace this with the file you wish to choose.

NVS partition offset - This is the offset at which that NVS partition shall be stored in the flash of ESP32-S2. The offset of your nvs-partition can be found be executing idf.py partition-table in the projtect directory. Please update the sample value of 0x3000 in the above-provided command to the correct offset.

Configure the project

Enable NVS Encryption by enabling CONFIG_NVS_ENCRYPTION.

Enable the HMAC based NVS Encryption by setting CONFIG_NVS_SEC_KEY_PROTECTION_SCHEME to CONFIG_NVS_SEC_KEY_PROTECT_USING_HMAC

Set the HMAC efuse key id at CONFIG_NVS_SEC_HMAC_EFUSE_KEY_ID to the one in which the eFuse key was burned in Step 2.

Flash NVS partition

The NVS partition (nvs_encr_partition.bin) generated in Step 3 can then be flashed to its respective offset using esptool.py. To see all of the command line options recommended for esptool.py, check the output printed when idf.py build succeeds. If Flash encryption is enabled for the chip then please encrypt the partition first before flashing. You may refer the flashing related steps of Flash Encryption workflow.

Enable NVS Encryption based on Flash Encryption

In this case we generate NVS Encryption keys on a host. This key is then flashed on the chip and protected with help of the Flash Encryption feature.

Generate the NVS Encryption key

For generation of respective keys, we shall use NVS partition generator utility. We shall generate the encryption key on host and this key key shall be stored on the flash of ESP32-S2 in encrypted state.

The key can be generated with the nvs_flash/nvs_partition_generator/nvs_partition_gen.py script with help of the following command:
python3 nvs_partition_gen.py generate-key --keyfile nvs_encr_key.bin
This shall generate the respective key in the keys folder.

Generate the encrypted NVS partition

We shall generate the actual encrypted NVS partition on host. More details about generating the encryption NVS partition can be found at 生成 NVS 加密分区. For this, the contents of the NVS file shall be available in a CSV file. Please refer CSV 文件格式 for more details.

The encrypted NVS partition can be generated with following command:
python3 nvs_partition_gen.py encrypt sample_singlepage_blob.csv nvs_encr_partition.bin 0x3000 --inputkey keys/nvs_encr_key.bin
Some command arguments are explained below:

CSV file name - In this case sample_singlepage_blob.csv is the CSV file which contains the NVS data, Replace this with the file you wish to choose.

NVS partition offset - This is the offset at which that NVS partition shall be stored in the flash of ESP32-S2. The offset of your nvs-partition can be found be executing idf.py partition-table in the projtect directory. Please update the sample value of 0x3000 in the above-provided command to the correct offset.

Configure the project

Enable NVS Encryption by enabling CONFIG_NVS_ENCRYPTION.

Set NVS to use Flash Encryption based scheme by setting CONFIG_NVS_SEC_KEY_PROTECTION_SCHEME to CONFIG_NVS_SEC_KEY_PROTECT_USING_FLASH_ENC.

Flash NVS partition and NVS Encryption keys

The NVS partition (nvs_encr_partition.bin) and NVS Encryption key (nvs_encr_key.bin) can then be flashed to their respective offset using esptool.py. To see all of the command line options recommended for esptool.py, check the output printed when idf.py build succeeds. If Flash encryption is enabled for the chip then please encrypt the partition first before flashing. You may refer the flashing related steps of Flash Encryption workflow.

提供有关此文档的反馈