esp-idf/components/hal/esp32c3/include/hal/hmac_hal.h

// Copyright 2020 Espressif Systems (Shanghai) PTE LTD
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

/*******************************************************************************
 * NOTICE
 * The hal is not public api, don't use it in application code.
 * See readme.md in soc/include/hal/readme.md
 ******************************************************************************/

#pragma once

#include <stdint.h>
#include <stdbool.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * The HMAC peripheral can be configured to deliver its output to the user directly, or to deliver
 * the output directly to another peripheral instead, e.g. the Digital Signature peripheral.
 */
typedef enum {
    HMAC_OUTPUT_USER = 0,           /**< Let user provide a message and read the HMAC result */
    HMAC_OUTPUT_DS = 1,             /**< HMAC is provided to the DS peripheral to decrypt DS private key parameters */
    HMAC_OUTPUT_JTAG_ENABLE = 2,    /**< HMAC is used to enable JTAG after soft-disabling it */
    HMAC_OUTPUT_ALL = 3             /**< HMAC is used for both as DS input for or enabling JTAG */
} hmac_hal_output_t;

/**
 * @brief Make the peripheral ready for use.
 *
 * This triggers any further steps necessary after enabling the device
 */
void hmac_hal_start(void);

/**
 * @brief Configure which hardware key slot should be used and configure the target of the HMAC output.
 *
 * @note Writing out-of-range values is undefined behavior. The user has to ensure that the parameters are in range.
 *
 * @param config The target of the HMAC. Possible targets are described in \c hmac_hal_output_t.
 * See the ESP32C3 TRM for more details.
 * @param key_id The ID of the hardware key slot to be used.
 *
 * @return 0 if the configuration was successful, non-zero if not.
 * An unsuccessful configuration means that the purpose value in the eFuse of the corresponding key slot
 * doesn't match to supplied value of \c config.
 */
uint32_t hmac_hal_configure(hmac_hal_output_t config, uint32_t key_id);

/**
 * @brief Write a padded single-block message of 512 bits to the HMAC peripheral.
 *
 * The message must not be longer than one block (512 bits) and the padding has to be applied by software before
 * writing. The padding has to be able to fit into the block after the message.
 * For more information on HMAC padding, see the ESP32C3 TRM.
 */
void hmac_hal_write_one_block_512(const void *block);

/**
 * @brief Write a message block of 512 bits to the HMAC peripheral.
 *
 * This function must be used incombination with \c hmac_hal_next_block_normal() or \c hmac_hal_next_block_padding().
 * The first message block is written without any prerequisite.
 * All message blocks which are not the last one, need a call to \c hmac_hal_next_block_normal() before, indicating
 * to the hardware that a "normal", i.e. non-padded block will follow. This is even the case for a block which begins
 * padding already but where the padding doesn't fit in (remaining message size > (block size - padding size)).
 * Before writing the last block which contains the padding, a call to \c hmac_hal_next_block_padding() is necessary
 * to indicate to the hardware that a block with padding will be written.
 *
 * For more information on HMAC padding, see the ESP32C3 TRM.
 */
void hmac_hal_write_block_512(const void *block);

/**
 * @brief Indicate to the hardware that a normal block will be written.
 */
void hmac_hal_next_block_normal(void);

/**
 * @brief Indicate to the hardware that a block with padding will be written.
 */
void hmac_hal_next_block_padding(void);

/**
 * @brief Read the 256 bit HMAC result from the hardware.
 */
void hmac_hal_read_result_256(void *result);

/**
 * @brief Clear (invalidate) the HMAC result provided to other hardware.
 */
void hmac_hal_clean(void);

#ifdef __cplusplus
}
#endif