Mbed TLS 3.0 迁移指南:从 2.x 升级的破坏性变更清单与实战迁移路径

原创2026-10-07 13:51:011,877 阅读
文章标签:人工智能AI AgentAgent 框架多模态语音音频后端

Mbed TLS 3.0 迁移指南:从 2.x 升级的破坏性变更清单与实战迁移路径

本篇指南以 Mbed TLS 官方 2.x→3.0 迁移文档为主体,结合当前仓库内置的 Mbed TLS 3.2.1 源码与头文件,系统梳理 3.0 版本的所有破坏性变更:配置体系重构、结构体私有化、API 签名变化、算法与协议移除、错误码收敛等,并为每一项给出"是否影响你 + 如何迁移"的实操路径。读完本文,你将能独立评估现有 Mbed TLS 2.x 代码的受影响面,并完成到 3.x 的平滑迁移。

导读:为什么 3.0 是一次"硬升级"

与普通的小版本发布不同,Mbed TLS 3.0 主动破坏了与 2.x 的源码级兼容性——移除大量不安全或过时的功能、整顿配置选项、修改函数签名(增加返回值、增加参数、把参数改为 const)、删除此前标记为 deprecated 的函数/宏/类型。因此,无论是普通应用开发者(users)还是 alt 实现提供者(alternative implementers),都可能需要改动自己的代码才能编译并正确运行在 3.0 之上。

当前仓库 third_party/mbedtls 内置的正是 3.x 主线版本:include/mbedtls/build_info.h 中定义 MBEDTLS_VERSION_MAJOR 3、MBEDTLS_VERSION_NUMBER 0x03020100、MBEDTLS_VERSION_STRING "3.2.1",即 3.2.1。因此本指南中的所有代码示例、头文件路径与配置项,均以该版本的实际状态为准进行验证。

迁移所需的 2.x 细节,最权威的来源是 Mbed TLS 2.28 LTS 分支的文档,尤其是 apidoc/deprecated.html。本仓库只包含 3.x 代码,以下所有结论以仓库内 3.x 头文件与官方迁移文档为准。

一、通用层面的破坏性变更

1.1 配置文件引入间接层与版本号:config.h 一分为二

这是 3.0 最基础的结构性变化:

  • 原 config.h 被拆分为 build_info.h 与 mbedtls_config.h;
  • 代码中:统一使用 #include <mbedtls/build_info.h>,不要再 include mbedtls/config.h,也不要再引用 MBEDTLS_CONFIG_FILE;
  • 构建工具中:仍可编辑 mbedtls_config.h,或按老方式通过 MBEDTLS_CONFIG_FILE 指向自定义配置;
  • 版本号位置迁移:原来从 include/mbedtls/version.h 解析库版本的工具,需要改从 include/mbedtls/build_info.h 读取;从 C 代码角度看,两个头文件现在都定义 MBEDTLS_VERSION_xxx 宏。

在仓库中可验证:third_party/mbedtls/include/mbedtls/build_info.h 同时定义了 MBEDTLS_VERSION_MAJOR/NUMBER/STRING/STRING_FULL,且第 58~67 行通过 MBEDTLS_CONFIG_FILE 引入自定义配置并校验配置版本:

#if !defined(MBEDTLS_CONFIG_FILE)
#include "mbedtls/mbedtls_config.h"
#else
#include MBEDTLS_CONFIG_FILE
#endif
#if defined(MBEDTLS_CONFIG_VERSION) && ( \
    MBEDTLS_CONFIG_VERSION < 0x03000000 || \
    MBEDTLS_CONFIG_VERSION > MBEDTLS_VERSION_NUMBER )
#error "Invalid config version, defined value of MBEDTLS_CONFIG_VERSION is unsupported"
#endif

若你维护自定义配置文件,还需注意:

  • 不要再 include check_config.h 或 config_psa.h(两者现在由 build_info.h 内部处理);
  • 不要再定义 MBEDTLS_CONFIG_H;
  • 新增配置版本符号 MBEDTLS_CONFIG_VERSION:把它定义为某个值,可确保 Mbed TLS 以与该值对应的发布版(其 MBEDTLS_VERSION_NUMBER 相同)兼容的方式解析配置文件。3.0.0 唯一支持的值是 0x03000000。从上面源码可见,当前 3.2.1 会拒绝大于 0x03020100 的配置版本。

1.2 大多数结构体字段转为私有(MBEDTLS_PRIVATE)

3.0 起,公共头文件中结构体的布局不再属于稳定 API,3.1、3.2 等小版本都可能增删、改名、重排或改变结构体字段的类型。只有少数明确文档化为 public 的字段保证在 3.x 全生命周期内稳定;即便某结构体所有字段都是 public,未来版本仍可能新增字段;且部分 public 字段是只读的(修改会破坏结构体一致性)。

直接访问私有字段会编译失败。迁移路径依次为:

  1. 优先使用访问器函数,命名约定通常是 mbedtls_<MODULE>_{get,set}_<FIELD> 或 mbedtls_<MODULE>_<STRUCTURE>_{get,set}_<FIELD>;改变数据格式的访问器可能用其他动词,如 read/write(用于从文本/字节串导入导出数据);
  2. 若无访问器,向 Mbed TLS 提 enhancement request 描述你的用例(官方已知 3.0 缺失部分访问器,预期在 3.1 等小版本补充);
  3. 万不得已时可用 bar.MBEDTLS_PRIVATE(foo) 访问结构体 bar 的字段 foo——但后果自负,这类代码很可能在未来小版本中失效。

仓库中 private_access.h 即定义了 MBEDTLS_PRIVATE 宏,供 alt 实现与紧急场景使用。

1.3 timing 模块部分函数移出库

受影响的函数:mbedtls_timing_self_test()、mbedtls_hardclock_poll()、mbedtls_timing_hardclock()、mbedtls_set_alarm()。若依赖它们,请改为直接调用所在平台的对等函数。

1.4 net.h 头文件被移除

include/mbedtls/net.h 原本只是转发 include mbedtls/net_sockets.h,现在直接 include 后者。仓库中 include/mbedtls 目录已无 net.h,只有 net_sockets.h,可验证该变更。

1.5 移除 MBEDTLS_CHECK_PARAMS 选项

该选项默认关闭,仅影响显式开启它的用户。它曾提供两类"参数校验":

  • 指针非空校验:约 90% 的使用场景属于此类。关闭时空指针与其他非法指针无异,通常导致运行时崩溃;
  • 枚举类参数取值校验:关闭时非法值会静默回退到某个合法值。

默认失败动作是调用应用必须提供的 mbedtls_param_failed();若该函数返回,调用方返回 MBEDTLS_ERR_xxx_BAD_INPUT_DATA。该特性只用于部分经典(非 PSA)密码模块,未覆盖 X.509、TLS、PSA crypto,也未在所有经典模块中实现。

3.0 起该特性整体移除:库不再做 NULL 指针检查;枚举类参数校验改为按个案保留/重新引入,且不再依赖编译期开关(详见官方 issue #4313)。

1.6 移除 MBEDTLS_TEST_NULL_ENTROPY 选项

默认配置不受影响(该选项本就默认关闭)。若你依赖它且平台没有熵源,应改用 MBEDTLS_ENTROPY_NV_SEED 并确保设备在出厂时预置强随机种子;仅限测试场景,可创建并注册一个假的熵函数。

1.7 移除 HAVEGE 模块

默认配置不受影响(本就默认关闭)。仅影响直接调用 HAVEGE 模块(不推荐),或把它作为唯一熵源经熵模块使用的用户。替代方案:用 mbedtls_entropy_add_source() 声明 OS/硬件 RNG 接口,或使用设备预置阶段安全生成的熵种子文件。

1.8 移除 1.3→2.0 过渡辅助头文件

仅影响仍在使用 compat-1.3.h 的老用户。请直接在代码中使用新命名,可借助 2.x 版本中的 scripts/rename.pl(3.0 已不再包含)完成批量改名。

二、低层密码学(Low-level crypto)变更

同时参见"高层密码学"一节,部分变更两类兼有。

2.1 bignum:移除 mbedtls_mpi_is_prime()

改用 mbedtls_mpi_is_prime_ext(),它额外允许指定 Miller-Rabin 轮数。仓库 bignum.h 第 977 行确认该函数存在:int mbedtls_mpi_is_prime_ext( const mbedtls_mpi *X, int rounds, ... )。

2.2 DRBG:*_ret 函数改名

mbedtls_ctr_drbg_update_ret()、mbedtls_hmac_drbg_update_ret() 已改回无 _ret 的名字(mbedtls_ctr_drbg_update()、mbedtls_hmac_drbg_update()),调用时请检查返回值。

2.3 DHM:移除十六进制编码素数宏

以下宏全部移除:

  • RFC 5114:MBEDTLS_DHM_RFC5114_MODP_2048_P/G
  • RFC 3526:MBEDTLS_DHM_RFC3526_MODP_2048_P/G、MBEDTLS_DHM_RFC3526_MODP_3072_P/G、MBEDTLS_DHM_RFC3526_MODP_4096_P/G

RFC 5114 素数因推导过程未公开而构成安全风险,被完全移出库;RFC 3526 素数仍保留但仅以二进制形式存在。请改用 RFC 3526、RFC 7919 或其他可信来源的参数。

2.4 哈希模块:移除 deprecated 函数(MD5/SHA1/SHA256/SHA512/MD)

  • mbedtls_xxx_starts_ret() / update_ret() / finish_ret() / xxx_ret() 全部改回无 _ret 名字,调用时检查返回值;
  • mbedtls_md_init_ctx() 被移除,改用 mbedtls_md_setup();
  • mbedtls_xxx_process() 被移除,若确需调用(或要提供自定义实现),改用 mbedtls_internal_xxx_process() 并检查返回值。

2.5 MBEDTLS_ECP_FIXED_POINT_OPTIM 行为变化

该选项现在增大代码体积,但不再增加峰值 RAM 占用。若受代码体积限制,可在配置中把它定义为 0;影响取决于启用的曲线数量与大小,例如 P-256 的差异约为 1KB。仓库 ecp.h 第 286~300 行显示该宏默认值仍为 1(启用)。

2.6 MBEDTLS_SHA224_C 与 MBEDTLS_SHA256_C 分离

默认配置下两者现在都默认启用(此前仅 SHA256 默认启用)。自定义配置若启用 MBEDTLS_SHA256_C,必须额外添加 #define MBEDTLS_SHA224_C——当前库不支持只开 SHA256 不开 SHA224。仓库 mbedtls_config.h 第 2789~2822 行可见 MBEDTLS_SHA224_C 与 MBEDTLS_SHA256_C 均默认定义,且注释明确两者互相关联。

2.7 MBEDTLS_SHA512_NO_SHA384 替换为 MBEDTLS_SHA384_C

默认配置下 MBEDTLS_SHA384_C 现在默认启用(此前 MBEDTLS_SHA512_NO_SHA384 默认关闭)。迁移:

  • 配置中同时有 MBEDTLS_SHA512_C 与 MBEDTLS_SHA512_NO_SHA384:直接删掉后者;
  • 配置中有 MBEDTLS_SHA512_C 但无 MBEDTLS_SHA512_NO_SHA384,且需要 SHA-384:添加 #define MBEDTLS_SHA384_C。

仓库配置文件中第 2875~2905 行可确认 MBEDTLS_SHA384_C 与 MBEDTLS_SHA512_C 均默认定义。

2.8 GCM 多段(multipart)接口改造

GCM 模块现在支持任意分块输入。仅直接使用 GCM 多段接口的应用受影响;使用一次性 GCM,或经由 mbedtls_cipher_xxx / psa_aead_xxx 接口的应用无需改动。仓库 gcm.h 可验证新接口原型:

  • mbedtls_gcm_starts():现在只设置模式与 nonce(IV);关联数据(AAD)改由新函数 mbedtls_gcm_update_ad() 传入(第 234、259 行);
  • mbedtls_gcm_update():新增一个输出长度参数(第 314 行)。2.x 要求输入除最后一块外必须整 16 字节对齐,此限制已解除:块对齐时输出长度等于输入长度;最后一段输入长度非 16 的倍数时,alt 实现可能把最后一个不完整块推迟到 mbedtls_gcm_finish() 返回;
  • mbedtls_gcm_finish():新增一个输出缓冲区参数用于承载最后的不完整块(第 352 行),满足只能整块处理的 alt 实现需要。

对 alt 实现(MBEDTLS_GCM_ALT)的影响:starts 只管模式与 nonce;update_ad 接收 AAD 且可多次调用;update 接受任意长度输入并新增输出长度参数,alt 实现可在"立即返回部分输出"与"缓存最后的不完整块到下次 update/finish 再返回"两种模式间选择;finish 按需增加最后不完整块输出缓冲。

2.9 移除 MBEDTLS_ECP_NO_INTERNAL_RNG 选项

默认配置不受影响。该选项曾是代码体积与侧信道防护间的权衡,如今防护措施无条件开启且不增加代码体积,故移除。

2.10 SHA-256 / SHA-512 输出参数类型变化

mbedtls_sha256_finish()、mbedtls_sha256()、mbedtls_sha512_finish()、mbedtls_sha512() 的输出参数由数组类型改为指针类型。C 语义上无差异,但消除了在 48 字节缓冲区输出 SHA-384、在 28 字节缓冲区输出 SHA-224 时某些编译器产生的多余警告。绝大多数应用无感知;若你的代码持有指向这些函数的指针,需同步修改指针类型;SHA256/SHA512 模块的 alt 实现必须相应调整函数原型。

2.11 移除硬件失败的 deprecated 错误码

  • 各密码模块的 MBEDTLS_ERR_xxx_FEATURE_UNAVAILABLE 移除,统一改用 MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED;
  • MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION 移除,同上;
  • 各模块的 MBEDTLS_ERR_xxx_HW_ACCEL_FAILED 移除,统一改用 MBEDTLS_ERR_PLATFORM_HW_ACCEL_FAILED。

仓库 error.h 第 117、119 行可确认这两个统一错误码的定义。

2.12 移除非法输入数据的 deprecated 错误码

ARIA 与 Camellia 模块的 MBEDTLS_ERR_xxx_INVALID_KEY_LENGTH 移除,统一改用 MBEDTLS_ERR_xxx_BAD_INPUT_DATA。

2.13 RSA:移除模式参数

所有使用 RSA 加密/解密/签名/验签 API 的用户均受影响。RSA 模块不再支持"用公钥做私钥操作、用私钥做公钥操作",因此操作函数不再有 mode 参数:

  • 正常用法(公钥用于验签/加密,私钥用于签名/解密):直接删掉 MBEDTLS_RSA_PUBLIC / MBEDTLS_RSA_PRIVATE 实参;
  • 反向用法(从安全角度本就罕见):3.0 不再支持。

2.14 AES:移除 deprecated 函数

mbedtls_aes_encrypt() 与 mbedtls_aes_decrypt() 移除:

  • 普通使用:改调更上层的 mbedtls_aes_crypt_xxx() 系列(仓库 aes.h 中 mbedtls_aes_crypt_ecb/cbc/xts/cfb128/cfb8/ofb 等均在列);
  • alt 实现(MBEDTLS_AES_ENCRYPT_ALT / MBEDTLS_AES_DECRYPT_ALT):改用 mbedtls_internal_aes_encrypt() / mbedtls_internal_aes_decrypt()(aes.h 第 604 行确认)。

2.15 ECDSA:移除 deprecated 函数

mbedtls_ecdsa_write_signature_det() 与 mbedtls_ecdsa_sign_det() 移除,分别由 mbedtls_ecdsa_write_signature() 与 mbedtls_ecdsa_sign_det_ext()(ecdsa.h 第 213 行确认)取代。

2.16 *_ret() 加密函数批量还原命名

2.x 因"函数必须返回错误码"的要求引入了带 _ret 后缀的变体;3.0 将这些函数改回原始名字(现在都返回错误码)。完整对照表:

变更前(2.x) 变更后(3.x)
mbedtls_ctr_drbg_update_ret mbedtls_ctr_drbg_update
mbedtls_hmac_drbg_update_ret mbedtls_hmac_drbg_update
mbedtls_md5_starts_ret / update_ret / finish_ret / ret mbedtls_md5_starts / update / finish / md5
mbedtls_ripemd160_starts_ret / update_ret / finish_ret / ret mbedtls_ripemd160_starts / update / finish / ripemd160
mbedtls_sha1_starts_ret / update_ret / finish_ret / ret mbedtls_sha1_starts / update / finish / sha1
mbedtls_sha256_starts_ret / update_ret / finish_ret / ret mbedtls_sha256_starts / update / finish / sha256
mbedtls_sha512_starts_ret / update_ret / finish_ret / ret mbedtls_sha512_starts / update / finish / sha512

两条迁移路径:① 代码中继续保留 *_ret 名,但 include 头文件 compat_2.x.h(仓库中该文件确实存在:third_party/mbedtls/include/mbedtls/compat-2.x.h),其中定义了正确的重命名宏;② 按上表直接改名。

2.17 RSA 验签函数移除 RNG 参数

RSA 验签函数不再接受随机数生成器参数(原仅私钥操作需要)。所有使用 RSA 验签 API 的应用都受影响。

2.18 mbedtls_rsa_init() 移除 padding 参数

所有使用 RSA 加解密/签名/验签 API 的用户受影响。mbedtls_rsa_init() 不再负责选择 PKCS#1 v2.1 编码及其哈希,默认选中 PKCS#1 v1.5。若需 PKCS#1 v2.1,需在 mbedtls_rsa_init() 之后调用 mbedtls_rsa_set_padding()(仓库 rsa.h 第 146、182 行确认两者新原型)。

初始化时选择 padding:

/* 2.x */
mbedtls_rsa_init(ctx, padding, hash_id);

/* 3.x */
mbedtls_rsa_init(ctx);
mbedtls_rsa_set_padding(ctx, padding, hash_id);

仅用 PKCS#1 v1.5:

/* 2.x */
mbedtls_rsa_init(ctx, MBEDTLS_RSA_PKCS_V15, <ignored>);

/* 3.x */
mbedtls_rsa_init(ctx);

三、高层密码学(High-level crypto)变更

3.1 所有多段 AEAD 操作必须调用 mbedtls_cipher_finish()

仅影响用多段 API 做 AEAD 的 cipher 模块用户。此前文档未明确是否可在最后一次 mbedtls_cipher_update() 后直接调用 mbedtls_cipher_check_tag() / mbedtls_cipher_write_tag()。现在必须补上 mbedtls_cipher_finish(),并准备它最多产生 15 字节输出(当前实现恒为 0 字节,但 alt 底层实现或未来版本可能更多)。

3.2 移除 MD2、MD4、RC4、Blowfish、XTEA 算法

这些算法已小众或过时,多数存在弱点或已被攻破,建议改用文献中的现代安全替代方案。

3.3 cipher:移除 deprecated 函数

mbedtls_cipher_auth_encrypt() / mbedtls_cipher_auth_decrypt() 移除,由 mbedtls_cipher_auth_encrypt_ext() / mbedtls_cipher_auth_decrypt_ext() 取代,后者额外支持 NIST_KW 等密钥包装算法。

3.4 签名函数新增输出缓冲区大小参数

以下函数新增输出缓冲区大小参数:

  • mbedtls_ecdsa_write_signature()、mbedtls_ecdsa_write_signature_restartable()
  • mbedtls_pk_sign()、mbedtls_pk_sign_restartable()

缓冲区要求本身未变,但传入过小的缓冲区现在可靠返回错误而非溢出。

3.5 签名函数要求 hash 长度与期望值匹配

影响 PK API 与 RSA 低层 API 用户(PSA API 与 ECDSA 模块用户不受影响)。

  • RSA 模块中所有接受 hashlen 的函数:2.x 中除非 md_alg == MBEDTLS_MD_NONE(裸数据签名),否则忽略 hashlen;现在 hashlen 恒为从 hash 输入缓冲读取的大小,签名哈希时必须等于所用哈希算法的输出大小。涉及:mbedtls_rsa_pkcs1_sign/verify、mbedtls_rsa_rsassa_pkcs1_v15_sign/verify、mbedtls_rsa_rsassa_pss_sign/verify、mbedtls_rsa_rsassa_pss_sign_ext/verify_ext。
  • PK 模块签名函数不再接受 hash_len == 0,涉及:mbedtls_pk_sign/verify、mbedtls_pk_sign_restartable/verify_restartable、mbedtls_pk_verify_ext。

迁移路径:向这些函数传入正确值。

3.6 部分函数参数改为 const

PK 与 ASN.1 模块的若干函数参数增加了 const 限定符。通常无感,除非你用指针引用这些函数——此时需更新指针类型以匹配新签名。

3.7 所有接受 f_rng 的函数,RNG 参数变为必填

影响所有以 NULL 作为 f_rng 实参的调用,不再支持。涉及:X.509 CRT/CSR 写入函数;PK 与 RSA 的签名、解密函数;mbedtls_rsa_private();DHM 与 ECDH 中计算共享秘密的函数;ECP 的标量乘法函数。

现在必须向所有接受 f_rng 的函数传入正确播种、密码学安全的 RNG;若 RNG 函数不需要上下文,p_rng 传 NULL 仍可。alt 实现(MBEDTLS_<module>_ALT)可用内部 RNG 并忽略该参数,但必须允许用户传入。

3.8 部分函数新增 RNG 参数

mbedtls_ecp_check_pub_priv()、mbedtls_pk_check_pair()、mbedtls_pk_parse_key()、mbedtls_pk_parse_keyfile() 现在都需要传入正确播种的密码学安全 RNG——用于盲化(blinding),是对抗侧信道攻击的防护措施。

四、PSA 变更

4.1 移除 PSA 常量与类型的 deprecated 名字

PSA Crypto API 1.0 规范删除了一批测试版(beta)中出现的常量与类型名,请切换到 1.0 规范提供的新名字。

五、仅影响 alt 实现的变更

5.1 内部/alt 头文件移至私有位置

若你此前遵循"不在公共 include 目录引用内部头文件"的约定,则不受影响。若你提供 ECP 或 RSA 的 alt 实现:构建 alt 实现时需把本库的 library 目录加入 include path,并注意 ecp_internal.h 与 rsa_internal.h 分别改名为 ecp_internal_alt.h 与 rsa_alt_helpers.h。

5.2 CCM 接口变化:alt 实现需新增 5 个函数

CCM 模块新增多段操作支持,定义了 5 个新 API:mbedtls_ccm_starts()、mbedtls_ccm_set_lengths()、mbedtls_ccm_update_ad()、mbedtls_ccm_update()、mbedtls_ccm_finish()。MBEDTLS_CCM_ALT 的 alt 实现必须实现这 5 个新函数。

六、X.509 变更

6.1 certs 模块移出库

不影响生产使用(该模块内证书从未适合生产)。若测试依赖它,请把自有测试证书嵌入测试代码;certs.c 出库后不再有任何稳定性保证。

6.2 CSR 支持关键扩展:API 新增 critical 参数

调用 mbedtls_x509write_csr_set_extension() 的应用受影响。API 新增 critical 参数,用于把 CSR 中的扩展标记为关键;保持旧行为传 0 即可。

6.3 移除 MBEDTLS_X509_ALLOW_UNSUPPORTED_CRITICAL_EXTENSION 选项

默认配置不受影响。X.509 标准要求实现必须拒绝不认识的 critical 扩展,Mbed TLS 默认即如此;该选项虽允许继续解析这类证书,但缺少便捷的处理方式。迁移路径:改用 mbedtls_x509_crt_parse_der_with_ext_cb()——功能上等价于 mbedtls_x509_crt_parse_der() / mbedtls_x509_crt_parse_der_nocopy(),但会把每个不支持的证书扩展(以及含不支持证书策略的 "certificate policies" 扩展)通过回调交给调用方处理。仓库 x509_crt.h 第 425~490 行多处提及该回调函数的行为。

6.4 移除 MBEDTLS_X509_CHECK_*_KEY_USAGE 选项

影响曾通过配置关闭 keyUsage / extendedKeyUsage 校验的用户。两个选项(MBEDTLS_X509_CHECK_KEY_USAGE、MBEDTLS_X509_CHECK_EXTENDED_KEY_USAGE)移除,X.509 代码现在恒等于"总是启用"该校验,不再可能编译期关闭。该校验很重要,关闭可能引发安全问题,不推荐。若确需关闭,可通过传给 mbedtls_x509_crt_verify() 的验证回调实现。

6.5 移除 MBEDTLS_X509_ALLOW_EXTENSIONS_NON_V3 选项

默认配置不受影响(本就默认关闭);使用当前 V3 证书的用户也不受影响。扩展是 V3 才引入的,pre-V3 证书带扩展本就不合规,Mbed TLS 现在所有配置下都以解析错误拒绝(此前默认配置已如此)。若还在处理 pre-V3 证书,请切换到当前版本。

6.6 强化 X.509 默认算法选择

见下文"强化 X.509 与 TLS 的默认算法选择"。

6.7 移除 libpkcs11-helper 封装

默认配置不受影响(本就默认关闭)。若曾依赖它安全存储私钥,请考察 PSA crypto API 的密钥管理能力;未覆盖的用例可在邮件列表提出。

七、SSL/TLS 变更

7.1 移除 TLS 1.0、1.1 与 DTLS 1.0 支持

影响使用这些协议版本的用户。它们已被 RFC 8996 弃用,保留它们会带来错误配置与降级攻击风险,且更多代码意味着更大的攻击面。迁移路径:采用最新协议版本。

连锁移除:

  • CBC record splitting 随之移除(它是针对 TLS 1.0 特定弱点的补救措施),无迁移路径;
  • fallback SCSV(RFC 7507) 移除——当前只支持单一版本(D)TLS,未来 1.3 的版本协商机制不同,TLS 1.2 及以后不再需要;
  • 按版本分别配置 ciphersuite 的 API mbedtls_ssl_conf_ciphersuites_for_version() 移除,请用 mbedtls_ssl_conf_ciphersuites() 配置 (D)TLS 1.2 的 ciphersuite;未来 1.3 会新增独立 API。

7.2 移除 SSL 3.0 支持

默认配置不受影响(本就默认关闭)。仅影响显式启用 MBEDTLS_SSL_PROTO_SSL3 且依赖该版本与未升级对端通信的用户——请敦促对端升级。

7.3 移除 SSLv2 ClientHello 解析

默认配置不受影响。仅影响仍会收到 SSLv2 ClientHello 的 TLS 服务器(如今客户端几乎不会这样做)。

7.4 移除 truncated HMAC

影响调用 mbedtls_ssl_conf_truncated_hmac(..., MBEDTLS_SSL_TRUNC_HMAC_ENABLED) 的用户(无论标准版还是 MBEDTLS_SSL_TRUNCATED_HMAC_COMPAT 兼容版)。追求最小开销的迁移路径:改用 CCM-8 ciphersuite。

7.5 移除 TLS record 级压缩

默认配置不受影响。仅影响启用 MBEDTLS_ZLIB_SUPPORT 的用户。移除后带宽占用可能上升;没有通用解决方案,应用协议自带压缩更有利于规避 CRIME/BREACH 变体攻击。

7.6 移除基于 RC4 的 ciphersuite

默认配置与默认 ciphersuite 列表用户不受影响(RC4 本就未被协商)。请切换到现代推荐 ciphersuite(AES-GCM、AES-CCM 或 ChachaPoly 等),对端不支持则敦促其升级。

7.7 移除单 DES ciphersuite

同上,默认配置不受影响,请切换到现代推荐 ciphersuite。

7.8 移除 record 级硬件加速

默认配置不受影响。该特性已损坏多时,若仍在用请到邮件列表说明用例。

7.9 移除 MBEDTLS_SSL_DEFAULT_TICKET_LIFETIME 选项

默认配置不受影响。该选项早已无效,请改用 mbedtls_ssl_ticket_setup() 的 lifetime 参数。

7.10 合并 CID 与 TLS 1.3 的 padding 粒度选项

影响修改过默认 padding 粒度(启用过至少一个相关选项)的用户。MBEDTLS_SSL_CID_PADDING_GRANULARITY 与 MBEDTLS_SSL_TLS1_3_PADDING_GRANULARITY 因使用完全相同的 padding 机制而合并为单一选项 MBEDTLS_SSL_CID_TLS1_3_PADDING_GRANULARITY,同时适用于 DTLS-CID 与 TLS 1.3,简化维护。

7.11 TLS 曲线默认偏好:更快优先于更大

TLS 默认曲线偏好现在优先考虑资源占用(性能与内存)而非曲线大小。具体顺序未规定且可能变化,但通常 256 位曲线优先于更大曲线。若需自定义顺序,配置 TLS 连接时调用 mbedtls_ssl_conf_curves()。

7.12 SSL 密钥导出接口变化

影响使用以下旧 API 的用户:

mbedtls_ssl_conf_export_keys_cb()
mbedtls_ssl_conf_export_keys_ext_cb()

二者移除,由新 API mbedtls_ssl_set_export_keys_cb()(仓库 ssl.h 第 2403 行确认)取代。差异:

  • 不再绑定 SSL 配置,而绑定 SSL context——便于识别导出密钥所属的连接;
  • 不再导出裸密钥与 IV;
  • 新增 secret type 参数标识导出的是哪种密钥:TLS 1.2 目前只导出 master secret,未来 TLS 1.3 将增加其他类型;
  • 回调改为 void 返回类型,不再返回错误码;密钥导出回调中的失败由应用负责处理(例如关闭 TLS 连接)。

不依赖裸密钥与 IV 的用户,适配新回调类型即可(可参考示例程序 programs/ssl/ssl_client2 与 programs/ssl/ssl_server2 中 NSSKeylog、EAP-TLS、DTLS-SRTP 的回调写法);需要裸流量密钥的用户,可基于 master secret 与握手转录哈希手工推导,并建议向 Mbed TLS 团队反馈用例。

7.13 移除 MaximumFragmentLength(MFL)查询 API

影响使用 mbedtls_ssl_get_{input,output}_max_frag_len() 推断记录明文大小上界的用户。请改用 mbedtls_ssl_get_max_{in,out}_record_payload()——同样提供上界,且比仅考虑 MFL 配置纳入更多因素。

7.14 PSK 配置语义放宽

影响在同一 SSL 配置上多次调用 mbedtls_ssl_conf_psk() / mbedtls_ssl_conf_psk_opaque() 的用户。2.x 中后调覆盖先调、最后一次生效;3.0 起重复调用返回错误,首个 PSK 保持生效。迁移:删除所有多余调用,只保留最后一次对 mbedtls_ssl_conf_psk() 或 mbedtls_ssl_conf_psk_opaque() 的调用。

7.15 移除启用弱 ciphersuite 的配置

默认配置不受影响(本就默认关闭)。弱 ciphersuite 用户请切换到 AES-GCM、AES-CCM、ChachaPoly 等现代推荐项,对端不支持则敦促升级。若用的是无加密 ciphersuite,现在只需启用 MBEDTLS_CIPHER_NULL_CIPHER。

7.16 移除 MBEDTLS_SSL_MAX_CONTENT_LEN 选项

影响用该选项设置最大明文分片长度、以缩小 TLS I/O 缓冲区省内存的用户。由更细粒度的 MBEDTLS_SSL_IN_CONTENT_LEN 与 MBEDTLS_SSL_OUT_CONTENT_LEN 取代,分别设置最大入站/出站明文分片长度。仓库 ssl.h 第 353~358 行可见两者默认均为 16384。

7.17 移除 mbedtls_ssl_get_session_pointer()

影响两类用户:

  1. 直接通过结构体字段访问手动检视当前会话——3.0 中 mbedtls_ssl_session 结构同样不再属于公共 API(见"结构体字段私有化"一节),无迁移路径;
  2. 会话恢复用户在保存/导出前先 mbedtls_ssl_get_session_pointer() 再 mbedtls_ssl_session_copy() / mbedtls_ssl_session_save()——请改用 mbedtls_ssl_get_session()(参考示例程序 programs/ssl/ssl_client2.c)。

7.18 移除 MBEDTLS_SSL_DTLS_BADMAC_LIMIT 选项

默认配置不受影响(本就默认开启)。该选项原是功能与代码体积的权衡;现已移除,但功能始终启用。

7.19 SSL 模块移除 deprecated 函数

  • mbedtls_ssl_conf_dh_param() 移除,改用 mbedtls_ssl_conf_dh_param_bin() 或 mbedtls_ssl_conf_dh_param_ctx();
  • mbedtls_ssl_get_max_frag_len() 移除,改用 mbedtls_ssl_get_max_out_record_payload() 与 mbedtls_ssl_get_max_in_record_payload()。

7.20 移除 MBEDTLS_SSL_RECORD_CHECKING 选项并默认启用其功能

默认配置不受影响(本就默认开启)。该选项仅为控制 mbedtls_ssl_check_record() 单函数的编译,以省代码空间;现在同样效果可通过链接时垃圾回收(link-time garbage collection)实现。改动过默认设置的用户需在配置/构建系统中撤掉该改动。

7.21 会话缓存 API 变更

影响用 mbedtls_ssl_conf_session_cache() 配置自定义会话缓存(区别于库内置的 library/ssl_cache.c 实现)的用户。需把自定义缓存实现改为键值存储接口:键为 session ID,值为 mbedtls_ssl_session 实例:

typedef int mbedtls_ssl_cache_get_t( void *data,
                                     unsigned char const *session_id,
                                     size_t session_id_len,
                                     mbedtls_ssl_session *session );
typedef int mbedtls_ssl_cache_set_t( void *data,
                                     unsigned char const *session_id,
                                     size_t session_id_len,
                                     const mbedtls_ssl_session *session );

由于 3.0 起 mbedtls_ssl_session 结构不再公共,可移植的会话缓存实现不得访问其字段。实在无法迁移的用例请到邮件列表说明。

7.22 SSL 错误码空间调整

影响手动检查下列错误码的用户:

  • MBEDTLS_ERR_SSL_CERTIFICATE_REQUIRED
  • MBEDTLS_ERR_SSL_INVALID_VERIFY_HASH
  • MBEDTLS_ERR_SSL_CERTIFICATE_TOO_LARGE
  • MBEDTLS_ERR_SSL_NO_CIPHER_CHOSEN
  • MBEDTLS_ERR_SSL_NO_USABLE_CIPHERSUITE
  • MBEDTLS_ERR_SSL_BAD_HS_XXX

迁移路径:

  • MBEDTLS_ERR_SSL_CERTIFICATE_TOO_LARGE 移除:自有证书过大放不进输出缓冲区时改返回 MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL。请改检查后者,并可将证书大小与输出缓冲区配置大小对比判断错误成因;
  • MBEDTLS_ERR_SSL_NO_CIPHER_CHOSEN 与 MBEDTLS_ERR_SSL_NO_USABLE_CIPHERSUITE 合并为 MBEDTLS_ERR_SSL_HANDSHAKE_FAILURE;
  • 所有 MBEDTLS_ERR_SSL_BAD_HS_XXX 由信息更丰富的新通用错误码取代:MBEDTLS_ERR_SSL_DECODE_ERROR、MBEDTLS_ERR_SSL_ILLEGAL_PARAMETER、MBEDTLS_ERR_SSL_HANDSHAKE_FAILURE、MBEDTLS_ERR_SSL_BAD_PROTOCOL_VERSION、MBEDTLS_ERR_SSL_BAD_CERTIFICATE、MBEDTLS_ERR_SSL_UNRECOGNIZED_NAME、MBEDTLS_ERR_SSL_UNSUPPORTED_EXTENSION、MBEDTLS_ERR_SSL_NO_APPLICATION_PROTOCOL,以及既有通用错误码 MBEDTLS_ERR_SSL_UNEXPECTED_MESSAGE、MBEDTLS_ERR_SSL_INTERNAL_ERROR。

7.23 mbedtls_ssl_{get,set}_session() 语义变化

影响在同一已建立 TLS 1.2 连接的 SSL context 上多次调用 mbedtls_ssl_get_session() / mbedtls_ssl_set_session() 的用户。现在第二次调用会以 MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE 失败。

迁移路径:

  • 多次导出同一 TLS 1.2 连接(get_session)会得到多份相同会话副本,不推荐。若这些副本之后经 set_session 载入新 context:只导出一次,再把同一会话载入不同 context(set_session 会复制载入的会话,功能等价);若这些副本之后经 mbedtls_ssl_session_save() 序列化:只导出并序列化一次,然后复制原始数据;
  • 2.x 中多次调用 set_session 本就无意义(后调覆盖前调),应用只需发出最后一次调用即可获得等价行为。

7.24 MBEDTLS_SSL_SRV_RESPECT_CLIENT_PREFERENCE 改为运行时选项

影响在 mbedtls_config.h 中启用该选项的用户。选项已移除,由新 SSL API mbedtls_ssl_conf_preference_order()(ssl.h 第 4071 行确认)取代:

mbedtls_ssl_conf_preference_order(ssl_config, MBEDTLS_SSL_SRV_CIPHERSUITE_ORDER_CLIENT);

与旧选项效果相同(服务器改用客户端的 ciphersuite 顺序);默认状态仍是使用服务器侧顺序。

7.25 强化 X.509 与 TLS 的默认算法选择

默认 X.509 验证 profile(mbedtls_x509_crt_profile_default)与 TLS 的默认曲线/哈希选择已变更并相互对齐(X.509 profile 仅列出支持签名验证的曲线):

  • 安全强度低于 128 位(曲线/哈希弱于 255 位)的算法不再被默认接受;
  • 移除的哈希:SHA-1(此前仅密钥交换接受、证书签名不接受)、SHA-224;
  • 移除的曲线:secp192r1、secp224r1、secp192k1、secp224k1;
  • 编译期选项 MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_CERTIFICATES 与 MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_KEY_EXCHANGE 不再可用;
  • secp256k1 也从默认 X.509/TLS profile 移除(RFC 8422 在 TLS 中弃用该曲线,极少使用,撰写本文时未发现其存在弱点)。

仍需要接受被默认 profile 排除的算法时:

  • X.509:改用 mbedtls_x509_crt_verify_with_profile() 并传入允许所需曲线/哈希的 profile。例如允许 SHA-224:
mbedtls_x509_crt_profile my_profile = mbedtls_x509_crt_profile_default;
my_profile.allowed_mds |= MBEDTLS_X509_ID_FLAG( MBEDTLS_MD_SHA224 );
  • TLS:用 mbedtls_ssl_conf_sig_hashes() 与 mbedtls_ssl_conf_curves() 传入期望的哈希与曲线列表。

7.26 移除 3DES ciphersuite

默认配置用户不受影响(3DES ciphersuite 本就默认禁用)。3DES 存在弱点且越来越多的标准组织建议在 TLS 中停用,迁移路径是选择文献推荐的替代方案,如 AES。

八、快速自查清单

完成迁移前,按此清单逐项核对你的代码与配置:

  1. 头文件是否已改为 #include <mbedtls/build_info.h>?是否仍残留 config.h / MBEDTLS_CONFIG_H / 直接 include check_config.h、config_psa.h 的写法?
  2. 自定义配置是否设置了 MBEDTLS_CONFIG_VERSION(3.0.0 唯一支持 0x03000000)?是否补齐了 MBEDTLS_SHA224_C、MBEDTLS_SHA384_C?
  3. 是否直接访问了结构体字段(mbedtls_ssl_session、RSA、ECP、X.509 等)?是否全部改走 get/set 访问器?
  4. 是否仍调用 *_ret 函数、mbedtls_mpi_is_prime()、mbedtls_aes_encrypt/decrypt()、mbedtls_md_init_ctx()、mbedtls_ecdsa_*_det() 等已移除函数?是否已 include compat-2.x.h 或按表改名?
  5. RSA 调用是否已去掉 mode 参数与 RNG 参数?mbedtls_rsa_init() 后是否需要补 mbedtls_rsa_set_padding()?
  6. 签名相关调用是否传入了正确的 hash_len / 输出缓冲区大小?
  7. 多段 AEAD 是否补上了 mbedtls_cipher_finish()?GCM 多段流程是否已适配 update_ad / 输出长度参数 / finish 末块缓冲?
  8. 是否仍在按旧错误码(MBEDTLS_ERR_SSL_BAD_HS_XXX、MBEDTLS_ERR_xxx_FEATURE_UNAVAILABLE 等)分支?是否已切换到统一/新错误码?
  9. TLS 侧是否仍依赖 TLS 1.0/1.1/DTLS 1.0、SSL 3.0、RC4/单 DES/3DES/truncated HMAC 等已移除能力?
  10. 是否还在使用已移除的配置选项(MBEDTLS_CHECK_PARAMS、MBEDTLS_SSL_MAX_CONTENT_LEN、MBEDTLS_X509_CHECK_*_KEY_USAGE、MBEDTLS_SSL_DTLS_BADMAC_LIMIT 等)?

九、结语

Mbed TLS 3.0 的破坏性变更覆盖了配置体系、结构体可见性、低层/高层密码 API、PSA、X.509 与 SSL/TLS 六个层面,其核心目的只有一个:移除不安全或过时的能力、收紧默认安全策略、统一并简化 API 面。绝大多数变更都有明确的替代路径——本文所列的对照表、代码示例与自查清单,配合仓库内 mbedtls_config.h、ssl.h、rsa.h、gcm.h、compat-2.x.h 等头文件可直接对照验证。按"先评估受影响面、再逐项替换、最后回归测试"的顺序执行,即可平稳完成从 2.x 到 3.x 的迁移。

登录后查看全文
ten-framework