[incubator-nuttx] branch master updated: documentation: Added Secure Boot and Flash Encryption section to ESP32

[xi...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

xiaoxiang pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-nuttx.git


The following commit(s) were added to refs/heads/master by this push:
     new 3aa08e4d78 documentation: Added Secure Boot and Flash Encryption section to ESP32
3aa08e4d78 is described below

commit 3aa08e4d7880043337998ea1a74e670b5c5c0e46
Author: Lucas Saavedra Vaz <lu...@espressif.com>
AuthorDate: Mon Sep 19 11:55:26 2022 -0300

    documentation: Added Secure Boot and Flash Encryption section to ESP32
    
    documentation: Fixed typos in ESP32 Secure Boot section
    documentation/esp32: Improved note about the MCUboot port
    
    documentation/esp32: Improved instructions in Secure Boot section
    
    documentation/esp32: Fix information in Secure Boot section
    
    documentation/esp32: Added info in Secure Boot section
    
    documentation/esp32: Fix Secure Boot Instructions
---
 Documentation/platforms/xtensa/esp32/index.rst | 103 +++++++++++++++++++++++++
 1 file changed, 103 insertions(+)

diff --git a/Documentation/platforms/xtensa/esp32/index.rst b/Documentation/platforms/xtensa/esp32/index.rst
index c6e26123fb..7cb1a258f5 100644
--- a/Documentation/platforms/xtensa/esp32/index.rst
+++ b/Documentation/platforms/xtensa/esp32/index.rst
@@ -368,6 +368,109 @@ A QEMU-compatible ``nuttx.merged.bin`` binary image will be created. It can be r
 
  $ qemu-system-xtensa -nographic -machine esp32 -drive file=nuttx.merged.bin,if=mtd,format=raw
 
+Secure Boot and Flash Encryption
+================================
+
+Secure Boot
+-----------
+
+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, 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/>`_).
+
+The Secure Boot process on the ESP32 involves the following steps performed:
+
+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.
+
+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.
+
+.. 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's Secure boot
+   `here <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/security/secure-boot-v2.html>`_.
+
+.. 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.
+
+Flash Encryption
+----------------
+
+Flash encryption is intended for encrypting the contents of the ESP32'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.
+
+.. 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's Flash Encryption
+   `here <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/security/flash-encryption.html>`_.
+
+Prerequisites
+-------------
+
+First of all, we need to install ``imgtool`` (a MCUboot utiliy application to manipulate binary images) and
+``esptool`` (the ESP32 toolkit)::
+
+    $ pip install imgtool esptool
+
+We also need to make sure that the python modules are added to ``PATH``::
+
+    $ echo "PATH=$PATH:/home/$USER/.local/bin" >> ~/.bashrc
+
+Now, we will create a folder to store the generated keys (such as ``~/signing_keys``)::
+
+    $ mkdir ~/signing_keys && cd ~/signing_keys
+
+With all set up, we can now generate keys to sign the bootloader and application binary images,
+respectively, of the compiled project::
+
+    $ espsecure.py generate_signing_key --version 2 bootloader_signing_key.pem
+    $ imgtool keygen --key app_signing_key.pem --type rsa-3072
+
+.. important:: The contents of the key files must be stored securely and kept secret.
+
+Enabling Secure Boot and Flash Encryption
+-----------------------------------------
+
+To enable Secure Boot for the current project, go to the project's NuttX directory, execute ``make menuconfig`` and the following steps::
+
+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`.
+
+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/incubator-nuttx-apps/tree/master/examples/mcuboot>`_.
+
+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``.
+
+When creating update images, make sure to change :menuselection:`System Type --> Application Image Configuration --> Target slot for image flashing`
+to ``Application image secondary slot``.
+
+.. 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.**
+
+
 Things to Do
 ============