1.. _burn-key-digest-cmd: 2 3Burn key Digest 4=============== 5 6The ``espefuse.py burn_key_digest`` command parses a RSA public key and burns the digest to eFuse block for use with `Secure Boot V2 <https://docs.espressif.com/projects/esp-idf/en/latest/{IDF_TARGET_PATH_NAME}/security/secure-boot-v2.html#signature-block-format>`_. 7 8Positional arguments: 9 10.. list:: 11 12 :not esp32 and not esp32c2: - ``block`` - Name of key block. 13 - ``Keyfile``. Key file to digest (PEM format). 14 :not esp32 and not esp32c2: - ``Key purpose``. The purpose of this key [``SECURE_BOOT_DIGEST0``, ``SECURE_BOOT_DIGEST1``, ``SECURE_BOOT_DIGEST2``]. 15 16.. only:: not esp32 and not esp32c2 17 18 It can be list of blocks and keyfiles and key purposes (like BLOCK_KEY0 keyfile0.pem SECURE_BOOT_DIGEST0 BLOCK_KEY1 keyfile1.pem SECURE_BOOT_DIGEST1 etc.). 19 20Optional arguments: 21 22.. list:: 23 24 :esp32: - ``--no-protect-key``. Disable default read and write protecting of the key. 25 :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. 26 :not esp32: - ``--no-read-protect``. Disable read-protecting of the key. This option does not change anything, because Secure Boot keys are readable anyway. 27 - ``--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. 28 - ``--show-sensitive-info``. Show data to be burned (may expose sensitive data). Enabled if --debug is used. Use this option to see the byte order of the data being written. 29 30.. only:: esp32 31 32 {IDF_TARGET_NAME} must have chip version > 3 (v300) and coding scheme = ``None`` otherwise an error will be shown. The key will be burned to BLOCK2. 33 34.. only:: esp32c2 35 36 The key will be burned to BLOCK3. 37 38The secure boot v2 key(s) will be readable and write protected. 39 40Usage 41----- 42 43.. only:: esp32 44 45 .. code-block:: none 46 47 > espefuse.py burn_key_digest secure_boot_key_v2_0.pem 48 49 === Run "burn_key_digest" command === 50 Sensitive data will be hidden (see --show-sensitive-info) 51 - BLOCK2 -> [?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ??] 52 Disabling write to efuse BLOCK2... 53 54 Check all blocks for burn... 55 idx, BLOCK_NAME, Conclusion 56 [00] BLOCK0 is empty, will burn the new value 57 [02] BLOCK2 is empty, will burn the new value 58 . 59 This is an irreversible operation! 60 Type 'BURN' (all capitals) to continue. 61 BURN 62 BURN BLOCK2 - OK (write block == read block) 63 BURN BLOCK0 - OK (write block == read block) 64 Reading updated efuses... 65 Successful 66 67 > espefuse.py summary 68 ... 69 BLOCK2 (BLOCK2): Secure boot key 70 = a2 cd 39 85 df 00 d7 95 07 0f f6 7c 8b ab e1 7d 39 11 95 c4 5b 37 6e 7b f0 ec 04 5e 36 30 02 5d R/- 71 72.. only:: esp32c2 73 74 See :ref:`perform-multiple-operations` for how to burn flash encryption and secure boot keys to the same eFuse key block at the same time. 75 76 .. code-block:: none 77 78 > espefuse.py burn_key_digest secure_boot_v2_ecdsa192.pem 79 80 === Run "burn_key_digest" command === 81 Sensitive data will be hidden (see --show-sensitive-info) 82 Burn keys to blocks: 83 - BLOCK_KEY0_HI_128 -> [?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ??] 84 Disabling write to key block 85 86 Check all blocks for burn... 87 idx, BLOCK_NAME, Conclusion 88 [00] BLOCK0 is empty, will burn the new value 89 [03] BLOCK_KEY0 is empty, will burn the new value 90 . 91 This is an irreversible operation! 92 Type 'BURN' (all capitals) to continue. 93 BURN 94 BURN BLOCK3 - OK (write block == read block) 95 BURN BLOCK0 - OK (write block == read block) 96 Reading updated efuses... 97 Successful 98 99 > espefuse.py summary 100 ... 101 XTS_KEY_LENGTH_256 (BLOCK0) Flash encryption key length = 128 bits key R/W (0b0) 102 ... 103 BLOCK_KEY0 (BLOCK3) BLOCK_KEY0 - 256-bits. 256-bit key of Flash Encryp 104 = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 02 c2 bd 9c 1a b4 b7 44 22 59 c6 d3 12 0b 79 1f R/- 105 tion 106 BLOCK_KEY0_LOW_128 (BLOCK3) BLOCK_KEY0 - lower 128-bits. 128-bit key of Flash 107 = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/- 108 Encryption 109 BLOCK_KEY0_HI_128 (BLOCK3) BLOCK_KEY0 - higher 128-bits. 128-bits key of Secu 110 = 02 c2 bd 9c 1a b4 b7 44 22 59 c6 d3 12 0b 79 1f R/- 111 re Boot. 112 113.. only:: esp32c3 or esp32s2 or esp32s3 114 115 .. code-block:: none 116 117 > espefuse.py burn_key_digest \ 118 BLOCK_KEY0 ~/esp/tests/efuse/secure_boot_key_v2_0.pem SECURE_BOOT_DIGEST0 \ 119 BLOCK_KEY1 ~/esp/tests/efuse/secure_boot_key_v2_1.pem SECURE_BOOT_DIGEST1 \ 120 BLOCK_KEY2 ~/esp/tests/efuse/secure_boot_key_v2_2.pem SECURE_BOOT_DIGEST2 121 122 === Run "burn_key_digest" command === 123 Sensitive data will be hidden (see --show-sensitive-info) 124 Burn keys to blocks: 125 - BLOCK_KEY0 -> [?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ??] 126 'KEY_PURPOSE_0': 'USER' -> 'SECURE_BOOT_DIGEST0'. 127 Disabling write to 'KEY_PURPOSE_0'. 128 Disabling write to key block 129 130 - BLOCK_KEY1 -> [?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ??] 131 'KEY_PURPOSE_1': 'USER' -> 'SECURE_BOOT_DIGEST1'. 132 Disabling write to 'KEY_PURPOSE_1'. 133 Disabling write to key block 134 135 - BLOCK_KEY2 -> [?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ??] 136 'KEY_PURPOSE_2': 'USER' -> 'SECURE_BOOT_DIGEST2'. 137 Disabling write to 'KEY_PURPOSE_2'. 138 Disabling write to key block 139 140 Check all blocks for burn... 141 idx, BLOCK_NAME, Conclusion 142 [00] BLOCK0 is empty, will burn the new value 143 [04] BLOCK_KEY0 is empty, will burn the new value 144 [05] BLOCK_KEY1 is empty, will burn the new value 145 [06] BLOCK_KEY2 is empty, will burn the new value 146 . 147 This is an irreversible operation! 148 Type 'BURN' (all capitals) to continue. 149 BURN 150 BURN BLOCK6 - OK (write block == read block) 151 BURN BLOCK5 - OK (write block == read block) 152 BURN BLOCK4 - OK (write block == read block) 153 BURN BLOCK0 - OK (write block == read block) 154 Reading updated efuses... 155 Successful 156 157 > espefuse.py summary 158 159 KEY_PURPOSE_0 (BLOCK0) KEY0 purpose = SECURE_BOOT_DIGEST0 R/- (0x9) 160 KEY_PURPOSE_1 (BLOCK0) KEY1 purpose = SECURE_BOOT_DIGEST1 R/- (0xa) 161 KEY_PURPOSE_2 (BLOCK0) KEY2 purpose = SECURE_BOOT_DIGEST2 R/- (0xb) 162 ... 163 BLOCK_KEY0 (BLOCK4) 164 Purpose: SECURE_BOOT_DIGEST0 165 Encryption key0 or user data 166 = a2 cd 39 85 df 00 d7 95 07 0f f6 7c 8b ab e1 7d 39 11 95 c4 5b 37 6e 7b f0 ec 04 5e 36 30 02 5d R/- 167 BLOCK_KEY1 (BLOCK5) 168 Purpose: SECURE_BOOT_DIGEST1 169 Encryption key1 or user data 170 = a3 cd 39 85 df 00 d7 95 07 0f f6 7c 8b ab e1 7d 39 11 95 c4 5b 37 6e 7b f0 ec 04 5e 36 30 02 5d R/- 171 BLOCK_KEY2 (BLOCK6) 172 Purpose: SECURE_BOOT_DIGEST2 173 Encryption key2 or user data 174 = a4 cd 39 85 df 00 d7 95 07 0f f6 7c 8b ab e1 7d 39 11 95 c4 5b 37 6e 7b f0 ec 04 5e 36 30 02 5d R/- 175
