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