【C++三方组件】mbedTLS：面向嵌入式的轻量 TLS

【摘要】：mbedTLS（现由 ARM 阵营 Mbed-TLS 维护）是「小而全」的 TLS 与密码库：模块化可裁剪、代码量约为 OpenSSL 的十分之一、3 KB 起步的 RAM 占用。本篇实测 PSA Crypto 接口（随机数、SHA-256 与 OpenSSL 逐字节一致、AES-GCM 密钥句柄式用法）与 TLS 回环，并记录 4.x 的 API 巨变：entropy/ctr_drbg 整层消失。什么时候它是 OpenSSL 的正确替代------嵌入式、静态链接体积、裁剪自由度。

【关键词】：mbedTLS、PSA Crypto、嵌入式 TLS、TLS 回环、裁剪

【版本基准】：mbedTLS 4.2.0（Apache-2.0；3.x 起含 tf-psa-crypto 子模块）｜示例 C++17｜实测环境：MSVC v145／VS2026，Windows；摘要为确定性输出，其余随机器而变

1. What：把 TLS 装进 3 KB RAM 的库

mbedTLS（前身 PolarSSL）是面向嵌入式场景重新设计 的 TLS 栈：模块化（每个算法、每个协议特性都是可裁剪的配置项）、低内存（握手 RAM 占用从几十 KB 量级起步，最小配置可到几十 KB 以下）、C99 纯净（无外部依赖，连 libc 都可裁）。它活在路由器固件、IoT 设备、引导加载器里，也是 TF-M（ARM 可信固件）的密码层；许可 Apache-2.0 无商用负担。

4.x 的结构：TLS 协议栈（library/）与密码学层 tf-psa-crypto （独立子模块）分层，密码 API 全面转向 PSA Crypto------ARM 主导的密码学接口标准（Platform Security Architecture），也用于 TF-M 和 PSA Certified 认证体系。同一份 PSA API 正在成为嵌入式的「密码学通用语」。

2. Why：OpenSSL 的体积与裁剪自由度是它的反面

OpenSSL（第 40 篇）为桌面与服务器设计：功能全、依赖多、编译产物大（本系列示例构建出的静态库以百 MB 级源码计）。嵌入式的三个硬约束它都顶不住：Flash/RAM 预算 （整库塞不进去）、裁剪粒度 （「只要 TLS 1.3 客户端 + 两三个套件」做不到声明式表达）、依赖面（perl/perl5 模块才能构建 vs mbedTLS 一套 CMake 直接编）。

mbedTLS 的答案：mbedtls_config.h 一个头文件勾选全部能力（算法、协议版本、X.509 特性、甚至 printf），不勾的不进二进制。代价也直白：算法与协议跟随裁剪（没有 OpenSSL 的「全都有」）、性能优化（汇编路径）少于 OpenSSL、生态位偏嵌入式------桌面/服务端没有理由换它。

3. How：接入与 PSA Crypto

接入两条路：vcpkg（vcpkg install mbedtls）；或源码（注意 4.x 需带子模块：git clone --recursive，本机用这条拿到 tf-psa-crypto；GitHub 的自动打包 tarball 不含子模块，要下 release 资产包）。CMake 源码子目录产出 MbedTLS::mbedtls / MbedTLS::mbedx509 / MbedTLS::mbedcrypto 三个目标。

4.x 最重要的事实：entropy/ctr_drbg 整层从 API 面消失。 3.x 时代每个示例都要「先组装熵源 → 喂 CTR_DRBG → 把回调挂进 ssl_conf」四步；4.x 里随机数是 PSA 的内部事务，TLS 配置不再需要 mbedtls_ssl_conf_rng。新代码从 psa_crypto_init() 开始：

cpp 复制代码

psa_crypto_init();
psa_generate_random(rnd, 16);          // 随机数
psa_hash_compute(PSA_ALG_SHA_256,      // 一步式摘要
                 msg, len, md, 32, &mdLen);

实测：SHA-256("hello, openssl") 的摘要与第 40 篇 OpenSSL 的输出逐字节一致------密码学库的互操作不是「大致相同」，是 bit 级相同。

4. How：PSA 的 AES-GCM------密钥句柄式

PSA 风格与 OpenSSL EVP 的最大差别：密钥不直接出现在加解密调用里，而是先导入成句柄（key id），操作引用句柄------这是为密钥不落内存的安全模型设计的（真硬件里句柄可指向隔离区）：

cpp 复制代码

psa_key_attributes_t attr = psa_key_attributes_init();
psa_set_key_type(&attr, PSA_KEY_TYPE_AES);
psa_set_key_bits(&attr, 256);
psa_set_key_usage_flags(&attr, PSA_KEY_USAGE_ENCRYPT
                              | PSA_KEY_USAGE_DECRYPT);
psa_set_key_algorithm(&attr, PSA_ALG_GCM);
mbedtls_svc_key_id_t kid;
psa_import_key(&attr, key, 32, &kid);

psa_aead_encrypt(kid, PSA_ALG_GCM, nonce, 12,
                 aad, aadLen, pt, ptLen,
                 out, sizeof out, &outLen);
// 输出 = 密文 + 16 字节标签（追加在尾部）

实测（密钥/IV/明文与第 40 篇 OpenSSL 示例完全相同）：加密输出 40 B（24 B 明文 + 16 B 标签） ；解密 roundtrip 还原明文；篡改一字节后 PSA_ERROR_INVALID_SIGNATURE（-149） ------与第 40 篇 EVP 路线行为一一对应，错误形态不同（状态码 vs 返回值）。更妙的是：密文与标签和 OpenSSL 的输出逐字节相同 （2066e7cb...fe30530e...）------同参数的 GCM 是确定的，两家实现殊途同归，这就是密码学「标准」的含义。

5. How：TLS 回环与互通

TLS 的经典三件：ssl_config（服务端/客户端 + 校验策略）、证书装载（x509_crt_parse_file + pk_parse_keyfile------4.x 精简为 3 参 ，rng 参数没了）、ssl_context 逐连接。客户端与 OpenSSL 篇同一个开关的对照：mbedtls_ssl_conf_authmode(&conf, MBEDTLS_SSL_VERIFY_REQUIRED) + conf_ca_chain。

实测（进程内回环，与 openssl_demo 共用同一张自签证书）：

text 复制代码

== 3. TLS 回环（VERIFY_REQUIRED + 自签 CA）==
服务端 listening on 127.0.0.1:18041
协商结果：TLSv1.3 / TLS1-3-CHACHA20-POLY1305-SHA256
对端证书：CN=localhost
verify flags = 0x0（0 即通过）
TLS 回显：ping

两家互通（线上的字节就是协议标准，本机实测）：

text 复制代码

# mbedTLS 客户端 -> OpenSSL 服务端（openssl_demo serve）
TLSv1.3 / TLS1-3-CHACHA20-POLY1305-SHA256，verify flags = 0x0
TLS 回显：ping
# OpenSSL s_client -> mbedTLS 服务端（mbedtls_demo serve）
depth=0 CN=localhost
verify return:1
ping from s_client（回显成功）

互通里还有个耐人寻味的细节：回环里 mbedTLS 协商出的是 ChaCha20-Poly1305 套件，而 OpenSSL 回环选了 AES-256-GCM------套件偏好不同，互相都能解；这正是「TLS 库只是实现，协议才是契约」的现场证明。README 记录了互通的完整命令。

6. 边界与选型

选 mbedTLS 的三个信号：体积/内存预算紧 （固件、MCU、引导链）、要声明式裁剪 （配置头一刀切）、目标体系在 PSA 生态 （TF-M、PSA Certified）。反过来：桌面/服务端应用、需要 OpenSSL 的算法广度与性能汇编路径、或生态工具链（s_client 之外的 OpenSSL 兼容层）------留在 OpenSSL。两者之间还有 C++ 血统的 Botan 可作第三选项。

版本注意：4.x 是 API 大改版（本文实测的接口面与 3.x 教程差异极大：entropy 层消失、pk 解析精简）；存量 3.x 代码看官方迁移指南再动。

〔关联〕第 40 篇 OpenSSL（对照组与互通实测）、第 26 篇（HTTPS 客户端的 TLS 底座）。

7. 参考资料

mbedTLS GitHub（v4.2.0 tag）与 PSA Crypto API 规范；
PSA Certified：ARM 主导的安全认证体系（PSA Crypto 的出处）；
完整示例：mbedtls_demo.cpp（与 openssl_demo 共用证书互通），构建见 README。

参考：本篇实测（PSA 摘要与 GCM 行为、TLS 协商结果、两家互通）均出自配套示例在本机的运行输出；4.x 接口事实以 v4.2.0 头文件为准。