1  menu "Bootloader config"
  2  choice LOG_BOOTLOADER_LEVEL
  3     bool "Bootloader log verbosity"
  4     default LOG_BOOTLOADER_LEVEL_INFO
  5     help
  6         Specify how much output to see in bootloader logs.
  7  
  8  config LOG_BOOTLOADER_LEVEL_NONE
  9     bool "No output"
 10  config LOG_BOOTLOADER_LEVEL_ERROR
 11     bool "Error"
 12  config LOG_BOOTLOADER_LEVEL_WARN
 13     bool "Warning"
 14  config LOG_BOOTLOADER_LEVEL_INFO
 15     bool "Info"
 16  config LOG_BOOTLOADER_LEVEL_DEBUG
 17     bool "Debug"
 18  config LOG_BOOTLOADER_LEVEL_VERBOSE
 19     bool "Verbose"
 20  endchoice
 21  
 22  config LOG_BOOTLOADER_LEVEL
 23      int
 24      default 0 if LOG_BOOTLOADER_LEVEL_NONE
 25      default 1 if LOG_BOOTLOADER_LEVEL_ERROR
 26      default 2 if LOG_BOOTLOADER_LEVEL_WARN
 27      default 3 if LOG_BOOTLOADER_LEVEL_INFO
 28      default 4 if LOG_BOOTLOADER_LEVEL_DEBUG
 29      default 5 if LOG_BOOTLOADER_LEVEL_VERBOSE
 30  
 31  config BOOTLOADER_SPI_WP_PIN
 32      int "SPI Flash WP Pin when customising pins via efuse (read help)"
 33      range 0 33
 34      default 7
 35      depends on FLASHMODE_QIO || FLASHMODE_QOUT
 36      help
 37          This value is ignored unless flash mode is set to QIO or QOUT *and* the SPI flash pins have been
 38          overriden by setting the efuses SPI_PAD_CONFIG_xxx.
 39  
 40          When this is the case, the Efuse config only defines 3 of the 4 Quad I/O data pins. The WP pin (aka ESP32
 41          pin "SD_DATA_3" or SPI flash pin "IO2") is not specified in Efuse. That pin number is compiled into the bootloader
 42          instead.
 43  
 44          The default value (GPIO 7) is correct for WP pin on ESP32-D2WD integrated flash.
 45  
 46  choice BOOTLOADER_VDDSDIO_BOOST
 47      bool "VDDSDIO LDO voltage"
 48      default BOOTLOADER_VDDSDIO_BOOST_1_9V
 49      help
 50          If this option is enabled, and VDDSDIO LDO is set to 1.8V (using EFUSE
 51          or MTDI bootstrapping pin), bootloader will change LDO settings to
 52          output 1.9V instead. This helps prevent flash chip from browning out
 53          during flash programming operations.
 54  
 55          This option has no effect if VDDSDIO is set to 3.3V, or if the internal
 56          VDDSDIO regulator is disabled via efuse.
 57  
 58  config BOOTLOADER_VDDSDIO_BOOST_1_8V
 59      bool "1.8V"
 60      depends on !ESPTOOLPY_FLASHFREQ_80M
 61  config BOOTLOADER_VDDSDIO_BOOST_1_9V
 62      bool "1.9V"
 63  endchoice
 64  
 65  config BOOTLOADER_FACTORY_RESET
 66      bool "GPIO triggers factory reset"
 67      default N
 68      help
 69          Allows to reset the device to factory settings:
 70          - clear one or more data partitions;
 71          - boot from "factory" partition.
 72          The factory reset will occur if there is a GPIO input pulled low while device starts up.
 73          See settings below.
 74  
 75  config BOOTLOADER_NUM_PIN_FACTORY_RESET
 76      int "Number of the GPIO input for factory reset"
 77      depends on BOOTLOADER_FACTORY_RESET
 78      range 0 39
 79      default 4
 80      help
 81          The selected GPIO will be configured as an input with internal pull-up enabled.
 82          To trigger a factory reset, this GPIO must be pulled low on reset.
 83          Note that GPIO34-39 do not have an internal pullup and an external one must be provided.
 84  
 85  config BOOTLOADER_OTA_DATA_ERASE
 86      bool "Clear OTA data on factory reset (select factory partition)"
 87      depends on BOOTLOADER_FACTORY_RESET
 88      help
 89          The device will boot from "factory" partition (or OTA slot 0 if no factory partition is present) after a factory reset.
 90  
 91  config BOOTLOADER_DATA_FACTORY_RESET
 92       string "Comma-separated names of partitions to clear on factory reset"
 93       depends on BOOTLOADER_FACTORY_RESET
 94       default "nvs"
 95       help
 96          Allows customers to select which data partitions will be erased while factory reset.
 97          
 98          Specify the names of partitions as a comma-delimited with optional spaces for readability. (Like this: "nvs, phy_init, ...")
 99          Make sure that the name specified in the partition table and here are the same. 
100          Partitions of type "app" cannot be specified here.
101  
102  config BOOTLOADER_APP_TEST
103      bool "GPIO triggers boot from test app partition"
104      default N
105      help
106          Allows to run the test app from "TEST" partition.
107          A boot from "test" partition will occur if there is a GPIO input pulled low while device starts up.
108          See settings below.
109  
110  config BOOTLOADER_NUM_PIN_APP_TEST
111      int "Number of the GPIO input to boot TEST partition"
112      depends on BOOTLOADER_APP_TEST
113      range 0 39
114      default 18
115      help
116          The selected GPIO will be configured as an input with internal pull-up enabled.
117          To trigger a test app, this GPIO must be pulled low on reset.
118          After the GPIO input is deactivated and the device reboots, the old application will boot. 
119          (factory or OTA[x]).
120          Note that GPIO34-39 do not have an internal pullup and an external one must be provided.
121  
122  config BOOTLOADER_HOLD_TIME_GPIO
123      int "Hold time of GPIO for reset/test mode (seconds)"
124      depends on BOOTLOADER_FACTORY_RESET || BOOTLOADER_APP_TEST
125      default 5
126      help
127          The GPIO must be held low continuously for this period of time after reset 
128          before a factory reset or test partition boot (as applicable) is performed.
129  
130  config BOOTLOADER_WDT_ENABLE
131      bool "Use RTC watchdog in start code"
132      default y
133      help
134          Tracks the execution time of startup code.
135          If the execution time is exceeded, the RTC_WDT will restart system.
136          It is also useful to prevent a lock up in start code caused by an unstable power source.
137          NOTE: Tracks the execution time starts from the bootloader code - re-set timeout, while selecting the source for slow_clk - and ends calling app_main.
138          Re-set timeout is needed due to WDT uses a SLOW_CLK clock source. After changing a frequency slow_clk a time of WDT needs to re-set for new frequency.
139          slow_clk depends on ESP32_RTC_CLOCK_SOURCE (INTERNAL_RC or EXTERNAL_CRYSTAL).
140  
141  config BOOTLOADER_WDT_DISABLE_IN_USER_CODE
142      bool "Allows RTC watchdog disable in user code"
143      depends on BOOTLOADER_WDT_ENABLE
144      default n
145      help
146          If it is set, the client must itself reset or disable rtc_wdt in their code (app_main()).
147          Otherwise rtc_wdt will be disabled before calling app_main function.
148          Use function rtc_wdt_feed() for resetting counter of rtc_wdt.
149          Use function rtc_wdt_disable() for disabling rtc_wdt.
150  
151  config BOOTLOADER_WDT_TIME_MS
152      int "Timeout for RTC watchdog (ms)"
153      depends on BOOTLOADER_WDT_ENABLE
154      default 9000
155      range 0 120000
156      help
157          Verify that this parameter is correct and more then the execution time. 
158          Pay attention to options such as reset to factory, trigger test partition and encryption on boot
159          - these options can increase the execution time. 
160          Note: RTC_WDT will reset while encryption operations will be performed.
161  
162  endmenu  # Bootloader
163  
164  
165  menu "Security features"
166  
167  # These three are the actual options to check in code,
168  # selected by the displayed options
169  config SECURE_SIGNED_ON_BOOT
170      bool
171      default y
172      depends on SECURE_BOOT_ENABLED || SECURE_SIGNED_ON_BOOT_NO_SECURE_BOOT
173  
174  config SECURE_SIGNED_ON_UPDATE
175      bool
176      default y
177      depends on SECURE_BOOT_ENABLED || SECURE_SIGNED_ON_UPDATE_NO_SECURE_BOOT
178  
179  config SECURE_SIGNED_APPS
180     bool
181     default y
182     depends on SECURE_SIGNED_ON_BOOT || SECURE_SIGNED_ON_UPDATE
183  
184  
185  config SECURE_SIGNED_APPS_NO_SECURE_BOOT
186      bool "Require signed app images"
187      default n
188      depends on !SECURE_BOOT_ENABLED
189      help
190          Require apps to be signed to verify their integrity.
191  
192          This option uses the same app signature scheme as hardware secure boot, but unlike hardware secure boot it does not prevent the bootloader from being physically updated. This means that the device can be secured against remote network access, but not physical access. Compared to using hardware Secure Boot this option is much simpler to implement.
193  
194  config SECURE_SIGNED_ON_BOOT_NO_SECURE_BOOT
195      bool "Bootloader verifies app signatures"
196      default n
197      depends on SECURE_SIGNED_APPS_NO_SECURE_BOOT
198      help
199          If this option is set, the bootloader will be compiled with code to verify that an app is signed before booting it.
200  
201          If hardware secure boot is enabled, this option is always enabled and cannot be disabled.
202          If hardware secure boot is not enabled, this option doesn't add significant security by itself so most users will want to leave it disabled.
203  
204  config SECURE_SIGNED_ON_UPDATE_NO_SECURE_BOOT
205      bool "Verify app signature on update"
206      default y
207      depends on SECURE_SIGNED_APPS_NO_SECURE_BOOT
208      help
209           If this option is set, any OTA updated apps will have the signature verified before being considered valid.
210  
211           When enabled, the signature is automatically checked whenever the esp_ota_ops.h APIs are used for OTA updates,
212           or esp_image_format.h APIs are used to verify apps.
213  
214           If hardware secure boot is enabled, this option is always enabled and cannot be disabled.
215           If hardware secure boot is not enabled, this option still adds significant security against network-based attackers by preventing spoofing of OTA updates.
216  
217  config SECURE_BOOT_ENABLED
218      bool "Enable hardware secure boot in bootloader (READ DOCS FIRST)"
219      default n
220      help
221          Build a bootloader which enables secure boot on first boot.
222  
223          Once enabled, secure boot will not boot a modified bootloader. The bootloader will only load a partition table or boot an app if the data has a verified digital signature. There are implications for reflashing updated apps once secure boot is enabled.
224  
225          When enabling secure boot, JTAG and ROM BASIC Interpreter are permanently disabled by default.
226  
227          Refer to https://docs.espressif.com/projects/esp-idf/en/latest/security/secure-boot.html before enabling.
228  
229  choice SECURE_BOOTLOADER_MODE
230      bool "Secure bootloader mode"
231      depends on SECURE_BOOT_ENABLED
232      default SECURE_BOOTLOADER_ONE_TIME_FLASH
233  
234  config SECURE_BOOTLOADER_ONE_TIME_FLASH
235         bool "One-time flash"
236         help
237             On first boot, the bootloader will generate a key which is not readable externally or by software. A digest is generated from the bootloader image itself. This digest will be verified on each subsequent boot.
238  
239             Enabling this option means that the bootloader cannot be changed after the first time it is booted.
240  
241  config SECURE_BOOTLOADER_REFLASHABLE
242      bool "Reflashable"
243      help
244          Generate a reusable secure bootloader key, derived (via SHA-256) from the secure boot signing key.
245  
246          This allows the secure bootloader to be re-flashed by anyone with access to the secure boot signing key.
247  
248          This option is less secure than one-time flash, because a leak of the digest key from one device allows reflashing of any device that uses it.
249  
250  endchoice
251  
252  config SECURE_BOOT_BUILD_SIGNED_BINARIES
253       bool "Sign binaries during build"
254       depends on SECURE_SIGNED_APPS
255       default y
256       help
257          Once secure boot or signed app requirement is enabled, app images are required to be signed.
258  
259          If enabled (default), these binary files are signed as part of the build process. The file named in "Secure boot private signing key" will be used to sign the image.
260  
261          If disabled, unsigned app/partition data will be built. They must be signed manually using espsecure.py (for example, on a remote signing server.)
262  
263  config SECURE_BOOT_SIGNING_KEY
264       string "Secure boot private signing key"
265       depends on SECURE_BOOT_BUILD_SIGNED_BINARIES
266       default secure_boot_signing_key.pem
267       help
268          Path to the key file used to sign app images.
269  
270          Key file is an ECDSA private key (NIST256p curve) in PEM format.
271  
272          Path is evaluated relative to the project directory.
273  
274          You can generate a new signing key by running the following command:
275          espsecure.py generate_signing_key secure_boot_signing_key.pem
276  
277          See docs/security/secure-boot.rst for details.
278  
279  config SECURE_BOOT_VERIFICATION_KEY
280      string "Secure boot public signature verification key"
281      depends on SECURE_SIGNED_APPS && !SECURE_BOOT_BUILD_SIGNED_BINARIES
282      default signature_verification_key.bin
283      help
284         Path to a public key file used to verify signed images. This key is compiled into the bootloader and/or app,
285         to verify app images.
286  
287         Key file is in raw binary format, and can be extracted from a
288         PEM formatted private key using the espsecure.py
289         extract_public_key command.
290  
291         Refer to https://docs.espressif.com/projects/esp-idf/en/latest/security/secure-boot.html before enabling.
292  
293  choice SECURE_BOOTLOADER_KEY_ENCODING
294      bool "Hardware Key Encoding"
295      depends on SECURE_BOOTLOADER_REFLASHABLE
296      default SECURE_BOOTLOADER_NO_ENCODING
297      help
298  
299      In reflashable secure bootloader mode, a hardware key is derived from the signing key (with SHA-256) and can be written to efuse
300      with espefuse.py.
301  
302      Normally this is a 256-bit key, but if 3/4 Coding Scheme is used on the device then the efuse key is truncated to 192 bits.
303  
304      This configuration item doesn't change any firmware code, it only changes the size of key binary which is generated at build time.
305  
306  config SECURE_BOOTLOADER_KEY_ENCODING_256BIT
307         bool "No encoding (256 bit key)"
308  
309  config SECURE_BOOTLOADER_KEY_ENCODING_192BIT
310         bool "3/4 encoding (192 bit key)"
311  
312  endchoice
313  
314  config SECURE_BOOT_INSECURE
315      bool "Allow potentially insecure options"
316      depends on SECURE_BOOT_ENABLED
317      default N
318      help
319         You can disable some of the default protections offered by secure boot, in order to enable testing or a custom combination of security features.
320  
321         Only enable these options if you are very sure.
322  
323         Refer to https://docs.espressif.com/projects/esp-idf/en/latest/security/secure-boot.html before enabling.
324  
325  config FLASH_ENCRYPTION_ENABLED
326      bool "Enable flash encryption on boot (READ DOCS FIRST)"
327      default N
328      help
329         If this option is set, flash contents will be encrypted by the bootloader on first boot.
330  
331         Note: After first boot, the system will be permanently encrypted. Re-flashing an encrypted
332         system is complicated and not always possible.
333  
334         Read https://docs.espressif.com/projects/esp-idf/en/latest/security/flash-encryption.html before enabling.
335  
336  config FLASH_ENCRYPTION_INSECURE
337      bool "Allow potentially insecure options"
338      depends on FLASH_ENCRYPTION_ENABLED
339      default N
340      help
341         You can disable some of the default protections offered by flash encryption, in order to enable testing or a custom combination of security features.
342  
343         Only enable these options if you are very sure.
344  
345         Refer to docs/security/secure-boot.rst and docs/security/flash-encryption.rst for details.
346  
347  menu "Potentially insecure options"
348      visible if FLASH_ENCRYPTION_INSECURE || SECURE_BOOT_INSECURE
349  
350  # NOTE: Options in this menu NEED to have SECURE_BOOT_INSECURE
351  # and/or FLASH_ENCRYPTION_INSECURE in "depends on", as the menu
352  # itself doesn't enable/disable its children (if it's not set,
353  # it's possible for the insecure menu to be disabled but the insecure option
354  # to remain on which is very bad.)
355  
356  config SECURE_BOOT_ALLOW_ROM_BASIC
357         bool "Leave ROM BASIC Interpreter available on reset"
358         depends on SECURE_BOOT_INSECURE || FLASH_ENCRYPTION_INSECURE
359         default N
360         help
361            By default, the BASIC ROM Console starts on reset if no valid bootloader is
362            read from the flash.
363  
364            When either flash encryption or secure boot are enabled, the default is to
365            disable this BASIC fallback mode permanently via efuse.
366  
367            If this option is set, this efuse is not burned and the BASIC ROM Console may
368            remain accessible.  Only set this option in testing environments.
369  
370  config SECURE_BOOT_ALLOW_JTAG
371         bool "Allow JTAG Debugging"
372         depends on SECURE_BOOT_INSECURE || FLASH_ENCRYPTION_INSECURE
373         default N
374         help
375            If not set (default), the bootloader will permanently disable JTAG (across entire chip) on first boot when either secure boot or flash encryption is enabled.
376  
377            Setting this option leaves JTAG on for debugging, which negates all protections of flash encryption and some of the protections of secure boot.
378  
379            Only set this option in testing environments.
380  
381  config SECURE_BOOT_ALLOW_SHORT_APP_PARTITION
382         bool "Allow app partition length not 64KB aligned"
383         depends on SECURE_BOOT_INSECURE
384         help
385             If not set (default), app partition size must be a multiple of 64KB. App images are padded to 64KB length, and the bootloader checks any trailing bytes after the signature (before the next 64KB boundary) have not been written. This is because flash cache maps entire 64KB pages into the address space. This prevents an attacker from appending unverified data after the app image in the flash, causing it to be mapped into the address space.
386  
387             Setting this option allows the app partition length to be unaligned, and disables padding of the app image to this length. It is generally not recommended to set this option, unless you have a legacy partitioning scheme which doesn't support 64KB aligned partition lengths.
388  
389  config FLASH_ENCRYPTION_UART_BOOTLOADER_ALLOW_ENCRYPT
390      bool "Leave UART bootloader encryption enabled"
391      depends on FLASH_ENCRYPTION_INSECURE
392      default N
393      help
394          If not set (default), the bootloader will permanently disable UART bootloader encryption access on first boot. If set, the UART bootloader will still be able to access hardware encryption.
395  
396          It is recommended to only set this option in testing environments.
397  
398  config FLASH_ENCRYPTION_UART_BOOTLOADER_ALLOW_DECRYPT
399      bool "Leave UART bootloader decryption enabled"
400      depends on FLASH_ENCRYPTION_INSECURE
401      default N
402      help
403          If not set (default), the bootloader will permanently disable UART bootloader decryption access on first boot. If set, the UART bootloader will still be able to access hardware decryption.
404  
405          Only set this option in testing environments. Setting this option allows complete bypass of flash encryption.
406  
407  config FLASH_ENCRYPTION_UART_BOOTLOADER_ALLOW_CACHE
408      bool "Leave UART bootloader flash cache enabled"
409      depends on FLASH_ENCRYPTION_INSECURE
410      default N
411      help
412          If not set (default), the bootloader will permanently disable UART bootloader flash cache access on first boot. If set, the UART bootloader will still be able to access the flash cache.
413  
414          Only set this option in testing environments.
415  
416  config SECURE_BOOT_TEST_MODE
417         bool "Secure boot test mode: don't permanently set any efuses"
418         depends on SECURE_BOOT_INSECURE
419         default N
420         help
421            If this option is set, all permanent secure boot changes (via Efuse) are disabled.
422  
423            Log output will state changes which would be applied, but they will not be.
424  
425            This option is for testing purposes only - it completely disables secure boot protection.
426  
427  
428  endmenu  # Potentially Insecure
429  endmenu  # Security features