Mbed TLS 3.0 迁移指南:从 2.x 升级的破坏性变更清单与实战迁移路径
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>,不要再 includembedtls/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 字段是只读的(修改会破坏结构体一致性)。
直接访问私有字段会编译失败。迁移路径依次为:
- 优先使用访问器函数,命名约定通常是
mbedtls_<MODULE>_{get,set}_<FIELD>或mbedtls_<MODULE>_<STRUCTURE>_{get,set}_<FIELD>;改变数据格式的访问器可能用其他动词,如read/write(用于从文本/字节串导入导出数据); - 若无访问器,向 Mbed TLS 提 enhancement request 描述你的用例(官方已知 3.0 缺失部分访问器,预期在 3.1 等小版本补充);
- 万不得已时可用
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()
影响两类用户:
- 直接通过结构体字段访问手动检视当前会话——3.0 中
mbedtls_ssl_session结构同样不再属于公共 API(见"结构体字段私有化"一节),无迁移路径; - 会话恢复用户在保存/导出前先
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_REQUIREDMBEDTLS_ERR_SSL_INVALID_VERIFY_HASHMBEDTLS_ERR_SSL_CERTIFICATE_TOO_LARGEMBEDTLS_ERR_SSL_NO_CIPHER_CHOSENMBEDTLS_ERR_SSL_NO_USABLE_CIPHERSUITEMBEDTLS_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。
八、快速自查清单
完成迁移前,按此清单逐项核对你的代码与配置:
- 头文件是否已改为
#include <mbedtls/build_info.h>?是否仍残留config.h/MBEDTLS_CONFIG_H/ 直接 includecheck_config.h、config_psa.h的写法? - 自定义配置是否设置了
MBEDTLS_CONFIG_VERSION(3.0.0 唯一支持0x03000000)?是否补齐了MBEDTLS_SHA224_C、MBEDTLS_SHA384_C? - 是否直接访问了结构体字段(
mbedtls_ssl_session、RSA、ECP、X.509 等)?是否全部改走 get/set 访问器? - 是否仍调用
*_ret函数、mbedtls_mpi_is_prime()、mbedtls_aes_encrypt/decrypt()、mbedtls_md_init_ctx()、mbedtls_ecdsa_*_det()等已移除函数?是否已 includecompat-2.x.h或按表改名? - RSA 调用是否已去掉 mode 参数与 RNG 参数?
mbedtls_rsa_init()后是否需要补mbedtls_rsa_set_padding()? - 签名相关调用是否传入了正确的
hash_len/ 输出缓冲区大小? - 多段 AEAD 是否补上了
mbedtls_cipher_finish()?GCM 多段流程是否已适配update_ad/ 输出长度参数 /finish末块缓冲? - 是否仍在按旧错误码(
MBEDTLS_ERR_SSL_BAD_HS_XXX、MBEDTLS_ERR_xxx_FEATURE_UNAVAILABLE等)分支?是否已切换到统一/新错误码? - TLS 侧是否仍依赖 TLS 1.0/1.1/DTLS 1.0、SSL 3.0、RC4/单 DES/3DES/truncated HMAC 等已移除能力?
- 是否还在使用已移除的配置选项(
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 的迁移。