Merge branch 'docs/security' into 'master'

docs: Added more wordings to capture secure boot and flash encryption dependency.

See merge request idf/esp-idf!2947

components/bootloader_support/include/esp_flash_encrypt.h

@@ -99,4 +99,14 @@ esp_err_t esp_flash_encrypt_check_and_update(void);
  */
 esp_err_t esp_flash_encrypt_region(uint32_t src_addr, size_t data_length);
 
+/** @brief Write protect FLASH_CRYPT_CNT
+ *
+ * Intended to be called as a part of boot process if flash encryption
+ * is enabled but secure boot is not used. This should protect against
+ * serial re-flashing of an unauthorised code in absence of secure boot.
+ *
+ * @return 
+ */
+void esp_flash_write_protect_crypt_cnt();
+
 #endif

components/bootloader_support/src/flash_encrypt.c

@@ -337,3 +337,13 @@ esp_err_t esp_flash_encrypt_region(uint32_t src_addr, size_t data_length)
     ESP_LOGE(TAG, "flash operation failed: 0x%x", err);
     return err;
 }
+
+void esp_flash_write_protect_crypt_cnt() 
+{
+    uint32_t efuse_blk0 = REG_READ(EFUSE_BLK0_RDATA0_REG);
+    bool flash_crypt_wr_dis = efuse_blk0 & EFUSE_WR_DIS_FLASH_CRYPT_CNT;
+    if(!flash_crypt_wr_dis) { 
+        REG_WRITE(EFUSE_BLK0_WDATA0_REG, EFUSE_WR_DIS_FLASH_CRYPT_CNT);
+        esp_efuse_burn_new_values();
+    }
+}

docs/en/security/flash-encryption.rst

@@ -3,7 +3,7 @@ Flash Encryption
 
 Flash Encryption is a feature for encrypting the contents of the ESP32's attached SPI flash. When flash encryption is enabled, physical readout of the SPI flash is not sufficient to recover most flash contents.
 
-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.
+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. In absence of secure boot, additional configuration needs to be performed to ensure effectiveness of flash encryption. See :ref:`flash-encryption-without-secure-boot` for more details.
 
 .. 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.
@@ -288,6 +288,17 @@ It is recommended to use flash encryption and secure boot together. However, if
 - :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-without-secure-boot:
+
+Using Flash Encryption without Secure Boot
+------------------------------------------
+
+If flash encryption is used without secure boot, it is possible to load unauthorised code using serial re-flashing. See :ref:`updating-encrypted-flash-serial` for details. This unauthorised code can then read all encrypted partitions (in decrypted form) making flash-encryption ineffective. This can be avoided by write-protecting :ref:`FLASH_CRYPT_CNT` and thereby disallowing serial re-flashing. :ref:`FLASH_CRYPT_CNT` can be write-protected using command::
+
+  espefuse.py --port PORT write_protect_efuse FLASH_CRYPT_CNT
+
+Alternatively, the app can call :func:`esp_flash_write_protect_crypt_cnt` during its startup process.
+
 .. _flash-encryption-advanced-features:
 
 Flash Encryption Advanced Features

docs/en/security/secure-boot.rst

@@ -3,7 +3,7 @@ Secure Boot
 
 Secure Boot is a feature for ensuring only your code can run on the chip. Data loaded from flash is verified on each reset.
 
-Secure Boot is separate from the :doc:`Flash Encryption <flash-encryption>` feature, and you can use secure boot without encrypting the flash contents. However we recommend using both features together for a secure environment.
+Secure Boot is separate from the :doc:`Flash Encryption <flash-encryption>` feature, and you can use secure boot without encrypting the flash contents. However we recommend using both features together for a secure environment. See :ref:`secure-boot-and-flash-encr` for more details.
 
 .. important::
 
@@ -253,3 +253,10 @@ Keyfile is the 32 byte raw secure boot key for the device. To flash this digest
 
   esptool.py write_flash 0x0 bootloader-digest.bin
 
+
+.. _secure-boot-and-flash-encr:
+
+Secure Boot & Flash Encryption
+------------------------------
+
+If secure boot is used without :doc:`Flash Encryption <flash-encryption>`, it is possible to launch "time-of-check to time-of-use" attack, where flash contents are swapped after the image is verified and running. Therefore, it is recommended to use both the features together.