documentation: update flash encryption docs for Espressif devices

Adds new subsection under MCUBoot regarding use of flash encryption.

Signed-off-by: Filipe Cavalcanti <filipe.cavalcanti@espressif.com>

Author: fdcavalcanti

Documentation/platforms/risc-v/esp32c3/index.rst

@@ -97,8 +97,8 @@ functions required to boot the device are built within NuttX. Simple boot does n
 require any specific configuration (it is selectable by default if no other
 2nd stage bootloader is used).
 
-If other features, like `Secure Boot and Flash Encryption`_, are required, an
-externally-built 2nd stage bootloader is needed. The bootloader is built using
+If features like `Flash Encryption`_ are required, an externally-built
+2nd stage bootloader is needed. The MCUBoot bootloader is built using
 the ``make bootloader`` command. This command generates the firmware in the
 ``nuttx`` folder. The ``ESPTOOL_BINDIR`` is used in the ``make flash`` command
 to specify the path to the bootloader. For compatibility among other SoCs and
@@ -497,108 +497,115 @@ Finally, the image is loaded but not confirmed.
 To make sure it won't rollback to the previous image, you must confirm with ``mcuboot_confirm`` and reboot the board.
 The OTA is now complete.
 
-Secure Boot and Flash Encryption
---------------------------------
-
-Secure Boot
-^^^^^^^^^^^
+Flash Encryption
+----------------
 
-Secure Boot protects a device from running any unauthorized (i.e., unsigned) code by checking that
-each piece of software that is being booted is signed. On an ESP32-C3, these pieces of software include
-the second stage bootloader and each application binary. Note that the first stage bootloader does not
-require signing as it is ROM code thus cannot be changed. This is achieved using specific hardware in
-conjunction with MCUboot (read more about MCUboot `here <https://docs.mcuboot.com/>`__).
+Flash encryption is intended for encrypting the contents of the ESP32-C3's off-chip flash memory. Once this feature is enabled,
+firmware is flashed as plaintext, and then the data is encrypted in place on the first boot. As a result, physical readout
+of flash will not be sufficient to recover most flash contents.
 
-The Secure Boot process on the ESP32-C3 involves the following steps performed:
+The current state of flash encryption for ESP32-C3 allows the use of Virtual E-Fuses and development mode, which permit users to evaluate and test the firmware before making definitive changes such as burning E-Fuses.
 
-1. The first stage bootloader verifies the second stage bootloader's RSA-PSS signature. If the verification is successful,
-   the first stage bootloader loads and executes the second stage bootloader.
+Flash encryption supports the following features:
 
-2. When the second stage bootloader loads a particular application image, the application's signature (RSA, ECDSA or ED25519) is verified
-   by MCUboot.
-   If the verification is successful, the application image is executed.
+  .. list-table::
+    :header-rows: 1
 
-.. warning:: Once enabled, Secure Boot will not boot a modified bootloader. The bootloader will only boot an
-   application firmware image if it has a verified digital signature. There are implications for reflashing
-   updated images once Secure Boot is enabled. You can find more information about the ESP32-C3's Secure boot
-   `here <https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/security/secure-boot-v2.html>`__.
+    * - Feature
+      - Description
+    * - **Flash Encryption with Virtual E-Fuses**
+      - Use flash encryption without burning E-Fuses. Default selection when flash encryption is enabled.
+    * - **Flash Encryption in Development mode**
+      - Allows reflashing an encrypted device by appending the ``--encrypt`` argument to the ``esptool.py write_flash`` command. This is done automatically if ``ESPRESSIF_SECURE_FLASH_ENC_FLASH_DEVICE_ENCRYPTED`` is set.
+    * - **Flash Encryption in Release mode**
+      - Does not allow reflashing the device. This is a permanent setting.
+    * - **Flash Encryption key**
+      - A user-generated key is required by default. Alternatively, a device-generated key is possible, but it will not be recoverable by the user (not recommended). See ``ESPRESSIF_SECURE_FLASH_ENC_USE_HOST_KEY``.
+    * - **Encrypted MTD Partition**
+      - If SPI Flash is enabled, an empty user MTD partition will be automatically encrypted on first flash.
 
-.. note:: As the bootloader image is built on top of the Hardware Abstraction Layer component
-   of `ESP-IDF <https://github.com/espressif/esp-idf>`_, the
-   `API port by Espressif <https://docs.mcuboot.com/readme-espressif.html>`_ will be used
-   by MCUboot rather than the original NuttX port.
+.. note::
 
-Flash Encryption
-^^^^^^^^^^^^^^^^
+   It is **strongly suggested** to read the following before working on flash encryption:
 
-Flash encryption is intended for encrypting the contents of the ESP32-C3's off-chip flash memory. Once this feature is enabled,
-firmware is flashed as plaintext, and then the data is encrypted in place on the first boot. As a result, physical readout
-of flash will not be sufficient to recover most flash contents.
+   - `MCUBoot Flash Encryption <https://docs.mcuboot.com/readme-espressif.html#flash-encryption>`_
+   - `General E-Fuse documentation <https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/api-reference/system/efuse.html>`_
+   - `Flash Encryption Relevant E-Fuses <https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/security/flash-encryption.html#relevant-efuses>`_
 
-.. warning::  After enabling Flash Encryption, an encryption key is generated internally by the device and
-   cannot be accessed by the user for re-encrypting data and re-flashing the system, hence it will be permanently encrypted.
-   Re-flashing an encrypted system is complicated and not always possible. You can find more information about the ESP32-C3's Flash Encryption
-   `here <https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/security/flash-encryption.html>`__.
+Flash Encryption Requirements
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Prerequisites
-^^^^^^^^^^^^^
+Flash encryption requires burning E-Fuses to enable it on chip. This is not a reversible operation and should be done with caution.
+There is, however, a way to test the flash encryption by simulating them on flash. Both paths are described below.
 
-First of all, we need to install ``imgtool`` (the MCUboot utility application to manipulate binary
-images)::
+Build System Features
+'''''''''''''''''''''
 
-  $ pip install imgtool
+The build system contains some safeguards to avoid accidentally burning E-Fuses and automations for convenience. Those are summarized below:
 
-We also need to make sure that the python modules are added to ``PATH``::
+  1. A yellow warning will show up during build alerting that flash encryption is enabled (same for Virtual E-Fuses).
+  2. If ``ESPRESSIF_SECURE_FLASH_ENC_USE_HOST_KEY`` is set, build will fail if the flash encryption key is not found.
+  3. If SPI Flash is enabled, the user MTD partition is automatically encrypted with the provided encryption key.
+  4. ``make flash`` command will prompt the user for confirmation before burning the E-Fuse, if Virtual E-Fuses are disabled.
 
-  $ echo "PATH=$PATH:/home/$USER/.local/bin" >> ~/.bashrc
 
-Now, we will create a folder to store the generated keys (such as ``~/signing_keys``)::
+Simulating Flash Encryption with Virtual E-Fuses
+'''''''''''''''''''''''''''''''''''''''''''''''''
 
-  $ mkdir ~/signing_keys && cd ~/signing_keys
+It is highly recommended to use this method for testing the flash encryption before actually burning the E-Fuses.
+The E-Fuses are stored in flash and persist between reboots. No real E-Fuses are changed.
 
-With all set up, we can now generate keys to sign the bootloader and application binary images,
-respectively, of the compiled project::
+To enable virtual E-Fuses for flash encryption testing, open ``menuconfig`` and:
+  1. Enable flash encryption on boot on: :menuselection:`System Type --> Bootloader and Image Configuration`
+  2. Verify Virtual E-Fuses are enabled (this is done by default): :menuselection:`System Type --> Peripheral Support --> E-Fuse support`
 
-  $ espsecure.py generate_signing_key --version 2 bootloader_signing_key.pem
-  $ imgtool keygen --key app_signing_key.pem --type rsa-3072
+.. note:: On ESP32-C3, testing is possible with QEMU. If that is the case, on step 2 disable Virtual E-Fuse and use normal E-Fuse support.
+  See `ESP32-C3 QEMU <https://github.com/espressif/esp-toolchain-docs/tree/main/qemu/esp32c3>`_.
 
-.. important:: The contents of the key files must be stored securely and kept secret.
+Now build the bootloader and the firmware. Flashing the device (or opening on QEMU) will trigger the following:
+  1. On the first boot, the bootloader will encrypt the flash::
 
-Enabling Secure Boot and Flash Encryption
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+      ...
+      [esp32c3] [WRN] eFuse virtual mode is enabled. If Secure boot or Flash encryption is enabled then it does not provide any security. FOR TESTING ONLY!
+      [esp32c3] [WRN] [efuse] [Virtual] try loading efuses from flash: 0x10000 (offset)
+      ...
+      [esp32c3] [INF] [flash_encrypt] Encrypting bootloader...
+      [esp32c3] [INF] [flash_encrypt] Bootloader encrypted successfully
+      [esp32c3] [INF] [flash_encrypt] Encrypting primary slot...
+      [esp32c3] [INF] [flash_encrypt] Encrypting remaining flash...
+      [esp32c3] [INF] [flash_encrypt] Flash encryption completed
+      ...
+      [esp32c3] [INF] Resetting with flash encryption enabled...
 
-To enable Secure Boot for the current project, go to the project's NuttX directory, execute ``make menuconfig`` and the following steps:
+  2. Device will reset and it should be now operating similar to an actual encrypted device::
 
-  1. Enable experimental features in :menuselection:`Build Setup --> Show experimental options`;
-  2. Enable MCUboot in :menuselection:`Application Configuration --> Bootloader Utilities --> MCUboot`;
-  3. Change image type to ``MCUboot-bootable format`` in :menuselection:`System Type --> Application Image Configuration --> Application Image Format`;
-  4. Enable building MCUboot from the source code by selecting ``Build binaries from source``;
-     in :menuselection:`System Type --> Application Image Configuration --> Source for bootloader binaries`;
-  5. Enable Secure Boot in :menuselection:`System Type --> Application Image Configuration --> Enable hardware Secure Boot in bootloader`;
-  6. If you want to protect the SPI Bus against data sniffing, you can enable Flash Encryption in
-     :menuselection:`System Type --> Application Image Configuration --> Enable Flash Encryption on boot`.
+      ...
+      [esp32c3] [INF] Checking flash encryption...
+      [esp32c3] [INF] [flash_encrypt] flash encryption is enabled (1 plaintext flashes left)
+      [esp32c3] [INF] Disabling RNG early entropy source...
+      [esp32c3] [INF] br_image_off = 0x20000
+      [esp32c3] [INF] ih_hdr_size = 0x20
+      [esp32c3] [INF] Loading image 0 - slot 0 from flash, area id: 1
+      ...
+      NuttShell (NSH) NuttX-12.8.0
+      nsh>
 
-Now you can design an update and confirm agent to your application. Check the `MCUboot design guide <https://docs.mcuboot.com/design.html>`_ and the
-`MCUboot Espressif port documentation <https://docs.mcuboot.com/readme-espressif.html>`_ for
-more information on how to apply MCUboot. Also check some `notes about the NuttX MCUboot port <https://github.com/mcu-tools/mcuboot/blob/main/docs/readme-nuttx.md>`_,
-the `MCUboot porting guide <https://github.com/mcu-tools/mcuboot/blob/main/docs/PORTING.md>`_ and some
-`examples of MCUboot applied in NuttX applications <https://github.com/apache/nuttx-apps/tree/master/examples/mcuboot>`_.
+Actual encryption and burning E-Fuses
+'''''''''''''''''''''''''''''''''''''
 
-After you developed an application which implements all desired functions, you need to flash it into the primary image slot
-of the device (it will automatically be in the confirmed state, you can learn more about image
-confirmation `here <https://docs.mcuboot.com/design.html#image-swapping>`_).
-To flash to the primary image slot, select ``Application image primary slot`` in
-:menuselection:`System Type --> Application Image Configuration --> Target slot for image flashing`
-and compile it using ``make -j ESPSEC_KEYDIR=~/signing_keys``.
+E-Fuses are burned by esptool and the bootloader on the first boot after flashing with encryption enabled.
+This process is automated on NuttX build system.
 
-When creating update images, make sure to change :menuselection:`System Type --> Application Image Configuration --> Target slot for image flashing`
-to ``Application image secondary slot``.
+.. warning::  Burning E-Fuses is NOT a reversible operation and should be done with caution.
 
-.. important:: When deploying your application, make sure to disable UART Download Mode by selecting ``Permanently disabled`` in
-   :menuselection:`System Type --> Application Image Configuration --> UART ROM download mode`
-   and change usage mode to ``Release`` in `System Type --> Application Image Configuration --> Enable usage mode`.
-   **After disabling UART Download Mode you will not be able to flash other images through UART.**
+To build a firmware with E-Fuse support and flash encryption enabled, open ``menuconfig`` and:
+  1. Enable flash encryption on boot on: :menuselection:`System Type --> Bootloader and Image Configuration`
+  2. Disable Virtual E-Fuses :menuselection:`System Type --> Peripheral Support --> E-Fuse support`
+  3. Check usage mode is Development (this allows reflashing, while Release mode does not).
 
+.. note::  If using development mode of flash encryption (see menuconfig and documentation above), it is still possible to re-flash the device with esptool by
+  setting ``ESPRESSIF_SECURE_FLASH_ENC_FLASH_DEVICE_ENCRYPTED`` which adds ``--encrypt`` argument to the ``esptool.py write_flash`` command.
+  This will apply the burned encryption key to the image while flashing.
 
 Flash Allocation for MCUBoot
 ----------------------------