Commit b365e234 authored by Almir Okato's avatar Almir Okato Committed by Gustavo Henrique Nihei
Browse files

espressif: add missing information for secure features



Add instructions on the readme-espressif.md on how to encrypt
data on the host.
Also add configuration and instructions for disabling/switch
UART ROM Download Mode.

Signed-off-by: default avatarAlmir Okato <almir.okato@espressif.com>
parent 611ea503
......@@ -15,6 +15,7 @@
#include "esp_efuse_table.h"
#include "esp_log.h"
#include "hal/wdt_hal.h"
#include "soc/soc_caps.h"
#include "esp_mcuboot_image.h"
......@@ -167,6 +168,26 @@ static esp_err_t initialise_flash_encryption(void)
return err;
}
#if defined(SOC_SUPPORTS_SECURE_DL_MODE) && defined(CONFIG_SECURE_ENABLE_SECURE_ROM_DL_MODE)
ESP_LOGI(TAG, "Enabling Secure Download mode...");
err = esp_efuse_enable_rom_secure_download_mode();
if (err != ESP_OK) {
ESP_LOGE(TAG, "Could not enable Secure Download mode...");
esp_efuse_batch_write_cancel();
return err;
}
#elif CONFIG_SECURE_DISABLE_ROM_DL_MODE
ESP_LOGI(TAG, "Disable ROM Download mode...");
err = esp_efuse_disable_rom_download_mode();
if (err != ESP_OK) {
ESP_LOGE(TAG, "Could not disable ROM Download mode...");
esp_efuse_batch_write_cancel();
return err;
}
#else
ESP_LOGW(TAG, "UART ROM Download mode kept enabled - SECURITY COMPROMISED");
#endif
err = esp_efuse_batch_write_commit();
if (err != ESP_OK) {
ESP_LOGE(TAG, "Error programming security eFuses (err=0x%x).", err);
......
......@@ -71,21 +71,22 @@ esptool.py --chip <TARGET> elf2image --flash_mode dio --flash_freq 40m --flash_s
esptool.py -p <PORT> -b <BAUD> --before default_reset --after hard_reset --chip <TARGET> write_flash --flash_mode dio --flash_size <FLASH_SIZE> --flash_freq 40m <BOOTLOADER_FLASH_OFFSET> build/mcuboot_<TARGET>.bin
```
---
***Note***
You may adjust the port `<PORT>` (like `/dev/ttyUSB0`) and baud rate `<BAUD>` (like `2000000`) according to the connection with your board.
***Note***
You may adjust the port `<PORT>` (like `/dev/ttyUSB0`) and baud rate `<BAUD>` (like `2000000`) according to the connection to your board.
You can also skip `<PORT>` and `<BAUD>` parameters so that esptool tries to automatically detect it.
*`<FLASH_SIZE>` can be found using the command below:*
```
esptool.py -p <PORT> -b <BAUD> flash_id
```
The output contains device information and its flash size:
The output contains device information and its flash size:
```
Detected flash size: 4MB
```
*`<BOOTLOADER_FLASH_OFFSET>` value must follow one of the addresses below:*
| ESP32 | ESP32-S2 | ESP32-C3 | ESP32-S3 |
| :-----: | :-----: | :-----: | :-----: |
| 0x1000 | 0x1000 | 0x0000 | 0x0000 |
......@@ -102,8 +103,8 @@ imgtool.py sign --align 4 -v 0 -H 32 --pad-header -S <SLOT_SIZE> <BIN_IN> <SIGNE
---
***Note***
`<SLOT_SIZE>` is the size of the slot to be used.
***Note***
`<SLOT_SIZE>` is the size of the slot to be used.
Default slot0 size is `0x100000`, but it can change as per application flash partitions.
For Zephyr images, `--pad-header` is not needed as it already has the padding for MCUboot header.
......@@ -213,6 +214,25 @@ CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH=1
---
---
:warning: ***ATTENTION***
*You can disable UART Download Mode by adding the following configuration:*
```
CONFIG_SECURE_DISABLE_ROM_DL_MODE=1
```
*This may be suitable for **production** builds. **After disabling UART Download Mode you will not be able to flash other images through UART.***
*Otherwise, you can switch the UART ROM Download Mode to the Secure Download Mode. It will limit the use of Download Mode functions to simple flash read, write and erase operations.*
```
CONFIG_SECURE_ENABLE_SECURE_ROM_DL_MODE=1
```
*Once the device makes its first full boot, these configurations cannot be reverted*
---
Once the **bootloader image** is built, the resulting binary file is required to be signed with `espsecure.py` tool.
First create a signing key:
......@@ -284,6 +304,8 @@ For **development mode**:
CONFIG_SECURE_FLASH_ENC_ENABLED=1
CONFIG_SECURE_FLASH_ENCRYPTION_MODE_DEVELOPMENT=1
```
---
:warning: ***ATTENTION***
*On development phase is strongly recommended adding the following configuration in order to keep the debugging enabled and also to avoid any unrecoverable/permanent state change:*
......@@ -297,6 +319,7 @@ CONFIG_SECURE_BOOT_ALLOW_JTAG=1
CONFIG_EFUSE_VIRTUAL=1
CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH=1
```
---
---
:warning: ***ATTENTION***
......@@ -305,6 +328,20 @@ CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH=1
*Once the bootloader is flashed and the device resets, the **first boot will enable Flash Encryption, encrypt the flash content including bootloader and image slots, burn the eFuses that no longer can be modified** and if device generated the key **it will not be recoverable**.* \
*When on **RELEASE MODE**, **ENSURE** that the application with an update agent is flashed before reset the device.*
*In the same way as Secure Boot feature, you can disable UART Download Mode by adding the following configuration:*
```
CONFIG_SECURE_DISABLE_ROM_DL_MODE=1
```
*This may be suitable for **production** builds. **After disabling UART Download Mode you will not be able to flash other images through UART.***
*Otherwise, you can switch the UART Download Mode to the Secure Download Mode. It will limit the use of Download Mode functions to simple flash read, write and erase operations.*
```
CONFIG_SECURE_ENABLE_SECURE_ROM_DL_MODE=1
```
*These configurations cannot be reverted after the device's first boot*
---
### [Signing the image when working with Flash Encryption](#signing-the-image-when-working-with-flash-encryption)
......@@ -336,18 +373,18 @@ On the **first boot**, the bootloader will:
### [Host generated key](#host-generated-key)
First ensure that the application image is able to perform encrypted read and write operations to the SPI Flash.
First ensure that the application image is able to perform encrypted read and write operations to the SPI Flash. Also ensure that the **UART ROM Download Mode is not disabled** - or that the **Secure Download Mode is enabled**.
Before flashing, generate the encryption key using `espsecure.py` tool:
```
espsecure.py generate_flash_encryption_key <FLASH_ENCRYPTION_KEY.bin>
```
Burn the key into the device's eFuse, this action can be done **only once**:
Burn the key into the device's eFuse (keep a copy on the host), this action can be done **only once**:
---
:warning: ***ATTENTION***
*eFuse emulation in Flash configuration options do not have any effect, so if the key burning command is used, it will actually burn the physical eFuse.*
*eFuse emulation in Flash configuration options do not have any effect, so if the key burning command below is used, it will actually burn the physical eFuse.*
---
......@@ -379,6 +416,25 @@ On the **first boot**, the bootloader will:
2. Burn eFuse to enable Flash Encryption.
3. Reset system to ensure Flash Encryption cache resets properly.
Encrypting data on the host:
- ESP32
```
espsecure.py encrypt_flash_data --keyfile <FLASH_ENCRYPTION_KEY.bin> --address <FLASH_OFFSET> --output <OUTPUT_DATA> <INPUT_DATA>
```
- ESP32-S2, ESP32-C3 and ESP32-S3
```
espsecure.py encrypt_flash_data --aes_xts --keyfile <FLASH_ENCRYPTION_KEY.bin> --address <FLASH_OFFSET> --output <OUTPUT_DATA> <INPUT_DATA>
```
---
***Note***
OTA updates are required to be sent plaintext. The reason is that, as said before, after the Flash Encryption is enabled all read/write operations are decrypted/encrypted in runtime, so as e.g. if pre-encrypted data is sent for an OTA update, it would be wrongly double-encrypted when the update agent writes to the flash.
For updating with an image encrypted on the host, flash it through serial using `esptool.py` as above. **UART ROM Download Mode must not be disabled**.
---
## [Security Chain scheme](#security-chain-scheme)
Using the 3 features, Secure Boot, Image signature verification and Flash Encryption, a Security Chain can be established so only trusted code is executed, and also the code and content residing in the off-chip flash are protected against undesirable reading.
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment