基于 ESP-IDF v5.5 安全迁移:硬件 SHA 子函数 API 必须显式调用 esp_sha_set_mode
基于 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(); /* 关闭时钟并释放硬件锁 */
以下几点可从源码得到印证:
esp_sha_set_mode的底层实现:在 core/sha.c 中,其实现为sha_hal_wait_idle()+sha_hal_set_mode(sha_type),即先等待 SHA 引擎空闲,再通过 HAL 层将模式寄存器配置为指定算法;esp_sha_block的底层实现:同样是 core/sha.c 中的sha_hal_hash_block(sha_type, data_block, block_length(sha_type) / 4, is_first_block),其中数据块长度由算法决定(见下文);- 头文件注释的明确要求:
sha_core.h中esp_sha_block与esp_sha_dma的文档注释均明确写道:"Callesp_sha_acquire_hardware()andesp_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(中文)。