doc: espressif: Add warning note for Flash Encryption with Serial Recovery usage

## [Installing requirements and dependencies](#installing-requirements-and-dependencies)

1. Install additional packages required for development with MCUboot:

```

```bash

  cd ~/mcuboot  # or to your directory where MCUboot is cloned

```

```bash

  pip3 install --user -r scripts/requirements.txt

```

2. Update the submodules needed by the Espressif port. This may take a while.

```

```bash

git submodule update --init --recursive --checkout boot/espressif/hal/esp-idf

```

3. Next, get the Mbed TLS submodule required by MCUboot.

```

```bash

git submodule update --init --recursive ext/mbedtls

```

4. Now we need to install IDF dependencies and set environment variables. This step may take some time:

```

```bash

cd boot/espressif/hal/esp-idf

```

```bash

./install.sh

```

```bash

. ./export.sh

```

```bash

cd ../..

```

---

1. Compile and generate the BIN:

```

```bash

cmake -DCMAKE_TOOLCHAIN_FILE=tools/toolchain-<TARGET>.cmake -DMCUBOOT_TARGET=<TARGET> -DMCUBOOT_FLASH_PORT=<PORT> -B build -GNinja

```

```bash

ninja -C build/

```

2. Flash MCUboot in your device:

```

```bash

ninja -C build/ flash

```

If `MCUBOOT_FLASH_PORT` arg was not passed to `cmake`, the default `PORT` for flashing will be `/dev/ttyUSB0`.

Alternatively:

```

```bash

esptool.py -p <PORT> -b <BAUD> --before default_reset --after no_reset --chip <TARGET> write_flash --flash_mode dio --flash_size <FLASH_SIZE> --flash_freq 40m <BOOTLOADER_FLASH_OFFSET> build/mcuboot_<TARGET>.bin

```

---

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:*

```

```bash

esptool.py -p <PORT> -b <BAUD> flash_id

```

The output contains device information and its flash size:

## [Signing and flashing an application](#signing-and-flashing-an-application)

1. Images can be regularly signed with the `scripts/imgtool.py` script:

```

```bash

imgtool.py sign --align 4 -v 0 -H 32 --pad-header -S <SLOT_SIZE> <BIN_IN> <SIGNED_BIN>

```

---

2. Flash the signed application:

```

```bash

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 <SLOT_OFFSET> <SIGNED_BIN>

```

### [Signing the image](#signing-the-image)

Now you need to sign the **image binary**, use the `imgtool` with `-k` parameter:

```

```bash

imgtool.py sign -k <YOUR_SIGNING_KEY.pem> --pad --pad-sig --align 4 -v 0 -H 32 --pad-header -S 0x00100000 <BIN_IN> <BIN_OUT>

```

If signing a Zephyr image, the `--pad-header` is not needed, as it already have the padding for MCUboot header.

Once the **bootloader image** is built, the resulting binary file is required to be signed with `espsecure.py` tool.

First create a signing key:

```

```bash

espsecure.py generate_signing_key --version 2 <BOOTLOADER_SIGNING_KEY.pem>

```

Then sign the bootloader image:

```

```bash

espsecure.py sign_data --version 2 --keyfile <BOOTLOADER_SIGNING_KEY.pem> -o <BOOTLOADER_BIN_OUT> <BOOTLOADER_BIN_IN>

```

---

Flash the bootloader as following, with `--after no_reset` flag, so you can reset the device only when assured:

```

```bash

esptool.py -p <PORT> -b 2000000 --after no_reset --chip <ESP_CHIP> write_flash --flash_mode dio --flash_size <FLASH_SIZE> --flash_freq 40m <BOOTLOADER_FLASH_OFFSET> <SIGNED_BOOTLOADER_BIN>

```

When enabling flash encryption, it is required to signed the image using 32-byte alignment: `--align 32 --max-align 32`.

Command example:

```

```bash

imgtool.py sign -k <YOUR_SIGNING_KEY.pem> --pad --pad-sig --align 32 --max-align 32 -v 0 -H 32 --pad-header -S <SLOT_SIZE> <BIN_IN> <BIN_OUT>

```

First ensure that the application image is able to perform encrypted read and write operations to the SPI Flash.

Flash the bootloader and application normally:

```

```bash

esptool.py -p <PORT> -b 2000000 --after no_reset --chip <ESP_CHIP> write_flash --flash_mode dio --flash_size <FLASH_SIZE> --flash_freq 40m <BOOTLOADER_FLASH_OFFSET> <BOOTLOADER_BIN>

```

```

```bash

esptool.py -p <PORT> -b 2000000 --after no_reset --chip <ESP_CHIP> write_flash --flash_mode dio --flash_size <FLASH_SIZE> --flash_freq 40m <PRIMARY_SLOT_FLASH_OFFSET> <APPLICATION_BIN>

```

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:

```

```bash

espsecure.py generate_flash_encryption_key <FLASH_ENCRYPTION_KEY.bin>

```

---

- ESP32

```

```bash

espefuse.py --port PORT burn_key flash_encryption <FLASH_ENCRYPTION_KEY.bin>

```

- ESP32S2, ESP32C3 and ESP32S3

```

```bash

espefuse.py --port PORT burn_key BLOCK <FLASH_ENCRYPTION_KEY.bin> <KEYPURPOSE>

```

Now, similar as the Device generated key, the bootloader and application can be flashed plaintext. The **first boot** will encrypt the flash content using the host key burned in the eFuse instead of generate a new one.

Flashing the bootloader and application:

```

```bash

esptool.py -p <PORT> -b 2000000 --after no_reset --chip <ESP_CHIP> write_flash --flash_mode dio --flash_size <FLASH_SIZE> --flash_freq 40m <BOOTLOADER_FLASH_OFFSET> <BOOTLOADER_BIN>

```

```

```bash

esptool.py -p <PORT> -b 2000000 --after no_reset --chip <ESP_CHIP> write_flash --flash_mode dio --flash_size <FLASH_SIZE> --flash_freq 40m <PRIMARY_SLOT_FLASH_OFFSET> <APPLICATION_BIN>

```

Encrypting data on the host:

- ESP32

```

```bash

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

```

```bash

espsecure.py encrypt_flash_data --aes_xts --keyfile <FLASH_ENCRYPTION_KEY.bin> --address <FLASH_OFFSET> --output <OUTPUT_DATA> <INPUT_DATA>

```

### [Image version dependency](#image-version-dependency)

MCUboot allows version dependency check between the images when updating them. As `imgtool.py` allows a version assigment when signing an image, it is also possible to add the version dependency constraint:

```

```bash

imgtool.py sign --align 4 -v <VERSION> -d "(<IMAGE_INDEX>, <VERSION_DEPENDENCY>)" -H 32 --pad-header -S <SLOT_SIZE> <BIN_IN> <SIGNED_BIN>

```

---

Example:

```

```bash

imgtool.py sign --align 4 -v 1.0.0 -d "(1, 0.0.1+0)" -H 32 --pad-header -S 0x100000 image0.bin image0-signed.bin

```

Serial recovery mode allows management through MCUMGR (more information and how to install it: https://github.com/apache/mynewt-mcumgr-cli) for communicating and uploading a firmware to the device.

---

***Note***

Supported on ESP32, ESP32-C3, ESP32-S2 and ESP32-S3.

---

Configuration example:

```

# Enables the MCUboot Serial Recovery, that allows the use of

### [Serial Recovery through USB JTAG Serial port](#serial-recovery-through-usb-jtag-serial-port)

Some chips, like ESP32-C3, have an integrated USB JTAG Serial Controller that implements a serial port (CDC) that can also be used for handling MCUboot Serial Recovery.

More information about the USB pins and hardware configuration on ESP32-C3: https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/api-guides/usb-serial-jtag-console.html.

Some chips, like ESP32-C3 and ESP32-S3 have an integrated USB JTAG Serial Controller that implements a serial port (CDC) that can also be used for handling MCUboot Serial Recovery.

More information about the USB pins and hardware configuration:

- ESP32-C3: https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/api-guides/usb-serial-jtag-console.html

- ESP32-S3: https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-guides/usb-serial-jtag-console.html.

Configuration example:

```

CONFIG_ESP_SERIAL_BOOT_DETECT_DELAY_S=5

```

---

:warning: ***ATTENTION***

*When working with Flash Encryption enabled, `CONFIG_ESP_MCUBOOT_ERASE_PROGRESSIVELY` must be ***disabled***, although it is recommended for common Serial Recovery usage*

---

### [MCUMGR image upload example](#mcumgr-image-upload-example)

After entering the Serial recovery mode on the device, MCUMGR can be used as following:

Configure the connection:

```

```bash

mcumgr conn add esp type="serial" connstring="dev=<PORT>,baud=115200,mtu=256"

```

Upload the image (the process may take some time):

```

```bash

mcumgr -c esp image upload <IMAGE_BIN>

```

Reset the device:

```

```bash

mcumgr -c esp reset

```