From 3aa08e4d7880043337998ea1a74e670b5c5c0e46 Mon Sep 17 00:00:00 2001 From: Lucas Saavedra Vaz Date: Mon, 19 Sep 2022 11:55:26 -0300 Subject: [PATCH] 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 --- .../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 `_). + +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 `_. + +.. note:: As the bootloader image is built on top of the Hardware Abstraction Layer component + of `ESP-IDF `_, the + `API port by Espressif `_ 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 `_. + +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 `_ and the +`MCUboot Espressif port documentation `_ for +more information on how to apply MCUboot. Also check some `notes about the NuttX MCUboot port `_, +the `MCUboot porting guide `_ and some +`examples of MCUboot applied in Nuttx applications `_. + +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 `_). +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 ============