eaw/esp-idf
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Digital Signature (ds):) Update the documentation for esp_ds_sign and

Browse Source 
esp_ds_start_sign with additional information.
ii) Updated the DS docs for signature calculation.
Closes https://github.com/espressif/esp-idf/issues/8242
This commit is contained in:
Aditya Patwardhan
2022-01-31 16:06:12 +05:30
committed by bot
parent e6c0d1e481
commit bb7be628a0
5 changed files with 56 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/en/api-reference/peripherals/ds.rst
View File

@@ -43,6 +43,8 @@ The first one is :cpp:func:`esp_ds_sign` and simply blocks until the calculation
If software needs to do something else during the calculation, :cpp:func:`esp_ds_start_sign` can be called, followed by periodic calls to :cpp:func:`esp_ds_is_busy` to check when the calculation has finished.
Once the calculation has finished, :cpp:func:`esp_ds_finish_sign` can be called to get the resulting signature.
The APIs :cpp:func:`esp_ds_sign` and :cpp:func:`esp_ds_start_sign` calculate a plain RSA signature with help of the DS peripheral. This signature needs to be converted to appropriate format for further use. For example, MbedTLS SSL stack supports PKCS#1 format. The API :cpp:func:`esp_ds_rsa_sign` can be used to obtain the signature directly in the PKCS#1 v1.5 format. It internally uses :cpp:func:`esp_ds_start_sign` and converts the signature into PKCS#1 v1.5 format.
.. note::
Note that this is only the basic DS building block, the message length is fixed.
To create signatures of arbitrary messages, the input is normally a hash of the actual message, padded up to the required length.
@@ -67,7 +69,7 @@ More details about the `configure_ds.py` script can be found at :example_file:`m
The encrypted private key parameters obtained after the DS peripheral configuration are then to be kept in flash. Furthermore, they are to be passed to the DS peripheral which makes use of those parameters for the Digital Signature operation.
:doc:`Non Volatile Storage<../storage/nvs_flash>` can be used to store the encrypted private key parameters in flash.
The script :example_file:`configure_ds.py<protocols/mqtt/ssl_ds/configure_ds.py>` creates an NVS partition for the encrypted private key parameters. Then the script flashes this partition onto the {IDF_TARGET_NAME}.
The application then needs to read the DS data from NVS, which can be done with the function `esp_read_ds_data_from_nvs` in file :example_file:`ssl_mutual_auth/main/app_main.c <protocols/mqtt/ssl_mutual_auth/main/app_main.c>`
The application then needs to read the DS data from NVS, which can be done with the function ``esp_read_ds_data_from_nvs()`` in file :example_file:`ssl_ds/main/app_main.c <protocols/mqtt/ssl_ds/main/app_main.c>`
The process of initializing the DS peripheral and then performing the Digital Signature operation is done internally with help of `ESP-TLS`. Please refer to `Digital Signature with ESP-TLS` in :doc:`ESP-TLS <../protocols/esp_tls>` for more details.
As mentioned in the `ESP-TLS` documentation, the application only needs to provide the encrypted private key parameters to the esp_tls context (as `ds_data`), which internally performs