Merge branch 'doc/flash_encryption_development' into 'master'

doc: Mention Flash Encryption on the host is possible in Release mode

Closes IDFGH-4074

See merge request espressif/esp-idf!12721

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

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 <CONFIG_SECURE_FLASH_ENC_ENABLED>`
-    :esp32: - :ref:`Select Release mode <CONFIG_SECURE_FLASH_ENCRYPTION_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 <CONFIG_SECURE_UART_ROM_DL_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 <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)
-    :not esp32: - :ref:`Select UART ROM download mode <CONFIG_SECURE_UART_ROM_DL_MODE>` (By default the option to permanently switch to UART ROM Secure download mode is selected)
+    :esp32: - :ref:`Select Release mode <CONFIG_SECURE_FLASH_ENCRYPTION_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)) <CONFIG_SECURE_UART_ROM_DL_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 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 <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 flash encryption hardware in ROM Download Mode.)
+    :not esp32: - :ref:`Select UART ROM download mode (Permanently switch to Secure mode (recommended)) <CONFIG_SECURE_UART_ROM_DL_MODE>`. 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 <CONFIG_BOOTLOADER_LOG_LEVEL>`
     - 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 <updating-encrypted-flash-ota>`.
 
+.. 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: