From 6a498bfe2bf7a5ac28f0222adc9e598769ded05b Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Fri, 13 Jul 2018 16:19:23 +1000 Subject: [PATCH] docs: Add note about bootloader size for flash encryption & secure boot --- docs/en/security/flash-encryption.rst | 2 ++ docs/en/security/secure-boot.rst | 14 ++++++++++++++ 2 files changed, 16 insertions(+) diff --git a/docs/en/security/flash-encryption.rst b/docs/en/security/flash-encryption.rst index e925ee618..c36839ef4 100644 --- a/docs/en/security/flash-encryption.rst +++ b/docs/en/security/flash-encryption.rst @@ -55,6 +55,8 @@ Process to enable flash encryption: - Build and flash the bootloader, partition table and factory app image as normal. These partitions are initially written to the flash unencrypted. +.. note:: The bootloader app binary ``bootloader.bin`` may become too large when both secure boot and flash encryption are enabled. See :ref:`secure-boot-bootloader-size`. + - On first boot, the bootloader sees :ref:`FLASH_CRYPT_CNT` is set to 0 (factory default) so it generates a flash encryption key using the hardware random number generator. This key is stored in efuse. The key is read and write protected against further software access. - All of the encrypted partitions are then encrypted in-place by the bootloader. Encrypting in-place can take some time (up to a minute for large partitions.) diff --git a/docs/en/security/secure-boot.rst b/docs/en/security/secure-boot.rst index da9a203d3..7910fa365 100644 --- a/docs/en/security/secure-boot.rst +++ b/docs/en/security/secure-boot.rst @@ -55,6 +55,20 @@ The following keys are used by the secure boot process: - The private key from this key pair *must be securely kept private*, as anyone who has this key can authenticate to any bootloader that is configured with secure boot and the matching public key. +.. _secure-boot-bootloader-size: + +Bootloader Size +--------------- + +When secure boot is enabled the bootloader app binary ``bootloader.bin`` may exceed the default bootloader size limit. This is especially likely if flash encryption is enabled as well. The default size limit is 0x7000 (28672) bytes (partition table offset 0x8000 - bootloader offset 0x1000). + +If the bootloader becomes too large, the ESP32 will fail to boot - errors will be logged about either invalid partition table or invalid bootloader checksum. + +Options to work around this are: + +- Reduce :envvar:`bootloader log level `. Setting log level to Warning, Error or None all significantly reduce the final binary size (but may make it harder to debug). +- Set :envvar:`partition table offset ` to a higher value than 0x8000, to place the partition table later in the flash. This increases the space available for the bootloader. If the :doc:`partition table ` CSV file contains explicit partition offsets, they will need changing so no partition has an offset lower than ``CONFIG_PARTITION_TABLE_OFFSET + 0x1000``. (This includes the default partition CSV files supplied with ESP-IDF.) + .. _secure-boot-howto: How To Enable Secure Boot