docs: add ECDSA peripheral chapter for H2/P4

- Add ECDSA peripheral chapter and instructions to program efuse key block
- Update security guide for ECDSA peripheral mention for device identity
- Link with ESP-TLS guide about using ECDSA peripheral in TLS connection

components/efuse/include/esp_efuse.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2017-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2017-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -235,7 +235,7 @@ esp_err_t esp_efuse_write_reg(esp_efuse_block_t blk, unsigned int num_reg, uint3
 /**
  * @brief   Return efuse coding scheme for blocks.
  *
- * Note: The coding scheme is applicable only to 1, 2 and 3 blocks. For 0 block, the coding scheme is always ``NONE``.
+ * @note The coding scheme is applicable only to 1, 2 and 3 blocks. For 0 block, the coding scheme is always ``NONE``.
  *
  * @param[in]  blk     Block number of eFuse.
  * @return Return efuse coding scheme for blocks
@@ -708,6 +708,12 @@ esp_err_t esp_efuse_set_write_protect_of_digest_revoke(unsigned num_digest);
  *
  * The burn of a key, protection bits, and a purpose happens in batch mode.
  *
+ * @note This API also enables the read protection efuse bit for certain key blocks like XTS-AES, HMAC, ECDSA etc.
+ * This ensures that the key is only accessible to hardware peripheral.
+ *
+ * @note For SoC's with capability `SOC_EFUSE_ECDSA_USE_HARDWARE_K` (e.g., ESP32-H2), this API writes an additional
+ * efuse bit for ECDSA key purpose to enforce hardware TRNG generated k mode in the peripheral.
+ *
  * @param[in] block Block to read purpose for. Must be in range EFUSE_BLK_KEY0 to EFUSE_BLK_KEY_MAX. Key block must be unused (esp_efuse_key_block_unused).
  * @param[in] purpose Purpose to set for this key. Purpose must be already unset.
  * @param[in] key Pointer to data to write.
@@ -727,6 +733,12 @@ esp_err_t esp_efuse_write_key(esp_efuse_block_t block, esp_efuse_purpose_t purpo
  *
  * The burn of keys, protection bits, and purposes happens in batch mode.
  *
+ * @note This API also enables the read protection efuse bit for certain key blocks like XTS-AES, HMAC, ECDSA etc.
+ * This ensures that the key is only accessible to hardware peripheral.
+ *
+ * @note For SoC's with capability `SOC_EFUSE_ECDSA_USE_HARDWARE_K` (e.g., ESP32-H2), this API writes an additional
+ * efuse bit for ECDSA key purpose to enforce hardware TRNG generated k mode in the peripheral.
+ *
  * @param[in] purposes Array of purposes (purpose[number_of_keys]).
  * @param[in] keys Array of keys (uint8_t keys[number_of_keys][32]). Each key is 32 bytes long.
  * @param[in] number_of_keys The number of keys to write (up to 6 keys).

components/mbedtls/port/include/ecdsa/ecdsa_alt.h

@@ -24,10 +24,10 @@ extern "C" {
  *        by the peripheral, a flag load_pubkey that is used specify if the public key has to be populated
  */
 typedef struct {
-    mbedtls_ecp_group_id grp_id;
-    uint8_t efuse_block;
+    mbedtls_ecp_group_id grp_id;            /*!< MbedTLS ECP group identifier */
+    uint8_t efuse_block;                    /*!< EFuse block id for ECDSA private key */
 #ifdef SOC_ECDSA_SUPPORT_EXPORT_PUBKEY
-    bool load_pubkey;
+    bool load_pubkey;                       /*!< Export ECDSA public key from the hardware */
 #endif
 } esp_ecdsa_pk_conf_t;  //TODO: IDF-7925 (Add a config to select the ecdsa key from the key manager peripheral)
 

docs/conf_common.py

@@ -210,6 +210,7 @@ conditional_include_dict = {'SOC_BT_SUPPORTED':BT_DOCS,
                             'SOC_RISCV_COPROC_SUPPORTED':RISCV_COPROC_DOCS,
                             'SOC_LP_CORE_SUPPORTED':LP_CORE_DOCS,
                             'SOC_DIG_SIGN_SUPPORTED':['api-reference/peripherals/ds.rst'],
+                            'SOC_ECDSA_SUPPORTED':['api-reference/peripherals/ecdsa.rst'],
                             'SOC_HMAC_SUPPORTED':['api-reference/peripherals/hmac.rst'],
                             'SOC_ASYNC_MEMCPY_SUPPORTED':['api-reference/system/async_memcpy.rst'],
                             'CONFIG_IDF_TARGET_ARCH_XTENSA':XTENSA_DOCS,

docs/doxygen/Doxyfile

@@ -265,6 +265,7 @@ INPUT = \
     $(PROJECT_PATH)/components/lwip/include/apps/esp_sntp.h \
     $(PROJECT_PATH)/components/lwip/include/apps/ping/ping_sock.h \
     $(PROJECT_PATH)/components/mbedtls/esp_crt_bundle/include/esp_crt_bundle.h \
+    $(PROJECT_PATH)/components/mbedtls/port/include/ecdsa/ecdsa_alt.h \
     $(PROJECT_PATH)/components/mqtt/esp-mqtt/include/mqtt_client.h \
     $(PROJECT_PATH)/components/nvs_flash/include/nvs_flash.h \
     $(PROJECT_PATH)/components/nvs_flash/include/nvs.h \

docs/en/api-reference/peripherals/ecdsa.rst

@@ -0,0 +1,74 @@
+Elliptic Curve Digital Signature Algorithm (ECDSA)
+==================================================
+
+The Elliptic Curve Digital Signature Algorithm (ECDSA) offers a variant of the Digital Signature Algorithm (DSA) which uses elliptic-curve cryptography.
+
+{IDF_TARGET_NAME}'s ECDSA peripheral provides a secure and efficient environment for computing ECDSA signatures. It offers fast computations while ensuring the confidentiality of the signing process to prevent information leakage. ECDSA private key used in the signing process is accessible only to the hardware peripheral, and it is not readable by software.
+
+ECDSA peripheral can help to establish **Secure Device Identity** for TLS mutual authentication and similar use-cases.
+
+Supported Features
+------------------
+
+- ECDSA digital signature generation and verification
+- Two different elliptic curves, namely P-192 and P-256 (FIPS 186-3 specification)
+- Two hash algorithms for message hash in the ECDSA operation, namely SHA-224 and SHA-256 (FIPS PUB 180-4 specification)
+
+
+ECDSA on {IDF_TARGET_NAME}
+--------------------------
+
+On {IDF_TARGET_NAME}, the ECDSA module works with a secret key burnt into an eFuse block. This eFuse key is made completely inaccessible (default mode) for any resources outside the cryptographic modules, thus avoiding key leakage.
+
+ECDSA key can be programmed externally through ``espefuse.py`` script using:
+
+.. code:: bash
+
+   espefuse.py burn_key <BLOCK_NUM> </path/to/ecdsa_private_key.pem> ECDSA_KEY
+
+.. only:: SOC_EFUSE_BLOCK9_KEY_PURPOSE_QUIRK
+
+    .. note::
+
+        Five physical eFuse blocks can be used as keys for the ECDSA module: block 4 ~ block 8. E.g., for block 4 (which is the first key block) , the argument should be ``BLOCK_KEY0``.
+
+.. only:: not SOC_EFUSE_BLOCK9_KEY_PURPOSE_QUIRK
+
+    .. note::
+
+        Six physical eFuse blocks can be used as keys for the ECDSA module: block 4 ~ block 9. E.g., for block 4 (which is the first key block) , the argument should be ``BLOCK_KEY0``.
+
+
+Alternatively the ECDSA key can also be programmed through the application running on the target.
+
+Following code snippet uses :cpp:func:`esp_efuse_write_key` to set physical key block 0 in the eFuse with key purpose as :cpp:enumerator:`esp_efuse_purpose_t::ESP_EFUSE_KEY_PURPOSE_ECDSA_KEY`:
+
+.. code-block:: c
+
+    #include "esp_efuse.h"
+
+    const uint8_t key_data[32] = { ... };
+
+    esp_err_t status = esp_efuse_write_key(EFUSE_BLK_KEY0,
+                        ESP_EFUSE_KEY_PURPOSE_ECDSA_KEY,
+                        key_data, sizeof(key_data));
+
+    if (status == ESP_OK) {
+        // written key
+    } else {
+        // writing key failed, maybe written already
+    }
+
+Application Outline
+-------------------
+
+Please refer to the :ref:`ecdsa-peri-with-esp-tls` guide for details on how-to use ECDSA peripheral for establishing a mutually authenticated TLS connection.
+
+The ECDSA peripheral in mbedTLS stack is integrated by overriding the ECDSA sign and verify APIs. Please note that, the ECDSA peripheral does not support all curvers or hash algorithms and hence for cases where the requirements do not meet the hardware, implementation falls back to the software.
+
+For a particular TLS context, additional APIs have been supplied to populate certain fields (e.g., private key ctx) to differentiate routing to hardware. ESP-TLS layer integrates these APIs internally and hence no additional work is required at the application layer. However, for custom use-cases please refer to API details below.
+
+API Reference
+-------------
+
+.. include-build-file:: inc/ecdsa_alt.inc

docs/en/api-reference/peripherals/index.rst

@@ -12,6 +12,7 @@ Peripherals API
     :SOC_ANA_CMPR_SUPPORTED: ana_cmpr
     clk_tree
     :SOC_DAC_SUPPORTED: dac
+    :SOC_ECDSA_SUPPORTED: ecdsa
     :SOC_ETM_SUPPORTED: etm
     gpio
     gptimer

docs/en/api-reference/protocols/esp_tls.rst

@@ -203,6 +203,8 @@ The following table shows a typical comparison between WolfSSL and MbedTLS when
 
 .. only:: SOC_ECDSA_SUPPORTED
 
+    .. _ecdsa-peri-with-esp-tls:
+
     ECDSA Peripheral with ESP-TLS
     -----------------------------
 

docs/en/security/security.rst

@@ -1,6 +1,10 @@
 Security
 ========
 
+{IDF_TARGET_CIPHER_SCHEME:default="RSA", esp32h2="RSA or ECDSA", esp32p4="RSA or ECDSA"}
+
+{IDF_TARGET_SIG_PERI:default="DS", esp32h2="DS or ECDSA", esp32p4="DS or ECDSA"}
+
 :link_to_translation:`zh_CN:[中文]`
 
 This guide provides an overview of the overall security features available in various Espressif solutions. It is highly recommended to consider this guide while designing the products with the Espressif platform and the ESP-IDF software stack from the **security** perspective.
@@ -73,10 +77,20 @@ Flash Encryption Best Practices
 
     The Digital Signature peripheral in {IDF_TARGET_NAME} produces hardware-accelerated RSA digital signatures with the assistance of HMAC, without the RSA private key being accessible by software. This allows the private key to be kept secured on the device without anyone other than the device hardware being able to access it.
 
-    This peripheral can help to establish the **Secure Device Identity** to the remote endpoint, e.g., in the case of TLS mutual authentication based on the RSA cipher scheme.
+    .. only:: SOC_ECDSA_SUPPORTED
+
+        {IDF_TARGET_NAME} also supportes ECDSA peripheral for generating hardware-accelerated ECDSA digital signatures. ECDSA private key can be directly programmed in an eFuse block and marked as read protected from the software.
+
+    {IDF_TARGET_SIG_PERI} peripheral can help to establish the **Secure Device Identity** to the remote endpoint, e.g., in the case of TLS mutual authentication based on the {IDF_TARGET_CIPHER_SCHEME} cipher scheme.
+
+    .. only:: not SOC_ECDSA_SUPPORTED
 
         Please refer to the :doc:`../api-reference/peripherals/ds` for detailed documentation.
 
+    .. only:: SOC_ECDSA_SUPPORTED
+
+        Please refer to the :doc:`../api-reference/peripherals/ecdsa` and :doc:`../api-reference/peripherals/ds` guides for detailed documentation.
+
 .. only:: SOC_MEMPROT_SUPPORTED or SOC_CPU_IDRAM_SPLIT_USING_PMP
 
     Memory Protection

docs/zh_CN/api-reference/peripherals/ecdsa.rst

@@ -0,0 +1 @@
+.. include:: ../../../en/api-reference/peripherals/ecdsa.rst

docs/zh_CN/api-reference/peripherals/index.rst

@@ -12,6 +12,7 @@
     :SOC_ANA_CMPR_SUPPORTED: ana_cmpr
     clk_tree
     :SOC_DAC_SUPPORTED: dac
+    :SOC_ECDSA_SUPPORTED: ecdsa
     :SOC_ETM_SUPPORTED: etm
     gpio
     gptimer

docs/zh_CN/api-reference/protocols/esp_tls.rst

@@ -203,6 +203,8 @@ MbedTLS 与 WolfSSL 对比
 
 .. only:: SOC_ECDSA_SUPPORTED
 
+    .. _ecdsa-peri-with-esp-tls:
+
     在 ESP-TLS 中使用 ECDSA 外设
     -----------------------------