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 29.. only:: esp32 30 31 {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. 32 33.. only:: esp32c2 34 35 The key will be burned to BLOCK3. 36 37The secure boot v2 key(s) will be readable and write protected. 38 39Usage 40----- 41 42.. only:: esp32 43 44 .. code-block:: none 45 46 > espefuse.py burn_key_digest secure_boot_key_v2_0.pem 47 48 === Run "burn_key_digest" command === 49 - BLOCK2 -> [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] 50 Disabling write to efuse BLOCK2... 51 52 Check all blocks for burn... 53 idx, BLOCK_NAME, Conclusion 54 [00] BLOCK0 is empty, will burn the new value 55 [02] BLOCK2 is empty, will burn the new value 56 . 57 This is an irreversible operation! 58 Type 'BURN' (all capitals) to continue. 59 BURN 60 BURN BLOCK2 - OK (write block == read block) 61 BURN BLOCK0 - OK (write block == read block) 62 Reading updated efuses... 63 Successful 64 65 > espefuse.py summary 66 ... 67 BLOCK2 (BLOCK2): Secure boot key 68 = 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/- 69 70.. only:: esp32c2 71 72 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. 73 74 .. code-block:: none 75 76 > espefuse.py burn_key_digest secure_boot_v2_ecdsa192.pem 77 78 === Run "burn_key_digest" command === 79 Burn keys to blocks: 80 - BLOCK_KEY0_HI_128 -> [02 c2 bd 9c 1a b4 b7 44 22 59 c6 d3 12 0b 79 1f] 81 Disabling write to key block 82 83 Check all blocks for burn... 84 idx, BLOCK_NAME, Conclusion 85 [00] BLOCK0 is empty, will burn the new value 86 [03] BLOCK_KEY0 is empty, will burn the new value 87 . 88 This is an irreversible operation! 89 Type 'BURN' (all capitals) to continue. 90 BURN 91 BURN BLOCK3 - OK (write block == read block) 92 BURN BLOCK0 - OK (write block == read block) 93 Reading updated efuses... 94 Successful 95 96 > espefuse.py summary 97 ... 98 XTS_KEY_LENGTH_256 (BLOCK0) Flash encryption key length = 128 bits key R/W (0b0) 99 ... 100 BLOCK_KEY0 (BLOCK3) BLOCK_KEY0 - 256-bits. 256-bit key of Flash Encryp 101 = 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/- 102 tion 103 BLOCK_KEY0_LOW_128 (BLOCK3) BLOCK_KEY0 - lower 128-bits. 128-bit key of Flash 104 = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/- 105 Encryption 106 BLOCK_KEY0_HI_128 (BLOCK3) BLOCK_KEY0 - higher 128-bits. 128-bits key of Secu 107 = 02 c2 bd 9c 1a b4 b7 44 22 59 c6 d3 12 0b 79 1f R/- 108 re Boot. 109 110.. only:: esp32c3 or esp32s2 or esp32s3 111 112 .. code-block:: none 113 114 > espefuse.py burn_key_digest \ 115 BLOCK_KEY0 ~/esp/tests/efuse/secure_boot_key_v2_0.pem SECURE_BOOT_DIGEST0 \ 116 BLOCK_KEY1 ~/esp/tests/efuse/secure_boot_key_v2_1.pem SECURE_BOOT_DIGEST1 \ 117 BLOCK_KEY2 ~/esp/tests/efuse/secure_boot_key_v2_2.pem SECURE_BOOT_DIGEST2 118 119 === Run "burn_key_digest" command === 120 Burn keys to blocks: 121 - BLOCK_KEY0 -> [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] 122 'KEY_PURPOSE_0': 'USER' -> 'SECURE_BOOT_DIGEST0'. 123 Disabling write to 'KEY_PURPOSE_0'. 124 Disabling write to key block 125 126 - BLOCK_KEY1 -> [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] 127 'KEY_PURPOSE_1': 'USER' -> 'SECURE_BOOT_DIGEST1'. 128 Disabling write to 'KEY_PURPOSE_1'. 129 Disabling write to key block 130 131 - BLOCK_KEY2 -> [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] 132 'KEY_PURPOSE_2': 'USER' -> 'SECURE_BOOT_DIGEST2'. 133 Disabling write to 'KEY_PURPOSE_2'. 134 Disabling write to key block 135 136 Check all blocks for burn... 137 idx, BLOCK_NAME, Conclusion 138 [00] BLOCK0 is empty, will burn the new value 139 [04] BLOCK_KEY0 is empty, will burn the new value 140 [05] BLOCK_KEY1 is empty, will burn the new value 141 [06] BLOCK_KEY2 is empty, will burn the new value 142 . 143 This is an irreversible operation! 144 Type 'BURN' (all capitals) to continue. 145 BURN 146 BURN BLOCK6 - OK (write block == read block) 147 BURN BLOCK5 - OK (write block == read block) 148 BURN BLOCK4 - OK (write block == read block) 149 BURN BLOCK0 - OK (write block == read block) 150 Reading updated efuses... 151 Successful 152 153 > espefuse.py summary 154 155 KEY_PURPOSE_0 (BLOCK0) KEY0 purpose = SECURE_BOOT_DIGEST0 R/- (0x9) 156 KEY_PURPOSE_1 (BLOCK0) KEY1 purpose = SECURE_BOOT_DIGEST1 R/- (0xa) 157 KEY_PURPOSE_2 (BLOCK0) KEY2 purpose = SECURE_BOOT_DIGEST2 R/- (0xb) 158 ... 159 BLOCK_KEY0 (BLOCK4) 160 Purpose: SECURE_BOOT_DIGEST0 161 Encryption key0 or user data 162 = 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/- 163 BLOCK_KEY1 (BLOCK5) 164 Purpose: SECURE_BOOT_DIGEST1 165 Encryption key1 or user data 166 = 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/- 167 BLOCK_KEY2 (BLOCK6) 168 Purpose: SECURE_BOOT_DIGEST2 169 Encryption key2 or user data 170 = 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/- 171
