From 0449ba7f9148532203a8aad3d7b042fad008ab8c 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 | 4 ++-- 4 files changed, 34 insertions(+), 3 deletions(-) diff --git a/components/bootloader_support/include/esp_flash_encrypt.h b/components/bootloader_support/include/esp_flash_encrypt.h index 31b77a734..45fce4465 100644 --- a/components/bootloader_support/include/esp_flash_encrypt.h +++ b/components/bootloader_support/include/esp_flash_encrypt.h @@ -101,4 +101,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 4c6d7e356..00f60286a 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 777ae5188..c9c83aac6 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.** @@ -272,6 +272,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/en/security/secure-boot.rst b/docs/en/security/secure-boot.rst index fa349ddcb..2ac5ca1bc 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:: @@ -244,6 +244,7 @@ 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 @@ -279,4 +280,3 @@ How To Enable Signed App Verification 4. If you disable "Sign binaries during build" option then you'll have to enter path of a public key file used to verify signed images in "Secure boot public signature verification key". In this case, private signing key should be generated by following instructions in :ref:`secure-boot-generate-key`; public verification key and signed image should be generated by following instructions in :ref:`remote-sign-image`. -