Merge branch 'doc/ds_S2_4.2' into 'release/v4.2'

Doc: DS documentation for S2

See merge request espressif/esp-idf!9358

components/esp32s2/include/esp_ds.h

@@ -50,7 +50,8 @@ typedef enum {
  * @note This struct has to match to one from the ROM code! This documentation is mostly taken from there.
  */
 typedef struct esp_digital_signature_data {
-    /* RSA LENGTH register parameters
+    /**
+     * RSA LENGTH register parameters
      * (number of words in RSA key & operands, minus one).
      *
      * Max value 127 (for RSA 4096).
@@ -66,16 +67,19 @@ typedef struct esp_digital_signature_data {
      */
     esp_digital_signature_length_t rsa_length;
 
-    /* IV value used to encrypt 'c' */
+    /**
+     * IV value used to encrypt 'c'
+     */
     uint8_t iv[ESP_DS_IV_LEN];
 
-    /* Encrypted Digital Signature parameters. Result of AES-CBC encryption
-       of plaintext values. Includes an encrypted message digest.
-    */
+    /**
+     * Encrypted Digital Signature parameters. Result of AES-CBC encryption
+     * of plaintext values. Includes an encrypted message digest.
+     */
     uint8_t c[ESP_DS_C_LEN];
 } esp_ds_data_t;
 
-/* Plaintext parameters used by Digital Signature.
+/** Plaintext parameters used by Digital Signature.
  *
  * Not used for signing with DS peripheral, but can be encrypted
  * in-device by calling esp_ds_encrypt_params()
@@ -83,11 +87,11 @@ typedef struct esp_digital_signature_data {
  * @note This documentation is mostly taken from the ROM code.
  */
 typedef struct {
-    uint32_t Y[4096/32];
-    uint32_t M[4096/32];
-    uint32_t Rb[4096/32];
-    uint32_t M_prime;
-    esp_digital_signature_length_t length;
+    uint32_t Y[4096/32];                    //!< RSA exponent
+    uint32_t M[4096/32];                    //!< RSA modulus
+    uint32_t Rb[4096/32];                   //!< RSA r inverse operand
+    uint32_t M_prime;                       //!< RSA M prime operand
+    esp_digital_signature_length_t length;  //!< RSA length
 } esp_ds_p_data_t;
 
 /**

docs/Doxyfile

@@ -111,6 +111,7 @@ INPUT = \
     $(IDF_PATH)/components/driver/include/driver/uart.h \
     $(IDF_PATH)/components/esp_adc_cal/include/esp_adc_cal.h \
     $(IDF_PATH)/components/esp32s2/include/esp_hmac.h \
+    $(IDF_PATH)/components/esp32s2/include/esp_ds.h \
     $(IDF_PATH)/components/soc/include/hal/rmt_types.h \
     $(IDF_PATH)/components/soc/include/hal/spi_types.h \
     $(IDF_PATH)/components/soc/include/hal/pcnt_types.h \

docs/conf_common.py

@@ -162,6 +162,7 @@ ESP32S2_DOCS = ['esp32s2.rst',
                 'api-guides/ulps2_instruction_set.rst',
                 'api-guides/dfu.rst',
                 'api-reference/peripherals/hmac.rst',
+                'api-reference/peripherals/ds.rst',
                 'api-reference/peripherals/temp_sensor.rst'
                 '']
 

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

@@ -0,0 +1,52 @@
+Digital Signature
+=================
+
+The Digital Signature (DS) module provides hardware acceleration of signing messages based on RSA.
+It uses pre-encrypted parameters to calculate a signature.
+The parameters are encrypted using HMAC as a key-derivation function.
+In turn, the HMAC uses eFuses as input key.
+The whole process happens in hardware so that neither the decryption key for the RSA parameters nor the input key for the HMAC key derivation function can be seen by the software while calculating the signature.
+
+Look into the `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_ (PDF) for more detailed information about the involved hardware during the signature calculation process and the used registers.
+
+Private Key Parameters
+----------------------
+The private key parameters for the RSA signature are stored in flash.
+To prevent unauthorized access, they are AES-encrypted.
+The HMAC module is used as a key-derivation function to calculate the AES encryption key for the private key parameters.
+In turn, the HMAC module uses a key from the eFuses key block which can be read-protected to prevent unauthorized access as well.
+
+Upon signature calculation invocation, the software only specifies which eFuse key to use, the corresponding eFuse key purpose, the location of the encrypted RSA parameters and the message.
+
+Key Generation
+--------------
+Both the HMAC key and the RSA private key have to be created and stored before the DS module can be used.
+This needs to be done in software on the {IDF_TARGET_NAME} or alternatively on a host.
+For this context, the IDF provides :cpp:func:`esp_efuse_write_block` to set the HMAC key and :cpp:func:`esp_hmac_calculate` to encrypt the private RSA key parameters.
+
+Instructions on how to calculate and assemble the private key parameters are described in the `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_.
+
+Signature Calculation with IDF
+------------------------------
+*For thorough information about involved registers and the workflow, please have a look at the* `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_.
+
+Three parameters need to be prepared to calculate the digital signature:
+
+#. the eFuse key block ID which is used as key for the HMAC,
+#. the location of the encrypted private key parameters,
+#. and the message to be signed.
+
+Since the signature calculation takes some time, there are two possible API versions to use in IDF.
+The first one is :cpp:func:`esp_ds_sign` and simply blocks until the calculation is finished.
+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.
+
+.. 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.
+    An API to do this is planned in the future.
+
+API Reference
+-------------
+
+.. include-build-file:: inc/esp_ds.inc

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

@@ -12,6 +12,7 @@ Peripherals API
     DAC <dac>
     GPIO (including RTC low power I/O) <gpio>
     :esp32s2: HMAC <hmac>
+    :esp32s2: Digital Signature <ds>
     I2C <i2c>
     I2S <i2s>
     LED Control <ledc>

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

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

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

@@ -11,6 +11,7 @@
    DAC <dac>
    GPIO (including RTC low power I/O) <gpio>
    :esp32s2: HMAC <hmac>
+   :esp32s2: Digital Signature <ds>
    I2C <i2c>
    I2S <i2s>
    LED Control <ledc>