From e97ae26f48b2e43a92e104a2bbadacfa4b13e6c2 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Fri, 12 Mar 2021 11:41:07 +1100 Subject: [PATCH] doc: Mention pre-encrypting on the host is possible in Release mode Closes https://github.com/espressif/esp-idf/issues/5945 --- components/bootloader/Kconfig.projbuild | 14 ++++++++------ docs/en/security/flash-encryption.rst | 21 ++++++++++++++------- 2 files changed, 22 insertions(+), 13 deletions(-) diff --git a/components/bootloader/Kconfig.projbuild b/components/bootloader/Kconfig.projbuild index 371fce7762..2bb0a1be02 100644 --- a/components/bootloader/Kconfig.projbuild +++ b/components/bootloader/Kconfig.projbuild @@ -656,16 +656,18 @@ menu "Security features" depends on SECURE_FLASH_ENC_ENABLED default SECURE_FLASH_ENCRYPTION_MODE_DEVELOPMENT help - By default Development mode is enabled which allows UART bootloader to perform flash encryption operations + By default Development mode is enabled which allows ROM download mode to perform flash encryption + operations (plaintext is sent to the device, and it encrypts it internally and writes ciphertext + to flash.) This mode is not secure, it's possible for an attacker to write their own chosen plaintext + to flash. - Select Release mode only for production or manufacturing. Once enabled you can not reflash using UART - bootloader + Release mode should always be selected for production or manufacturing. Once enabled it's no longer + possible for the device in ROM Download Mode to use the flash encryption hardware. - Refer to the Secure Boot section of the ESP-IDF Programmer's Guide for this version and - https://docs.espressif.com/projects/esp-idf/en/latest/security/flash-encryption.html for details. + Refer to the Flash Encryption section of the ESP-IDF Programmer's Guide for details. config SECURE_FLASH_ENCRYPTION_MODE_DEVELOPMENT - bool "Development(NOT SECURE)" + bool "Development (NOT SECURE)" select SECURE_FLASH_UART_BOOTLOADER_ALLOW_ENC config SECURE_FLASH_ENCRYPTION_MODE_RELEASE diff --git a/docs/en/security/flash-encryption.rst b/docs/en/security/flash-encryption.rst index 924f81fad5..8978ad0c0a 100644 --- a/docs/en/security/flash-encryption.rst +++ b/docs/en/security/flash-encryption.rst @@ -1,6 +1,12 @@ Flash Encryption ================ +{IDF_TARGET_CRYPT_CNT:default="SPI_BOOT_CRYPT_CNT",esp32="FLASH_CRYPT_CNT"} + +{IDF_TARGET_ESP32_V3_ONLY:default="", esp32="(ESP32 V3 only)"} + +{IDF_TARGET_ENCRYPT_COMMAND:default="espsecure.py encrypt_flash_data --aes_xts", esp32="espsecure.py encrypt_flash_data"} + :link_to_translation:`zh_CN:[中文]` This is a quick start guide to {IDF_TARGET_NAME}'s flash encryption feature. Using an application code example, it demonstrates how to test and verify flash encryption operations during development and production. @@ -34,8 +40,6 @@ Other types of data can be encrypted conditionally: 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. -{IDF_TARGET_CRYPT_CNT:default="SPI_BOOT_CRYPT_CNT",esp32="FLASH_CRYPT_CNT"} - .. _flash-encryption-efuse: Relevant eFuses @@ -225,7 +229,7 @@ Flash Encryption Configuration The following flash encryption modes are available: -- :ref:`flash-enc-development-mode` - recommended for use ONLY DURING DEVELOPMENT, as it does not prevent modification and possible readout of encrypted flash contents. +- :ref:`flash-enc-development-mode` - recommended for use ONLY DURING DEVELOPMENT, as it does not prevent modification and readout of encrypted flash contents. - :ref:`flash-enc-release-mode` - recommended for manufacturing and production to prevent physical readout of encrypted flash contents. @@ -439,10 +443,10 @@ To use this mode, take the following steps: .. list:: - :ref:`Enable flash encryption on boot ` - :esp32: - :ref:`Select Release mode ` (Note that once Release mode is selected, the ``DISABLE_DL_ENCRYPT`` and ``DISABLE_DL_DECRYPT`` eFuse bits will be burned to disable UART bootloader access to flash contents) - :esp32: - :ref:`Select UART ROM download mode ` (Note that this option is only available when :ref:`CONFIG_ESP32_REV_MIN` is set to 3 (ESP32 V3). The default choice is to keep it enabled (insecure). This has been done in order to prevent permanently disabling of the UART download mode by default.) - :not esp32: - :ref:`Select Release 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) - :not esp32: - :ref:`Select UART ROM download mode ` (By default the option to permanently switch to UART ROM Secure download mode is selected) + :esp32: - :ref:`Select Release mode ` (Note that once Release mode is selected, the ``DISABLE_DL_ENCRYPT`` and ``DISABLE_DL_DECRYPT`` eFuse bits will be burned to disable flash encryption hardware in ROM Download Mode.) + :esp32: - :ref:`Select UART ROM download mode (Permanently disabled (recommended)) ` (Note that this option is only available when :ref:`CONFIG_ESP32_REV_MIN` is set to 3 (ESP32 V3).) The default choice is to keep UART ROM download mode enabled, however it's recommended to permanently disable this mode to reduce the options available to an attacker. + :not esp32: - :ref:`Select Release mode ` (Note that once Release mode is selected, the ``EFUSE_DIS_DOWNLOAD_MANUAL_ENCRYPT`` eFuse bit will be burned to disable flash encryption hardware in ROM Download Mode.) + :not esp32: - :ref:`Select UART ROM download mode (Permanently switch to Secure mode (recommended)) `. This is the default option, and is recommended. It is also possible to change this configuration setting to permanently disable UART ROM download mode, if this mode is not needed. - :ref:`Select the appropriate bootloader log verbosity ` - Save the configuration and exit. @@ -465,6 +469,9 @@ Once the flash encryption is enabled in Release mode, the bootloader will write- For subsequent plaintext field updates, use :ref:`OTA scheme `. +.. note:: + + If you have pre-generated the flash encryption key and stored a copy, and the UART download mode is not permanently disabled via :ref:`CONFIG_SECURE_UART_ROM_DL_MODE` {IDF_TARGET_ESP32_V3_ONLY}, then it is possible to update the flash locally by pre-encrypting the files using ``{IDF_TARGET_ENCRYPT_COMMAND}`` and then flashing the ciphertext. . _flash-encrypt-best-practices: