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 "esp_err.h" 11 #include "stdbool.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 57 * Use HMAC peripheral in Downstream mode to re-enable the JTAG, if it is not permanently disable by HW. 58 * In downstream mode HMAC calculations perfomred by peripheral used internally and not provided back to user. 59 * 60 * @param key_id Determines which of the 6 key blocks in the efuses should be used for the HMAC calculation. 61 * The corresponding purpose field of the key block in the efuse must be set to HMAC downstream purpose. 62 * 63 * @param token Pre calculated HMAC value of the 32-byte 0x00 using SHA-256 and the known private HMAC key. The key is already 64 * programmed to a eFuse key block. The key block number is provided as the first parameter to this function. 65 * 66 * @return 67 * * ESP_OK, if the calculation was successful, 68 * if the calculated HMAC value matches with provided token, 69 * JTAG will be re-enable otherwise JTAG will remain disabled. 70 * Return value does not indicate the JTAG status. 71 * * ESP_FAIL, if the hmac calculation failed or JTAG is permanently disabled by EFUSE_HARD_DIS_JTAG eFuse parameter. 72 * * ESP_ERR_INVALID_ARG, invalid input arguments 73 */ 74 esp_err_t esp_hmac_jtag_enable(hmac_key_id_t key_id, 75 const uint8_t *token); 76 77 /** 78 * @brief 79 * Disable the JTAG which might be enable using the HMAC downstream mode. This function just clear the result generated by 80 * JTAG key by calling esp_hmac_jtag_enable() API. 81 * 82 * @return 83 * * ESP_OK return ESP_OK after writing the HMAC_SET_INVALIDATE_JTAG_REG with value 1. 84 */ 85 esp_err_t esp_hmac_jtag_disable(void); 86 87 #ifdef __cplusplus 88 } 89 #endif 90 91 #endif // _ESP_HMAC_H_ 92
