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