From b45b0f23481ee83a570323f968583c6bf90529bb Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Tue, 4 Dec 2018 12:34:38 +1100 Subject: [PATCH 1/3] doc: security: Use less ambiguous language about using bot flash encryption & secure boot together --- docs/en/security/flash-encryption.rst | 2 +- docs/en/security/secure-boot.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/en/security/flash-encryption.rst b/docs/en/security/flash-encryption.rst index e9a87913eb..f65fb6f4ff 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. 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. +Flash Encryption is separate from the :doc:`Secure Boot ` feature, and you can use flash encryption without enabling secure boot. However, for a secure environment both should be used simultaneously. 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. diff --git a/docs/en/security/secure-boot.rst b/docs/en/security/secure-boot.rst index bacff37e1f..bec0dbdbf1 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. See :ref:`secure-boot-and-flash-encr` for more details. +Secure Boot is separate from the :doc:`Flash Encryption ` feature, and you can use secure boot without encrypting the flash contents. However, for a secure environment both should be used simultaneously. See :ref:`secure-boot-and-flash-encr` for more details. .. important:: From ac1d1aa3c8c57f29872ea05a8d5806da19979f7e Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Tue, 4 Dec 2018 12:34:59 +1100 Subject: [PATCH 2/3] doc: secure boot: Explain output of digest_secure_bootloader command Mentioned on forum https://esp32.com/viewtopic.php?f=13&t=8162&start=10#p34714 --- docs/en/security/secure-boot.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/en/security/secure-boot.rst b/docs/en/security/secure-boot.rst index bec0dbdbf1..79baa87255 100644 --- a/docs/en/security/secure-boot.rst +++ b/docs/en/security/secure-boot.rst @@ -258,7 +258,9 @@ To generate a bootloader digest:: espsecure.py digest_secure_bootloader --keyfile ./securebootkey.bin --output ./bootloader-digest.bin build/bootloader/bootloader.bin -Keyfile is the 32 byte raw secure boot key for the device. To flash this digest onto the device:: +Keyfile is the 32 byte raw secure boot key for the device. + +The output of the ``espsecure.py digest_secure_bootloader`` command is a single file which contains both the digest and the bootloader appended to it. To flash the combined digest plus bootloader to the device:: esptool.py write_flash 0x0 bootloader-digest.bin From a2d0fbb9abebe7670200b523cb8bc170c990db7d Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Tue, 4 Dec 2018 12:38:28 +1100 Subject: [PATCH 3/3] docs: flash encryption: Fix description of behaviour when all bits of FLASH_CRYPT_CNT are set Correct behaviour is described in section 25.3.3 Flash Decryption Block of the ESP32 TRM --- docs/en/security/flash-encryption.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/security/flash-encryption.rst b/docs/en/security/flash-encryption.rst index f65fb6f4ff..82e6fb379c 100644 --- a/docs/en/security/flash-encryption.rst +++ b/docs/en/security/flash-encryption.rst @@ -146,7 +146,7 @@ Limited Updates Only 4 plaintext serial update cycles of this kind are possible, including the initial encrypted flash. -After the fourth time encryption is disabled, :ref:`FLASH_CRYPT_CNT` has the maximum value `0xFF` and encryption is permanently disabled. +After the fourth time encryption is enabled, :ref:`FLASH_CRYPT_CNT` has the maximum value ``0x7F`` (7 bits set) and encryption is permanently enabled. Flashing :ref:`FLASH_CRYPT_CNT` to ``0xFF`` (8 bits set) does not re-disable encryption, the eighth bit is ignored. Using :ref:`updating-encrypted-flash-ota` or :ref:`pregenerated-flash-encryption-key` allows you to exceed this limit.