diff --git a/Documentation/platforms/risc-v/esp32c3/index.rst b/Documentation/platforms/risc-v/esp32c3/index.rst index 49955aa5a32..f5807f8aeb7 100644 --- a/Documentation/platforms/risc-v/esp32c3/index.rst +++ b/Documentation/platforms/risc-v/esp32c3/index.rst @@ -125,6 +125,114 @@ RSA Yes CDC Console Yes Rev.3 =========== ======= ===== +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-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 `__). + +The Secure Boot process on the ESP32-C3 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-C3'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-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. + +.. 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 `__. + +Prerequisites +------------- + +First of all, we need to install ``imgtool`` (a MCUboot utility application to manipulate binary +images) and ``esptool`` (the ESP32-C3 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.** + + Supported Boards ================ diff --git a/Documentation/platforms/xtensa/esp32/index.rst b/Documentation/platforms/xtensa/esp32/index.rst index a68c7eb644b..e93b5faa271 100644 --- a/Documentation/platforms/xtensa/esp32/index.rst +++ b/Documentation/platforms/xtensa/esp32/index.rst @@ -429,8 +429,8 @@ of flash will not be sufficient to recover most flash contents. Prerequisites ------------- -First of all, we need to install ``imgtool`` (a MCUboot utiliy application to manipulate binary images) and -``esptool`` (the ESP32 toolkit):: +First of all, we need to install ``imgtool`` (a MCUboot utility application to manipulate binary +images) and ``esptool`` (the ESP32 toolkit):: $ pip install imgtool esptool @@ -453,14 +453,19 @@ respectively, of the compiled project:: 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:: +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`. diff --git a/Documentation/platforms/xtensa/esp32s2/index.rst b/Documentation/platforms/xtensa/esp32s2/index.rst index 7b82326c213..609e2531054 100644 --- a/Documentation/platforms/xtensa/esp32s2/index.rst +++ b/Documentation/platforms/xtensa/esp32s2/index.rst @@ -312,8 +312,8 @@ of flash will not be sufficient to recover most flash contents. Prerequisites ------------- -First of all, we need to install ``imgtool`` (a MCUboot utiliy application to manipulate binary images) and -``esptool`` (the ESP32-S2 toolkit):: +First of all, we need to install ``imgtool`` (a MCUboot utility application to manipulate binary +images) and ``esptool`` (the ESP32-S2 toolkit):: $ pip install imgtool esptool @@ -336,16 +336,21 @@ respectively, of the compiled project:: 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:: +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`. + 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