Merge branch 'fix/update_docs_for_hmac_api' into 'master'

esp_hmac: Fix documentation for API and Programming Guide

See merge request espressif/esp-idf!18703

components/esp_hw_support/include/soc/esp32c3/esp_hmac.h

@@ -41,10 +41,11 @@ typedef enum {
  * @param message the message for which to calculate the HMAC
  * @param message_len message length
  *             return ESP_ERR_INVALID_STATE if unsuccessful
- * @param [out] hmac the hmac result; the buffer behind the provided pointer must be 32 bytes long
+ * @param [out] hmac the hmac result; the buffer behind the provided pointer must be a writeable buffer of 32 bytes
  *
  * @return
  *      * ESP_OK, if the calculation was successful,
+ *      * ESP_ERR_INVALID_ARG if message or hmac is a nullptr or if key_id out of range
  *      * ESP_FAIL, if the hmac calculation failed
  */
 esp_err_t esp_hmac_calculate(hmac_key_id_t key_id,
@@ -63,12 +64,15 @@ esp_err_t esp_hmac_calculate(hmac_key_id_t key_id,
  *        programmed to a eFuse key block. The key block number is provided as the first parameter to this function.
  *
  * @return
- *      * ESP_OK, if the calculation was successful,
- *                if the calculated HMAC value matches with provided token,
- *                JTAG will be re-enable otherwise JTAG will remain disabled.
- *                Return value does not indicate the JTAG status.
- *      * ESP_FAIL, if the hmac calculation failed or JTAG is permanently disabled by EFUSE_HARD_DIS_JTAG eFuse parameter.
+ *      * ESP_OK, if the key_purpose of the key_id matches to HMAC downstread mode,
+ *                The API returns success even if calculated HMAC does not match with the provided token.
+ *                However, The JTAG will be re-enabled only if the calculated HMAC value matches with provided token,
+ *                otherwise JTAG will remain disabled.
+ *      * ESP_FAIL, if the key_purpose of the key_id is not set to HMAC downstream purpose
+ *                  or JTAG is permanently disabled by EFUSE_HARD_DIS_JTAG eFuse parameter.
  *      * ESP_ERR_INVALID_ARG, invalid input arguments
+ *
+ * @note  Return value of the API does not indicate the JTAG status.
  */
 esp_err_t esp_hmac_jtag_enable(hmac_key_id_t key_id, const uint8_t *token);
 

components/esp_hw_support/include/soc/esp32h2/esp_hmac.h

@@ -41,10 +41,11 @@ typedef enum {
  * @param message the message for which to calculate the HMAC
  * @param message_len message length
  *             return ESP_ERR_INVALID_STATE if unsuccessful
- * @param [out] hmac the hmac result; the buffer behind the provided pointer must be 32 bytes long
+ * @param [out] hmac the hmac result; the buffer behind the provided pointer must be a writeable buffer of 32 bytes
  *
  * @return
  *      * ESP_OK, if the calculation was successful,
+ *      * ESP_ERR_INVALID_ARG if message or hmac is a nullptr or if key_id out of range
  *      * ESP_FAIL, if the hmac calculation failed
  */
 esp_err_t esp_hmac_calculate(hmac_key_id_t key_id,
@@ -63,12 +64,15 @@ esp_err_t esp_hmac_calculate(hmac_key_id_t key_id,
  *        programmed to a eFuse key block. The key block number is provided as the first parameter to this function.
  *
  * @return
- *      * ESP_OK, if the calculation was successful,
- *                if the calculated HMAC value matches with provided token,
- *                JTAG will be re-enable otherwise JTAG will remain disabled.
- *                Return value does not indicate the JTAG status.
- *      * ESP_FAIL, if the hmac calculation failed or JTAG is permanently disabled by EFUSE_HARD_DIS_JTAG eFuse parameter.
+ *      * ESP_OK, if the key_purpose of the key_id matches to HMAC downstread mode,
+ *                The API returns success even if calculated HMAC does not match with the provided token.
+ *                However, The JTAG will be re-enabled only if the calculated HMAC value matches with provided token,
+ *                otherwise JTAG will remain disabled.
+ *      * ESP_FAIL, if the key_purpose of the key_id is not set to HMAC downstream purpose
+ *                  or JTAG is permanently disabled by EFUSE_HARD_DIS_JTAG eFuse parameter.
  *      * ESP_ERR_INVALID_ARG, invalid input arguments
+ *
+ * @note  Return value of the API does not indicate the JTAG status.
  */
 esp_err_t esp_hmac_jtag_enable(hmac_key_id_t key_id, const uint8_t *token);
 

components/esp_hw_support/include/soc/esp32s2/esp_hmac.h

@@ -41,10 +41,11 @@ typedef enum {
  * @param message the message for which to calculate the HMAC
  * @param message_len message length
  *             return ESP_ERR_INVALID_STATE if unsuccessful
- * @param [out] hmac the hmac result; the buffer behind the provided pointer must be 32 bytes long
+ * @param [out] hmac the hmac result; the buffer behind the provided pointer must be a writeable buffer of 32 bytes
  *
  * @return
  *      * ESP_OK, if the calculation was successful,
+ *      * ESP_ERR_INVALID_ARG if message or hmac is a nullptr or if key_id out of range
  *      * ESP_FAIL, if the hmac calculation failed
  */
 esp_err_t esp_hmac_calculate(hmac_key_id_t key_id,
@@ -64,12 +65,15 @@ esp_err_t esp_hmac_calculate(hmac_key_id_t key_id,
  *        programmed to a eFuse key block. The key block number is provided as the first parameter to this function.
  *
  * @return
- *      * ESP_OK, if the calculation was successful,
- *                if the calculated HMAC value matches with provided token,
- *                JTAG will be re-enable otherwise JTAG will remain disabled.
- *                Return value does not indicate the JTAG status.
- *      * ESP_FAIL, if the hmac calculation failed or JTAG is permanently disabled by EFUSE_HARD_DIS_JTAG eFuse parameter.
+ *      * ESP_OK, if the key_purpose of the key_id matches to HMAC downstread mode,
+ *                The API returns success even if calculated HMAC does not match with the provided token.
+ *                However, The JTAG will be re-enabled only if the calculated HMAC value matches with provided token,
+ *                otherwise JTAG will remain disabled.
+ *      * ESP_FAIL, if the key_purpose of the key_id is not set to HMAC downstream purpose
+ *                  or JTAG is permanently disabled by EFUSE_HARD_DIS_JTAG eFuse parameter.
  *      * ESP_ERR_INVALID_ARG, invalid input arguments
+ *
+ * @note  Return value of the API does not indicate the JTAG status.
  */
 esp_err_t esp_hmac_jtag_enable(hmac_key_id_t key_id,
         const uint8_t *token);

components/esp_hw_support/include/soc/esp32s3/esp_hmac.h

@@ -38,7 +38,7 @@ typedef enum {
  *        The corresponding purpose field of the key block in the efuse must be set to the HMAC upstream purpose value.
  * @param message the message for which to calculate the HMAC
  * @param message_len message length
- * @param [out] hmac the hmac result; the buffer behind the provided pointer must be 32 bytes long
+ * @param [out] hmac the hmac result; the buffer behind the provided pointer must be a writeable buffer of 32 bytes
  *
  * @return
  *      * ESP_OK, if the calculation was successful,
@@ -61,12 +61,15 @@ esp_err_t esp_hmac_calculate(hmac_key_id_t key_id,
  *        programmed to a eFuse key block. The key block number is provided as the first parameter to this function.
  *
  * @return
- *      * ESP_OK, if the calculation was successful,
- *                if the calculated HMAC value matches with provided token,
- *                JTAG will be re-enable otherwise JTAG will remain disabled.
- *                Return value does not indicate the JTAG status.
- *      * ESP_FAIL, if the hmac calculation failed or JTAG is permanently disabled by EFUSE_HARD_DIS_JTAG eFuse parameter.
+ *      * ESP_OK, if the key_purpose of the key_id matches to HMAC downstread mode,
+ *                The API returns success even if calculated HMAC does not match with the provided token.
+ *                However, The JTAG will be re-enabled only if the calculated HMAC value matches with provided token,
+ *                otherwise JTAG will remain disabled.
+ *      * ESP_FAIL, if the key_purpose of the key_id is not set to HMAC downstream purpose
+ *                  or JTAG is permanently disabled by EFUSE_HARD_DIS_JTAG eFuse parameter.
  *      * ESP_ERR_INVALID_ARG, invalid input arguments
+ *
+ * @note  Return value of the API does not indicate the JTAG status.
  */
 esp_err_t esp_hmac_jtag_enable(hmac_key_id_t key_id, const uint8_t *token);
 

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

@@ -32,7 +32,7 @@ Furthermore, the {IDF_TARGET_NAME} has three different application scenarios for
 #. HMAC is used as a key for the Digital Signature (DS) module
 #. HMAC is used for enabling the soft-disabled JTAG interface
 
-The first mode is also called *Upstream* mode, while the last two modes are also called *Downstream* modes.
+The first mode is called *Upstream* mode, while the last two modes are called *Downstream* modes.
 
 eFuse Keys for HMAC
 ^^^^^^^^^^^^^^^^^^^
@@ -59,7 +59,7 @@ This is to prevent the usage of a key for a different function than originally i
 
 To calculate an HMAC, the software has to provide the ID of the key block containing the secret key as well as the *key purpose* (see *{IDF_TARGET_NAME} Technical Reference Manual* > *eFuse Controller (eFuse)* [`PDF <{IDF_TARGET_TRM_EN_URL}#efuse>`__]).
 Before the HMAC key calculation, the HMAC module looks up the purpose of the provided key block.
-The calculation only proceeds if the provided key purpose matches the purpose stored in the eFuses of the key block provided by the ID.
+The calculation only proceeds if the purpose of the provided key block matches the purpose stored in the eFuses of the key block provided by the ID.
 
 HMAC Generation for Software
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -68,8 +68,7 @@ Key Purpose value: 8
 In this case, the HMAC is given out to the software (e.g. to authenticate a message).
 
 The API to calculate the HMAC is :cpp:func:`esp_hmac_calculate`.
-Only the message, message length and the eFuse key block ID have to be provided to that function.
-The rest, like setting the key purpose, is done automatically.
+The input arguments for the function are the message, message length and the eFuse key block ID which contains the secret and has efuse key purpose set to Upstream mode.
 
 HMAC for Digital Signature
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -95,7 +94,15 @@ Setup
 1. Generate a 256-bit HMAC secret key to use for JTAG re-enable.
 2. Write the key to an eFuse block with key purpose HMAC_DOWN_ALL (5) or HMAC_DOWN_JTAG (6). This can be done using the ets_efuse_write_key() function in the firmware or using espefuse.py from the host.
 3. Configure the eFuse key block to be read protected using the esp_efuse_set_read_protect(), so that software cannot read back the value.
-4. Burn the "soft JTAG disable" bit by esp_efuse_write_field_bit(ESP_EFUSE_SOFT_DIS_JTAG). This will permanently disable JTAG unless the correct key value is provided by software.
+4. Burn the "soft JTAG disable" bit/bits on {IDF_TARGET_NAME}. This will permanently disable JTAG unless the correct key value is provided by software.
+
+.. only:: esp32s2
+
+    .. note:: The API *esp_efuse_write_field_bit(ESP_EFUSE_SOFT_DIS_JTAG)* can be used to burn "soft JTAG disable" bit on {IDF_TARGET_NAME}.
+
+.. only:: esp32s3 or esp32c3 or esp32h2
+
+    .. note:: The API *esp_efuse_write_field_cnt(ESP_EFUSE_SOFT_DIS_JTAG, ESP_EFUSE_SOFT_DIS_JTAG[0]->bit_count)* can be used to burn "soft JTAG disable" bits on {IDF_TARGET_NAME}.
 
 JTAG enable