基于 ESP-IDF v5.5 安全迁移:硬件 SHA 子函数 API 必须显式调用 esp_sha_set_mode

原创2026-09-16 16:23:48828 阅读
文章标签:物联网嵌入式嵌入式OSRTOS固件驱动开发硬件开发网络蓝牙IoT协议系统编程认证鉴权

基于 ESP-IDF v5.5 安全迁移:硬件 SHA 子函数 API 必须显式调用 esp_sha_set_mode

从 ESP-IDF v5.5 开始,Mbed TLS 底层硬件 SHA 加速相关的子函数 API(:cpp:func:esp_sha_block与:cpp:func:esp_sha_dma)在使用方式上发生了一项关键行为变更:此前这两个 API 会在内部自动设置 SHA 工作模式(SHA mode),而从 v5.5 起,调用者必须在调用它们之前显式地通过 esp_sha_set_mode 指定所需的哈希算法。本文面向从 v5.5 之前的版本迁移,或正在直接使用 ESP-IDF 硬件 SHA 底层接口的开发者,说明该变更的来龙去脉、正确调用序列、可用的算法类型枚举,以及迁移时的注意事项与验证方法。

一、变更背景:硬件 SHA 引擎与子函数 API

ESP32 系列芯片内置硬件 SHA 加速引擎(SHA Accelerator),可大幅提升 SHA-1 / SHA-2 系列哈希计算的性能与功耗表现。ESP-IDF 的 mbedtls 组件为其提供了两层接口:

  • 面向应用的高层 API:mbedtls/shaXX.h(如 mbedtls_sha256() 等),内部自动使用硬件加速;
  • 面向底层实现/高级用户的子函数 API:esp_sha_block、esp_sha_dma、esp_sha_set_mode、esp_sha_read_digest_state 等,这些接口是构建完整 SHA 算法的“积木”(building blocks),声明于 sha_core.h(DMA 版本,SOC_SHA_SUPPORT_DMA)与 sha_parallel_engine.h(并行引擎版本)。

根据 v5.5 迁移文档,变更核心可概括为:

此前,这些 API 会在内部设置 SHA 模式;更新后,你必须在使用它们之前显式设置 SHA 模式。例如,若打算使用 SHA-256 算法,必须先以参数 SHA2_256 调用 esp_sha_set_mode。

二、正确调用序列:显式设置模式

迁移后的标准调用模式为:先 esp_sha_set_mode(...),再调用 esp_sha_block 或 esp_sha_dma。文档给出的最小示例:

esp_sha_set_mode(SHA2_256);

结合 sha_core.h 中的接口注释与 sha_dma.c 测试用例的用法,一次完整的硬件 SHA 操作通常遵循如下调用序列:

esp_sha_acquire_hardware();          /* 使能 SHA 外设时钟并获取硬件锁 */
esp_sha_set_mode(sha_type);          /* 显式设置 SHA 算法模式,如 SHA2_256 */
esp_sha_dma(sha_type, input, ilen, buf, buf_len, is_first_block);
/* 或 esp_sha_block(sha_type, data_block, is_first_block); */
esp_sha_release_hardware();          /* 关闭时钟并释放硬件锁 */

以下几点可从源码得到印证:

  1. esp_sha_set_mode 的底层实现:在 core/sha.c 中,其实现为 sha_hal_wait_idle() + sha_hal_set_mode(sha_type),即先等待 SHA 引擎空闲,再通过 HAL 层将模式寄存器配置为指定算法;
  2. esp_sha_block 的底层实现:同样是 core/sha.c 中的 sha_hal_hash_block(sha_type, data_block, block_length(sha_type) / 4, is_first_block),其中数据块长度由算法决定(见下文);
  3. 头文件注释的明确要求:sha_core.h 中 esp_sha_block 与 esp_sha_dma 的文档注释均明确写道:"Call esp_sha_acquire_hardware() and esp_sha_set_mode() before calling this function."——即调用前必须先获取硬件并设置模式,这正是 v5.5 强制要求的新契约。

三、SHA 算法类型枚举与块长度约束

esp_sha_type 类型定义于 sha_types.h,其本质是 typedef SHA_TYPE esp_sha_type;,可用算法包括:

算法枚举 摘要长度(字节) 数据块大小(字节)
SHA1 20 64
SHA2_224 28 64
SHA2_256 32 64
SHA2_384(需 SOC_SHA_SUPPORT_SHA384) 48 128
SHA2_512(需 SOC_SHA_SUPPORT_SHA512) 64 128
SHA2_512224 / SHA2_512256 / SHA2_512T(需 SOC_SHA_SUPPORT_SHA512_T) 按 t 截断 128

注:块长度信息来自 sha_core.h 与 sha.c 中 block_length() 的实现。部分算法(如 SHA-384/512)仅在支持相应外设能力的芯片上可用,具体以 soc_caps.h 中的 SOC_SHA_SUPPORT_* 宏为准。

四、迁移注意事项与边界约束

直接使用这些子函数 API 属于底层用法,迁移到 v5.5 及以后版本时需要注意:

  • 必须保持调用顺序:esp_sha_set_mode 需在 esp_sha_block / esp_sha_dma 之前调用;若跳过该步骤,硬件 SHA 引擎的模式将处于未定义状态,计算结果不可预期。esp_sha_dma 的 buf 参数长度不能超过单个块长度(128 字节),其返回值 0 表示成功;
  • 硬件锁与并发安全:esp_sha_acquire_hardware() 会同时获取 SHA 与 crypto DMA 的锁,esp_sha_release_hardware() 负责释放;SHA 与 AES 引擎共享 crypto DMA,二者无法并行计算(见 sha_core.h 头注释)。若与 TLS 连接同时使用,锁竞争可能造成阻塞,此时应优先使用 mbedtls 高层 SHA API 或 esp_sha_try_lock_engine() 并回退到软件实现(见 sha_parallel_engine.h);
  • is_first_block 语义:esp_sha_block 与 esp_sha_dma 的 is_first_block 参数为 true 时,引擎会以该算法的初始状态开始计算;为 false 时沿用引擎已有状态,用于分块连续哈希;
  • 对大多数应用无感知:普通应用通过 mbedtls 高层 API(如 mbedtls_sha256)使用 SHA 功能,不受本次 API 行为变更影响;该变更主要影响直接调用上述底层子函数 API 的驱动、安全库与测试代码。

五、参考实现与验证路径

仓库中可找到遵循新调用契约的参考实现与测试:

  • 底层实现:core/sha.c(esp_sha_set_mode / esp_sha_block / esp_sha_dma 实现)、parallel_engine/sha.c;
  • 头文件契约:sha_core.h、sha_parallel_engine.h;
  • 使用示例(先 acquire 再 set_mode 再 dma):sha_dma.c;
  • 迁移前行为对比:v5.5 之前的版本中,esp_sha_block / esp_sha_dma 会在内部自行设置模式,升级后请检查所有直接调用点,为每个调用补充 esp_sha_set_mode。

如需进一步了解迁移影响范围,可查阅 v5.5 迁移指南目录 中其他章节;中文版对应文档见 security.rst(中文)。

登录后查看全文
esp-idf