components/bootloader/Kconfig.projbuild

   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 endmenu  # Bootloader
  66
  67
  68 menu "Security features"
  69
  70 config SECURE_BOOT_ENABLED
  71     bool "Enable secure boot in bootloader (READ DOCS FIRST)"
  72     default N
  73     help
  74         Build a bootloader which enables secure boot on first boot.
  75
  76         Once enabled, secure boot will not boot a modified bootloader. The bootloader will only load a partition table or boot an app if the data has a verified digital signature. There are implications for reflashing updated apps once secure boot is enabled.
  77
  78         When enabling secure boot, JTAG and ROM BASIC Interpreter are permanently disabled by default.
  79
  80         Refer to https://esp-idf.readthedocs.io/en/latest/security/secure-boot.html before enabling.
  81
  82 choice SECURE_BOOTLOADER_MODE
  83     bool "Secure bootloader mode"
  84     depends on SECURE_BOOT_ENABLED
  85     default SECURE_BOOTLOADER_ONE_TIME_FLASH
  86
  87 config SECURE_BOOTLOADER_ONE_TIME_FLASH
  88        bool "One-time flash"
  89        help
  90            On first boot, the bootloader will generate a key which is not readable externally or by software. A digest is generated from the bootloader image itself. This digest will be verified on each subsequent boot.
  91
  92            Enabling this option means that the bootloader cannot be changed after the first time it is booted.
  93
  94 config SECURE_BOOTLOADER_REFLASHABLE
  95     bool "Reflashable"
  96     help
  97         Generate a reusable secure bootloader key, derived (via SHA-256) from the secure boot signing key.
  98
  99         This allows the secure bootloader to be re-flashed by anyone with access to the secure boot signing key.
 100
 101         This option is less secure than one-time flash, because a leak of the digest key from one device allows reflashing of any device that uses it.
 102
 103 endchoice
 104
 105 config SECURE_BOOT_BUILD_SIGNED_BINARIES
 106      bool "Sign binaries during build"
 107      depends on SECURE_BOOT_ENABLED
 108      default y
 109      help
 110         Once secure boot is enabled, bootloader will only boot if partition table and app image are signed.
 111
 112         If enabled, these binary files are signed as part of the build process. The file named in "Secure boot private signing key" will be used to sign the image.
 113
 114         If disabled, unsigned app/partition data will be built. They must be signed manually using espsecure.py (for example, on a remote signing server.)
 115
 116 config SECURE_BOOT_SIGNING_KEY
 117      string "Secure boot private signing key"
 118      depends on SECURE_BOOT_BUILD_SIGNED_BINARIES
 119      default secure_boot_signing_key.pem
 120      help
 121         Path to the key file used to sign partition tables and app images for secure boot. Once secure boot is enabled, bootloader will only boot if partition table and app image are signed.
 122
 123         Key file is an ECDSA private key (NIST256p curve) in PEM format.
 124
 125         Path is evaluated relative to the project directory.
 126
 127         You can generate a new signing key by running the following command:
 128         espsecure.py generate_signing_key secure_boot_signing_key.pem
 129
 130         See docs/security/secure-boot.rst for details.
 131
 132 config SECURE_BOOT_VERIFICATION_KEY
 133     string "Secure boot public signature verification key"
 134     depends on SECURE_BOOT_ENABLED && !SECURE_BOOT_BUILD_SIGNED_BINARIES
 135     default signature_verification_key.bin
 136     help
 137        Path to a public key file used to verify signed images. This key is compiled into the bootloader,
 138        and may also be used to verify signatures on OTA images after download.
 139
 140        Key file is in raw binary format, and can be extracted from a
 141        PEM formatted private key using the espsecure.py
 142        extract_public_key command.
 143
 144        Refer to https://esp-idf.readthedocs.io/en/latest/security/secure-boot.html before enabling.
 145
 146 config SECURE_BOOT_INSECURE
 147     bool "Allow potentially insecure options"
 148     depends on SECURE_BOOT_ENABLED
 149     default N
 150     help
 151        You can disable some of the default protections offered by secure boot, in order to enable testing or a custom combination of security features.
 152
 153        Only enable these options if you are very sure.
 154
 155        Refer to https://esp-idf.readthedocs.io/en/latest/security/secure-boot.html before enabling.
 156
 157 config FLASH_ENCRYPTION_ENABLED
 158     bool "Enable flash encryption on boot (READ DOCS FIRST)"
 159     default N
 160     help
 161        If this option is set, flash contents will be encrypted by the bootloader on first boot.
 162
 163        Note: After first boot, the system will be permanently encrypted. Re-flashing an encrypted
 164        system is complicated and not always possible.
 165
 166        Read https://esp-idf.readthedocs.io/en/latest/security/flash-encryption.html before enabling.
 167
 168 config FLASH_ENCRYPTION_INSECURE
 169     bool "Allow potentially insecure options"
 170     depends on FLASH_ENCRYPTION_ENABLED
 171     default N
 172     help
 173        You can disable some of the default protections offered by flash encryption, in order to enable testing or a custom combination of security features.
 174
 175        Only enable these options if you are very sure.
 176
 177        Refer to docs/security/secure-boot.rst and docs/security/flash-encryption.rst for details.
 178
 179 menu "Potentially insecure options"
 180     visible if FLASH_ENCRYPTION_INSECURE || SECURE_BOOT_INSECURE
 181
 182 # NOTE: Options in this menu NEED to have SECURE_BOOT_INSECURE
 183 # and/or FLASH_ENCRYPTION_INSECURE in "depends on", as the menu
 184 # itself doesn't enable/disable its children (if it's not set,
 185 # it's possible for the insecure menu to be disabled but the insecure option
 186 # to remain on which is very bad.)
 187
 188 config SECURE_BOOT_ALLOW_ROM_BASIC
 189        bool "Leave ROM BASIC Interpreter available on reset"
 190        depends on SECURE_BOOT_INSECURE || FLASH_ENCRYPTION_INSECURE
 191        default N
 192        help
 193           By default, the BASIC ROM Console starts on reset if no valid bootloader is
 194           read from the flash.
 195
 196           When either flash encryption or secure boot are enabled, the default is to
 197           disable this BASIC fallback mode permanently via efuse.
 198
 199           If this option is set, this efuse is not burned and the BASIC ROM Console may
 200           remain accessible.  Only set this option in testing environments.
 201
 202 config SECURE_BOOT_ALLOW_JTAG
 203        bool "Allow JTAG Debugging"
 204        depends on SECURE_BOOT_INSECURE || FLASH_ENCRYPTION_INSECURE
 205        default N
 206        help
 207           If not set (default), the bootloader will permanently disable JTAG (across entire chip) on first boot when either secure boot or flash encryption is enabled.
 208
 209           Setting this option leaves JTAG on for debugging, which negates all protections of flash encryption and some of the protections of secure boot.
 210
 211           Only set this option in testing environments.
 212
 213
 214 config FLASH_ENCRYPTION_UART_BOOTLOADER_ALLOW_ENCRYPT
 215     bool "Leave UART bootloader encryption enabled"
 216     depends on FLASH_ENCRYPTION_INSECURE
 217     default N
 218     help
 219         If not set (default), the bootloader will permanently disable UART bootloader encryption access on first boot. If set, the UART bootloader will still be able to access hardware encryption.
 220
 221         It is recommended to only set this option in testing environments.
 222
 223 config FLASH_ENCRYPTION_UART_BOOTLOADER_ALLOW_DECRYPT
 224     bool "Leave UART bootloader decryption enabled"
 225     depends on FLASH_ENCRYPTION_INSECURE
 226     default N
 227     help
 228         If not set (default), the bootloader will permanently disable UART bootloader decryption access on first boot. If set, the UART bootloader will still be able to access hardware decryption.
 229
 230         Only set this option in testing environments. Setting this option allows complete bypass of flash encryption.
 231
 232 config FLASH_ENCRYPTION_UART_BOOTLOADER_ALLOW_CACHE
 233     bool "Leave UART bootloader flash cache enabled"
 234     depends on FLASH_ENCRYPTION_INSECURE
 235     default N
 236     help
 237         If not set (default), the bootloader will permanently disable UART bootloader flash cache access on first boot. If set, the UART bootloader will still be able to access the flash cache.
 238
 239         Only set this option in testing environments.
 240
 241 config SECURE_BOOT_TEST_MODE
 242        bool "Secure boot test mode: don't permanently set any efuses"
 243        depends on SECURE_BOOT_INSECURE
 244        default N
 245        help
 246           If this option is set, all permanent secure boot changes (via Efuse) are disabled.
 247
 248           Log output will state changes which would be applied, but they will not be.
 249
 250           This option is for testing purposes only - it completely disables secure boot protection.
 251
 252
 253 endmenu  # Potentially Insecure
 254 endmenu  # Security features