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