doc: Add and fix Secure Boot and Flash Encryption section for ESP boards
This commit is contained in:
Lucas Saavedra Vaz
Xiang Xiao
parent
f56710c121
commit
4d164bb995
@ -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 <https://docs.mcuboot.com/>`__).
|
||||
|
||||
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 <https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/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-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 <https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/security/flash-encryption.html>`__.
|
||||
|
||||
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 <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.**
|
||||
|
||||
|
||||
Supported Boards
|
||||
================
|
||||
|
||||
|
||||
@ -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`.
|
||||
|
||||
|
||||
@ -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,14 +336,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`.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user