feat(espefuse): Support burning ECDSA_384 keys

Author: KonstantinKondrashov

docs/en/espefuse/burn-key-cmd.rst

@@ -63,9 +63,14 @@ Optional arguments:
 
         - USER.
         - RESERVED.
-        :esp32c5 or esp32c61 or esp32p4 or esp32s2 or esp32s3: - XTS_AES_256_KEY_1. The first 256 bits of 512bit flash encryption key.
-        :esp32c5 or esp32c61 or esp32p4 or esp32s2 or esp32s3: - XTS_AES_256_KEY_2. The second 256 bits of 512bit flash encryption key.
-        ::esp32c5 or esp32c61 or esp32h2 or esp32h21 or esp32h4 or esp32p4: - ECDSA_KEY. It can be ECDSA private keys based on NIST192p or NIST256p curve. The private key is extracted from the given file and written into a eFuse block with write and read protection enabled. This private key shall be used by ECDSA accelerator for the signing purpose.
+        :esp32c5 or esp32p4 or esp32s2 or esp32s3: - XTS_AES_256_KEY_1. The first 256 bits of 512bit flash encryption key.
+        :esp32c5 or esp32p4 or esp32s2 or esp32s3: - XTS_AES_256_KEY_2. The second 256 bits of 512bit flash encryption key.
+        :esp32c5 or esp32c61 or esp32h2 or esp32h21 or esp32h4 or esp32p4: - ECDSA_KEY. It can be ECDSA private keys based on NIST192p or NIST256p curve. The private key is extracted from the given file and written into a eFuse block with write and read protection enabled. This private key shall be used by ECDSA accelerator for the signing purpose.
+        :esp32c5: - ECDSA_KEY_P192. ECDSA private keys based on NIST192p curve.
+        :esp32c5: - ECDSA_KEY_P256. ECDSA private keys based on NIST256p curve.
+        :esp32c5: - ECDSA_KEY_P384. ECDSA private keys based on NIST384p curve. This allows you to write a whole 48-byte key into two blocks with ``ECDSA_KEY_P384_H`` and ``ECDSA_KEY_P384_L`` purposes.
+        :esp32c5: - ECDSA_KEY_P384_H. Upper 32 bytes of the 48-byte ECDSA_P384 key (last 16 bytes of key + 16 padding bytes).
+        :esp32c5: - ECDSA_KEY_P384_L. Lower 32 bytes of the 48-byte ECDSA_P384 key.
         - XTS_AES_128_KEY. 256 bit flash encryption key.
         - HMAC_DOWN_ALL.
         - HMAC_DOWN_JTAG.
@@ -74,17 +79,21 @@ Optional arguments:
         - SECURE_BOOT_DIGEST0. 1 secure boot key.
         - SECURE_BOOT_DIGEST1. 2 secure boot key.
         - SECURE_BOOT_DIGEST2. 3 secure boot key.
-        :esp32c5 or esp32c61 or esp32p4 or 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.
+        :esp32c5 or esp32p4 or 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.
         :esp32c5: - XTS_AES_256_PSRAM_KEY. This is a virtual key purpose for psram encryption key. This allows you to write a whole 512-bit key into two blocks with ``XTS_AES_256_PSRAM_KEY_1`` and ``XTS_AES_256_PSRAM_KEY_2`` purposes without splitting the key file.
         :esp32c5: - XTS_AES_256_PSRAM_KEY_1. The first 256 bits of 512bit psram encryption key.
         :esp32c5: - XTS_AES_256_PSRAM_KEY_2. The second 256 bits of 512bit psram encryption key.
         :esp32c5 or esp32h4 or esp32p4: - KM_INIT_KEY. This is a key that is used for the generation of AES/ECDSA keys by the key manager.
 
-.. only:: esp32h2
+.. only:: esp32c5 or esp32c61 or esp32h2 or esp32h21 or esp32h4 or esp32p4
 
-    {IDF_TARGET_NAME} has the ECDSA accelerator for signature purposes and supports private keys based on the NIST192p or NIST256p curve. These two commands below can be used to generate such keys (``PEM`` file). The ``burn_key`` command with the ``ECDSA_KEY`` purpose takes the ``PEM`` file and writes the private key into a eFuse block. The key is written to the block in reverse byte order.
+    {IDF_TARGET_NAME} has the ECDSA accelerator for signature purposes and supports private keys based on the NIST192p or NIST256p curve (some chips support NIST384p). These two commands below can be used to generate such keys (``PEM`` file). The ``burn-key`` command with the ``ECDSA_KEY`` purpose takes the ``PEM`` file and writes the private key into a eFuse block. The key is written to the block in reverse byte order.
 
-    For NIST192p, the private key is 192 bits long, so 8 padding bytes ("0x00") are added.
+    .. list::
+
+      - For NIST192p, the private key is 192 bits long, so 8 padding bytes ("0x00") are added.
+      - For NIST256p, the private key is 256 bits long.
+      - For NIST384p, the private key is 384 bits long, so 16 padding bytes ("0x00") are added.
 
     .. code-block:: none
 
@@ -347,3 +356,44 @@ Usage
         BURN BLOCK3  - OK (write block == read block)
         BURN BLOCK0  - OK (write block == read block)
         Reading updated efuses...
+
+.. only:: esp32c5
+
+    .. code-block:: none
+
+        > espefuse -c esp32c2  BLOCK_KEY0 secure_images/ecdsa384_secure_boot_signing_key.pem ECDSA_KEY_P384 --no-read-protect --show-sensitive-info
+
+        === Run "burn-key" command ===
+        Burn keys to blocks:
+        - BLOCK_KEY0 -> [0e d2 8e c6 86 f0 f6 af 50 51 c3 5c 41 2b c7 48 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00]
+                Reversing byte order for ECDSA_KEY_P384_H hardware peripheral...
+                'KEY_PURPOSE_0': 'USER' -> 'ECDSA_KEY_P384_H'.
+                Disabling write to 'KEY_PURPOSE_0'...
+                Disabling write to key block...
+
+        - BLOCK_KEY1 -> [65 ca a4 5b 5f 67 5c fe 34 89 f3 4a 57 d1 5a 41 d6 1c 7d ea 7a 3f cd 34 79 f2 94 c2 ad cb 94 7d]
+                Reversing byte order for ECDSA_KEY_P384_L hardware peripheral...
+                'KEY_PURPOSE_1': 'USER' -> 'ECDSA_KEY_P384_L'.
+                Disabling write to 'KEY_PURPOSE_1'...
+                Disabling write to key block...
+
+        Keys will remain readable (due to --no-read-protect).
+
+        Check all blocks for burn...
+        idx, BLOCK_NAME,          Conclusion
+        [00] BLOCK0               is empty, will burn the new value
+        [04] BLOCK_KEY0           is empty, will burn the new value
+        [05] BLOCK_KEY1           is empty, will burn the new value
+        .
+        This is an irreversible operation!
+        Type 'BURN' (all capitals) to continue.
+        BURN
+        BURN BLOCK5  - OK (write block == read block)
+        BURN BLOCK4  - OK (write block == read block)
+        BURN BLOCK0  - OK (write block == read block)
+        Reading updated eFuses...
+        Successful.
+
+    .. note::
+
+        The flags ``--no-read-protect`` and ``--show-sensitive-info`` in this command are used for demonstration purposes only, to show the key byte order. The ECDSA_KEY keys is always written in reverse byte order. The 48 bytes of the key are extracted from the provided PEM file, and 16 padding bytes are added to form a total of 64 bytes for two eFuse blocks. Due to the required reverse byte order, the last 16 bytes of the key plus 16 padding bytes are written to BLOCK_KEY0 with the key purpose ``ECDSA_KEY_P384_H``, and the remaining 32 bytes are written to the next available eFuse block (here, BLOCK_KEY1) with the key purpose ``ECDSA_KEY_P384_L``.

espefuse/efuse/base_operations.py

@@ -12,6 +12,7 @@
 
 from bitstring import BitStream
 
+import espsecure
 import esptool
 
 from . import base_fields
@@ -839,12 +840,95 @@ def _get_next_key_block(efuses, current_key_block, block_name_list):
     return None
 
 
-def split_512_bit_key(
+def adjust_key_data_for_blocks(efuses, block_names, datafiles, keypurposes):
+    """Split a key that takes more than one efuse block into two blocks.
+    It handles all key purposes that require splitting into two blocks.
+
+    This method checks if key purposes require splitting into two blocks,
+    such as "XTS_AES_256_KEY", "XTS_AES_256_PSRAM_KEY", and "ECDSA_KEY_P384".
+
+    Args:
+        block_names: List of block names.
+        datafiles: List of BinaryIO objects containing key data.
+        keypurposes: List of key purposes.
+
+    Returns:
+        A tuple containing updated block names, datafiles, and keypurposes.
+    """
+    keypurposes = list(keypurposes)
+    datafiles = list(datafiles)
+    block_names = list(block_names)
+
+    if "XTS_AES_256_KEY" in keypurposes:
+        # XTS_AES_256_KEY is not an actual HW key purpose, needs to be split into
+        # XTS_AES_256_KEY_1 and XTS_AES_256_KEY_2
+        block_names, datafiles, keypurposes = _split_multiblock_key(
+            efuses,
+            block_names,
+            datafiles,  # type: ignore
+            keypurposes,
+            "XTS_AES_256_KEY",
+        )
+
+    if "XTS_AES_256_PSRAM_KEY" in keypurposes:
+        # XTS_AES_256_PSRAM_KEY -> XTS_AES_256_PSRAM_KEY_1 and ..._KEY_2
+        block_names, datafiles, keypurposes = _split_multiblock_key(
+            efuses,
+            block_names,
+            datafiles,  # type: ignore
+            keypurposes,
+            "XTS_AES_256_PSRAM_KEY",
+        )
+
+    # ECDSA keys can be present in a command multiple times
+    i = 0
+    while i < len(keypurposes):
+        if "ECDSA_KEY" in keypurposes[i]:
+            if keypurposes[i] not in ["ECDSA_KEY_P384_L", "ECDSA_KEY_P384_H"]:
+                sk = espsecure.load_ecdsa_signing_key(datafiles[i])  # type: ignore
+                data = sk.to_string()
+                if "ECDSA_KEY_P384" == keypurposes[i]:
+                    assert (
+                        len(data) == 48
+                    ), "NIST384p private key should be 48 bytes long"
+                    datafiles[i] = io.BytesIO(b"\x00" * 16 + data)
+                    # ECDSA_KEY_P384 -> ECDSA_KEY_P384_L and ECDSA_KEY_P384_H
+                    block_names, datafiles, keypurposes = _split_multiblock_key(
+                        efuses,
+                        block_names,
+                        datafiles,  # type: ignore
+                        keypurposes,
+                        "ECDSA_KEY_P384",
+                    )
+                else:
+                    # the private key is 24 bytes long for NIST192p,
+                    # and 8 bytes of padding
+                    datafiles[i] = (
+                        io.BytesIO(b"\x00" * 8 + data)
+                        if len(data) == 24
+                        else io.BytesIO(data)
+                    )
+
+        i += 1
+
+    # Check that all block names are unique
+    util.check_duplicate_name_in_list(block_names)
+
+    # Check that the number of blocks, datafiles, and keypurposes is equal
+    if len(block_names) != len(datafiles) or len(block_names) != len(keypurposes):
+        raise esptool.FatalError(
+            f"The number of blocks ({len(block_names)}), "
+            f"datafile ({len(datafiles)}) and keypurpose ({len(keypurposes)}) "
+            "should be the same."
+        )
+
+    return block_names, datafiles, keypurposes
+
+
+def _split_multiblock_key(
     efuses, block_names, datafiles, keypurposes, base_keypurpose="XTS_AES_256_KEY"
 ):
     """Helper method to split 512-bit key into two 256-bit keys"""
-    if base_keypurpose not in keypurposes:
-        return block_names, datafiles, keypurposes
 
     keypurpose_list = list(keypurposes)
     datafile_list = list(datafiles)
@@ -867,16 +951,15 @@ def split_512_bit_key(
     if not key_block_2:
         raise esptool.FatalError(f"{base_keypurpose} requires two free keyblocks")
 
-    keypurpose_list.append(f"{base_keypurpose}_1")
-    datafile_list.append(io.BytesIO(data[:32]))
-    block_name_list.append(block_name)
-
-    keypurpose_list.append(f"{base_keypurpose}_2")
-    datafile_list.append(io.BytesIO(data[32:]))
-    block_name_list.append(key_block_2.name)
+    postfix = (
+        ["_1", "_2"] if base_keypurpose.startswith("XTS_AES_256") else ["_H", "_L"]
+    )
+    keypurpose_list[i] = f"{base_keypurpose}{postfix[0]}"
+    datafile_list[i] = io.BytesIO(data[:32])
+    block_name_list[i] = block_name
 
-    keypurpose_list.pop(i)
-    datafile_list.pop(i)
-    block_name_list.pop(i)
+    keypurpose_list.insert(i + 1, f"{base_keypurpose}{postfix[1]}")
+    datafile_list.insert(i + 1, io.BytesIO(data[32:]))
+    block_name_list.insert(i + 1, key_block_2.name)
 
     return block_name_list, datafile_list, keypurpose_list

espefuse/efuse/esp32c3/operations.py

@@ -26,6 +26,7 @@
     read_protect_efuse,
     summary,
     write_protect_efuse,
+    adjust_key_data_for_blocks,
 )
 
 
@@ -224,15 +225,12 @@ def burn_key(esp, efuses, args, digest=None):
         0 : len([name for name in args.keypurpose if name is not None]) :
     ]
 
-    util.check_duplicate_name_in_list(block_name_list)
-    if len(block_name_list) != len(datafile_list) or len(block_name_list) != len(
-        keypurpose_list
-    ):
-        raise esptool.FatalError(
-            "The number of blocks (%d), datafile (%d) and keypurpose (%d) "
-            "should be the same."
-            % (len(block_name_list), len(datafile_list), len(keypurpose_list))
-        )
+    block_name_list, datafile_list, keypurpose_list = adjust_key_data_for_blocks(
+        efuses,
+        block_name_list,
+        datafile_list,
+        keypurpose_list,
+    )
 
     print("Burn keys to blocks:")
     for block_name, datafile, keypurpose in zip(

espefuse/efuse/esp32c5/fields.py

@@ -405,8 +405,8 @@ def print_field(e, new_value):
 class EfuseKeyPurposeField(EfuseField):
     KEY_PURPOSES = [
         ("USER",                         0,  None,       None,      "no_need_rd_protect"),   # User purposes (software-only use)
-        ("ECDSA_KEY",                    1,  None,       "Reverse", "need_rd_protect"),      # ECDSA key P256
         ("ECDSA_KEY_P256",               1,  None,       "Reverse", "need_rd_protect"),      # ECDSA key P256
+        ("ECDSA_KEY",                    1,  None,       "Reverse", "need_rd_protect"),      # ECDSA key P256
         ("RESERVED",                     1,  None,       None,      "no_need_rd_protect"),   # Reserved
         ("XTS_AES_256_KEY_1",            2,  None,       "Reverse", "need_rd_protect"),      # XTS_AES_256_KEY_1 (flash/PSRAM encryption)
         ("XTS_AES_256_KEY_2",            3,  None,       "Reverse", "need_rd_protect"),      # XTS_AES_256_KEY_2 (flash/PSRAM encryption)
@@ -427,6 +427,7 @@ class EfuseKeyPurposeField(EfuseField):
         ("ECDSA_KEY_P192",               16, None,       "Reverse", "need_rd_protect"),      # ECDSA key P192
         ("ECDSA_KEY_P384_L",             17, None,       "Reverse", "need_rd_protect"),      # ECDSA key P384 low
         ("ECDSA_KEY_P384_H",             18, None,       "Reverse", "need_rd_protect"),      # ECDSA key P384 high
+        ("ECDSA_KEY_P384",               -3, "VIRTUAL",  None,      "need_rd_protect"),      # Virtual purpose splits to ECDSA_KEY_P384_L and ECDSA_KEY_P384_H
     ]
 # fmt: on
     KEY_PURPOSES_NAME = [name[0] for name in KEY_PURPOSES]

espefuse/efuse/esp32c5/operations.py

@@ -26,7 +26,7 @@
     read_protect_efuse,
     summary,
     write_protect_efuse,
-    split_512_bit_key,
+    adjust_key_data_for_blocks,
 )
 
 
@@ -215,36 +215,12 @@ def burn_key(esp, efuses, args, digest=None):
         0 : len([name for name in args.keypurpose if name is not None]) :
     ]
 
-    if "XTS_AES_256_KEY" in keypurpose_list:
-        # XTS_AES_256_KEY is not an actual HW key purpose, needs to be split into
-        # XTS_AES_256_KEY_1 and XTS_AES_256_KEY_2
-        block_name_list, datafile_list, keypurpose_list = split_512_bit_key(
-            efuses,
-            block_name_list,
-            datafile_list,
-            keypurpose_list,
-            "XTS_AES_256_KEY",
-        )
-
-    if "XTS_AES_256_PSRAM_KEY" in keypurpose_list:
-        # XTS_AES_256_PSRAM_KEY -> XTS_AES_256_PSRAM_KEY_1 and XTS_AES_256_PSRAM_KEY_2
-        block_name_list, datafile_list, keypurpose_list = split_512_bit_key(
-            efuses,
-            block_name_list,
-            datafile_list,
-            keypurpose_list,
-            "XTS_AES_256_PSRAM_KEY",
-        )
-
-    util.check_duplicate_name_in_list(block_name_list)
-    if len(block_name_list) != len(datafile_list) or len(block_name_list) != len(
-        keypurpose_list
-    ):
-        raise esptool.FatalError(
-            "The number of blocks (%d), datafile (%d) and keypurpose (%d) "
-            "should be the same."
-            % (len(block_name_list), len(datafile_list), len(keypurpose_list))
-        )
+    block_name_list, datafile_list, keypurpose_list = adjust_key_data_for_blocks(
+        efuses,
+        block_name_list,
+        datafile_list,
+        keypurpose_list,
+    )
 
     print("Burn keys to blocks:")
     for block_name, datafile, keypurpose in zip(
@@ -262,14 +238,7 @@ def burn_key(esp, efuses, args, digest=None):
         block = efuses.blocks[block_num]
 
         if digest is None:
-            if keypurpose.startswith("ECDSA_KEY"):
-                sk = espsecure.load_ecdsa_signing_key(datafile)
-                data = sk.to_string()
-                if len(data) == 24:
-                    # the private key is 24 bytes long for NIST192p, and 8 bytes of padding
-                    data = b"\x00" * 8 + data
-            else:
-                data = datafile.read()
+            data = datafile.read()
         else:
             data = datafile
 

espefuse/efuse/esp32c6/operations.py

@@ -26,6 +26,7 @@
     read_protect_efuse,
     summary,
     write_protect_efuse,
+    adjust_key_data_for_blocks,
 )
 
 
@@ -231,15 +232,12 @@ def burn_key(esp, efuses, args, digest=None):
         0 : len([name for name in args.keypurpose if name is not None]) :
     ]
 
-    util.check_duplicate_name_in_list(block_name_list)
-    if len(block_name_list) != len(datafile_list) or len(block_name_list) != len(
-        keypurpose_list
-    ):
-        raise esptool.FatalError(
-            "The number of blocks (%d), datafile (%d) and keypurpose (%d) "
-            "should be the same."
-            % (len(block_name_list), len(datafile_list), len(keypurpose_list))
-        )
+    block_name_list, datafile_list, keypurpose_list = adjust_key_data_for_blocks(
+        efuses,
+        block_name_list,
+        datafile_list,
+        keypurpose_list,
+    )
 
     print("Burn keys to blocks:")
     for block_name, datafile, keypurpose in zip(

espefuse/efuse/esp32c61/fields.py

@@ -406,8 +406,6 @@ class EfuseKeyPurposeField(EfuseField):
     KEY_PURPOSES = [
         ("USER",                         0,  None,       None,      "no_need_rd_protect"),   # User purposes (software-only use)
         ("ECDSA_KEY",                    1,  None,       "Reverse", "need_rd_protect"),      # ECDSA key
-        ("XTS_AES_256_KEY_1",            2,  None,       "Reverse", "need_rd_protect"),      # XTS_AES_256_KEY_1 (flash/PSRAM encryption)
-        ("XTS_AES_256_KEY_2",            3,  None,       "Reverse", "need_rd_protect"),      # XTS_AES_256_KEY_2 (flash/PSRAM encryption)
         ("XTS_AES_128_KEY",              4,  None,       "Reverse", "need_rd_protect"),      # XTS_AES_128_KEY (flash/PSRAM encryption)
         ("HMAC_DOWN_ALL",                5,  None,       None,      "need_rd_protect"),      # HMAC Downstream mode
         ("HMAC_DOWN_JTAG",               6,  None,       None,      "need_rd_protect"),      # JTAG soft enable key (uses HMAC Downstream mode)
@@ -416,7 +414,6 @@ class EfuseKeyPurposeField(EfuseField):
         ("SECURE_BOOT_DIGEST0",          9,  "DIGEST",   None,      "no_need_rd_protect"),   # SECURE_BOOT_DIGEST0 (Secure Boot key digest)
         ("SECURE_BOOT_DIGEST1",          10, "DIGEST",   None,      "no_need_rd_protect"),   # SECURE_BOOT_DIGEST1 (Secure Boot key digest)
         ("SECURE_BOOT_DIGEST2",          11, "DIGEST",   None,      "no_need_rd_protect"),   # SECURE_BOOT_DIGEST2 (Secure Boot key digest)
-        ("XTS_AES_256_KEY",              -1, "VIRTUAL",  None,      "no_need_rd_protect"),   # Virtual purpose splits to XTS_AES_256_KEY_1 and XTS_AES_256_KEY_2
     ]
 # fmt: on
     KEY_PURPOSES_NAME = [name[0] for name in KEY_PURPOSES]