[esp_hw_support]: HMAC upstream support for S3

components/hal/esp32s3/hmac_hal.c

@@ -0,0 +1,74 @@
+/*
+ * SPDX-FileCopyrightText: 2015-2021 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include "hal/hmac_hal.h"
+#include "hal/hmac_ll.h"
+
+void hmac_hal_start(void)
+{
+    hmac_ll_wait_idle();
+    hmac_ll_start();
+}
+
+uint32_t hmac_hal_configure(hmac_hal_output_t config, uint32_t key_id)
+{
+    hmac_ll_wait_idle();
+    hmac_ll_config_output(config);
+    hmac_ll_config_hw_key_id(key_id);
+    hmac_ll_config_finish();
+    hmac_ll_wait_idle();
+
+    uint32_t conf_error = hmac_ll_query_config_error();
+    if (conf_error) {
+        hmac_ll_calc_finish();
+        return 1;
+    } else if (config != HMAC_OUTPUT_USER) {
+        // In "downstream" mode, this will be the last hmac operation. Make sure HMAC is ready for
+        // the other peripheral.
+        hmac_ll_wait_idle();
+    }
+
+    return 0;
+}
+
+void hmac_hal_write_one_block_512(const void *block)
+{
+    hmac_ll_wait_idle();
+    hmac_ll_write_block_512(block);
+    hmac_ll_wait_idle();
+    hmac_ll_msg_one_block();
+}
+
+void hmac_hal_write_block_512(const void *block)
+{
+    hmac_ll_wait_idle();
+    hmac_ll_write_block_512(block);
+}
+
+void hmac_hal_next_block_padding(void)
+{
+    hmac_ll_wait_idle();
+    hmac_ll_msg_padding();
+}
+
+void hmac_hal_next_block_normal(void)
+{
+    hmac_ll_wait_idle();
+    hmac_ll_msg_continue();
+}
+
+void hmac_hal_read_result_256(void *result)
+{
+    hmac_ll_wait_idle();
+    hmac_ll_read_result_256(result);
+    hmac_ll_calc_finish();
+}
+
+void hmac_hal_clean(void)
+{
+    hmac_ll_wait_idle();
+    hmac_ll_clean();
+}

components/hal/esp32s3/include/hal/clk_gate_ll.h

@@ -1,16 +1,8 @@
-// Copyright 2015-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.
+/*
+ * SPDX-FileCopyrightText: 2015-2021 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
 
 #pragma once
 
@@ -99,6 +91,10 @@ static inline uint32_t periph_ll_get_clk_en_mask(periph_module_t periph)
         return SYSTEM_CRYPTO_SHA_CLK_EN;
     case PERIPH_RSA_MODULE:
         return SYSTEM_CRYPTO_RSA_CLK_EN;
+    case PERIPH_HMAC_MODULE:
+        return SYSTEM_CRYPTO_HMAC_CLK_EN;
+    case PERIPH_DS_MODULE:
+        return SYSTEM_CRYPTO_DS_CLK_EN;
     default:
         return 0;
     }
@@ -106,9 +102,6 @@ static inline uint32_t periph_ll_get_clk_en_mask(periph_module_t periph)
 
 static inline uint32_t periph_ll_get_rst_en_mask(periph_module_t periph, bool enable)
 {
-
-    (void)enable; // unused
-
     switch (periph) {
     case PERIPH_RMT_MODULE:
         return SYSTEM_RMT_RST;
@@ -162,6 +155,8 @@ static inline uint32_t periph_ll_get_rst_en_mask(periph_module_t periph, bool en
         return SYSTEM_RST_EN_DEDICATED_GPIO;
     case PERIPH_GDMA_MODULE:
         return SYSTEM_DMA_RST;
+    case PERIPH_HMAC_MODULE:
+        return SYSTEM_CRYPTO_HMAC_RST;
     case PERIPH_AES_MODULE:
         if (enable == true) {
             // Clear reset on digital signature, otherwise AES unit is held in reset also.
@@ -207,6 +202,7 @@ static uint32_t periph_ll_get_clk_en_reg(periph_module_t periph)
     case PERIPH_SDMMC_MODULE:
     case PERIPH_LCD_CAM_MODULE:
     case PERIPH_GDMA_MODULE:
+    case PERIPH_HMAC_MODULE:
     case PERIPH_AES_MODULE:
     case PERIPH_SHA_MODULE:
     case PERIPH_RSA_MODULE:
@@ -230,8 +226,9 @@ static uint32_t periph_ll_get_rst_en_reg(periph_module_t periph)
         return SYSTEM_CORE_RST_EN_REG;
     case PERIPH_UART2_MODULE:
     case PERIPH_SDMMC_MODULE:
-    case PERIPH_GDMA_MODULE:
     case PERIPH_LCD_CAM_MODULE:
+    case PERIPH_GDMA_MODULE:
+    case PERIPH_HMAC_MODULE:
     case PERIPH_AES_MODULE:
     case PERIPH_SHA_MODULE:
     case PERIPH_RSA_MODULE:

components/hal/esp32s3/include/hal/hmac_hal.h

@@ -0,0 +1,101 @@
+/*
+ * SPDX-FileCopyrightText: 2015-2021 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/*******************************************************************************
+ * 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 ESP32S3 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 ESP32S3 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 ESP32S3 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

components/hal/esp32s3/include/hal/hmac_ll.h

@@ -0,0 +1,187 @@
+/*
+ * SPDX-FileCopyrightText: 2015-2021 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/*******************************************************************************
+ * 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 "soc/hwcrypto_reg.h"
+
+#define SHA256_BLOCK_SZ 64
+#define SHA256_DIGEST_SZ 32
+
+#define HMAC_LL_EFUSE_KEY_PURPOSE_DOWN_JTAG 6
+#define HMAC_LL_EFUSE_KEY_PURPOSE_DOWN_DIGITAL_SIGNATURE 7
+#define HMAC_LL_EFUSE_KEY_PURPOSE_UP 8
+#define HMAC_LL_EFUSE_KEY_PURPOSE_DOWN_ALL 5
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * Makes the peripheral ready for use, after enabling it.
+ */
+static inline void hmac_ll_start(void)
+{
+    REG_WRITE(HMAC_SET_START_REG, 1);
+}
+
+/**
+ * @brief Determine where the HMAC output should go.
+ *
+ * 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.
+ */
+static inline void hmac_ll_config_output(hmac_hal_output_t config)
+{
+    switch(config) {
+    case HMAC_OUTPUT_USER:
+        REG_WRITE(HMAC_SET_PARA_PURPOSE_REG, HMAC_LL_EFUSE_KEY_PURPOSE_UP);
+        break;
+    case HMAC_OUTPUT_DS:
+        REG_WRITE(HMAC_SET_PARA_PURPOSE_REG, HMAC_LL_EFUSE_KEY_PURPOSE_DOWN_DIGITAL_SIGNATURE);
+        break;
+    case HMAC_OUTPUT_JTAG_ENABLE:
+        REG_WRITE(HMAC_SET_PARA_PURPOSE_REG, HMAC_LL_EFUSE_KEY_PURPOSE_DOWN_JTAG);
+        break;
+    case HMAC_OUTPUT_ALL:
+        REG_WRITE(HMAC_SET_PARA_PURPOSE_REG, HMAC_LL_EFUSE_KEY_PURPOSE_DOWN_ALL);
+        break;
+    default:
+        ; // do nothing, error will be indicated by hmac_hal_config_error()
+    }
+}
+
+/**
+ * @brief Selects which hardware key should be used.
+ */
+static inline void hmac_ll_config_hw_key_id(uint32_t key_id)
+{
+    REG_WRITE(HMAC_SET_PARA_KEY_REG, key_id);
+}
+
+/**
+ * @brief Apply and check configuration.
+ *
+ * Afterwards, the configuration can be checked for errors with hmac_hal_config_error().
+ */
+static inline void hmac_ll_config_finish(void)
+{
+    REG_WRITE(HMAC_SET_PARA_FINISH_REG, 1);
+}
+
+/**
+ *
+ * @brief Query HMAC error state after configuration actions.
+ *
+ * @return
+ *  - 1 or greater on error
+ *  - 0 on success
+ */
+static inline uint32_t hmac_ll_query_config_error(void)
+{
+    return REG_READ(HMAC_QUERY_ERROR_REG);
+}
+
+/**
+ * Wait until the HAL is ready for the next interaction.
+ */
+static inline void hmac_ll_wait_idle(void)
+{
+    uint32_t query;
+    do {
+        query = REG_READ(HMAC_QUERY_BUSY_REG);
+    } while(query != 0);
+}
+
+/**
+ * @brief Write a message block of 512 bits to the HMAC peripheral.
+ */
+static inline void hmac_ll_write_block_512(const uint32_t *block)
+{
+    const size_t REG_WIDTH = sizeof(uint32_t);
+    for (size_t i = 0; i < SHA256_BLOCK_SZ / REG_WIDTH; i++) {
+        REG_WRITE(HMAC_WDATA_BASE + (i * REG_WIDTH), block[i]);
+    }
+
+    REG_WRITE(HMAC_SET_MESSAGE_ONE_REG, 1);
+}
+
+/**
+ * @brief Read the 256 bit HMAC.
+ */
+static inline void hmac_ll_read_result_256(uint32_t *result)
+{
+    const size_t REG_WIDTH = sizeof(uint32_t);
+    for (size_t i = 0; i < SHA256_DIGEST_SZ / REG_WIDTH; i++) {
+        result[i] = REG_READ(HMAC_RDATA_BASE + (i * REG_WIDTH));
+    }
+}
+
+/**
+ * @brief Clean the HMAC result provided to other hardware.
+ */
+static inline void hmac_ll_clean(void)
+{
+    REG_WRITE(HMAC_SET_INVALIDATE_DS_REG, 1);
+    REG_WRITE(HMAC_SET_INVALIDATE_JTAG_REG, 1);
+}
+
+/**
+ * @brief Signals that the following block will be the padded last block.
+ */
+static inline void hmac_ll_msg_padding(void)
+{
+    REG_WRITE(HMAC_SET_MESSAGE_PAD_REG, 1);
+}
+
+/**
+ * @brief Signals that all blocks have been written and a padding block will automatically be applied by hardware.
+ *
+ * Only applies if the message length is a multiple of 512 bits.
+ * See ESP32S3 TRM HMAC chapter for more details.
+ */
+static inline void hmac_ll_msg_end(void)
+{
+    REG_WRITE(HMAC_SET_MESSAGE_END_REG, 1);
+}
+
+/**
+ * @brief The message including padding fits into one block, so no further action needs to be taken.
+ *
+ * This is called after the one-block-message has been written.
+ */
+static inline void hmac_ll_msg_one_block(void)
+{
+    REG_WRITE(HMAC_ONE_BLOCK_REG, 1);
+}
+
+/**
+ * @brief Indicate that more blocks will be written after the last block.
+ */
+static inline void hmac_ll_msg_continue(void)
+{
+    REG_WRITE(HMAC_SET_MESSAGE_ING_REG, 1);
+}
+
+/**
+ * @brief Clear the HMAC result.
+ *
+ * Use this after reading the HMAC result or if aborting after any of the other steps above.
+ */
+static inline void hmac_ll_calc_finish(void)
+{
+    REG_WRITE(HMAC_SET_RESULT_FINISH_REG, 2);
+}
+
+#ifdef __cplusplus
+}
+#endif