From cdabee59ef6e333f719d768fe1fddae6c208e00c Mon Sep 17 00:00:00 2001 From: Sagar Bijwe Date: Tue, 7 Aug 2018 17:29:11 +0530 Subject: [PATCH] docs: Added more wordings to capture secure boot and flash encryption dependency. --- .../bootloader_support/include/esp_flash_encrypt.h | 10 ++++++++++ components/bootloader_support/src/flash_encrypt.c | 10 ++++++++++ docs/security/flash-encryption.rst | 13 ++++++++++++- docs/security/secure-boot.rst | 8 +++++++- 4 files changed, 39 insertions(+), 2 deletions(-) diff --git a/components/bootloader_support/include/esp_flash_encrypt.h b/components/bootloader_support/include/esp_flash_encrypt.h index ba370644a..2f4679b2a 100644 --- a/components/bootloader_support/include/esp_flash_encrypt.h +++ b/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 diff --git a/components/bootloader_support/src/flash_encrypt.c b/components/bootloader_support/src/flash_encrypt.c index 7a4cfcb83..40ec7b859 100644 --- a/components/bootloader_support/src/flash_encrypt.c +++ b/components/bootloader_support/src/flash_encrypt.c @@ -342,3 +342,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(); + } +} diff --git a/docs/security/flash-encryption.rst b/docs/security/flash-encryption.rst index 433578a46..8471ce29d 100644 --- a/docs/security/flash-encryption.rst +++ b/docs/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 ` 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 ` 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.** @@ -270,6 +270,17 @@ Flash Encryption prevents plaintext readout of the encrypted flash, to protect f - Flash encryption alone may not prevent an attacker from modifying the firmware of the device. To prevent unauthorised firmware from runningon the device, use flash encryption in combination with :doc:`Secure Boot `. +.. _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 diff --git a/docs/security/secure-boot.rst b/docs/security/secure-boot.rst index dcd6d4b60..0030cabbc 100644 --- a/docs/security/secure-boot.rst +++ b/docs/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 ` 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 ` 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:: @@ -235,3 +235,9 @@ 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 `, 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.