1.. _burn-key-cmd: 2 3Burn Key 4======== 5 6The ``espefuse.py burn_key`` command burns keys to eFuse blocks: 7 8.. list:: 9 10 :esp32: - `Secure Boot V1 <https://docs.espressif.com/projects/esp-idf/en/latest/{IDF_TARGET_PATH_NAME}/security/secure-boot-v1.html>`_ 11 - `Secure Boot V2 <https://docs.espressif.com/projects/esp-idf/en/latest/{IDF_TARGET_PATH_NAME}/security/secure-boot-v2.html>`_ 12 - `Flash Encryption <https://docs.espressif.com/projects/esp-idf/en/latest/{IDF_TARGET_PATH_NAME}/security/flash-encryption.html>`_ 13 - etc. 14 15Positional arguments: 16 17.. list:: 18 19 - ``block`` - Name of key block. 20 :esp32: - ``Keyfile``. It is a raw binary file. It must contain 256 bits of binary key if the coding scheme is ``None`` and 128 bits if ``3/4``. 21 :not esp32: - ``Keyfile``. It is a raw binary file. The length of binary key depends on the key purpose option. 22 :not esp32: - ``Key purpose``. The purpose of this key. 23 24.. only:: esp32 25 26 It can be list of key blocks and keyfiles (like BLOCK1 file1.bin BLOCK2 file2.bin etc.). 27 28.. only:: not esp32 29 30 It can be list of key blocks and keyfiles and key purposes (like BLOCK_KEY1 file1.bin USER BLOCK_KEY2 file2.bin USER etc.). 31 32Optional arguments: 33 34.. list:: 35 36 :esp32: - ``--no-protect-key``. Disable default read and write protecting of the key. If this option is not set, once the key is flashed it can not be read back. 37 :not esp32: - ``--no-write-protect``. Disable write-protecting of the key. The key remains writable. The keys use the RS coding scheme that does not support post-write data changes. Forced write can damage RS encoding bits. The write-protecting of keypurposes does not depend on the option, it will be set anyway. 38 :not esp32: - ``--no-read-protect``. Disable read-protecting of the key. The key remains readable software. The key with keypurpose [USER, RESERVED and .._DIGEST] will remain readable anyway, but for the rest keypurposes the read-protection will be defined by this option (Read-protect by default). 39 - ``--force-write-always``. Write the eFuse key even if it looks like it is already been written, or is write protected. Note that this option can't disable write protection, or clear any bit which has already been set. 40 41.. only:: esp32 42 43 {IDF_TARGET_NAME} supportes keys: 44 45 * Secure boot key. Use ``secure_boot_v1`` or ``secure_boot_v2`` as block name. The key is placed in BLOCK2. 46 * Flash encryption key. Use ``flash_encryption`` as block name. The key is placed in BLOCK1. 47 48 Keys for ``flash_encryption`` and ``secure_boot_v1`` will be burned as read and write protected. The hardware will still have access to them. These keys are burned in reversed byte order. 49 50 Key for ``secure_boot_v2`` will be burned only as write protected. The key must be readable because the software need acces to it. 51 52 .. warning:: 53 54 Do not use the names ``BLOCK1`` and ``BLOCK2`` to burn flash encryption and secure boot v2 keys because byte order will be incorrect and read protection will not meet security requirements. 55 56.. only:: esp32c3 or esp32s2 or esp32s3 57 58 {IDF_TARGET_NAME} supportes eFuse key purposes. This means that each eFuse block has a special eFuse field that indicates which key is in the eFuse block. During the burn operation this eFuse key purpose is burned as well with write protection (the ``--no-write-protect`` flag has no effect on this field). The {IDF_TARGET_NAME} chip supports the following key purposes: 59 60 .. list:: 61 62 - USER. 63 - RESERVED. 64 :esp32s2 or esp32s3: - XTS_AES_256_KEY_1. The first 256 bits of 512bit flash encryption key. 65 :esp32s2 or esp32s3: - XTS_AES_256_KEY_2. The second 256 bits of 512bit flash encryption key. 66 - XTS_AES_128_KEY. 256 bit flash encryption key. 67 - HMAC_DOWN_ALL. 68 - HMAC_DOWN_JTAG. 69 - HMAC_DOWN_DIGITAL_SIGNATURE. 70 - HMAC_UP. 71 - SECURE_BOOT_DIGEST0. 1 secure boot key. 72 - SECURE_BOOT_DIGEST1. 2 secure boot key. 73 - SECURE_BOOT_DIGEST2. 3 secure boot key. 74 :esp32s2 or esp32s3: - XTS_AES_256_KEY. This is a virtual key purpose for flash encryption key. This allows you to write a whole 512-bit key into two blocks with ``XTS_AES_256_KEY_1`` and ``XTS_AES_256_KEY_2`` purposes without splitting the key file. 75 76.. only:: esp32c2 77 78 {IDF_TARGET_NAME} has only one eFuse key block (256 bits long). It is block #3 - ``BLOCK_KEY0``. This block can have user, flash encryption, secure boot keys. This chip does not have any eFuse key purpose fields, but we use the key purpose option to distinguish between such keys. The key purpose option determines protection and byte order for key. 79 80 .. list:: 81 82 - USER 83 - XTS_AES_128_KEY. 256 bits flash encryption key. The secure boot key can not be used with this option. In addition, eFuse ``XTS_KEY_LENGTH_256`` is set to 1, which means that the flash encryption key is 256 bits long. 84 - XTS_AES_128_KEY_DERIVED_FROM_128_EFUSE_BITS. 128 bits flash encryption key. The 128 bits of this key will be burned to the low part of the eFuse block. These bits will be read protected. 85 - SECURE_BOOT_DIGEST. Secure boot key. The first 128 bits of key will be burned to the high part of the eFuse block. 86 87 {IDF_TARGET_NAME} can have in eFuse block the following combination of keys: 88 89 1. Both, Flash encryption (low 128 bits of eFuse block) and Secure boot key (high 128 bits of eFuse block). 90 2. only Flash encryption (low 128 bits of eFuse block), rest part of eFuse block is not possible to use in future. 91 3. only Flash encryption key (256 bits long), whole eFuse key block. 92 4. only Secure boot key (high 128 bits of eFuse block). 93 5. no keys, used for user purposes. Chip does not have security features. 94 95.. only:: not esp32 96 97 All keys will be burned with write protection if ``--no-write-protect`` is not used. 98 99 Only flash encryption key is read protected if ``--no-read-protect`` is not used. 100 101 All keys, except flash encryption, will be burned in direct byte order. The encryption key is written in reverse byte order for compatibility with encryption hardware. 102 103.. only:: esp32 104 105 Key Coding Scheme 106 ^^^^^^^^^^^^^^^^^ 107 108 When the ``None`` coding scheme is in use, keys are 256-bits (32 bytes) long. When 3/4 Coding Scheme is in use (``CODING_SCHEME`` eFuse has value 1 not 0), keys are 192-bits (24 bytes) long and an additional 64 bits of error correction data are also written. 109 espefuse v2.6 or newer supports the 3/4 Coding Scheme. The key file must be the appropriate length for the coding scheme currently in use. 110 111Unprotected Keys 112^^^^^^^^^^^^^^^^ 113 114By default, when an encryption key block is burned it is also read and write protected. 115 116.. only:: esp32 117 118 The ``--no-protect-key`` option will disable this behaviour (you can separately read or write protect the key later). 119 120.. only:: not esp32 121 122 The ``--no-read-protect`` and ``--no-write-protect`` options will disable this behaviour (you can separately read or write protect the key later). 123 124.. note:: 125 126 Leaving a key unprotected may compromise its use as a security feature. 127 128.. code-block:: none 129 130 espefuse.py burn_key secure_boot_v1 secure_boot_key_v1.bin 131 132.. only:: esp32 133 134 Note that the hardware flash encryption and secure boot v1 features require the key to be written to the eFuse block in reversed byte order, compared to the order used by the AES algorithm on the host. Using corresponding block name, the tool automatically reverses the bytes when writing. For this reason, an unprotected key will read back in the reverse order. 135 136Force Writing a Key 137^^^^^^^^^^^^^^^^^^^ 138 139Normally, a key will only be burned if the efuse block has not been previously written to. The ``--force-write-always`` option can be used to ignore this and try to burn the key anyhow. 140 141Note that this option is still limited by the eFuse hardware - hardware does not allow any eFuse bits to be cleared 1->0, and can not write anything to write protected eFuse blocks. 142 143Usage 144----- 145 146.. only:: esp32 147 148 .. code-block:: none 149 150 > espefuse.py burn_key flash_encryption 256bit_fe_key.bin 151 152 === Run "burn_key" command === 153 Burn keys to blocks: 154 - BLOCK1 -> [1f 1e 1d 1c 1b 1a 19 18 17 16 15 14 13 12 11 10 0f 0e 0d 0c 0b 0a 09 08 07 06 05 04 03 02 01 00] 155 Reversing the byte order 156 Disabling read to key block 157 Disabling write to key block 158 159 Burn keys in efuse blocks. 160 The key block will be read and write protected 161 162 Check all blocks for burn... 163 idx, BLOCK_NAME, Conclusion 164 [00] BLOCK0 is empty, will burn the new value 165 [01] BLOCK1 is empty, will burn the new value 166 . 167 This is an irreversible operation! 168 Type 'BURN' (all capitals) to continue. 169 BURN 170 BURN BLOCK1 - OK (write block == read block) 171 BURN BLOCK0 - OK (write block == read block) 172 Reading updated efuses... 173 Successful 174 175 .. code-block:: none 176 177 > espefuse.py summary 178 ... 179 BLOCK1 (BLOCK1): Flash encryption key 180 = ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? -/- 181 182 Byte order for flash encryption key is reversed. Content of flash encryption key file ("256bit_fe_key.bin"): 183 184 .. code-block:: none 185 186 0001 0203 0405 0607 0809 0a0b 0c0d 0e0f 1011 1213 1415 1617 1819 1a1b 1c1d 1e1f 187 188 When the ``no protection`` option is used then you can see the burned key: 189 190 .. code-block:: none 191 192 > espefuse.py burn_key flash_encryption 256bit_fe_key.bin --no-protect-key 193 194 === Run "burn_key" command === 195 Burn keys to blocks: 196 - BLOCK1 -> [1f 1e 1d 1c 1b 1a 19 18 17 16 15 14 13 12 11 10 0f 0e 0d 0c 0b 0a 09 08 07 06 05 04 03 02 01 00] 197 Reversing the byte order 198 199 Key is left unprotected as per --no-protect-key argument. 200 Burn keys in efuse blocks. 201 The key block will left readable and writeable (due to --no-protect-key) 202 203 Check all blocks for burn... 204 idx, BLOCK_NAME, Conclusion 205 [01] BLOCK1 is empty, will burn the new value 206 . 207 This is an irreversible operation! 208 Type 'BURN' (all capitals) to continue. 209 BURN 210 BURN BLOCK1 - OK (write block == read block) 211 Reading updated efuses... 212 Successful 213 214 .. code-block:: none 215 216 > espefuse.py summary 217 ... 218 BLOCK1 (BLOCK1): Flash encryption key 219 = 1f 1e 1d 1c 1b 1a 19 18 17 16 15 14 13 12 11 10 0f 0e 0d 0c 0b 0a 09 08 07 06 05 04 03 02 01 00 R/W 220 221.. only:: esp32s2 or esp32s3 222 223 Burning XTS_AES_256_KEY: 224 225 The first 256 bit of the key goes to given BLOCK (here it is ``BLOCK_KEY0``) with key purpose = ``XTS_AES_256_KEY_1``. The last 256 bit of the key will be burned to the first free key block after BLOCK (here it is ``BLOCK_KEY1``) and set key purpose to ``XTS_AES_256_KEY_2`` for this block. 226 227 This example uses ``--no-read-protect`` to expose the byte order written into eFuse blocks. 228 229 Content of flash encryption key file (``512bits_0.bin``): 230 231 .. code-block:: none 232 233 0001 0203 0405 0607 0809 0a0b 0c0d 0e0f 1011 1213 1415 1617 1819 1a1b 1c1d 1e1f 234 2021 2223 2425 2627 2829 2a2b 2c2d 2e2f 3031 3233 3435 3637 3839 3a3b 3c3d 3e3f 235 236 .. code-block:: none 237 238 > espefuse.py burn_key BLOCK_KEY0 ~/esp/tests/efuse/512bits_0.bin XTS_AES_256_KEY --no-read-protect 239 240 === Run "burn_key" command === 241 Burn keys to blocks: 242 - BLOCK_KEY0 -> [1f 1e 1d 1c 1b 1a 19 18 17 16 15 14 13 12 11 10 0f 0e 0d 0c 0b 0a 09 08 07 06 05 04 03 02 01 00] 243 Reversing byte order for AES-XTS hardware peripheral 244 'KEY_PURPOSE_0': 'USER' -> 'XTS_AES_256_KEY_1'. 245 Disabling write to 'KEY_PURPOSE_0'. 246 Disabling write to key block 247 248 - BLOCK_KEY1 -> [3f 3e 3d 3c 3b 3a 39 38 37 36 35 34 33 32 31 30 2f 2e 2d 2c 2b 2a 29 28 27 26 25 24 23 22 21 20] 249 Reversing byte order for AES-XTS hardware peripheral 250 'KEY_PURPOSE_1': 'USER' -> 'XTS_AES_256_KEY_2'. 251 Disabling write to 'KEY_PURPOSE_1'. 252 Disabling write to key block 253 254 Keys will remain readable (due to --no-read-protect) 255 256 Check all blocks for burn... 257 idx, BLOCK_NAME, Conclusion 258 [00] BLOCK0 is empty, will burn the new value 259 [04] BLOCK_KEY0 is empty, will burn the new value 260 [05] BLOCK_KEY1 is empty, will burn the new value 261 . 262 This is an irreversible operation! 263 Type 'BURN' (all capitals) to continue. 264 BURN 265 BURN BLOCK5 - OK (write block == read block) 266 BURN BLOCK4 - OK (write block == read block) 267 BURN BLOCK0 - OK (write block == read block) 268 Reading updated efuses... 269 Successful 270 271 > espefuse.py summary 272 ... 273 KEY_PURPOSE_0 (BLOCK0) KEY0 purpose = XTS_AES_256_KEY_1 R/- (0x2) 274 KEY_PURPOSE_1 (BLOCK0) KEY1 purpose = XTS_AES_256_KEY_2 R/- (0x3) 275 ... 276 BLOCK_KEY0 (BLOCK4) 277 Purpose: XTS_AES_256_KEY_1 278 Encryption key0 or user data 279 = 1f 1e 1d 1c 1b 1a 19 18 17 16 15 14 13 12 11 10 0f 0e 0d 0c 0b 0a 09 08 07 06 05 04 03 02 01 00 R/- 280 BLOCK_KEY1 (BLOCK5) 281 Purpose: XTS_AES_256_KEY_2 282 Encryption key1 or user data 283 = 3f 3e 3d 3c 3b 3a 39 38 37 36 35 34 33 32 31 30 2f 2e 2d 2c 2b 2a 29 28 27 26 25 24 23 22 21 20 R/- 284 285.. only:: esp32c2 286 287 .. code-block:: none 288 289 > espefuse.py -c esp32c2 \ 290 burn_key_digest secure_images/ecdsa256_secure_boot_signing_key_v2.pem \ 291 burn_key BLOCK_KEY0 images/efuse/128bit_key.bin XTS_AES_128_KEY_DERIVED_FROM_128_EFUSE_BITS 292 293 === Run "burn_key_digest" command === 294 Burn keys to blocks: 295 - BLOCK_KEY0_HI_128 -> [bf 0f 6a f6 8b d3 6d 8b 53 b3 da a9 33 f6 0a 04] 296 Disabling write to key block 297 298 299 Batch mode is enabled, the burn will be done at the end of the command. 300 301 === Run "burn_key" command === 302 Burn keys to blocks: 303 - BLOCK_KEY0_LOW_128 -> [0f 0e 0d 0c 0b 0a 09 08 07 06 05 04 03 02 01 00] 304 Reversing byte order for AES-XTS hardware peripheral 305 Disabling read to key block 306 Disabling write to key block 307 The same value for WR_DIS is already burned. Do not change the efuse. 308 309 Batch mode is enabled, the burn will be done at the end of the command. 310 311 Check all blocks for burn... 312 idx, BLOCK_NAME, Conclusion 313 [00] BLOCK0 is empty, will burn the new value 314 [03] BLOCK_KEY0 is empty, will burn the new value 315 . 316 This is an irreversible operation! 317 Type 'BURN' (all capitals) to continue. 318 BURN 319 BURN BLOCK3 - OK (write block == read block) 320 BURN BLOCK0 - OK (write block == read block) 321 Reading updated efuses... 322
