doc: update flash encryption with S2 specific content
This commit is contained in:
Marius Vikhammer
parent
0cc9ffb8f7
commit
d193790f85
1 changed files with 169 additions and 104 deletions
|
|
@ -26,6 +26,10 @@ Other types of data can be encrypted conditionally:
|
|||
|
||||
:doc:`Secure Boot <secure-boot-v2>` is a separate feature which can be used together with flash encryption to create an even more secure environment.
|
||||
|
||||
.. important::
|
||||
For production use, flash encryption should be enabled in the "Release" mode only.
|
||||
|
||||
|
||||
.. important::
|
||||
|
||||
Enabling flash encryption limits the options for further updates of {IDF_TARGET_NAME}. Before using this feature, read the document and make sure to understand the implications.
|
||||
|
|
@ -96,16 +100,16 @@ The flash encryption operation is controlled by various eFuses available on {IDF
|
|||
- **Bit Depth**
|
||||
- **Locking for Reading/Writing Available**
|
||||
- **Default Value**
|
||||
* - ``EFUSE_KEY_PURPOSE_N``
|
||||
- Controls the purpose of ``KEYN``, where N is between 0 and 5. Possible values: ``2`` for ``XTS_AES_256_KEY_1`` , ``3`` for ``XTS_AES_256_KEY_2``, and ``4`` for ``XTS_AES_128_KEY``. Final AES key is derived based on TABLE X.
|
||||
- 4
|
||||
- Yes
|
||||
- 0
|
||||
* - ``KEYN``
|
||||
- AES key storage. N is between 0 and 5.
|
||||
- 256
|
||||
- Yes
|
||||
- x
|
||||
* - ``EFUSE_KEY_PURPOSE_N``
|
||||
- Controls the purpose of eFuse block ``KEYN``, where N is between 0 and 5. Possible values: ``2`` for ``XTS_AES_256_KEY_1`` , ``3`` for ``XTS_AES_256_KEY_2``, and ``4`` for ``XTS_AES_128_KEY``. Final AES key is derived based on the value of one or two of these purpose eFuses. For a detailed description of the possible combinations see `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_, chapter Flash Encryption.
|
||||
- 4
|
||||
- Yes
|
||||
- 0
|
||||
* - ``EFUSE_DIS_DOWNLOAD_MANUAL_ENCRYPT``
|
||||
- If set, disables flash encryption when in download bootmodes.
|
||||
- 1
|
||||
|
|
@ -123,25 +127,47 @@ The flash encryption operation is controlled by various eFuses available on {IDF
|
|||
Flash Encryption Process
|
||||
------------------------
|
||||
|
||||
Assuming that the eFuse values are in their default states and the firmware bootloader is compiled to support flash encryption, the flash encryption process executes as shown below:
|
||||
{IDF_TARGET_CRYPT_CNT:default="EFUSE_SPI_BOOT_CRYPT_CNT",esp32="FLASH_CRYPT_CNT",esp32s2="EFUSE_SPI_BOOT_CRYPT_CNT"}
|
||||
|
||||
1. On the first power-on reset, all data in flash is un-encrypted (plaintext). The ROM bootloader loads the firmware bootloader.
|
||||
Assuming that the eFuse values are in their default states and the firmware bootloader is compiled to support flash encryption, the flash encryption process executes as shown below:
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
2. Firmware bootloader reads the ``FLASH_CRYPT_CNT`` eFuse value (``0b00000000``). Since the value is ``0`` (even number of bits set), it configures and enables the flash encryption block. It also sets the ``FLASH_CRYPT_CONFIG`` eFuse to 0xF. For more information on the flash encryption block, see `{IDF_TARGET_NAME} Technical reference manual`_.
|
||||
1. On the first power-on reset, all data in flash is un-encrypted (plaintext). The ROM bootloader loads the firmware bootloader.
|
||||
|
||||
2. Firmware bootloader reads the ``FLASH_CRYPT_CNT`` eFuse value (``0b00000000``). Since the value is ``0`` (even number of bits set), it configures and enables the flash encryption block. It also sets the ``FLASH_CRYPT_CONFIG`` eFuse to 0xF. For more information on the flash encryption block, see `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_.
|
||||
|
||||
3. Flash encryption block generates an AES-256 bit key and writes it into the BLOCK1 eFuse. This operation is done entirely by hardware, and the key cannot be accessed via software.
|
||||
|
||||
4. Flash encryption block encrypts the flash contents - partitions encrypted by default and the ones marked as ``encrypted``. Encrypting in-place can take time, up to a minute for large partitions.
|
||||
|
||||
5. Firmware bootloader sets the first available bit in ``FLASH_CRYPT_CNT`` (0b00000001) to mark the flash contents as encrypted. Odd number of bits is set.
|
||||
|
||||
6. For :ref:`flash-enc-development-mode`, the firmware bootloader sets only the eFuse bits ``download_dis_decrypt`` and ``download_dis_cache`` to allow the UART bootloader to re-flash encrypted binaries. Also, the ``FLASH_CRYPT_CNT`` eFuse bits are NOT write-protected.
|
||||
|
||||
7. For :ref:`flash-enc-release-mode`, the firmware bootloader sets the eFuse bits ``download_dis_encrypt``, ``download_dis_decrypt``, and ``download_dis_cache`` to 1 to prevent the UART bootloader from decrypting the flash contents. It also write-protects the ``FLASH_CRYPT_CNT`` eFuse bits. To modify this behavior, see :ref:`uart-bootloader-encryption`.
|
||||
|
||||
8. The device is then rebooted to start executing the encrypted image. The firmware bootloader calls the flash decryption block to decrypt the flash contents and then loads the decrypted contents into IRAM.
|
||||
|
||||
.. only:: esp32s2
|
||||
|
||||
2. Firmware bootloader reads the ``EFUSE_SPI_BOOT_CRYPT_CNT`` eFuse value (``0b00000000``). Since the value is ``0`` (even number of bits set), it configures and enables the flash encryption block. It also sets the ``FLASH_CRYPT_CONFIG???`` eFuse to 0xF. For more information on the flash encryption block, see `{IDF_TARGET_NAME} Technical reference manual`_.
|
||||
1. On the first power-on reset, all data in flash is un-encrypted (plaintext). The ROM bootloader loads the firmware bootloader.
|
||||
|
||||
2. Firmware bootloader reads the ``EFUSE_SPI_BOOT_CRYPT_CNT`` eFuse value (``0b00000000``). Since the value is ``0`` (even number of bits set), it configures and enables the flash encryption block. For more information on the flash encryption block, see `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_.
|
||||
|
||||
3. Flash encryption block generates an 256 bit or 512 bit key, depending on the value of :ref:`Size of generated AES-XTS key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>`, and writes it into respectively one or two `KEYN` eFuses. The software also updates the ``EFUSE_KEY_PURPOSE_N`` for the blocks where the keys where stored. This operation is done entirely by hardware, and the key cannot be accessed via software.
|
||||
|
||||
3. Flash encryption block generates an AES-256 bit key and writes it into the BLOCK1 eFuse. This operation is done entirely by hardware, and the key cannot be accessed via software.
|
||||
4. Flash encryption block encrypts the flash contents - partitions encrypted by default and the ones marked as ``encrypted``. Encrypting in-place can take time, up to a minute for large partitions.
|
||||
5. Firmware bootloader sets the first available bit in ``FLASH_CRYPT_CNT`` (0b00000001) to mark the flash contents as encrypted. Odd number of bits is set.
|
||||
6. For :ref:`flash-enc-development-mode`, the firmware bootloader sets only the eFuse bits ``download_dis_decrypt`` and ``download_dis_cache`` to allow the UART bootloader to re-flash encrypted binaries. Also, the ``FLASH_CRYPT_CNT`` eFuse bits are NOT write-protected.
|
||||
7. For :ref:`flash-enc-release-mode`, the firmware bootloader sets the eFuse bits ``download_dis_encrypt``, ``download_dis_decrypt``, and ``download_dis_cache`` to 1 to prevent the UART bootloader from decrypting the flash contents. It also write-protects the ``FLASH_CRYPT_CNT`` eFuse bits. To modify this behavior, see :ref:`uart-bootloader-encryption`.
|
||||
|
||||
5. Firmware bootloader sets the first available bit in ``EFUSE_SPI_BOOT_CRYPT_CNT`` (0b00000001) to mark the flash contents as encrypted. Odd number of bits is set.
|
||||
|
||||
6. For :ref:`flash-enc-development-mode`, the firmware bootloader allows the UART bootloader to re-flash encrypted binaries. Also, the ``EFUSE_SPI_BOOT_CRYPT_CNT`` eFuse bits are NOT write-protected.
|
||||
|
||||
7. For :ref:`flash-enc-release-mode`, the firmware bootloader sets the eFuse bits ``EFUSE_DIS_DOWNLOAD_MANUAL_ENCRYPT``, ``EFUSE_DIS_BOOT_REMAP``, ``EFUSE_DIS_DOWNLOAD_ICACHE`` and ``EFUSE_DIS_DOWNLOAD_DCACHE``. It also write-protects the ``EFUSE_SPI_BOOT_CRYPT_CNT`` eFuse bits. To modify this behavior, see :ref:`uart-bootloader-encryption`.
|
||||
|
||||
8. The device is then rebooted to start executing the encrypted image. The firmware bootloader calls the flash decryption block to decrypt the flash contents and then loads the decrypted contents into IRAM.
|
||||
|
||||
|
||||
During the development stage, there is a frequent need to program different plaintext flash images and test the flash encryption process. This requires that Firmware Download mode is able to load new plaintext images as many times as it might be needed. However, during manufacturing or production stages, Firmware Download mode should not be allowed to access flash contents for security reasons.
|
||||
|
||||
Hence, two different flash encryption configurations were created: for development and for production. For details on these configurations, see Section `Flash Encryption Configuration`_.
|
||||
|
|
@ -182,8 +208,11 @@ To test flash encryption process, take the following steps:
|
|||
|
||||
2. In :ref:`project-configuration-menu`, do the following:
|
||||
|
||||
.. list::
|
||||
|
||||
- :ref:`Enable flash encryption on boot <CONFIG_SECURE_FLASH_ENC_ENABLED>`
|
||||
- :ref:`Select ecnryption mode <CONFIG_SECURE_FLASH_ENCRYPTION_MODE>` (**Development mode** by default)
|
||||
- :ref:`Select encryption mode <CONFIG_SECURE_FLASH_ENCRYPTION_MODE>` (**Development mode** by default)
|
||||
:esp32s2: - Set :ref:`Size of generated AES-XTS key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>`
|
||||
- :ref:`Select the appropriate bootloader log verbosity <CONFIG_BOOTLOADER_LOG_LEVEL>`
|
||||
- Save the configuration and exit.
|
||||
|
||||
|
|
@ -334,7 +363,7 @@ A sample output of subsequent {IDF_TARGET_NAME} boots just mentions that flash e
|
|||
I (0) cpu_start: Starting scheduler on APP CPU.
|
||||
|
||||
Sample program to check Flash Encryption
|
||||
This is {IDF_TARGET_NAME} chip with 2 CPU cores, WiFi/BT/BLE, silicon revision 1, 4MB external flash
|
||||
This is ESP32 chip with 2 CPU cores, WiFi/BT/BLE, silicon revision 1, 4MB external flash
|
||||
Flash encryption feature is enabled
|
||||
Flash encryption mode is DEVELOPMENT
|
||||
Flash in encrypted mode with flash_crypt_cnt = 1
|
||||
|
|
@ -377,7 +406,7 @@ To use a host generated key, take the following steps:
|
|||
4. In :ref:`project-configuration-menu`, do the following:
|
||||
|
||||
- :ref:`Enable flash encryption on boot <CONFIG_SECURE_FLASH_ENC_ENABLED>`
|
||||
- :ref:`Select ecnryption mode <CONFIG_SECURE_FLASH_ENCRYPTION_MODE>` (**Development mode** by default)
|
||||
- :ref:`Select encryption mode <CONFIG_SECURE_FLASH_ENCRYPTION_MODE>` (**Development mode** by default)
|
||||
- :ref:`Select the appropriate bootloader log verbosity <CONFIG_BOOTLOADER_LOG_LEVEL>`
|
||||
- Save the configuration and exit.
|
||||
|
||||
|
|
@ -429,8 +458,12 @@ To use this mode, take the following steps:
|
|||
|
||||
2. In :ref:`project-configuration-menu`, do the following:
|
||||
|
||||
.. list::
|
||||
|
||||
- :ref:`Enable flash encryption on boot <CONFIG_SECURE_FLASH_ENC_ENABLED>`
|
||||
- :ref:`Select Release mode <CONFIG_SECURE_FLASH_ENCRYPTION_MODE>` (Note that once Release mode is selected, the ``download_dis_encrypt`` and ``download_dis_decrypt`` eFuse bits will be burned to disable UART bootloader access to flash contents)
|
||||
:esp32: - :ref:`Select Release mode <CONFIG_SECURE_FLASH_ENCRYPTION_MODE>` (Note that once Release mode is selected, the ``download_dis_encrypt`` and ``download_dis_decrypt`` eFuse bits will be burned to disable UART bootloader access to flash contents)
|
||||
:esp32s2: - :ref:`Select Release mode <CONFIG_SECURE_FLASH_ENCRYPTION_MODE>` (Note that once Release mode is selected, the ``EFUSE_DIS_DOWNLOAD_MANUAL_ENCRYPT`` eFuse bit will be burned to disable UART bootloader access to flash contents)
|
||||
:esp32s2: - Set :ref:`Size of generated AES-XTS key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>`
|
||||
- :ref:`Select the appropriate bootloader log verbosity <CONFIG_BOOTLOADER_LOG_LEVEL>`
|
||||
- Save the configuration and exit.
|
||||
|
||||
|
|
@ -446,7 +479,7 @@ To use this mode, take the following steps:
|
|||
|
||||
The image will include the firmware bootloader, partition table, application, and other partitions marked by the user as ``encrypted``. These binaries will be written to flash memory unencrypted. Once the flashing is complete, your device will reset. On the next boot, the firmware bootloader encrypts the flash application partition and then resets. After that, the sample application is decrypted at runtime and executed.
|
||||
|
||||
Once the flash encryption is enabled in Release mode, the bootloader will write-protect the ``FLASH_CRYPT_CNT`` eFuse.
|
||||
Once the flash encryption is enabled in Release mode, the bootloader will write-protect the ``{IDF_TARGET_CRYPT_CNT}`` eFuse.
|
||||
|
||||
For subsequent plaintext field updates, use :ref:`OTA scheme <updating-encrypted-flash-ota>`.
|
||||
|
||||
|
|
@ -454,7 +487,7 @@ For subsequent plaintext field updates, use :ref:`OTA scheme <updating-encrypted
|
|||
Possible Failures
|
||||
-----------------
|
||||
|
||||
Once flash encryption is enabled, the ``FLASH_CRYPT_CNT`` eFuse value will have an odd number of bits set. It means that all the partitions marked with the encryption flag are expected to contain encrypted ciphertext. Below are the three typical failure cases if the {IDF_TARGET_NAME} is erroneously loaded with plaintext data:
|
||||
Once flash encryption is enabled, the ``{IDF_TARGET_CRYPT_CNT}`` eFuse value will have an odd number of bits set. It means that all the partitions marked with the encryption flag are expected to contain encrypted ciphertext. Below are the three typical failure cases if the {IDF_TARGET_NAME} is erroneously loaded with plaintext data:
|
||||
|
||||
1. If the bootloader partition is re-flashed with a **plaintext firmware bootloader image**, the ROM bootloader will fail to load the firmware bootloader resulting in the following failure:
|
||||
|
||||
|
|
@ -554,13 +587,7 @@ Once flash encryption is enabled, the ``FLASH_CRYPT_CNT`` eFuse value will have
|
|||
|
||||
To check if flash encryption on your {IDF_TARGET_NAME} device is enabled, do one of the following:
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
- flash the application example :example:`security/flash_encryption` onto your device. This application prints the ``FLASH_CRYPT_CNT`` eFuse value and if flash encryption is enabled or disabled.
|
||||
|
||||
.. only:: esp32s2
|
||||
|
||||
- flash the application example :example:`security/flash_encryption` onto your device. This application prints the ``EFUSE_SPI_BOOT_CRYPT_CNT`` eFuse value and if flash encryption is enabled or disabled.
|
||||
- flash the application example :example:`security/flash_encryption` onto your device. This application prints the ``{IDF_TARGET_CRYPT_CNT}`` eFuse value and if flash encryption is enabled or disabled.
|
||||
|
||||
- :doc:`Find the serial port name <../get-started/establish-serial-connection>` under which your {IDF_TARGET_NAME} device is connected, replace ``PORT`` with your port name in the following command, and run it:
|
||||
|
||||
|
|
@ -582,7 +609,7 @@ Once flash encryption is enabled, be more careful with accessing flash contents
|
|||
Scope of Flash Encryption
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Whenever the ``FLASH_CRYPT_CNT`` eFuse is set to a value with an odd number of bits, all flash content accessed via the MMU's flash cache is transparently decrypted. It includes:
|
||||
Whenever the ``{IDF_TARGET_CRYPT_CNT}`` eFuse is set to a value with an odd number of bits, all flash content accessed via the MMU's flash cache is transparently decrypted. It includes:
|
||||
|
||||
- Executable application code in flash (IROM).
|
||||
- All read-only data stored in flash (DROM).
|
||||
|
|
@ -650,16 +677,22 @@ Disabling Flash Encryption
|
|||
|
||||
If flash encryption was enabled accidentally, flashing of plaintext data will soft-brick the {IDF_TARGET_NAME}. The device will reboot continuously, printing the error ``flash read err, 1000``.
|
||||
|
||||
For flash encryption in Development mode, encryption can be disabled by burning the ``FLASH_CRYPT_CNT`` eFuse. It can only be done three times per chip by taking the following steps:
|
||||
.. only:: esp32
|
||||
|
||||
For flash encryption in Development mode, encryption can be disabled by burning the ``{IDF_TARGET_CRYPT_CNT}`` eFuse. It can only be done three times per chip by taking the following steps:
|
||||
|
||||
.. only:: esp32s2
|
||||
|
||||
For flash encryption in Development mode, encryption can be disabled by burning the ``{IDF_TARGET_CRYPT_CNT}`` eFuse. It can only be done one time per chip by taking the following steps:
|
||||
|
||||
#. In :ref:`project-configuration-menu`, disable :ref:`Enable flash encryption on boot <CONFIG_SECURE_FLASH_ENC_ENABLED>`, then save and exit.
|
||||
#. Open project configuration menu again and **double-check** that you have disabled this option! If this option is left enabled, the bootloader will immediately re-enable encryption when it boots.
|
||||
#. With flash encryption disabled, build and flash the new bootloader and application by running ``idf.py flash``.
|
||||
#. Use ``espefuse.py`` (in ``components/esptool_py/esptool``) to disable the ``FLASH_CRYPT_CNT`` by running:
|
||||
#. Use ``espefuse.py`` (in ``components/esptool_py/esptool``) to disable the ``{IDF_TARGET_CRYPT_CNT}`` by running:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
espefuse.py burn_efuse FLASH_CRYPT_CNT
|
||||
espefuse.py burn_efuse {IDF_TARGET_CRYPT_CNT}
|
||||
|
||||
Reset the {IDF_TARGET_NAME}. Flash encryption will be disabled, and the bootloader will boot as usual.
|
||||
|
||||
|
|
@ -667,9 +700,13 @@ Reset the {IDF_TARGET_NAME}. Flash encryption will be disabled, and the bootload
|
|||
Key Points About Flash Encryption
|
||||
---------------------------------
|
||||
|
||||
- Flash memory contents are encrypted using AES-256. The flash encryption key is stored in the ``BLOCK1`` eFuse internal to the chip and, by default, is protected from software access.
|
||||
.. list::
|
||||
|
||||
- The flash encryption algorithm is AES-256, where the key is "tweaked" with the offset address of each 32 byte block of flash. This means that every 32-byte block (two consecutive 16 byte AES blocks) is encrypted with a unique key derived from the flash encryption key.
|
||||
:esp32: - Flash memory contents are encrypted using AES-256. The flash encryption key is stored in the ``BLOCK1`` eFuse internal to the chip and, by default, is protected from software access.
|
||||
|
||||
:esp32: - The flash encryption algorithm is AES-256, where the key is "tweaked" with the offset address of each 32 byte block of flash. This means that every 32-byte block (two consecutive 16 byte AES blocks) is encrypted with a unique key derived from the flash encryption key.
|
||||
|
||||
:esp32s2: - Flash memory contents are encrypted using XTS-AES-128 or XTS-AES-256. The flash encryption key is 256 bits and 512 bits respectively and stored one or two ``KEYN`` eFuses internal to the chip and, by default, is protected from software access.
|
||||
|
||||
- Flash access is transparent via the flash cache mapping feature of {IDF_TARGET_NAME} - any flash regions which are mapped to the address space will be transparently decrypted when read.
|
||||
|
||||
|
|
@ -695,19 +732,19 @@ Limitations of Flash Encryption
|
|||
|
||||
Flash encryption protects firmware against unauthorised readout and modification. It is important to understand the limitations of the flash encryption feature:
|
||||
|
||||
.. list::
|
||||
|
||||
- **Flash encryption is only as strong as the key**. It is recommended to generate keys on the device during first boot (default behaviour). If generating keys on a host computer, ensure to follow a proper procedure and do not use the same key for produced devices.
|
||||
|
||||
- **Not all data is stored encrypted**. If storing data in flash memory, make sure that the method you are using (library, API, etc.) supports flash encryption.
|
||||
|
||||
- **Flash encryption does not mask the high-level layout of flash**. This is because the same AES key is used for every pair of adjacent 16-byte AES blocks. If these blocks have identical content (such as empty or padding areas), these will produce matching pairs of encrypted blocks. It might allow an attacker to make high-level comparisons of firmware on encrypted devices, i.e., to tell if two devices are probably running the same firmware version.
|
||||
:esp32: - **Flash encryption does not mask the high-level layout of flash**. This is because the same AES key is used for every pair of adjacent 16-byte AES blocks. If these blocks have identical content (such as empty or padding areas), these will produce matching pairs of encrypted blocks. It might allow an attacker to make high-level comparisons of firmware on encrypted devices, i.e., to tell if two devices are probably running the same firmware version.
|
||||
|
||||
- **Flash encryption does not mask the high-level layout of flash**. Each pair of adjacent 16-byte AES blocks is encrypted with the same AES key. If these blocks have identical content (such as empty or padding areas), the result will be matching pairs of encrypted blocks. It might allow an attacker to make high-level comparisons of firmware on encrypted devices, i.e., to tell if two devices are probably running the same firmware version.
|
||||
:esp32: - **Flash encryption does not mask the high-level layout of flash**. Each pair of adjacent 16-byte AES blocks is encrypted with the same AES key. If these blocks have identical content (such as empty or padding areas), the result will be matching pairs of encrypted blocks. It might allow an attacker to make high-level comparisons of firmware on encrypted devices, i.e., to tell if two devices are probably running the same firmware version.
|
||||
|
||||
- **An attacker can tell if a pair of adjacent 16-byte blocks (32 byte aligned) contains two identical 16-byte sequences** (the same reason as the previous bullet point). Keep this in mind if storing sensitive data in flash memory. While designing your flash storage, it is sufficient to use a counter byte or some other non-identical value every 16 bytes. :ref:`NVS Encryption <nvs_encryption>` deals with this and is suitable for many uses.
|
||||
:esp32: - **An attacker can tell if a pair of adjacent 16-byte blocks (32 byte aligned) contains two identical 16-byte sequences** (the same reason as the previous bullet point). Keep this in mind if storing sensitive data in flash memory. While designing your flash storage, it is sufficient to use a counter byte or some other non-identical value every 16 bytes. :ref:`NVS Encryption <nvs_encryption>` deals with this and is suitable for many uses.
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
- **Flash encryption alone may not prevent an attacker from modifying the firmware on the device**. To prevent unauthorized firmware from running on the device, use flash encryption in combination with :doc:`Secure Boot <secure-boot-v2>`.
|
||||
:esp32: - **Flash encryption alone may not prevent an attacker from modifying the firmware on the device**. To prevent unauthorized firmware from running on the device, use flash encryption in combination with :doc:`Secure Boot <secure-boot-v2>`.
|
||||
|
||||
.. _flash-encryption-and-secure-boot:
|
||||
|
||||
|
|
@ -751,7 +788,7 @@ For details on partition table description, see :doc:`partition table <../api-gu
|
|||
Further information about encryption of partitions:
|
||||
|
||||
- Default partition tables do not include any encrypted data partitions.
|
||||
- With enabled flash encryption, the ``app`` partition is always treated as encrypted and does not require marking.
|
||||
- With flash encryption enabled, the ``app`` partition is always treated as encrypted and does not require marking.
|
||||
- If flash encryption is not enabled, the flag "encrypted" has no effect.
|
||||
- You can also consider protecting ``phy_init`` data from physical access, readout, or modification, by marking the optional ``phy`` partition with the flag ``encrypted``.
|
||||
- The ``nvs`` partition cannot be encrypted, because the NVS library is not directly compatible with flash encryption.
|
||||
|
|
@ -764,12 +801,20 @@ Enabling UART Bootloader Encryption/Decryption
|
|||
|
||||
On the first boot, the flash encryption process burns by default the following eFuses:
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
- ``DISABLE_DL_ENCRYPT`` which disables flash encryption operation when running in UART bootloader boot mode.
|
||||
- ``DISABLE_DL_DECRYPT`` which disables transparent flash decryption when running in UART bootloader mode, even if the eFuse ``FLASH_CRYPT_CNT`` is set to enable it in normal operation.
|
||||
- ``DISABLE_DL_CACHE`` which disables the entire MMU flash cache when running in UART bootloader mode.
|
||||
|
||||
.. only:: esp32s2
|
||||
|
||||
- ``EFUSE_DIS_DOWNLOAD_MANUAL_ENCRYPT`` flash encryption operation when running in UART bootloader boot mode.
|
||||
|
||||
However, before the first boot you can choose to keep any of these features enabled by burning only selected eFuses and write-protect the rest of eFuses with unset value 0. For example:
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
espefuse.py --port PORT burn_efuse DISABLE_DL_DECRYPT
|
||||
|
|
@ -783,6 +828,8 @@ However, before the first boot you can choose to keep any of these features enab
|
|||
|
||||
Write protecting these eFuses to keep them unset is not currently very useful, as ``esptool.py`` does not support reading encrypted flash.
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
.. important::
|
||||
|
||||
Leaving ``DISABLE_DL_DECRYPT`` unset (0) makes flash encryption useless.
|
||||
|
|
@ -790,6 +837,8 @@ Write protecting these eFuses to keep them unset is not currently very useful, a
|
|||
An attacker with physical access to the chip can use UART bootloader mode with custom stub code to read out the flash contents.
|
||||
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
.. _setting-flash-crypt-config:
|
||||
|
||||
Setting FLASH_CRYPT_CONFIG
|
||||
|
|
@ -815,6 +864,8 @@ Technical Details
|
|||
|
||||
The following sections provide some reference information about the operation of flash encryption.
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
.. _flash-encryption-algorithm:
|
||||
|
||||
Flash Encryption Algorithm
|
||||
|
|
@ -847,3 +898,17 @@ Flash Encryption Algorithm
|
|||
- There is a particular mapping from each of the 19 block offset bits to the 256 bits of the flash encryption key to determine which bit is XORed with which. See the variable ``_FLASH_ENCRYPTION_TWEAK_PATTERN`` in the ``espsecure.py`` source code for complete mapping.
|
||||
|
||||
- To see the full flash encryption algorithm implemented in Python, refer to the `_flash_encryption_operation()` function in the ``espsecure.py`` source code.
|
||||
|
||||
.. only:: esp32s2
|
||||
|
||||
.. _flash-encryption-algorithm:
|
||||
|
||||
Flash Encryption Algorithm
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
- {IDF_TARGET_NAME} use the XTS-AES block chiper mode with 256 bit or 512 bit key size for flash encryption.
|
||||
|
||||
- XTS-AES is a block chiper mode specifically designed for disc encryption and addresses the weaknesses other potential modes (e.g. AES-CTR) have for this use case. A detailed description of the XTS-AES algorithm can be found in `IEEE Std 1619-2007 <https://ieeexplore.ieee.org/document/4493450>`_.
|
||||
|
||||
- The flash encryption key is stored in one or two ``KEYN`` eFuses and, by default, is protected from further writes or software readout.
|
||||
|
||||
- To see the full flash encryption algorithm implemented in Python, refer to the `_flash_encryption_operation()` function in the ``espsecure.py`` source code.
|
||||
Loading…
Reference in a new issue