ARMmbed Mbed TLS 3.0迁移指南：从2.x版本升级的关键变化

ARMmbed Mbed TLS 3.0迁移指南：从2.x版本升级的关键变化

mbedtls 项目地址: https://gitcode.com/gh_mirrors/mbe/mbedtls

前言

Mbed TLS作为一款轻量级的加密库，在3.0版本中进行了重大架构调整。本文将深入解析从2.x升级到3.0版本的关键变化，帮助开发者顺利完成迁移。与常规版本升级不同，3.0版本在多个方面打破了向后兼容性，需要开发者特别注意。

配置系统重构

配置头文件拆分

3.0版本对配置系统进行了重大重构：

1. 原config.h被拆分为build_info.h和mbedtls_config.h
2. 代码中应使用#include <mbedtls/build_info.h>，不再直接包含config.h
3. 构建工具仍编辑mbedtls_config.h或通过MBEDTLS_CONFIG_FILE指定

版本控制机制

新增了配置版本符号MBEDTLS_CONFIG_VERSION：

• 设置为特定值可确保配置文件的兼容性
• 3.0.0唯一支持的值为0x03000000

结构体访问权限变更

私有化结构体字段

3.0版本中，公开头文件中的结构体字段大多变为私有：

• 不再保证结构体布局稳定性
• 直接访问私有字段将导致编译错误

迁移建议

1. 优先使用官方提供的访问器函数（getter/setter）
2. 如无对应访问器，可提交功能请求
3. 最后手段：使用MBEDTLS_PRIVATE()宏访问（有未来兼容风险）

安全功能移除与调整

移除不安全特性

3.0版本移除了多项被认为不安全或过时的功能：

1. HAVEGE模块：已被禁用多年，建议改用硬件RNG或熵种子文件
2. RFC5114 DHM参数：因其来源不明存在安全风险
3. NULL熵源选项：测试用途的MBEDTLS_TEST_NULL_ENTROPY被移除

参数检查优化

移除了MBEDTLS_CHECK_PARAMS选项：

• 空指针检查现在统一处理
• 枚举值验证将按需实现，不再依赖编译选项

密码学接口变更

函数签名更新

多项密码学函数的签名发生变化：

1. 大数运算：

   • 移除mbedtls_mpi_is_prime()
   • 改用mbedtls_mpi_is_prime_ext()并指定Miller-Rabin轮数

2. 哈希函数：

   • 移除了_ret后缀变体函数
   • 例如mbedtls_sha256_update_ret()简化为mbedtls_sha256_update()

3. RSA操作：

   • 移除了模式参数（不再支持公私钥混用）

GCM接口改进

GCM模块现在支持任意长度的分块输入：

1. mbedtls_gcm_starts()仅设置模式和nonce
2. 新增mbedtls_gcm_update_ad()处理关联数据
3. mbedtls_gcm_update()新增输出长度参数
4. mbedtls_gcm_finish()增加部分块输出缓冲区

错误代码统一

硬件相关错误

统一使用平台相关错误码：

• 原MBEDTLS_ERR_xxx_HW_ACCEL_FAILED改为MBEDTLS_ERR_PLATFORM_HW_ACCEL_FAILED
• 原MBEDTLS_ERR_xxx_FEATURE_UNAVAILABLE改为MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED

输入验证错误

统一使用MBEDTLS_ERR_xxx_BAD_INPUT_DATA替代各模块特定的无效长度错误码

迁移实践建议

1. 文档参考：仔细查阅2.28 LTS版本的文档，特别是apidoc/deprecated.html
2. 逐步测试：建议在测试环境逐步验证各功能模块
3. 替代方案：对于移除的功能，寻找更安全的替代实现
4. 代码审查：特别注意直接访问结构体字段的代码

结语

Mbed TLS 3.0通过移除过时功能、统一接口标准、增强安全性等措施，为未来的发展奠定了更坚实的基础。虽然迁移过程可能需要一定工作量，但这些改进将带来更好的安全性、可维护性和一致性。建议开发者根据本文指南，结合自身应用特点，制定合理的迁移计划。

mbedtls 项目地址: https://gitcode.com/gh_mirrors/mbe/mbedtls