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