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 <[email protected]>
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
============
