From b27773e87c0038c848bf89162f446f37b40d9d4f 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/en/security/flash-encryption.rst | 13 ++++++++++++- docs/en/security/secure-boot.rst | 9 ++++++++- 4 files changed, 40 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 a9e8f8f9b..0d3dfa0fc 100644 --- a/components/bootloader_support/src/flash_encrypt.c +++ b/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(); + } +} diff --git a/docs/en/security/flash-encryption.rst b/docs/en/security/flash-encryption.rst index acc4b6b16..051fd469f 100644 --- a/docs/en/security/flash-encryption.rst +++ b/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 ` 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. @@ -288,6 +288,17 @@ It is recommended to use flash encryption and secure boot together. However, if - :ref:`Plaintext serial flash updates ` are only possible if the :envvar:`Reflashable ` Secure Boot mode is selected and a Secure Boot key was pre-generated and burned to the ESP32 (refer to :ref:`Secure Boot ` 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 ` 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 diff --git a/docs/en/security/secure-boot.rst b/docs/en/security/secure-boot.rst index dbf0e5267..d03a614d5 100644 --- a/docs/en/security/secure-boot.rst +++ b/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 ` 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:: @@ -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 `, 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.