1 /* 2 * SPDX-FileCopyrightText: 2020-2022 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 /******************************************************************************* 8 * NOTICE 9 * The hal is not public api, don't use it in application code. 10 * See readme.md in soc/include/hal/readme.md 11 ******************************************************************************/ 12 13 #pragma once 14 15 #include <stdint.h> 16 #include <stdbool.h> 17 18 #ifdef __cplusplus 19 extern "C" { 20 #endif 21 22 /** 23 * The HMAC peripheral can be configured to deliver its output to the user directly, or to deliver 24 * the output directly to another peripheral instead, e.g. the Digital Signature peripheral. 25 */ 26 typedef enum { 27 HMAC_OUTPUT_USER = 0, /**< Let user provide a message and read the HMAC result */ 28 HMAC_OUTPUT_DS = 1, /**< HMAC is provided to the DS peripheral to decrypt DS private key parameters */ 29 HMAC_OUTPUT_JTAG_ENABLE = 2, /**< HMAC is used to enable JTAG after soft-disabling it */ 30 HMAC_OUTPUT_ALL = 3 /**< HMAC is used for both as DS input for or enabling JTAG */ 31 } hmac_hal_output_t; 32 33 /** 34 * @brief Make the peripheral ready for use. 35 * 36 * This triggers any further steps necessary after enabling the device 37 */ 38 void hmac_hal_start(void); 39 40 /** 41 * @brief Configure which hardware key slot should be used and configure the target of the HMAC output. 42 * 43 * @note Writing out-of-range values is undefined behavior. The user has to ensure that the parameters are in range. 44 * 45 * @param config The target of the HMAC. Possible targets are described in \c hmac_hal_output_t. 46 * See the TRM of your target chip for more details. 47 * @param key_id The ID of the hardware key slot to be used. 48 * 49 * @return 0 if the configuration was successful, non-zero if not. 50 * An unsuccessful configuration means that the purpose value in the eFuse of the corresponding key slot 51 * doesn't match to supplied value of \c config. 52 */ 53 uint32_t hmac_hal_configure(hmac_hal_output_t config, uint32_t key_id); 54 55 /** 56 * @brief Write a padded single-block message of 512 bits to the HMAC peripheral. 57 * 58 * The message must not be longer than one block (512 bits) and the padding has to be applied by software before 59 * writing. The padding has to be able to fit into the block after the message. 60 * For more information on HMAC padding, see the TRM of your target chip. 61 */ 62 void hmac_hal_write_one_block_512(const void *block); 63 64 /** 65 * @brief Write a message block of 512 bits to the HMAC peripheral. 66 * 67 * This function must be used incombination with \c hmac_hal_next_block_normal() or \c hmac_hal_next_block_padding(). 68 * The first message block is written without any prerequisite. 69 * All message blocks which are not the last one, need a call to \c hmac_hal_next_block_normal() before, indicating 70 * to the hardware that a "normal", i.e. non-padded block will follow. This is even the case for a block which begins 71 * padding already but where the padding doesn't fit in (remaining message size > (block size - padding size)). 72 * Before writing the last block which contains the padding, a call to \c hmac_hal_next_block_padding() is necessary 73 * to indicate to the hardware that a block with padding will be written. 74 * 75 * For more information on HMAC padding, see the TRM of your target chip for more details. 76 */ 77 void hmac_hal_write_block_512(const void *block); 78 79 /** 80 * @brief Indicate to the hardware that a normal block will be written. 81 */ 82 void hmac_hal_next_block_normal(void); 83 84 /** 85 * @brief Indicate to the hardware that a block with padding will be written. 86 */ 87 void hmac_hal_next_block_padding(void); 88 89 /** 90 * @brief Read the 256 bit HMAC result from the hardware. 91 */ 92 void hmac_hal_read_result_256(void *result); 93 94 /** 95 * @brief Clear (invalidate) the HMAC result provided to other hardware. 96 */ 97 void hmac_hal_clean(void); 98 99 #ifdef __cplusplus 100 } 101 #endif 102
