mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
2882b6f68b
- 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
75 lines
3.5 KiB
ReStructuredText
75 lines
3.5 KiB
ReStructuredText
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
|