基于 ESP-IDF v5.5 安全迁移硬件 SHA 子函数 API 必须显式调用 esp_sha_set_mode【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf从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 引擎与子函数 APIESP32 系列芯片内置硬件 SHA 加速引擎SHA Accelerator可大幅提升 SHA-1 / SHA-2 系列哈希计算的性能与功耗表现。ESP-IDF 的 mbedtls 组件为其提供了两层接口面向应用的高层 APImbedtls/shaXX.h如mbedtls_sha256()等内部自动使用硬件加速面向底层实现/高级用户的子函数 APIesp_sha_block、esp_sha_dma、esp_sha_set_mode、esp_sha_read_digest_state等这些接口是构建完整 SHA 算法的“积木”building blocks声明于 sha_core.hDMA 版本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;可用算法包括算法枚举摘要长度字节数据块大小字节SHA12064SHA2_2242864SHA2_2563264SHA2_384需SOC_SHA_SUPPORT_SHA38448128SHA2_512需SOC_SHA_SUPPORT_SHA51264128SHA2_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.his_first_block语义esp_sha_block与esp_sha_dma的is_first_block参数为true时引擎会以该算法的初始状态开始计算为false时沿用引擎已有状态用于分块连续哈希对大多数应用无感知普通应用通过 mbedtls 高层 API如mbedtls_sha256使用 SHA 功能不受本次 API 行为变更影响该变更主要影响直接调用上述底层子函数 API 的驱动、安全库与测试代码。五、参考实现与验证路径仓库中可找到遵循新调用契约的参考实现与测试底层实现core/sha.cesp_sha_set_mode/esp_sha_block/esp_sha_dma实现、parallel_engine/sha.c头文件契约sha_core.h、sha_parallel_engine.h使用示例先 acquire 再 set_mode 再 dmasha_dma.c迁移前行为对比v5.5 之前的版本中esp_sha_block/esp_sha_dma会在内部自行设置模式升级后请检查所有直接调用点为每个调用补充esp_sha_set_mode。如需进一步了解迁移影响范围可查阅 v5.5 迁移指南目录 中其他章节中文版对应文档见 security.rst中文。【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考