1menu "Bootloader config" 2 3 config BOOTLOADER_OFFSET_IN_FLASH 4 hex 5 default 0x1000 if IDF_TARGET_ESP32 || IDF_TARGET_ESP32S2 6 default 0x0 7 help 8 Offset address that 2nd bootloader will be flashed to. 9 The value is determined by the ROM bootloader. 10 It's not configurable in ESP-IDF. 11 12 choice BOOTLOADER_COMPILER_OPTIMIZATION 13 prompt "Bootloader optimization Level" 14 default BOOTLOADER_COMPILER_OPTIMIZATION_SIZE 15 help 16 This option sets compiler optimization level (gcc -O argument) 17 for the bootloader. 18 19 - The default "Size" setting will add the -0s flag to CFLAGS. 20 - The "Debug" setting will add the -Og flag to CFLAGS. 21 - The "Performance" setting will add the -O2 flag to CFLAGS. 22 - The "None" setting will add the -O0 flag to CFLAGS. 23 24 Note that custom optimization levels may be unsupported. 25 26 config BOOTLOADER_COMPILER_OPTIMIZATION_SIZE 27 bool "Size (-Os)" 28 config BOOTLOADER_COMPILER_OPTIMIZATION_DEBUG 29 bool "Debug (-Og)" 30 config BOOTLOADER_COMPILER_OPTIMIZATION_PERF 31 bool "Optimize for performance (-O2)" 32 config BOOTLOADER_COMPILER_OPTIMIZATION_NONE 33 bool "Debug without optimization (-O0)" 34 endchoice 35 36 choice BOOTLOADER_LOG_LEVEL 37 bool "Bootloader log verbosity" 38 default BOOTLOADER_LOG_LEVEL_INFO 39 help 40 Specify how much output to see in bootloader logs. 41 42 config BOOTLOADER_LOG_LEVEL_NONE 43 bool "No output" 44 config BOOTLOADER_LOG_LEVEL_ERROR 45 bool "Error" 46 config BOOTLOADER_LOG_LEVEL_WARN 47 bool "Warning" 48 config BOOTLOADER_LOG_LEVEL_INFO 49 bool "Info" 50 config BOOTLOADER_LOG_LEVEL_DEBUG 51 bool "Debug" 52 config BOOTLOADER_LOG_LEVEL_VERBOSE 53 bool "Verbose" 54 endchoice 55 56 config BOOTLOADER_LOG_LEVEL 57 int 58 default 0 if BOOTLOADER_LOG_LEVEL_NONE 59 default 1 if BOOTLOADER_LOG_LEVEL_ERROR 60 default 2 if BOOTLOADER_LOG_LEVEL_WARN 61 default 3 if BOOTLOADER_LOG_LEVEL_INFO 62 default 4 if BOOTLOADER_LOG_LEVEL_DEBUG 63 default 5 if BOOTLOADER_LOG_LEVEL_VERBOSE 64 65 config BOOTLOADER_SPI_CUSTOM_WP_PIN 66 bool "Use custom SPI Flash WP Pin when flash pins set in eFuse (read help)" 67 depends on IDF_TARGET_ESP32 && (ESPTOOLPY_FLASHMODE_QIO || ESPTOOLPY_FLASHMODE_QOUT) 68 default y if BOOTLOADER_SPI_WP_PIN != 7 # backwards compatibility, can remove in IDF 5 69 default n 70 help 71 This setting is only used if the SPI flash pins have been overridden by setting the eFuses 72 SPI_PAD_CONFIG_xxx, and the SPI flash mode is QIO or QOUT. 73 74 When this is the case, the eFuse config only defines 3 of the 4 Quad I/O data pins. The WP pin (aka 75 ESP32 pin "SD_DATA_3" or SPI flash pin "IO2") is not specified in eFuse. The same pin is also used 76 for external SPIRAM if it is enabled. 77 78 If this config item is set to N (default), the correct WP pin will be automatically used for any 79 Espressif chip or module with integrated flash. If a custom setting is needed, set this config item to 80 Y and specify the GPIO number connected to the WP. 81 82 config BOOTLOADER_SPI_WP_PIN 83 int "Custom SPI Flash WP Pin" 84 range 0 33 85 default 7 86 depends on IDF_TARGET_ESP32 && (ESPTOOLPY_FLASHMODE_QIO || ESPTOOLPY_FLASHMODE_QOUT) 87 #depends on BOOTLOADER_SPI_CUSTOM_WP_PIN # backwards compatibility, can uncomment in IDF 5 88 help 89 The option "Use custom SPI Flash WP Pin" must be set or this value is ignored 90 91 If burning a customized set of SPI flash pins in eFuse and using QIO or QOUT mode for flash, set this 92 value to the GPIO number of the SPI flash WP pin. 93 94 choice BOOTLOADER_VDDSDIO_BOOST 95 bool "VDDSDIO LDO voltage" 96 default BOOTLOADER_VDDSDIO_BOOST_1_9V 97 help 98 If this option is enabled, and VDDSDIO LDO is set to 1.8V (using eFuse 99 or MTDI bootstrapping pin), bootloader will change LDO settings to 100 output 1.9V instead. This helps prevent flash chip from browning out 101 during flash programming operations. 102 103 This option has no effect if VDDSDIO is set to 3.3V, or if the internal 104 VDDSDIO regulator is disabled via eFuse. 105 106 config BOOTLOADER_VDDSDIO_BOOST_1_8V 107 bool "1.8V" 108 depends on !ESPTOOLPY_FLASHFREQ_80M 109 config BOOTLOADER_VDDSDIO_BOOST_1_9V 110 bool "1.9V" 111 endchoice 112 113 config BOOTLOADER_FACTORY_RESET 114 bool "GPIO triggers factory reset" 115 default N 116 help 117 Allows to reset the device to factory settings: 118 - clear one or more data partitions; 119 - boot from "factory" partition. 120 The factory reset will occur if there is a GPIO input held at the configured level while 121 device starts up. See settings below. 122 123 config BOOTLOADER_NUM_PIN_FACTORY_RESET 124 int "Number of the GPIO input for factory reset" 125 depends on BOOTLOADER_FACTORY_RESET 126 range 0 39 if IDF_TARGET_ESP32 127 range 0 44 if IDF_TARGET_ESP32S2 128 default 4 129 help 130 The selected GPIO will be configured as an input with internal pull-up enabled (note that on some SoCs. 131 not all pins have an internal pull-up, consult the hardware datasheet for details.) To trigger a factory 132 reset, this GPIO must be held high or low (as configured) on startup. 133 134 choice BOOTLOADER_FACTORY_RESET_PIN_LEVEL 135 bool "Factory reset GPIO level" 136 depends on BOOTLOADER_FACTORY_RESET 137 default BOOTLOADER_FACTORY_RESET_PIN_LOW 138 help 139 Pin level for factory reset, can be triggered on low or high. 140 141 config BOOTLOADER_FACTORY_RESET_PIN_LOW 142 bool "Reset on GPIO low" 143 144 config BOOTLOADER_FACTORY_RESET_PIN_HIGH 145 bool "Reset on GPIO high" 146 endchoice 147 148 config BOOTLOADER_OTA_DATA_ERASE 149 bool "Clear OTA data on factory reset (select factory partition)" 150 depends on BOOTLOADER_FACTORY_RESET 151 help 152 The device will boot from "factory" partition (or OTA slot 0 if no factory partition is present) after a 153 factory reset. 154 155 config BOOTLOADER_DATA_FACTORY_RESET 156 string "Comma-separated names of partitions to clear on factory reset" 157 depends on BOOTLOADER_FACTORY_RESET 158 default "nvs" 159 help 160 Allows customers to select which data partitions will be erased while factory reset. 161 162 Specify the names of partitions as a comma-delimited with optional spaces for readability. (Like this: 163 "nvs, phy_init, ...") 164 Make sure that the name specified in the partition table and here are the same. 165 Partitions of type "app" cannot be specified here. 166 167 config BOOTLOADER_APP_TEST 168 bool "GPIO triggers boot from test app partition" 169 default N 170 depends on !BOOTLOADER_APP_ANTI_ROLLBACK 171 help 172 Allows to run the test app from "TEST" partition. 173 A boot from "test" partition will occur if there is a GPIO input pulled low while device starts up. 174 See settings below. 175 176 config BOOTLOADER_NUM_PIN_APP_TEST 177 int "Number of the GPIO input to boot TEST partition" 178 depends on BOOTLOADER_APP_TEST 179 range 0 39 180 default 18 181 help 182 The selected GPIO will be configured as an input with internal pull-up enabled. 183 To trigger a test app, this GPIO must be pulled low on reset. 184 After the GPIO input is deactivated and the device reboots, the old application will boot. 185 (factory or OTA[x]). 186 Note that GPIO34-39 do not have an internal pullup and an external one must be provided. 187 188 config BOOTLOADER_HOLD_TIME_GPIO 189 int "Hold time of GPIO for reset/test mode (seconds)" 190 depends on BOOTLOADER_FACTORY_RESET || BOOTLOADER_APP_TEST 191 default 5 192 help 193 The GPIO must be held low continuously for this period of time after reset 194 before a factory reset or test partition boot (as applicable) is performed. 195 196 config BOOTLOADER_WDT_ENABLE 197 bool "Use RTC watchdog in start code" 198 default y 199 help 200 Tracks the execution time of startup code. 201 If the execution time is exceeded, the RTC_WDT will restart system. 202 It is also useful to prevent a lock up in start code caused by an unstable power source. 203 NOTE: Tracks the execution time starts from the bootloader code - re-set timeout, while selecting the 204 source for slow_clk - and ends calling app_main. 205 Re-set timeout is needed due to WDT uses a SLOW_CLK clock source. After changing a frequency slow_clk a 206 time of WDT needs to re-set for new frequency. 207 slow_clk depends on ESP32_RTC_CLK_SRC (INTERNAL_RC or EXTERNAL_CRYSTAL). 208 209 config BOOTLOADER_WDT_DISABLE_IN_USER_CODE 210 bool "Allows RTC watchdog disable in user code" 211 depends on BOOTLOADER_WDT_ENABLE 212 default n 213 help 214 If this option is set, the ESP-IDF app must explicitly reset, feed, or disable the rtc_wdt in 215 the app's own code. 216 If this option is not set (default), then rtc_wdt will be disabled by ESP-IDF before calling 217 the app_main() function. 218 219 Use function rtc_wdt_feed() for resetting counter of rtc_wdt. 220 Use function rtc_wdt_disable() for disabling rtc_wdt. 221 222 config BOOTLOADER_WDT_TIME_MS 223 int "Timeout for RTC watchdog (ms)" 224 depends on BOOTLOADER_WDT_ENABLE 225 default 9000 226 range 0 120000 227 help 228 Verify that this parameter is correct and more then the execution time. 229 Pay attention to options such as reset to factory, trigger test partition and encryption on boot 230 - these options can increase the execution time. 231 Note: RTC_WDT will reset while encryption operations will be performed. 232 233 config BOOTLOADER_APP_ROLLBACK_ENABLE 234 bool "Enable app rollback support" 235 default n 236 help 237 After updating the app, the bootloader runs a new app with the "ESP_OTA_IMG_PENDING_VERIFY" state set. 238 This state prevents the re-run of this app. After the first boot of the new app in the user code, the 239 function should be called to confirm the operability of the app or vice versa about its non-operability. 240 If the app is working, then it is marked as valid. Otherwise, it is marked as not valid and rolls back to 241 the previous working app. A reboot is performed, and the app is booted before the software update. 242 Note: If during the first boot a new app the power goes out or the WDT works, then roll back will happen. 243 Rollback is possible only between the apps with the same security versions. 244 245 config BOOTLOADER_APP_ANTI_ROLLBACK 246 bool "Enable app anti-rollback support" 247 depends on BOOTLOADER_APP_ROLLBACK_ENABLE 248 default n 249 help 250 This option prevents rollback to previous firmware/application image with lower security version. 251 252 config BOOTLOADER_APP_SECURE_VERSION 253 int "eFuse secure version of app" 254 depends on BOOTLOADER_APP_ANTI_ROLLBACK 255 default 0 256 help 257 The secure version is the sequence number stored in the header of each firmware. 258 The security version is set in the bootloader, version is recorded in the eFuse field 259 as the number of set ones. The allocated number of bits in the efuse field 260 for storing the security version is limited (see BOOTLOADER_APP_SEC_VER_SIZE_EFUSE_FIELD option). 261 262 Bootloader: When bootloader selects an app to boot, an app is selected that has 263 a security version greater or equal that recorded in eFuse field. 264 The app is booted with a higher (or equal) secure version. 265 266 The security version is worth increasing if in previous versions there is 267 a significant vulnerability and their use is not acceptable. 268 269 Your partition table should has a scheme with ota_0 + ota_1 (without factory). 270 271 config BOOTLOADER_APP_SEC_VER_SIZE_EFUSE_FIELD 272 int "Size of the efuse secure version field" 273 depends on BOOTLOADER_APP_ANTI_ROLLBACK 274 range 1 32 if IDF_TARGET_ESP32 275 default 32 if IDF_TARGET_ESP32 276 range 1 16 277 default 16 278 help 279 The size of the efuse secure version field. 280 Its length is limited to 32 bits for ESP32 and 16 bits for ESP32-S2. 281 This determines how many times the security version can be increased. 282 283 config BOOTLOADER_EFUSE_SECURE_VERSION_EMULATE 284 bool "Emulate operations with efuse secure version(only test)" 285 default n 286 depends on BOOTLOADER_APP_ANTI_ROLLBACK 287 select EFUSE_VIRTUAL 288 select EFUSE_VIRTUAL_KEEP_IN_FLASH 289 help 290 This option allows to emulate read/write operations with all eFuses and efuse secure version. 291 It allows to test anti-rollback implemention without permanent write eFuse bits. 292 There should be an entry in partition table with following details: `emul_efuse, data, efuse, , 0x2000`. 293 294 This option enables: EFUSE_VIRTUAL and EFUSE_VIRTUAL_KEEP_IN_FLASH. 295 296 config BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP 297 bool "Skip image validation when exiting deep sleep" 298 # note: dependencies for this config item are different to other "skip image validation" 299 # options, allowing to turn on "allow insecure options" and have secure boot with 300 # "skip validation when existing deep sleep". Keeping this to avoid a breaking change, 301 # but - as noted in help - it invalidates the integrity of Secure Boot checks 302 depends on (SECURE_BOOT && SECURE_BOOT_INSECURE) || !SECURE_BOOT 303 default n 304 help 305 This option disables the normal validation of an image coming out of 306 deep sleep (checksums, SHA256, and signature). This is a trade-off 307 between wakeup performance from deep sleep, and image integrity checks. 308 309 Only enable this if you know what you are doing. It should not be used 310 in conjunction with using deep_sleep() entry and changing the active OTA 311 partition as this would skip the validation upon first load of the new 312 OTA partition. 313 314 It is possible to enable this option with Secure Boot if "allow insecure 315 options" is enabled, however it's strongly recommended to NOT enable it as 316 it may allow a Secure Boot bypass. 317 318 config BOOTLOADER_SKIP_VALIDATE_ON_POWER_ON 319 bool "Skip image validation from power on reset (READ HELP FIRST)" 320 # only available if both Secure Boot and Check Signature on Boot are disabled 321 depends on !SECURE_SIGNED_ON_BOOT 322 default n 323 help 324 Some applications need to boot very quickly from power on. By default, the entire app binary 325 is read from flash and verified which takes up a significant portion of the boot time. 326 327 Enabling this option will skip validation of the app when the SoC boots from power on. 328 Note that in this case it's not possible for the bootloader to detect if an app image is 329 corrupted in the flash, therefore it's not possible to safely fall back to a different app 330 partition. Flash corruption of this kind is unlikely but can happen if there is a serious 331 firmware bug or physical damage. 332 333 Following other reset types, the bootloader will still validate the app image. This increases 334 the chances that flash corruption resulting in a crash can be detected following soft reset, and 335 the bootloader will fall back to a valid app image. To increase the chances of successfully recovering 336 from a flash corruption event, keep the option BOOTLOADER_WDT_ENABLE enabled and consider also enabling 337 BOOTLOADER_WDT_DISABLE_IN_USER_CODE - then manually disable the RTC Watchdog once the app is running. 338 In addition, enable both the Task and Interrupt watchdog timers with reset options set. 339 340 config BOOTLOADER_SKIP_VALIDATE_ALWAYS 341 bool "Skip image validation always (READ HELP FIRST)" 342 # only available if both Secure Boot and Check Signature on Boot are disabled 343 depends on !SECURE_SIGNED_ON_BOOT 344 default n 345 select BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP 346 select BOOTLOADER_SKIP_VALIDATE_ON_POWER_ON 347 help 348 Selecting this option prevents the bootloader from ever validating the app image before 349 booting it. Any flash corruption of the selected app partition will make the entire SoC 350 unbootable. 351 352 Although flash corruption is a very rare case, it is not recommended to select this option. 353 Consider selecting "Skip image validation from power on reset" instead. However, if boot time 354 is the only important factor then it can be enabled. 355 356 config BOOTLOADER_RESERVE_RTC_SIZE 357 hex 358 default 0x10 if BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP || BOOTLOADER_CUSTOM_RESERVE_RTC 359 default 0 360 help 361 Reserve RTC FAST memory for Skip image validation. This option in bytes. 362 This option reserves an area in the RTC FAST memory (access only PRO_CPU). 363 Used to save the addresses of the selected application. 364 When a wakeup occurs (from Deep sleep), the bootloader retrieves it and 365 loads the application without validation. 366 367 config BOOTLOADER_CUSTOM_RESERVE_RTC 368 bool "Reserve RTC FAST memory for custom purposes" 369 default n 370 help 371 This option allows the customer to place data in the RTC FAST memory, 372 this area remains valid when rebooted, except for power loss. 373 This memory is located at a fixed address and is available 374 for both the bootloader and the application. 375 (The application and bootoloader must be compiled with the same option). 376 The RTC FAST memory has access only through PRO_CPU. 377 378 config BOOTLOADER_CUSTOM_RESERVE_RTC_SIZE 379 hex "Size in bytes for custom purposes" 380 range 0 0x10 381 default 0 382 depends on BOOTLOADER_CUSTOM_RESERVE_RTC 383 help 384 This option reserves in RTC FAST memory the area for custom purposes. 385 If you want to create your own bootloader and save more information 386 in this area of memory, you can increase it. It must be a multiple of 4 bytes. 387 This area (rtc_retain_mem_t) is reserved and has access from the bootloader and an application. 388 389 config BOOTLOADER_FLASH_XMC_SUPPORT 390 bool "Enable the support for flash chips of XMC (READ HELP FIRST)" 391 default y 392 help 393 Perform the startup flow recommended by XMC. Please consult XMC for the details of this flow. 394 XMC chips will be forbidden to be used, when this option is disabled. 395 396 DON'T DISABLE THIS UNLESS YOU KNOW WHAT YOU ARE DOING. 397 398endmenu # Bootloader 399 400 401menu "Security features" 402 403 # These three are the actual options to check in code, 404 # selected by the displayed options 405 config SECURE_SIGNED_ON_BOOT 406 bool 407 default y 408 depends on SECURE_BOOT || SECURE_SIGNED_ON_BOOT_NO_SECURE_BOOT 409 410 config SECURE_SIGNED_ON_UPDATE 411 bool 412 default y 413 depends on SECURE_BOOT || SECURE_SIGNED_ON_UPDATE_NO_SECURE_BOOT 414 415 config SECURE_SIGNED_APPS 416 bool 417 default y 418 select MBEDTLS_ECP_DP_SECP256R1_ENABLED 419 select MBEDTLS_ECP_C 420 select MBEDTLS_ECDH_C 421 select MBEDTLS_ECDSA_C 422 depends on SECURE_SIGNED_ON_BOOT || SECURE_SIGNED_ON_UPDATE 423 424 config SECURE_BOOT_SUPPORTS_RSA 425 bool 426 default y 427 depends on ESP32_REV_MIN_3 || IDF_TARGET_ESP32S2 || IDF_TARGET_ESP32C3 || IDF_TARGET_ESP32S3 428 429 config SECURE_TARGET_HAS_SECURE_ROM_DL_MODE 430 bool 431 default y 432 depends on IDF_TARGET_ESP32S2 || IDF_TARGET_ESP32C3 || IDF_TARGET_ESP32S3 433 434 435 config SECURE_SIGNED_APPS_NO_SECURE_BOOT 436 bool "Require signed app images" 437 depends on !SECURE_BOOT 438 help 439 Require apps to be signed to verify their integrity. 440 441 This option uses the same app signature scheme as hardware secure boot, but unlike hardware secure boot it 442 does not prevent the bootloader from being physically updated. This means that the device can be secured 443 against remote network access, but not physical access. Compared to using hardware Secure Boot this option 444 is much simpler to implement. 445 446 choice SECURE_SIGNED_APPS_SCHEME 447 bool "App Signing Scheme" 448 depends on SECURE_BOOT || SECURE_SIGNED_APPS_NO_SECURE_BOOT 449 default SECURE_SIGNED_APPS_ECDSA_SCHEME if SECURE_BOOT_V1_ENABLED 450 default SECURE_SIGNED_APPS_RSA_SCHEME if SECURE_BOOT_V2_ENABLED 451 help 452 Select the Secure App signing scheme. Depends on the Chip Revision. 453 There are two options: 454 1. ECDSA based secure boot scheme. (Only choice for Secure Boot V1) 455 Supported in ESP32 and ESP32-ECO3. 456 2. The RSA based secure boot scheme. (Only choice for Secure Boot V2) 457 Supported in ESP32-ECO3 (ESP32 Chip Revision 3 onwards), ESP32-S2, ESP32-C3, ESP32-S3. 458 459 config SECURE_SIGNED_APPS_ECDSA_SCHEME 460 bool "ECDSA" 461 depends on IDF_TARGET_ESP32 && (SECURE_SIGNED_APPS_NO_SECURE_BOOT || SECURE_BOOT_V1_ENABLED) 462 help 463 Embeds the ECDSA public key in the bootloader and signs the application with an ECDSA key. 464 465 Refer to the documentation before enabling. 466 467 config SECURE_SIGNED_APPS_RSA_SCHEME 468 bool "RSA" 469 depends on SECURE_BOOT_SUPPORTS_RSA && (SECURE_SIGNED_APPS_NO_SECURE_BOOT || SECURE_BOOT_V2_ENABLED) 470 help 471 Appends the RSA-3072 based Signature block to the application. 472 Refer to <Secure Boot Version 2 documentation link> before enabling. 473 endchoice 474 475 config SECURE_SIGNED_ON_BOOT_NO_SECURE_BOOT 476 bool "Bootloader verifies app signatures" 477 default n 478 depends on SECURE_SIGNED_APPS_NO_SECURE_BOOT && SECURE_SIGNED_APPS_ECDSA_SCHEME 479 help 480 If this option is set, the bootloader will be compiled with code to verify that an app is signed before 481 booting it. 482 483 If hardware secure boot is enabled, this option is always enabled and cannot be disabled. 484 If hardware secure boot is not enabled, this option doesn't add significant security by itself so most 485 users will want to leave it disabled. 486 487 config SECURE_SIGNED_ON_UPDATE_NO_SECURE_BOOT 488 bool "Verify app signature on update" 489 default y 490 depends on SECURE_SIGNED_APPS_NO_SECURE_BOOT 491 help 492 If this option is set, any OTA updated apps will have the signature verified before being considered valid. 493 494 When enabled, the signature is automatically checked whenever the esp_ota_ops.h APIs are used for OTA 495 updates, or esp_image_format.h APIs are used to verify apps. 496 497 If hardware secure boot is enabled, this option is always enabled and cannot be disabled. 498 If hardware secure boot is not enabled, this option still adds significant security against network-based 499 attackers by preventing spoofing of OTA updates. 500 501 config SECURE_BOOT 502 bool "Enable hardware Secure Boot in bootloader (READ DOCS FIRST)" 503 default n 504 depends on IDF_TARGET_ESP32 || IDF_TARGET_ESP32S2 || ESP32C3_REV_MIN_3 || IDF_TARGET_ESP32S3 505 select ESPTOOLPY_NO_STUB if !IDF_TARGET_ESP32 && !IDF_TARGET_ESP32S2 506 help 507 Build a bootloader which enables Secure Boot on first boot. 508 509 Once enabled, Secure Boot will not boot a modified bootloader. The bootloader will only load a partition 510 table or boot an app if the data has a verified digital signature. There are implications for reflashing 511 updated apps once secure boot is enabled. 512 513 When enabling secure boot, JTAG and ROM BASIC Interpreter are permanently disabled by default. 514 515 choice SECURE_BOOT_VERSION 516 bool "Select secure boot version" 517 default SECURE_BOOT_V2_ENABLED if ESP32_REV_MIN_3 518 depends on SECURE_BOOT 519 help 520 Select the Secure Boot Version. Depends on the Chip Revision. 521 Secure Boot V2 is the new RSA based secure boot scheme. 522 Supported in ESP32-ECO3 (ESP32 Chip Revision 3 onwards), ESP32-S2, ESP32-C3 ECO3. 523 Secure Boot V1 is the AES based secure boot scheme. 524 Supported in ESP32 and ESP32-ECO3. 525 526 config SECURE_BOOT_V1_ENABLED 527 bool "Enable Secure Boot version 1" 528 depends on IDF_TARGET_ESP32 529 help 530 Build a bootloader which enables secure boot version 1 on first boot. 531 Refer to the Secure Boot section of the ESP-IDF Programmer's Guide for this version before enabling. 532 533 config SECURE_BOOT_V2_ENABLED 534 bool "Enable Secure Boot version 2" 535 depends on SECURE_BOOT_SUPPORTS_RSA 536 help 537 Build a bootloader which enables Secure Boot version 2 on first boot. 538 Refer to Secure Boot V2 section of the ESP-IDF Programmer's Guide for this version before enabling. 539 540 endchoice 541 542 choice SECURE_BOOTLOADER_MODE 543 bool "Secure bootloader mode" 544 depends on SECURE_BOOT_V1_ENABLED 545 default SECURE_BOOTLOADER_ONE_TIME_FLASH 546 547 config SECURE_BOOTLOADER_ONE_TIME_FLASH 548 bool "One-time flash" 549 help 550 On first boot, the bootloader will generate a key which is not readable externally or by software. A 551 digest is generated from the bootloader image itself. This digest will be verified on each subsequent 552 boot. 553 554 Enabling this option means that the bootloader cannot be changed after the first time it is booted. 555 556 config SECURE_BOOTLOADER_REFLASHABLE 557 bool "Reflashable" 558 help 559 Generate a reusable secure bootloader key, derived (via SHA-256) from the secure boot signing key. 560 561 This allows the secure bootloader to be re-flashed by anyone with access to the secure boot signing 562 key. 563 564 This option is less secure than one-time flash, because a leak of the digest key from one device 565 allows reflashing of any device that uses it. 566 567 endchoice 568 569 config SECURE_BOOT_BUILD_SIGNED_BINARIES 570 bool "Sign binaries during build" 571 depends on SECURE_SIGNED_APPS 572 default y 573 help 574 Once secure boot or signed app requirement is enabled, app images are required to be signed. 575 576 If enabled (default), these binary files are signed as part of the build process. The file named in 577 "Secure boot private signing key" will be used to sign the image. 578 579 If disabled, unsigned app/partition data will be built. They must be signed manually using espsecure.py. 580 Version 1 to enable ECDSA Based Secure Boot and Version 2 to enable RSA based Secure Boot. 581 (for example, on a remote signing server.) 582 583 config SECURE_BOOT_SIGNING_KEY 584 string "Secure boot private signing key" 585 depends on SECURE_BOOT_BUILD_SIGNED_BINARIES 586 default "secure_boot_signing_key.pem" 587 help 588 Path to the key file used to sign app images. 589 590 Key file is an ECDSA private key (NIST256p curve) in PEM format for Secure Boot V1. 591 Key file is an RSA private key in PEM format for Secure Boot V2. 592 593 Path is evaluated relative to the project directory. 594 595 You can generate a new signing key by running the following command: 596 espsecure.py generate_signing_key secure_boot_signing_key.pem 597 598 See the Secure Boot section of the ESP-IDF Programmer's Guide for this version for details. 599 600 config SECURE_BOOT_VERIFICATION_KEY 601 string "Secure boot public signature verification key" 602 depends on SECURE_SIGNED_APPS && !SECURE_BOOT_BUILD_SIGNED_BINARIES && !SECURE_SIGNED_APPS_RSA_SCHEME 603 default "signature_verification_key.bin" 604 help 605 Path to a public key file used to verify signed images. 606 Secure Boot V1: This ECDSA public key is compiled into the bootloader and/or 607 app, to verify app images. 608 Secure Boot V2: This RSA public key is compiled into the signature block at 609 the end of the bootloader/app. 610 611 Key file is in raw binary format, and can be extracted from a 612 PEM formatted private key using the espsecure.py 613 extract_public_key command. 614 615 Refer to the Secure Boot section of the ESP-IDF Programmer's Guide for this version before enabling. 616 617 config SECURE_BOOT_ENABLE_AGGRESSIVE_KEY_REVOKE 618 bool "Enable Aggressive key revoke strategy" 619 depends on SECURE_BOOT && (IDF_TARGET_ESP32S2 || IDF_TARGET_ESP32C3 || IDF_TARGET_ESP32S3) 620 default N 621 help 622 If this option is set, ROM bootloader will revoke the public key digest burned in efuse block 623 if it fails to verify the signature of software bootloader with it. 624 Revocation of keys does not happen when enabling secure boot. Once secure boot is enabled, 625 key revocation checks will be done on subsequent boot-up, while verifying the software bootloader 626 627 This feature provides a strong resistance against physical attacks on the device. 628 629 NOTE: Once a digest slot is revoked, it can never be used again to verify an image 630 This can lead to permanent bricking of the device, in case all keys are revoked 631 because of signature verification failure. 632 633 choice SECURE_BOOTLOADER_KEY_ENCODING 634 bool "Hardware Key Encoding" 635 depends on SECURE_BOOTLOADER_REFLASHABLE 636 default SECURE_BOOTLOADER_KEY_ENCODING_256BIT 637 help 638 639 In reflashable secure bootloader mode, a hardware key is derived from the signing key (with SHA-256) and 640 can be written to eFuse with espefuse.py. 641 642 Normally this is a 256-bit key, but if 3/4 Coding Scheme is used on the device then the eFuse key is 643 truncated to 192 bits. 644 645 This configuration item doesn't change any firmware code, it only changes the size of key binary which is 646 generated at build time. 647 648 config SECURE_BOOTLOADER_KEY_ENCODING_256BIT 649 bool "No encoding (256 bit key)" 650 651 config SECURE_BOOTLOADER_KEY_ENCODING_192BIT 652 bool "3/4 encoding (192 bit key)" 653 654 endchoice 655 656 config SECURE_BOOT_INSECURE 657 bool "Allow potentially insecure options" 658 depends on SECURE_BOOT 659 default N 660 help 661 You can disable some of the default protections offered by secure boot, in order to enable testing or a 662 custom combination of security features. 663 664 Only enable these options if you are very sure. 665 666 Refer to the Secure Boot section of the ESP-IDF Programmer's Guide for this version before enabling. 667 668 config SECURE_FLASH_ENC_ENABLED 669 bool "Enable flash encryption on boot (READ DOCS FIRST)" 670 default N 671 select SPI_FLASH_ENABLE_ENCRYPTED_READ_WRITE 672 help 673 If this option is set, flash contents will be encrypted by the bootloader on first boot. 674 675 Note: After first boot, the system will be permanently encrypted. Re-flashing an encrypted 676 system is complicated and not always possible. 677 678 Read https://docs.espressif.com/projects/esp-idf/en/latest/security/flash-encryption.html 679 before enabling. 680 681 choice SECURE_FLASH_ENCRYPTION_KEYSIZE 682 bool "Size of generated AES-XTS key" 683 default SECURE_FLASH_ENCRYPTION_AES128 684 depends on (IDF_TARGET_ESP32S2 || IDF_TARGET_ESP32S3) && SECURE_FLASH_ENC_ENABLED 685 help 686 Size of generated AES-XTS key. 687 688 AES-128 uses a 256-bit key (32 bytes) which occupies one Efuse key block. 689 AES-256 uses a 512-bit key (64 bytes) which occupies two Efuse key blocks. 690 691 This setting is ignored if either type of key is already burned to Efuse before the first boot. 692 In this case, the pre-burned key is used and no new key is generated. 693 694 config SECURE_FLASH_ENCRYPTION_AES128 695 bool "AES-128 (256-bit key)" 696 697 config SECURE_FLASH_ENCRYPTION_AES256 698 bool "AES-256 (512-bit key)" 699 endchoice 700 701 choice SECURE_FLASH_ENCRYPTION_MODE 702 bool "Enable usage mode" 703 depends on SECURE_FLASH_ENC_ENABLED 704 default SECURE_FLASH_ENCRYPTION_MODE_DEVELOPMENT 705 help 706 By default Development mode is enabled which allows ROM download mode to perform flash encryption 707 operations (plaintext is sent to the device, and it encrypts it internally and writes ciphertext 708 to flash.) This mode is not secure, it's possible for an attacker to write their own chosen plaintext 709 to flash. 710 711 Release mode should always be selected for production or manufacturing. Once enabled it's no longer 712 possible for the device in ROM Download Mode to use the flash encryption hardware. 713 714 Refer to the Flash Encryption section of the ESP-IDF Programmer's Guide for details. 715 716 config SECURE_FLASH_ENCRYPTION_MODE_DEVELOPMENT 717 bool "Development (NOT SECURE)" 718 select SECURE_FLASH_UART_BOOTLOADER_ALLOW_ENC 719 720 config SECURE_FLASH_ENCRYPTION_MODE_RELEASE 721 bool "Release" 722 select PARTITION_TABLE_MD5 if !ESP32_COMPATIBLE_PRE_V3_1_BOOTLOADERS 723 724 endchoice 725 726 menu "Potentially insecure options" 727 visible if SECURE_FLASH_ENCRYPTION_MODE_DEVELOPMENT || SECURE_BOOT_INSECURE 728 729 # NOTE: Options in this menu NEED to have SECURE_BOOT_INSECURE 730 # and/or SECURE_FLASH_ENCRYPTION_MODE_DEVELOPMENT in "depends on", as the menu 731 # itself doesn't enable/disable its children (if it's not set, 732 # it's possible for the insecure menu to be disabled but the insecure option 733 # to remain on which is very bad.) 734 735 config SECURE_BOOT_ALLOW_ROM_BASIC 736 bool "Leave ROM BASIC Interpreter available on reset" 737 depends on (SECURE_BOOT_INSECURE || SECURE_FLASH_ENCRYPTION_MODE_DEVELOPMENT) && IDF_TARGET_ESP32 738 default N 739 help 740 By default, the BASIC ROM Console starts on reset if no valid bootloader is 741 read from the flash. 742 743 When either flash encryption or secure boot are enabled, the default is to 744 disable this BASIC fallback mode permanently via eFuse. 745 746 If this option is set, this eFuse is not burned and the BASIC ROM Console may 747 remain accessible. Only set this option in testing environments. 748 749 config SECURE_BOOT_ALLOW_JTAG 750 bool "Allow JTAG Debugging" 751 depends on SECURE_BOOT_INSECURE || SECURE_FLASH_ENCRYPTION_MODE_DEVELOPMENT 752 default N 753 help 754 If not set (default), the bootloader will permanently disable JTAG (across entire chip) on first boot 755 when either secure boot or flash encryption is enabled. 756 757 Setting this option leaves JTAG on for debugging, which negates all protections of flash encryption 758 and some of the protections of secure boot. 759 760 Only set this option in testing environments. 761 762 config SECURE_BOOT_ALLOW_SHORT_APP_PARTITION 763 bool "Allow app partition length not 64KB aligned" 764 depends on SECURE_BOOT_INSECURE 765 help 766 If not set (default), app partition size must be a multiple of 64KB. App images are padded to 64KB 767 length, and the bootloader checks any trailing bytes after the signature (before the next 64KB 768 boundary) have not been written. This is because flash cache maps entire 64KB pages into the address 769 space. This prevents an attacker from appending unverified data after the app image in the flash, 770 causing it to be mapped into the address space. 771 772 Setting this option allows the app partition length to be unaligned, and disables padding of the app 773 image to this length. It is generally not recommended to set this option, unless you have a legacy 774 partitioning scheme which doesn't support 64KB aligned partition lengths. 775 776 config SECURE_BOOT_V2_ALLOW_EFUSE_RD_DIS 777 bool "Allow additional read protecting of efuses" 778 depends on SECURE_BOOT_INSECURE && SECURE_BOOT_V2_ENABLED 779 help 780 If not set (default, recommended), on first boot the bootloader will burn the WR_DIS_RD_DIS 781 efuse when Secure Boot is enabled. This prevents any more efuses from being read protected. 782 783 If this option is set, it will remain possible to write the EFUSE_RD_DIS efuse field after Secure 784 Boot is enabled. This may allow an attacker to read-protect the BLK2 efuse (for ESP32) and 785 BLOCK4-BLOCK10 (i.e. BLOCK_KEY0-BLOCK_KEY5)(for other chips) holding the public key digest, causing an 786 immediate denial of service and possibly allowing an additional fault injection attack to 787 bypass the signature protection. 788 789 NOTE: Once a BLOCK is read-protected, the application will read all zeros from that block 790 791 NOTE: If "UART ROM download mode (Permanently disabled (recommended))" or 792 "UART ROM download mode (Permanently switch to Secure mode (recommended))" is set, 793 then it is __NOT__ possible to read/write efuses using espefuse.py utility. 794 However, efuse can be read/written from the application 795 796 config SECURE_BOOT_ALLOW_UNUSED_DIGEST_SLOTS 797 bool "Leave unused digest slots available (not revoke)" 798 depends on SECURE_BOOT_INSECURE && !IDF_TARGET_ESP32 799 default N 800 help 801 If not set (default), during startup in the app all unused digest slots will be revoked. 802 To revoke unused slot will be called esp_efuse_set_digest_revoke(num_digest) for each digest. 803 Revoking unused digest slots makes ensures that no trusted keys can be added later by an attacker. 804 If set, it means that you have a plan to use unused digests slots later. 805 806 config SECURE_FLASH_UART_BOOTLOADER_ALLOW_ENC 807 bool "Leave UART bootloader encryption enabled" 808 depends on SECURE_FLASH_ENCRYPTION_MODE_DEVELOPMENT 809 default N 810 help 811 If not set (default), the bootloader will permanently disable UART bootloader encryption access on 812 first boot. If set, the UART bootloader will still be able to access hardware encryption. 813 814 It is recommended to only set this option in testing environments. 815 816 config SECURE_FLASH_UART_BOOTLOADER_ALLOW_DEC 817 bool "Leave UART bootloader decryption enabled" 818 depends on SECURE_FLASH_ENCRYPTION_MODE_DEVELOPMENT && IDF_TARGET_ESP32 819 default N 820 help 821 If not set (default), the bootloader will permanently disable UART bootloader decryption access on 822 first boot. If set, the UART bootloader will still be able to access hardware decryption. 823 824 Only set this option in testing environments. Setting this option allows complete bypass of flash 825 encryption. 826 827 config SECURE_FLASH_UART_BOOTLOADER_ALLOW_CACHE 828 bool "Leave UART bootloader flash cache enabled" 829 depends on SECURE_FLASH_ENCRYPTION_MODE_DEVELOPMENT 830 default N 831 help 832 If not set (default), the bootloader will permanently disable UART bootloader flash cache access on 833 first boot. If set, the UART bootloader will still be able to access the flash cache. 834 835 Only set this option in testing environments. 836 837 config SECURE_FLASH_REQUIRE_ALREADY_ENABLED 838 bool "Require flash encryption to be already enabled" 839 depends on SECURE_FLASH_ENCRYPTION_MODE_DEVELOPMENT 840 default N 841 help 842 If not set (default), and flash encryption is not yet enabled in eFuses, the 2nd stage bootloader 843 will enable flash encryption: generate the flash encryption key and program eFuses. 844 If this option is set, and flash encryption is not yet enabled, the bootloader will error out and 845 reboot. 846 If flash encryption is enabled in eFuses, this option does not change the bootloader behavior. 847 848 Only use this option in testing environments, to avoid accidentally enabling flash encryption on 849 the wrong device. The device needs to have flash encryption already enabled using espefuse.py. 850 851 endmenu # Potentially Insecure 852 853 config SECURE_FLASH_CHECK_ENC_EN_IN_APP 854 bool "Check Flash Encryption enabled on app startup" 855 depends on SECURE_FLASH_ENC_ENABLED 856 default y 857 help 858 If set (default), in an app during startup code, 859 there is a check of the flash encryption eFuse bit is on 860 (as the bootloader should already have set it). 861 The app requires this bit is on to continue work otherwise abort. 862 863 If not set, the app does not care if the flash encryption eFuse bit is set or not. 864 865 choice SECURE_UART_ROM_DL_MODE 866 bool "UART ROM download mode" 867 default SECURE_ENABLE_SECURE_ROM_DL_MODE if SECURE_TARGET_HAS_SECURE_ROM_DL_MODE && !SECURE_FLASH_ENCRYPTION_MODE_DEVELOPMENT # NOERROR 868 default SECURE_INSECURE_ALLOW_DL_MODE 869 depends on SECURE_BOOT_V2_ENABLED || SECURE_FLASH_ENC_ENABLED 870 depends on !IDF_TARGET_ESP32 || ESP32_REV_MIN_3 871 872 config SECURE_DISABLE_ROM_DL_MODE 873 bool "UART ROM download mode (Permanently disabled (recommended))" 874 help 875 If set, during startup the app will burn an eFuse bit to permanently disable the UART ROM 876 Download Mode. This prevents any future use of esptool.py, espefuse.py and similar tools. 877 878 Once disabled, if the SoC is booted with strapping pins set for ROM Download Mode 879 then an error is printed instead. 880 881 It is recommended to enable this option in any production application where Flash 882 Encryption and/or Secure Boot is enabled and access to Download Mode is not required. 883 884 It is also possible to permanently disable Download Mode by calling 885 esp_efuse_disable_rom_download_mode() at runtime. 886 887 config SECURE_ENABLE_SECURE_ROM_DL_MODE 888 bool "UART ROM download mode (Permanently switch to Secure mode (recommended))" 889 depends on SECURE_TARGET_HAS_SECURE_ROM_DL_MODE 890 select ESPTOOLPY_NO_STUB 891 help 892 If set, during startup the app will burn an eFuse bit to permanently switch the UART ROM 893 Download Mode into a separate Secure Download mode. This option can only work if 894 Download Mode is not already disabled by eFuse. 895 896 Secure Download mode limits the use of Download Mode functions to simple flash read, 897 write and erase operations, plus a command to return a summary of currently enabled 898 security features. 899 900 Secure Download mode is not compatible with the esptool.py flasher stub feature, 901 espefuse.py, read/writing memory or registers, encrypted download, or any other 902 features that interact with unsupported Download Mode commands. 903 904 Secure Download mode should be enabled in any application where Flash Encryption 905 and/or Secure Boot is enabled. Disabling this option does not immediately cancel 906 the benefits of the security features, but it increases the potential "attack 907 surface" for an attacker to try and bypass them with a successful physical attack. 908 909 It is also possible to enable secure download mode at runtime by calling 910 esp_efuse_enable_rom_secure_download_mode() 911 912 Note: Secure Download mode is not available for ESP32 (includes revisions till ECO3). 913 914 config SECURE_INSECURE_ALLOW_DL_MODE 915 bool "UART ROM download mode (Enabled (not recommended))" 916 help 917 This is a potentially insecure option. 918 Enabling this option will allow the full UART download mode to stay enabled. 919 This option SHOULD NOT BE ENABLED for production use cases. 920 endchoice 921endmenu # Security features 922
