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