mbedtls TLS 1.2 与 1.3 共存实战双版本 TLS 支持配置完全指南【免费下载链接】mbedtlsAn open source, portable, easy to use, readable and flexible TLS library, and reference implementation of the PSA Cryptography API. Releases are on a varying cadence, typically around 3 - 6 months between releases.项目地址: https://gitcode.com/GitHub_Trending/mb/mbedtls这篇文章从老设备卡在 TLS 1.2、新设备只认 TLS 1.3的真实矛盾切入讲清 mbedtls 多版本 TLS 支持的完整链路版本开关在哪里、版本协商怎么走、代码里如何同时启用 TLS 1.2 与 1.3。读完你可以直接完成兼容性配置并在协商结果不符合预期时按清单定位问题。场景为什么不能一刀切选 1.3你的服务端想用上 TLS 1.3 更快的握手但存量客户端还停在 TLS 1.2。只开 1.3老设备直接掉线只开 1.2新能力浪费。mbedtls 的解法是两句话编译期决定支持什么运行期协商实际用什么。两个协议各有独立开关且默认都开着握手时客户端上报自己接受的版本区间服务端在其中挑最高的之后双方各走各的协议状态机。所以结论很直接——双版本支持 两个配置宏 两个运行期 API不需要自己写任何协商逻辑。版本开关在哪mbedtls_config.h 里的两个宏两个协议开关都在 include/mbedtls/mbedtls_config.h宏作用依赖项默认状态MBEDTLS_SSL_PROTO_TLS1_2启用 TLS 1.2含 DTLS 1.2 的前提需PSA_WANT_ALG_SHA_256或PSA_WANT_ALG_SHA_384已启用MBEDTLS_SSL_PROTO_TLS1_3启用 TLS 1.3需MBEDTLS_SSL_KEEP_PEER_CERTIFICATE与MBEDTLS_PSA_CRYPTO_C已启用几个容易忽略的点MBEDTLS_SSL_PROTO_DTLS不是独立的 DTLS 开关它和 TLS 1.2 宏组合后才启用 DTLS 1.2。TLS 1.3 的专属扩展是单独开关比如MBEDTLS_SSL_RECORD_SIZE_LIMITRFC 8449默认关闭。如果目标是裁剪体积而不是加功能可以参考 configs/ 目录里现成的裁剪组合按需删宏即可。握手差异mbedtls 如何分流两套协议版本协商用的是协议原生机制ClientHello 携带版本区间ServerHello 返回选定版本区间无交集则握手直接失败。一旦版本敲定mbedtls 把流程分给完全独立的实现。派发逻辑在 library/ssl_tls.c命中 TLS 1.3 时进入mbedtls_ssl_tls13_handshake_client_step/mbedtls_ssl_tls13_handshake_server_step1.2 和 1.3 的客户端、服务端逻辑分别放在ssl_tls12_client.c、ssl_tls12_server.c、ssl_tls13_client.c、ssl_tls13_server.c四个文件里。对调用方来说这只是内部路由接口不变。维度TLS 1.2TLS 1.3完整握手指轮2 轮1 轮套件形态逐条命名加密与校验分开收敛为 AES-GCM 与 ChaCha20-Poly1305 三种固定套件恢复与早数据Session 复用PSK 恢复 0-RTT 早期数据独立配置项控制版本标识minor version 3minor version 4TLS 1.3 在 mbedtls 里的完整能力边界见 docs/architecture/tls13-support.md比这里更细。️ 落地代码里同时启用 TLS 1.2 与 1.3分三步。第一步是编译期确认打开mbedtls_config.h检查两个宏都在#define MBEDTLS_SSL_PROTO_TLS1_2 #define MBEDTLS_SSL_PROTO_TLS1_3注释掉其中任意一个该版本就从二进制里消失不存在运行时发现没装的情况。第二步是运行期圈定版本范围在配置mbedtls_ssl_config时调用/* 下限TLS 1.2 */ mbedtls_ssl_conf_min_version(conf, MBEDTLS_SSL_MAJOR_VERSION_3, MBEDTLS_SSL_MINOR_VERSION_3); /* 上限TLS 1.3 */ mbedtls_ssl_conf_max_version(conf, MBEDTLS_SSL_MAJOR_VERSION_3, MBEDTLS_SSL_MINOR_VERSION_4);这段代码的意思是本端只接受 1.2 到 1.3 之间的版本。如果只想要 1.3把下限的 minor version 改成 4 即可。第三步是加密套件。套件定义集中在 include/mbedtls/ssl_ciphersuites.h1.2 与 1.3 的套件各自独立参与协商。默认预设已同时覆盖两个版本但如果你按自己的安全策略裁剪套件列表务必两边都留条目否则某一侧会因为版本匹配但无共同套件而失败。 协商结果不符合预期时的排查步骤核对编译期开关。确认目标宏真的在生效的mbedtls_config.h里。注意构建系统可能引用了你没在看的那份配置。检查 TLS 1.3 的依赖项。手动裁剪配置后MBEDTLS_SSL_KEEP_PEER_CERTIFICATE或MBEDTLS_PSA_CRYPTO_C缺一个1.3 能力就名存实亡且不一定有显式报错。区分编译期与运行期范围。最终生效的区间是编译期支持 ∩ 运行期 min/max ∩ 对端区间。常见误解是只改了 API 却忘了宏也被裁掉或反之。用自带程序复现。programs/ssl/ 下的ssl_client1、ssl_server2适合做最小复现起一对端点确认协商出的版本与套件连接失败时重点看两端的版本区间和套件列表是否有交集。别漏掉 DTLS。如果你的场景是 QUIC 之外的裸 UDP记住 DTLS 1.2 还要MBEDTLS_SSL_PROTO_DTLS这个额外宏且它以 TLS 1.2 宏为前提。下一步复制一份mbedtls_config.h作为自己的基线配置按业务把不用的版本、算法和扩展关掉保留可审计的裁剪记录。用programs/ssl/的客户端/服务端程序各跑一遍分别验证协商到 1.3 和回落到 1.2 的两条路径都符合预期。遇到无法定位的问题先翻 docs/architecture/tls13-support.md 了解 TLS 1.3 的实现范围与限制再向仓库提交 issue 并附上双方的版本区间与套件列表。【免费下载链接】mbedtlsAn open source, portable, easy to use, readable and flexible TLS library, and reference implementation of the PSA Cryptography API. Releases are on a varying cadence, typically around 3 - 6 months between releases.项目地址: https://gitcode.com/GitHub_Trending/mb/mbedtls创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考