1 /*
2  * SPDX-FileCopyrightText: 2015-2021 Espressif Systems (Shanghai) CO LTD
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  */
6 
7 #pragma once
8 
9 #include "esp_err.h"
10 
11 #ifdef __cplusplus
12 extern "C" {
13 #endif
14 
15 /**
16  * The possible efuse keys for the HMAC peripheral
17  */
18 typedef enum {
19     HMAC_KEY0 = 0,
20     HMAC_KEY1,
21     HMAC_KEY2,
22     HMAC_KEY3,
23     HMAC_KEY4,
24     HMAC_KEY5,
25     HMAC_KEY_MAX
26 } hmac_key_id_t;
27 
28 /**
29  * @brief
30  * Calculate the HMAC of a given message.
31  *
32  * Calculate the HMAC \c hmac of a given message \c message with length \c message_len.
33  * SHA256 is used for the calculation (fixed on ESP32S3).
34  *
35  * @note Uses the HMAC peripheral in "upstream" mode.
36  *
37  * @param key_id Determines which of the 6 key blocks in the efuses should be used for the HMAC calcuation.
38  *        The corresponding purpose field of the key block in the efuse must be set to the HMAC upstream purpose value.
39  * @param message the message for which to calculate the HMAC
40  * @param message_len message length
41  * @param [out] hmac the hmac result; the buffer behind the provided pointer must be 32 bytes long
42  *
43  * @return
44  *      * ESP_OK, if the calculation was successful,
45  *      * ESP_ERR_INVALID_ARG if message or hmac is a nullptr or if key_id out of range
46  *      * ESP_FAIL, if the hmac calculation failed
47  */
48 esp_err_t esp_hmac_calculate(hmac_key_id_t key_id,
49         const void *message,
50         size_t message_len,
51         uint8_t *hmac);
52 
53 /**
54  * @brief Use HMAC peripheral in Downstream mode to re-enable the JTAG, if it is not permanently disabled by HW.
55  *        In downstream mode, HMAC calculations performed by peripheral are used internally and not provided back to user.
56  *
57  * @param key_id Determines which of the 6 key blocks in the efuses should be used for the HMAC calculation.
58  *        The corresponding purpose field of the key block in the efuse must be set to HMAC downstream purpose.
59  *
60  * @param token Pre calculated HMAC value of the 32-byte 0x00 using SHA-256 and the known private HMAC key. The key is already
61  *        programmed to a eFuse key block. The key block number is provided as the first parameter to this function.
62  *
63  * @return
64  *      * ESP_OK, if the calculation was successful,
65  *                if the calculated HMAC value matches with provided token,
66  *                JTAG will be re-enable otherwise JTAG will remain disabled.
67  *                Return value does not indicate the JTAG status.
68  *      * ESP_FAIL, if the hmac calculation failed or JTAG is permanently disabled by EFUSE_HARD_DIS_JTAG eFuse parameter.
69  *      * ESP_ERR_INVALID_ARG, invalid input arguments
70  */
71 esp_err_t esp_hmac_jtag_enable(hmac_key_id_t key_id, const uint8_t *token);
72 
73 /**
74  *  @brief Disable the JTAG which might be enabled using the HMAC downstream mode. This function just clears the result generated
75  *         by calling esp_hmac_jtag_enable() API.
76  *
77  *  @return
78  *       * ESP_OK return ESP_OK after writing the HMAC_SET_INVALIDATE_JTAG_REG with value 1.
79  */
80 esp_err_t esp_hmac_jtag_disable(void);
81 
82 #ifdef __cplusplus
83 }
84 #endif
85