 ESP-IDF Programming Guide

 » Security Guides » Host-Based Security Workflows  Edit on GitHub

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
1. Simplify the traditional workflow with stepwise instructions.
2. Design a more flexible workflow as compared to the traditional firmware-based workflow.
3. Improve reliability by dividing the workflow into small operations.
4. Eliminate dependency on Second Stage Bootloader (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
Security Workflows

Enable Flash Encryption and Secure Boot V2 Externally

 Important

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

1. Enable the Flash Encryption feature by following the steps listed in Enable Flash Encryption
Externally.
2. 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

1. Ensure that you have an ESP32-S2 device with default flash encryption eFuse settings as
shown in Relevant eFuses.

See how to check ESP32-S2 Flash Encryption Status.

In this case, the flash on the chip must be erased and flash encryption must not be enabled.
The chip can be erased by running:

esptool.py --port PORT erase_flash

2. 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

3. 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

4. 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

 Note

At this point, the flash encryption on the device has been enabled. You may test the
flash encryption process as given in step 5. Please note that the security-related eFuses
have not been burned at this point. It is recommended that they should be burned in
production use cases as explained in step 6.

5. Encrypt and flash the binaries.

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.

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 0x0 --

 espsecure.py encrypt_flash_data --aes_xts --keyfile my_flash_encryption_key.bin --address 0x8000

espsecure.py encrypt_flash_data --aes_xts --keyfile my_flash_encryption_key.bin --address 0x1000

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. 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. When the application contains the following partition:
otadata , nvs_encryption_keys they need to be encrypted as well. Please refer to Encrypted
Partitions for more details about encrypted partitions.

 Note

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.

6. Burn flash encryption-related security eFuses as listed below:

A. Burn security eFuses:

 Important

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

 Note

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.

B. Write protect security eFuses:

After burning the respective eFuses we need to write_protect the security

configurations

espefuse.py --port PORT write_protect_efuse DIS_ICACHE

 Note

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

C. Enable Security Download mode:

 Warning

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

ENABLE_SECURITY_DOWNLOAD : Enable Secure ROM download mode

The eFuse can be burned by running:

espefuse.py --port PORT burn_efuse ENABLE_SECURITY_DOWNLOAD

 Important

7. 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 Limitations of Flash Encryption 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

1. 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.

2. 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.

3. 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 SECURE_BOOT_DIGEST0 digest.bin

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.

4. Enable Secure Boot V2.

Secure Boot V2 eFuse can be enabled by running:

espefuse.py --port PORT --chip esp32s2 burn_efuse SECURE_BOOT_EN

 Note

At this stage the secure boot V2 has been enabled for the ESP32-S2. The ROM
bootloader shall now verify the authenticity of the Second Stage Bootloader on every
bootup. You may test the secure boot process by executing Steps 5 & 6. Please note that
security-related eFuses have not been burned at this point. For production use cases, all
security-related eFuses must be burned as given in step 7.

5. Build the binaries.

By default, the ROM bootloader would only verify the Second Stage Bootloader (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.

a. Open the Project Configuration Menu, 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.

b. Disable the option CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES for the project

in the Project Configuration Menu. 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.
 After the above configurations, the bootloader and application binaries can be built with
idf.py build command.

6. Sign and Flash the binaries.

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-sig

espsecure.py sign_data --version 2 --keyfile secure_boot_signing_key.pem --output my-app-signed.

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

espsecure.py sign_data --keyfile secure_boot_signing_key2.pem --version 2 --append_signatures -o

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 .

7. Burn relevant eFuses.

A. Burn security eFuses:

  Important

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

 Note

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

B. Secure Boot V2-related eFuses:

1. Disable the ability for read protection:

The secure boot digest burned in the eFuse must be kept readable otherwise secure
boot operation would result in a failure. To prevent the accidental enabling of read
protection for this key block we need to burn the following eFuse:

espefuse.py -p $ESPPORT write_protect_efuse RD_DIS

 Important

After this eFuse has been burned, 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 this.
 2. 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.

C. Enable Security Download mode:

 Warning

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

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.

Provide feedback about this document

 Previous Next 

© Copyright 2016 - 2024, Espressif Systems (Shanghai) Co., Ltd.


Built with Sphinx using a theme based on Read the Docs Sphinx Theme.  Download PDF