From 78453c891861faa5f2a4bc8a3195642f429199bd Mon Sep 17 00:00:00 2001 From: Mahavir Jain Date: Fri, 10 Nov 2023 14:38:44 +0530 Subject: [PATCH] docs(ecdsa): add a note about TRNG dependency for ECDSA peripheral --- docs/en/api-reference/peripherals/ecdsa.rst | 10 +++++++++- docs/en/api-reference/system/random.rst | 2 +- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/en/api-reference/peripherals/ecdsa.rst b/docs/en/api-reference/peripherals/ecdsa.rst index 1210694d9d..d6e19cf5bc 100644 --- a/docs/en/api-reference/peripherals/ecdsa.rst +++ b/docs/en/api-reference/peripherals/ecdsa.rst @@ -59,12 +59,20 @@ Following code snippet uses :cpp:func:`esp_efuse_write_key` to set physical key // writing key failed, maybe written already } + +Dependency on TRNG +------------------ + +ECDSA peripheral relies on the hardware True Random Number Generator (TRNG) for its internal entropy requirement. During ECDSA signature creation, the algorithm requires a random integer to be generated as specified in the `RFC 6090 `_ section 5.3.2. + +Please ensure that hardware :doc:`RNG <../system/random>` is enabled before starting ECDSA computations (primarily signing) in the application. + 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. +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 curves 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. diff --git a/docs/en/api-reference/system/random.rst b/docs/en/api-reference/system/random.rst index da4cb1e321..cfe6566f96 100644 --- a/docs/en/api-reference/system/random.rst +++ b/docs/en/api-reference/system/random.rst @@ -1,7 +1,7 @@ Random Number Generation ======================== -{IDF_TARGET_RF_NAME: default="Wi-Fi or Bluetooth", esp32s2="Wi-Fi"} +{IDF_TARGET_RF_NAME: default="Wi-Fi or Bluetooth", esp32s2="Wi-Fi", esp32h2="Bluetooth or 802.15.4 Thread/Zigbee", esp32c6="Wi-Fi or Bluetooth or 802.15.4 Thread/Zigbee"} {IDF_TARGET_RF_IS: default="are", esp32s2="is"} {IDF_TARGET_BOOTLOADER_RANDOM_INCOMPATIBLE: default="", esp32="I2S, "}