1 menu "Bootloader config"
2 choice LOG_BOOTLOADER_LEVEL
3 bool "Bootloader log verbosity"
4 default LOG_BOOTLOADER_LEVEL_INFO
6 Specify how much output to see in bootloader logs.
8 config LOG_BOOTLOADER_LEVEL_NONE
10 config LOG_BOOTLOADER_LEVEL_ERROR
12 config LOG_BOOTLOADER_LEVEL_WARN
14 config LOG_BOOTLOADER_LEVEL_INFO
16 config LOG_BOOTLOADER_LEVEL_DEBUG
18 config LOG_BOOTLOADER_LEVEL_VERBOSE
22 config LOG_BOOTLOADER_LEVEL
24 default 0 if LOG_BOOTLOADER_LEVEL_NONE
25 default 1 if LOG_BOOTLOADER_LEVEL_ERROR
26 default 2 if LOG_BOOTLOADER_LEVEL_WARN
27 default 3 if LOG_BOOTLOADER_LEVEL_INFO
28 default 4 if LOG_BOOTLOADER_LEVEL_DEBUG
29 default 5 if LOG_BOOTLOADER_LEVEL_VERBOSE
31 config BOOTLOADER_SPI_WP_PIN
32 int "SPI Flash WP Pin when customising pins via efuse (read help)"
35 depends on FLASHMODE_QIO || FLASHMODE_QOUT
37 This value is ignored unless flash mode is set to QIO or QOUT *and* the SPI flash pins have been
38 overriden by setting the efuses SPI_PAD_CONFIG_xxx.
40 When this is the case, the Efuse config only defines 3 of the 4 Quad I/O data pins. The WP pin (aka ESP32
41 pin "SD_DATA_3" or SPI flash pin "IO2") is not specified in Efuse. That pin number is compiled into the bootloader
44 The default value (GPIO 7) is correct for WP pin on ESP32-D2WD integrated flash.
46 choice BOOTLOADER_VDDSDIO_BOOST
47 bool "VDDSDIO LDO voltage"
48 default BOOTLOADER_VDDSDIO_BOOST_1_9V
50 If this option is enabled, and VDDSDIO LDO is set to 1.8V (using EFUSE
51 or MTDI bootstrapping pin), bootloader will change LDO settings to
52 output 1.9V instead. This helps prevent flash chip from browning out
53 during flash programming operations.
55 This option has no effect if VDDSDIO is set to 3.3V, or if the internal
56 VDDSDIO regulator is disabled via efuse.
58 config BOOTLOADER_VDDSDIO_BOOST_1_8V
60 depends on !ESPTOOLPY_FLASHFREQ_80M
61 config BOOTLOADER_VDDSDIO_BOOST_1_9V
68 menu "Security features"
70 config SECURE_BOOT_ENABLED
71 bool "Enable secure boot in bootloader (READ DOCS FIRST)"
74 Build a bootloader which enables secure boot on first boot.
76 Once enabled, secure boot will not boot a modified bootloader. The bootloader will only load a partition table or boot an app if the data has a verified digital signature. There are implications for reflashing updated apps once secure boot is enabled.
78 When enabling secure boot, JTAG and ROM BASIC Interpreter are permanently disabled by default.
80 Refer to https://esp-idf.readthedocs.io/en/latest/security/secure-boot.html before enabling.
82 choice SECURE_BOOTLOADER_MODE
83 bool "Secure bootloader mode"
84 depends on SECURE_BOOT_ENABLED
85 default SECURE_BOOTLOADER_ONE_TIME_FLASH
87 config SECURE_BOOTLOADER_ONE_TIME_FLASH
90 On first boot, the bootloader will generate a key which is not readable externally or by software. A digest is generated from the bootloader image itself. This digest will be verified on each subsequent boot.
92 Enabling this option means that the bootloader cannot be changed after the first time it is booted.
94 config SECURE_BOOTLOADER_REFLASHABLE
97 Generate a reusable secure bootloader key, derived (via SHA-256) from the secure boot signing key.
99 This allows the secure bootloader to be re-flashed by anyone with access to the secure boot signing key.
101 This option is less secure than one-time flash, because a leak of the digest key from one device allows reflashing of any device that uses it.
105 config SECURE_BOOT_BUILD_SIGNED_BINARIES
106 bool "Sign binaries during build"
107 depends on SECURE_BOOT_ENABLED
110 Once secure boot is enabled, bootloader will only boot if partition table and app image are signed.
112 If enabled, these binary files are signed as part of the build process. The file named in "Secure boot private signing key" will be used to sign the image.
114 If disabled, unsigned app/partition data will be built. They must be signed manually using espsecure.py (for example, on a remote signing server.)
116 config SECURE_BOOT_SIGNING_KEY
117 string "Secure boot private signing key"
118 depends on SECURE_BOOT_BUILD_SIGNED_BINARIES
119 default secure_boot_signing_key.pem
121 Path to the key file used to sign partition tables and app images for secure boot. Once secure boot is enabled, bootloader will only boot if partition table and app image are signed.
123 Key file is an ECDSA private key (NIST256p curve) in PEM format.
125 Path is evaluated relative to the project directory.
127 You can generate a new signing key by running the following command:
128 espsecure.py generate_signing_key secure_boot_signing_key.pem
130 See docs/security/secure-boot.rst for details.
132 config SECURE_BOOT_VERIFICATION_KEY
133 string "Secure boot public signature verification key"
134 depends on SECURE_BOOT_ENABLED && !SECURE_BOOT_BUILD_SIGNED_BINARIES
135 default signature_verification_key.bin
137 Path to a public key file used to verify signed images. This key is compiled into the bootloader,
138 and may also be used to verify signatures on OTA images after download.
140 Key file is in raw binary format, and can be extracted from a
141 PEM formatted private key using the espsecure.py
142 extract_public_key command.
144 Refer to https://esp-idf.readthedocs.io/en/latest/security/secure-boot.html before enabling.
146 config SECURE_BOOT_INSECURE
147 bool "Allow potentially insecure options"
148 depends on SECURE_BOOT_ENABLED
151 You can disable some of the default protections offered by secure boot, in order to enable testing or a custom combination of security features.
153 Only enable these options if you are very sure.
155 Refer to https://esp-idf.readthedocs.io/en/latest/security/secure-boot.html before enabling.
157 config FLASH_ENCRYPTION_ENABLED
158 bool "Enable flash encryption on boot (READ DOCS FIRST)"
161 If this option is set, flash contents will be encrypted by the bootloader on first boot.
163 Note: After first boot, the system will be permanently encrypted. Re-flashing an encrypted
164 system is complicated and not always possible.
166 Read https://esp-idf.readthedocs.io/en/latest/security/flash-encryption.html before enabling.
168 config FLASH_ENCRYPTION_INSECURE
169 bool "Allow potentially insecure options"
170 depends on FLASH_ENCRYPTION_ENABLED
173 You can disable some of the default protections offered by flash encryption, in order to enable testing or a custom combination of security features.
175 Only enable these options if you are very sure.
177 Refer to docs/security/secure-boot.rst and docs/security/flash-encryption.rst for details.
179 menu "Potentially insecure options"
180 visible if FLASH_ENCRYPTION_INSECURE || SECURE_BOOT_INSECURE
182 # NOTE: Options in this menu NEED to have SECURE_BOOT_INSECURE
183 # and/or FLASH_ENCRYPTION_INSECURE in "depends on", as the menu
184 # itself doesn't enable/disable its children (if it's not set,
185 # it's possible for the insecure menu to be disabled but the insecure option
186 # to remain on which is very bad.)
188 config SECURE_BOOT_ALLOW_ROM_BASIC
189 bool "Leave ROM BASIC Interpreter available on reset"
190 depends on SECURE_BOOT_INSECURE || FLASH_ENCRYPTION_INSECURE
193 By default, the BASIC ROM Console starts on reset if no valid bootloader is
196 When either flash encryption or secure boot are enabled, the default is to
197 disable this BASIC fallback mode permanently via efuse.
199 If this option is set, this efuse is not burned and the BASIC ROM Console may
200 remain accessible. Only set this option in testing environments.
202 config SECURE_BOOT_ALLOW_JTAG
203 bool "Allow JTAG Debugging"
204 depends on SECURE_BOOT_INSECURE || FLASH_ENCRYPTION_INSECURE
207 If not set (default), the bootloader will permanently disable JTAG (across entire chip) on first boot when either secure boot or flash encryption is enabled.
209 Setting this option leaves JTAG on for debugging, which negates all protections of flash encryption and some of the protections of secure boot.
211 Only set this option in testing environments.
214 config FLASH_ENCRYPTION_UART_BOOTLOADER_ALLOW_ENCRYPT
215 bool "Leave UART bootloader encryption enabled"
216 depends on FLASH_ENCRYPTION_INSECURE
219 If not set (default), the bootloader will permanently disable UART bootloader encryption access on first boot. If set, the UART bootloader will still be able to access hardware encryption.
221 It is recommended to only set this option in testing environments.
223 config FLASH_ENCRYPTION_UART_BOOTLOADER_ALLOW_DECRYPT
224 bool "Leave UART bootloader decryption enabled"
225 depends on FLASH_ENCRYPTION_INSECURE
228 If not set (default), the bootloader will permanently disable UART bootloader decryption access on first boot. If set, the UART bootloader will still be able to access hardware decryption.
230 Only set this option in testing environments. Setting this option allows complete bypass of flash encryption.
232 config FLASH_ENCRYPTION_UART_BOOTLOADER_ALLOW_CACHE
233 bool "Leave UART bootloader flash cache enabled"
234 depends on FLASH_ENCRYPTION_INSECURE
237 If not set (default), the bootloader will permanently disable UART bootloader flash cache access on first boot. If set, the UART bootloader will still be able to access the flash cache.
239 Only set this option in testing environments.
241 config SECURE_BOOT_TEST_MODE
242 bool "Secure boot test mode: don't permanently set any efuses"
243 depends on SECURE_BOOT_INSECURE
246 If this option is set, all permanent secure boot changes (via Efuse) are disabled.
248 Log output will state changes which would be applied, but they will not be.
250 This option is for testing purposes only - it completely disables secure boot protection.
253 endmenu # Potentially Insecure
254 endmenu # Security features