pioduino/esp-idf
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: added config member to store block number for high part of ecdsa key

Browse Source
This commit is contained in:
nilesh.kale
2025-07-21 15:40:52 +05:30
committed by Nilesh Kale
parent ba0618b672
commit 364adc79c3
22 changed files with 140 additions and 182 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/en/api-reference/peripherals/ecdsa.rst
+12 -31
View File
@@ -29,46 +29,27 @@ On {IDF_TARGET_NAME}, the ECDSA module works with a secret key burnt into an eFu
ECDSA Key Storage
^^^^^^^^^^^^^^^^^
ECDSA private keys are stored in eFuse key blocks. The number of key blocks required depends on the curve size:
.. only:: SOC_ECDSA_SUPPORT_CURVE_P384
- **P-192 and P-256 curves**: Require one eFuse key block (256 bits)
- **P-384 curve**: Requires two eFuse key blocks (512 bits total)
ECDSA private keys are stored in eFuse key blocks. The number of key blocks required depends on the curve size:
When using the P-384 curve or any other curves that require two key blocks, you must use the appropriate macro to combine the block numbers into a single integer that the ECDSA peripheral can understand:
- **P-256 curve**: Require one eFuse key block (256 bits)
- **P-384 curve**: Requires two eFuse key blocks (512 bits total)
- **For mbedTLS applications**: Use :c:macro:`MBEDTLS_ECDSA_COMBINE_KEY_BLOCKS` macro (defined in ``ecdsa/ecdsa_alt.h``)
- **For HAL applications**: Use :c:macro:`HAL_ECDSA_COMBINE_KEY_BLOCKS` macro (defined in ``hal/ecdsa_types.h``)
- **For ESP-TLS applications**: Use :c:macro:`ESP_TLS_ECDSA_COMBINE_KEY_BLOCKS` macro (defined in ``esp_tls.h``)
For curves requiring two key blocks (like P-384), configure the following fields:
You can also extract the individual block numbers using the corresponding extract macro:
- Set :cpp:member:`esp_tls_cfg_t::ecdsa_key_efuse_blk` to the low block number
- Set :cpp:member:`esp_tls_cfg_t::ecdsa_key_efuse_blk_high` to the high block number
- **For mbedTLS applications**: Use :c:macro:`MBEDTLS_ECDSA_EXTRACT_KEY_BLOCKS` macro
- **For HAL applications**: Use :c:macro:`HAL_ECDSA_EXTRACT_KEY_BLOCKS` macro
- **For ESP-TLS applications**: Use :c:macro:`ESP_TLS_ECDSA_EXTRACT_KEY_BLOCKS` macro
For single-block curves (like P-256), only set :cpp:member:`esp_tls_cfg_t::ecdsa_key_efuse_blk` and leave :cpp:member:`esp_tls_cfg_t::ecdsa_key_efuse_blk_high` as 0 or unassigned.
Here is an example of how to use these macros:
.. only:: not SOC_ECDSA_SUPPORT_CURVE_P384
.. code-block:: c
ECDSA private keys are stored in eFuse key blocks. One eFuse key block (256 bits) is required for P-256 curve.
#include "ecdsa/ecdsa_alt.h"
Configure the following field:
// Example: Using P-384 curve which requires two key blocks
// Assuming you want to use key blocks 4 and 5
uint8_t block_low = 4; // Lower key block
uint8_t block_high = 5; // Higher key block
// Combine the two block numbers into a single integer
// Note: First parameter is high block, second parameter is low block
uint16_t combined_blocks = MBEDTLS_ECDSA_COMBINE_KEY_BLOCKS(block_high, block_low);
// Use the combined_blocks value in your ECDSA operations
// This value can be passed to mbedTLS ECDSA functions
// To extract the individual block numbers later
uint8_t extracted_block_low, extracted_block_high;
MBEDTLS_ECDSA_EXTRACT_KEY_BLOCKS(combined_blocks, &extracted_block_high, &extracted_block_low);
// extracted_block_low will be 4, extracted_block_high will be 5
- Set :cpp:member:`esp_tls_cfg_t::ecdsa_key_efuse_blk` to the block number and leave :cpp:member:`esp_tls_cfg_t::ecdsa_key_efuse_blk_high` as 0 or unassigned.
ECDSA key can be programmed externally through ``idf.py`` script. Here is an example of how to program the ECDSA key:
docs/en/api-reference/protocols/esp_tls.rst
+4 -5
View File
@@ -217,17 +217,16 @@ To enable the secure element support, and use it in your project for TLS connect
ESP-TLS provides support for using the ECDSA peripheral with {IDF_TARGET_NAME}. The use of ECDSA peripheral is supported only when ESP-TLS is used with MbedTLS as its underlying SSL/TLS stack. The ECDSA private key should be present in the eFuse for using the ECDSA peripheral. Please refer to :doc:`ECDSA Guide <../peripherals/ecdsa>` for programming the ECDSA key in the eFuse.
To use ECDSA peripheral with ESP-TLS, set :cpp:member:`esp_tls_cfg_t::use_ecdsa_peripheral` to `true`, set :cpp:member:`esp_tls_cfg_t::ecdsa_key_efuse_blk` to the eFuse block ID in which ECDSA private key is stored, and set :cpp:member:`esp_tls_cfg_t::ecdsa_curve` to specify the ECDSA curve to use.
This will enable the use of ECDSA peripheral for private key operations. As the client private key is already present in the eFuse, it needs not be supplied to the :cpp:type:`esp_tls_cfg_t` structure.
This will enable the use of ECDSA peripheral for private key operations. As the client private key is already present in the eFuse, it need not be supplied to the :cpp:type:`esp_tls_cfg_t` structure. Please see the below code snippet for enabling the use of ECDSA peripheral for a given ESP-TLS connection.
.. code-block:: c
#include "esp_tls.h"
esp_tls_cfg_t cfg = {
.use_ecdsa_peripheral = true,
.ecdsa_key_efuse_blk = /* efuse block with ecdsa private key */,
.ecdsa_curve = ESP_TLS_ECDSA_CURVE_SECP256R1, // or ESP_TLS_ECDSA_CURVE_SECP384R1
.ecdsa_key_efuse_blk = 4, // Low eFuse block for ECDSA key
.ecdsa_key_efuse_blk_high = 5, // High eFuse block for ECDSA key (SECP384R1 only)
.ecdsa_curve = ESP_TLS_ECDSA_CURVE_SECP384R1, // set this to ESP_TLS_ECDSA_CURVE_SECP256R1 for SECP256R1 curve
};
.. note::
docs/en/api-reference/protocols/mqtt.rst
-3
View File
@@ -156,9 +156,6 @@ It is possible to set authentication parameters through the :cpp:class:`authenti
* :cpp:member:`certificate <esp_mqtt_client_config_t::credentials_t::authentication_t::certificate>` and :cpp:member:`key <esp_mqtt_client_config_t::credentials_t::authentication_t::key>`: mutual authentication with TLS, and both can be provided in PEM or DER format
* :cpp:member:`use_secure_element <esp_mqtt_client_config_t::credentials_t::authentication_t::use_secure_element>`: use secure element (ATECC608A) interfaced to ESP32 series
* :cpp:member:`ds_data <esp_mqtt_client_config_t::credentials_t::authentication_t::ds_data>`: use Digital Signature Peripheral available in some Espressif devices
* :cpp:member:`use_ecdsa_peripheral <esp_mqtt_client_config_t::credentials_t::authentication_t::use_ecdsa_peripheral>`: use ECDSA Peripheral available in some Espressif devices
* :cpp:member:`ecdsa_key_efuse_blk <esp_mqtt_client_config_t::credentials_t::authentication_t::ecdsa_key_efuse_blk>`: eFuse block containing ECDSA private key
* :cpp:member:`ecdsa_curve <esp_mqtt_client_config_t::credentials_t::authentication_t::ecdsa_curve>`: ECDSA curve to use (ESP_TLS_ECDSA_CURVE_SECP256R1 or ESP_TLS_ECDSA_CURVE_SECP384R1)
Session
^^^^^^^^^^^