docs: Add more ReST-isms in secure boot & flash encryption docs
(Original version of these docs were in Markdown.)
This commit is contained in:
Angus Gratton
Angus Gratton
parent
6a498bfe2b
commit
cee6d7d5a9
|
|
@ -43,6 +43,10 @@ config PARTITION_TABLE_OFFSET
|
|||
Allows you to move the partition table, it gives more space for the bootloader.
|
||||
Note that the bootloader and app will both need to be compiled with the same PARTITION_TABLE_OFFSET value.
|
||||
|
||||
This number should be a multiple of 0x1000.
|
||||
|
||||
Note that partition offsets in the partition table CSV file may need to be changed if this value is set to a higher value.
|
||||
|
||||
config PARTITION_TABLE_MD5
|
||||
bool "Generate an MD5 checksum for the partition table"
|
||||
default y
|
||||
|
|
|
|||
|
|
@ -5,7 +5,8 @@ Flash Encryption is a feature for encrypting the contents of the ESP32's attache
|
|||
|
||||
Flash Encryption is separate from the :doc:`Secure Boot <secure-boot>` feature, and you can use flash encryption without enabling secure boot. However we recommend using both features together for a secure environment.
|
||||
|
||||
**IMPORTANT: Enabling flash encryption limits your options for further updates of your ESP32. Make sure to read this document (including :ref:`flash-encryption-limitations`) and understand the implications of enabling flash encryption.**
|
||||
.. important::
|
||||
Enabling flash encryption limits your options for further updates of your ESP32. Make sure to read this document (including :ref:`flash-encryption-limitations`) and understand the implications of enabling flash encryption.
|
||||
|
||||
Background
|
||||
----------
|
||||
|
|
@ -41,7 +42,8 @@ Flash Encryption Initialisation
|
|||
|
||||
This is the default (and recommended) flash encryption initialisation process. It is possible to customise this process for development or other purposes, see :ref:`flash-encryption-advanced-features` for details.
|
||||
|
||||
**IMPORTANT: Once flash encryption is enabled on first boot, the hardware allows a maximum of 3 subsequent flash updates via serial re-flashing.** A special procedure (documented in :ref:`updating-encrypted-flash-serial`) must be followed to perform these updates.
|
||||
.. important::
|
||||
Once flash encryption is enabled on first boot, the hardware allows a maximum of 3 subsequent flash updates via serial re-flashing. A special procedure (documented in :ref:`updating-encrypted-flash-serial`) must be followed to perform these updates.
|
||||
|
||||
- If secure boot is enabled, physical reflashing with plaintext data requires a "Reflashable" secure boot digest (see :ref:`flash-encryption-and-secure-boot`).
|
||||
- OTA updates can be used to update flash content without counting towards this limit.
|
||||
|
|
@ -61,7 +63,8 @@ Process to enable flash encryption:
|
|||
|
||||
- All of the encrypted partitions are then encrypted in-place by the bootloader. Encrypting in-place can take some time (up to a minute for large partitions.)
|
||||
|
||||
**IMPORTANT: Do not interrupt power to the ESP32 while the first boot encryption pass is running. If power is interrupted, the flash contents will be corrupted and require flashing with unencrypted data again. A reflash like this will not count towards the flashing limit.**
|
||||
.. important::
|
||||
Do not interrupt power to the ESP32 while the first boot encryption pass is running. If power is interrupted, the flash contents will be corrupted and require flashing with unencrypted data again. A reflash like this will not count towards the flashing limit.
|
||||
|
||||
- Once flashing is complete. efuses are blown (by default) to disable encrypted flash access while the UART bootloader is running. See :ref:`uart-bootloader-encryption` for advanced details.
|
||||
|
||||
|
|
@ -90,7 +93,8 @@ Whenever the :ref:`FLASH_CRYPT_CNT` is set to a value with an odd number of bits
|
|||
- Any data accessed via :func:`esp_spi_flash_mmap`.
|
||||
- The software bootloader image when it is read by the ROM bootloader.
|
||||
|
||||
**IMPORTANT: The MMU flash cache unconditionally decrypts all data. Data which is stored unencrypted in the flash will be "transparently decrypted" via the flash cache and appear to software like random garbage.**
|
||||
.. important::
|
||||
The MMU flash cache unconditionally decrypts all data. Data which is stored unencrypted in the flash will be "transparently decrypted" via the flash cache and appear to software like random garbage.
|
||||
|
||||
Reading Encrypted Flash
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
|
@ -185,7 +189,8 @@ It is possible to pregenerate a flash encryption key on the host computer and bu
|
|||
|
||||
This is useful for development, because it removes the 4 time reflashing limit. It also allows reflashing the app with secure boot enabled, because the bootloader doesn't need to be reflashed each time.
|
||||
|
||||
**IMPORTANT This method is intended to assist with development only, not for production devices. If pre-generating flash encryption for production, ensure the keys are generated from a high quality random number source and do not share the same flash encryption key across multiple devices.**
|
||||
.. important::
|
||||
This method is intended to assist with development only, not for production devices. If pre-generating flash encryption for production, ensure the keys are generated from a high quality random number source and do not share the same flash encryption key across multiple devices.
|
||||
|
||||
Pregenerating a Flash Encryption Key
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
|
@ -196,7 +201,7 @@ Flash encryption keys are 32 bytes of random data. You can generate a random key
|
|||
|
||||
(The randomness of this data is only as good as the OS and it's Python installation's random data source.)
|
||||
|
||||
Alternatively, if you're using :doc:`secure boot <secure-boot>` and have a secure boot signing key then you can generate a deterministic SHA-256 digest of the secure boot private signing key and use this as the flash encryption key::
|
||||
Alternatively, if you're using :doc:`secure boot <secure-boot>` and have a :ref:`secure boot signing key <secure-boot-generate-key>` then you can generate a deterministic SHA-256 digest of the secure boot private signing key and use this as the flash encryption key::
|
||||
|
||||
espsecure.py digest_private_key --keyfile secure_boot_signing_key.pem my_flash_encryption_key.bin
|
||||
|
||||
|
|
@ -280,7 +285,7 @@ Flash Encryption & Secure Boot
|
|||
It is recommended to use flash encryption and secure boot together. However, if Secure Boot is enabled then additional restrictions apply to reflashing the device:
|
||||
|
||||
- :ref:`updating-encrypted-flash-ota` are not restricted (provided the new app is signed correctly with the Secure Boot signing key).
|
||||
- :ref:`Plaintext serial flash updates <updating-encrypted-flash-serial>` are only possible if the :envvar:`Reflashable <CONFIG_SECURE_BOOTLOADER_REFLASHABLE>` Secure Boot mode is selected and a Secure Boot key was pre-generated and burned to the ESP32 (refer to :doc:`Secure Boot <secure-boot>` docs.). In this configuration, ``make bootloader`` will produce a pre-digested bootloader and secure boot digest file for flashing at offset 0x0. When following the plaintext serial reflashing steps it is necessary to re-flash this file before flashing other plaintext data.
|
||||
- :ref:`Plaintext serial flash updates <updating-encrypted-flash-serial>` are only possible if the :envvar:`Reflashable <CONFIG_SECURE_BOOTLOADER_REFLASHABLE>` Secure Boot mode is selected and a Secure Boot key was pre-generated and burned to the ESP32 (refer to :ref:`Secure Boot <secure-boot-reflashable>` docs.). In this configuration, ``make bootloader`` will produce a pre-digested bootloader and secure boot digest file for flashing at offset 0x0. When following the plaintext serial reflashing steps it is necessary to re-flash this file before flashing other plaintext data.
|
||||
- :ref:`pregenerated-flash-encryption-key` is still possible, provided the bootloader is not reflashed. Reflashing the bootloader requires the same :envvar:`Reflashable <CONFIG_SECURE_BOOTLOADER_REFLASHABLE>` option to be enabled in the Secure Boot config.
|
||||
|
||||
.. _flash-encryption-advanced-features:
|
||||
|
|
@ -333,9 +338,11 @@ It is possible to burn only some of these efuses, and write-protect the rest (wi
|
|||
|
||||
(Note that all 3 of these efuses are disabled via one write protect bit, so write protecting one will write protect all of them. For this reason, it's necessary to set any bits before write-protecting.)
|
||||
|
||||
**IMPORTANT**: Write protecting these efuses to keep them unset is not currently very useful, as ``esptool.py`` does not support writing or reading encrypted flash.
|
||||
.. important::
|
||||
Write protecting these efuses to keep them unset is not currently very useful, as ``esptool.py`` does not support writing or reading encrypted flash.
|
||||
|
||||
**IMPORTANT**: If ``DISABLE_DL_DECRYPT`` is left unset (0) this effectively makes flash encryption useless, as an attacker with physical access can use UART bootloader mode (with custom stub code) to read out the flash contents.
|
||||
.. important::
|
||||
If ``DISABLE_DL_DECRYPT`` is left unset (0) this effectively makes flash encryption useless, as an attacker with physical access can use UART bootloader mode (with custom stub code) to read out the flash contents.
|
||||
|
||||
.. _setting-flash-crypt-config:
|
||||
|
||||
|
|
|
|||
|
|
@ -82,9 +82,11 @@ How To Enable Secure Boot
|
|||
|
||||
4. The first time you run ``make``, if the signing key is not found then an error message will be printed with a command to generate a signing key via ``espsecure.py generate_signing_key``.
|
||||
|
||||
**IMPORTANT** A signing key generated this way will use the best random number source available to the OS and its Python installation (`/dev/urandom` on OSX/Linux and `CryptGenRandom()` on Windows). If this random number source is weak, then the private key will be weak.
|
||||
.. important::
|
||||
A signing key generated this way will use the best random number source available to the OS and its Python installation (`/dev/urandom` on OSX/Linux and `CryptGenRandom()` on Windows). If this random number source is weak, then the private key will be weak.
|
||||
|
||||
**IMPORTANT** For production environments, we recommend generating the keypair using openssl or another industry standard encryption program. See :ref:`secure-boot-generate-key` for more details.
|
||||
.. important::
|
||||
For production environments, we recommend generating the keypair using openssl or another industry standard encryption program. See :ref:`secure-boot-generate-key` for more details.
|
||||
|
||||
5. Run ``make bootloader`` to build a secure boot enabled bootloader. The output of ``make`` will include a prompt for a flashing command, using ``esptool.py write_flash``.
|
||||
|
||||
|
|
@ -94,11 +96,13 @@ How To Enable Secure Boot
|
|||
|
||||
7. Run ``make flash`` to build and flash the partition table and the just-built app image. The app image will be signed using the signing key you generated in step 4.
|
||||
|
||||
*NOTE*: ``make flash`` doesn't flash the bootloader if secure boot is enabled.
|
||||
.. note:: ``make flash`` doesn't flash the bootloader if secure boot is enabled.
|
||||
|
||||
8. Reset the ESP32 and it will boot the software bootloader you flashed. The software bootloader will enable secure boot on the chip, and then it verifies the app image signature and boots the app. You should watch the serial console output from the ESP32 to verify that secure boot is enabled and no errors have occurred due to the build configuration.
|
||||
|
||||
**NOTE** Secure boot won't be enabled until after a valid partition table and app image have been flashed. This is to prevent accidents before the system is fully configured.
|
||||
.. note:: Secure boot won't be enabled until after a valid partition table and app image have been flashed. This is to prevent accidents before the system is fully configured.
|
||||
|
||||
.. note:: If the ESP32 is reset or powered down during the first boot, it will start the process again on the next boot.
|
||||
|
||||
9. On subsequent boots, the secure boot hardware will verify the software bootloader has not changed (using the secure bootloader key) and then the software bootloader will verify the signed partition table and app image (using the public key portion of the secure boot signing key).
|
||||
|
||||
|
|
@ -109,11 +113,11 @@ Re-Flashable Software Bootloader
|
|||
|
||||
Configuration "Secure Boot: One-Time Flash" is the recommended configuration for production devices. In this mode, each device gets a unique key that is never stored outside the device.
|
||||
|
||||
However, an alternative mode "Secure Boot: Reflashable" is also available. This mode allows you to supply a 256-bit key file that is used for the secure bootloader key. As you have the key file, you can generate new bootloader images and secure boot digests for them.
|
||||
However, an alternative mode :envvar:`Secure Boot: Reflashable <CONFIG_SECURE_BOOTLOADER_REFLASHABLE>` is also available. This mode allows you to supply a 256-bit key file that is used for the secure bootloader key. As you have the key file, you can generate new bootloader images and secure boot digests for them.
|
||||
|
||||
In the esp-idf build process, this 256-bit key file is derived from the app signing key generated during the generate_signing_key step above. The private key's SHA-256 digest is used as the 256-bit secure bootloader key. This is a convenience so you only need to generate/protect a single private key.
|
||||
|
||||
**NOTE**: Although it's possible, we strongly recommend not generating one secure boot key and flashing it to every device in a production environment. The "One-Time Flash" option is recommended for production environments.
|
||||
.. note:: Although it's possible, we strongly recommend not generating one secure boot key and flashing it to every device in a production environment. The "One-Time Flash" option is recommended for production environments.
|
||||
|
||||
To enable a reflashable bootloader:
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue