项目标题已经点得很具体STM32 上加 mbedTLS而且是在 Keil4 这种“上年纪”的 IDE 里加。这事儿听着像个体力活实际上真正费时间的不是敲代码而是版本选错、配置写崩、编译报一堆看不懂的错、跑起来一个-1甩你脸上。我在几个小容量 MCU 工程里反复折腾过这套组合踩坑踩得比较全下面把这些东西一次讲透——从为什么这么选、源码怎么裁、配置文件每个宏在算什么账到编译报错和握手失败的排查路径都按能直接抄作业的方式写。1. 先把需求捋清楚为什么是 mbedTLS为什么卡在 Keil41.1 老工程要联网绕不开的三件事设备要往服务端传数据只要走公网基本就绕不开三件事身份要能验证、数据要能加密、完整性要能校验。裸 TCP 传明文中间任何一跳都能看、能改、能重放产品一旦出门就是隐患。所以哪怕是个 64KB Flash 的小板子只要联网就得考虑 TLS。但单片机做 TLS 和 PC 上做 TLS 完全是两个难度。PC 上一个 OpenSSL 链接过去就完事单片机这里要面对三个硬约束Flash 装不下、RAM 装不下、没有操作系统帮忙。一个完整的 TLS 栈在桌面端动辄几 MB塞进 STM32 根本不可能必须找那种“能拆开、只拿需要的零件”的库。mbedTLS 就是靠这个吃饭的——它的设计思路是模块化加编译期裁剪不要的功能在config.h里一关连代码都不参与编译最后体积能压到几十 KB 级别。另一个现实问题是 Keil4。很多老项目、教学工程、还有一堆历史遗留的.uvproj就是用 MDK4 建的换 IDE 意味着整个工程结构、启动文件、链接脚本都要重弄成本比想象中高。所以现实做法往往是不动工程只往里加库。这就要接受 Keil4 自带 ARMCC 5 编译器的一些限制比如对 C99 的支持是“勾选式”的、部分标准头文件缺失、内联汇编写法和 GCC 不一样。这些限制会在后面每一步都跳出来提醒你。1.2 mbedTLS 的模块化结构为什么适合单片机我把 mbedTLS 的结构理解成四层从下往上层次主要文件作用能否裁剪基础算法层aes.csha256.csha1.cmd.cgcm.c对称加密、哈希、AEAD按需能去掉一半公钥层bignum.crsa.cecp.cecdsa.cecdh.c大数运算、签名验签、密钥交换ECC 和 RSA 可二选一证书层x509_crt.cpk.cpkparse.casn1parse.c解析证书、提取公钥只在需要验证服务端时用协议层ssl_tls.cssl_cli.cssl_ciphersuites.c握手状态机、记录层必须但可以只留客户端这个分层的好处是裁剪边界非常清晰。比如你只做本地数据加密存储不上网那ssl_*和x509_*全部不要只留aes.csha256.c代码量能压到 10KB 以内。反过来要连服务器就必须把协议层和证书层带上那体积自然就上去了。有一点必须提前说清楚mbedTLS 的“模块化”不等于“无依赖”。ssl_tls.c会依赖ctr_drbg.c做随机数依赖entropy.c收集熵依赖platform.c做内存和打印的抽象还依赖你自己实现的收发回调。所以哪怕配置文件只开了 TLS编译时也会连带着拉进来一堆基础文件这是正常的别慌。1.3 Keil4 的编译器特性直接决定了版本怎么选Keil4 的 ARMCC 5 有三个特点会直接影响 mbedTLS 的选型第一默认按 C90 编译。虽然可以勾 C99但 C90 模式下//注释、变量声明位置、long long这些都会报错。mbedTLS 从 2.x 开始大量用了 C99 特性所以 C99 必须开没有商量余地。第二内联汇编的支持范围窄。mbedTLS 的bn_mul.h里有一堆针对 GCC 和 x86 的内联汇编优化ARMCC 走不通。所以MBEDTLS_HAVE_ASM这个宏在 Keil4 上必须关掉让大数运算走纯 C 实现。代价是 RSA 运算慢一些但换来的是能编译过值。第三标准库是精简版。MicroLIB 砍掉了一堆东西time()、gmtime()、文件 IO、locale 全都没有。mbedTLS 里 X.509 的时间校验要用mbedtls_time_t熵源收集要用到平台抽象这些都得自己接。综合这三点我的结论是选 mbedTLS 2.x 系列不要碰 3.x。3.x 把密码学接口全面转向 PSA Crypto头文件依赖和初始化流程都变了对 ARMCC 5 的兼容性更差老工程接进去成本翻倍。2.x 系列在这方面成熟得多社区里跑通的例子也多。2. 动手前的准备版本、目录与源码裁剪2.1 版本怎么挑2.16、2.25、2.28 的差别2.x 系列里我实际用过的三个版本差别还是挺明显的版本C99 依赖编译难度推荐场景2.16.0较低最省心老工程、小 Flash、只求跑通2.25.0中等一般需要 TLS 1.3 部分特性、较新密码套件2.28.0较高稍麻烦长期维护、需要安全更新我一般建议新手从 2.16 起步原因是它内部代码风格更“老派”变量声明位置靠前对 C90 的容忍度反而更高就算你忘了勾 C99 也有可能编译过大半。等你把整个流程跑通了再考虑升到 2.28 拿安全补丁。版本还有个细节下载下来的是完整仓库里面programs/、tests/、visualc/这些目录完全不要往工程里加。只取include/和library/两个目录。我第一次搞的时候图省事把整个文件夹拖进去Keil4 直接卡死索引半天没反应。2.2 只留用得上的文件一份能直接抄的清单下面这份清单是做TLS 1.2 客户端 证书校验 ECDHE 密钥交换 AES-GCM 加密的最小集合我按用途分了组必须添加核心骨架 aes.c 对称加密 gcm.c AEAD 模式TLS 1.2 里最常用 sha256.c 握手过程中的 PRF 和完整性 md.c 消息摘要封装 ctr_drbg.c 伪随机数生成器 entropy.c 熵池 entropy_poll.c 熵源轮询裸机上会被替换 platform.c 平台抽象 platform_util.c bignum.c 大数运算底座 ecp.c ECC 曲线运算 ecp_curves.c 曲线参数表 ecdh.c 密钥交换 ssl_tls.c 协议核心 ssl_cli.c 客户端状态机 ssl_ciphersuites.c 密码套件表 error.c 错误码转字符串调试必留 按需添加要看服务端配置 rsa.c 服务端用 RSA 证书时必须 rsa_internal.c pk.c 公钥封装 pkparse.c 公钥解析 pk_wrap.c pkcs1.c pkcs5.c ecdsa.c 服务端用 ECDSA 证书时必须 x509.c 证书管理 x509_crt.c 证书解析要验证服务端必留 asn1parse.c DER 解析 asn1write.c oid.c OID 映射 base64.c pem.c 如果证书以 PEM 文本形式存储 可以不要 ssl_srv.c 做服务端才要 net_sockets.c 裸机不能用一定要排除 timing.c 依赖 gettimeofday裸机不要 threading.c 无操作系统不要 fs_io 相关 不要这张表的价值在于每多一个文件编译时间和链接体积就多一截。ssl_tls.c一个文件编译在 Keil4 上要几十秒全量编译一次能等好几分钟。裁到位以后一次全编译一两分钟就完事了。2.3 目录怎么摆Keil4 才不会乱我踩过的第一个坑就是目录太深。Keil4 对路径长度和中文路径非常敏感路径里出现空格、中文、甚至过深的层级都可能让编译器找不到头文件。我现在的固定摆法是这样Project/ ├── app/ 自己的业务代码 ├── mbedtls/ │ ├── include/ │ │ ├── mbedtls/ 库自带的头文件 │ │ └── mbedtls_config.h 我自己改过的配置 │ └── library/ 上面裁剪出来的 .c 文件 ├── drivers/ 外设驱动 └── mdk/ Keil 工程文件放这里关键点把修改过的配置文件放在工程目录下不要直接改include/mbedtls/config.h。原因很实在——将来升级库版本直接覆盖library和include/mbedtls就行自己的配置不受影响。用MBEDTLS_CONFIG_FILE宏指向自己的文件这个后面会讲。还有一个细节整个工程路径里绝对不能有中文和空格。这不是迷信Keil4 在某些系统区域设置下处理中文路径会直接把路径截断报“cannot open source input file”你还以为是文件名写错了找半天。3. 配置文件是整套东西的大脑这部分最值钱3.1 从模板开始改别从零写mbedTLS 的config.h有上千行全是#define和#if嵌套。从零写不现实正确做法是复制一份官方模板然后按“先全关、再按需开”的思路改。具体操作顺序是这样先把模板里所有MBEDTLS_XXX_C的代表模块宏注释掉只留#define MBEDTLS_PLATFORM_C #define MBEDTLS_AES_C #define MBEDTLS_SHA256_C #define MBEDTLS_MD_C #define MBEDTLS_CTR_DRBG_C #define MBEDTLS_ENTROPY_C #define MBEDTLS_SSL_TLS_C #define MBEDTLS_SSL_CLI_C然后编一次。能编过就说明骨架通了再一个个往上加每加一组编一次。这个“小步加法”是我最推荐的策略比一次开一堆然后面对 30 条报错强一百倍。加宏的时候有个规律要记住宏之间是有依赖链的。比如开了MBEDTLS_SSL_CLI_C就必须开MBEDTLS_SSL_TLS_C开了MBEDTLS_SSL_TLS_C就必须有MBEDTLS_MD_C和一个可用的哈希算法开了MBEDTLS_X509_CRT_PARSE_C就必须有MBEDTLS_PK_C、MBEDTLS_ASN1_PARSE_C、MBEDTLS_OID_C。少一个编译期就会用#error明确告诉你缺什么顺着提示补就行不要猜。3.2 内存账要提前算这是最容易翻车的地方很多人以为 mbedTLS 是小库随手往 20KB RAM 的板子上一放结果初始化就 HardFault。问题出在两个 16KB 的收发缓冲区上。mbedTLS 的 SSL 上下文里默认MBEDTLS_SSL_MAX_CONTENT_LEN是 16384 字节输入和输出各一份。这两块内存在mbedtls_ssl_setup时分配如果你的堆只有几 KB直接崩。算一笔账以 2.16 为例改过配置后项目默认值建议值说明MBEDTLS_SSL_IN_CONTENT_LEN163844096单方向最大分片调小要服务器支持MBEDTLS_SSL_OUT_CONTENT_LEN163842048发送方向数据量通常小MBEDTLS_MPI_MAX_SIZE10242562048 位 RSA 够用省大数缓冲区MBEDTLS_ECP_MAX_BITS521256只用 P-256 曲线就够MBEDTLS_ECP_WINDOW_SIZE42 或 3影响 ECC 速度和 RAM是此消彼长把IN_CONTENT_LEN调到 4096 有个前提服务端得接受更小的最大分片长度。TLS 里有max_fragment_length扩展客户端发出去服务端同意了才行。如果服务端不支持握手阶段可能因为分片太大失败。我在测试环境里遇到过调回 16384 就通了所以这个值不是想调就能调得配合实际服务端验证。还有一个常被忽略的点栈。mbedtls_ssl_handshake整个调用链很深里面有本地大数组RSA 验签和大数运算也在栈上放临时变量。实测下来主栈至少给到 4KB用 ECDSA 证书加 ECDHE 交换时大概 2.5KB 就够了但用 RSA-2048 验签的时候峰值能到 3.5KB。启动文件里Stack_Size默认 0x4001KB这个必须改改成 0x1000 起步。如果实在想要“不用堆”的方案可以开内存池#define MBEDTLS_MEMORY_BUFFER_ALLOC_C #define MBEDTLS_PLATFORM_MEMORY然后自己给一块静态数组static unsigned char heap_buf[24 * 1024] __attribute__((aligned(8))); void crypto_init(void) { mbedtls_memory_buffer_alloc_init(heap_buf, sizeof(heap_buf)); }这块必须在mbedtls_ssl_setup之前初始化否则内部calloc会走到标准库的堆上。用内存池的好处是 RAM 占用变成编译期可算的固定值跑起来不会因为碎片越跑越崩坏处是这块 24KB 直接被吃掉得看你板子剩多少。3.3 三个必须自己写的适配层随机数、时间、收发这可能是整套流程里最“非文档”的部分因为裸机上这三个东西都没有现成的。第一个是硬件随机数。mbedTLS 的熵池需要真正的物理熵源软件伪随机不够。STM32 部分型号自带 RNG 外设可以直接接进去#define MBEDTLS_ENTROPY_HARDWARE_ALT int mbedtls_hardware_poll(void *data, unsigned char *output, size_t len, size_t *olen) { (void)data; uint32_t rnd; *olen 0; for (size_t i 0; i len; i 4) { while (RNG_GetFlagStatus(RNG_FLAG_DRDY) RESET) {} rnd RNG_GetRandomNumber(); size_t n (len - i) 4 ? (len - i) : 4; memcpy(output i, rnd, n); *olen n; } return 0; }没有 RNG 外设的型号比如 F103 系列就得另想办法可以用内部 ADC 采噪声、可以用外部加密芯片、也可以在产线上烧一个唯一密钥做种子再混入计数器。最后这种严格来说不算真随机但在很多场景下够用前提是每个设备种子不同。种子一样的话随机数序列完全一样安全性直接归零这点必须说清楚。第二个是时间。X.509 证书有有效期验证时需要当前时间。裸机没有 RTC 就没法给两种处理有 RTC 的板子定义MBEDTLS_PLATFORM_TIME_ALT自己实现mbedtls_platform_set_time把 RTC 转成 Unix 时间戳。没有 RTC注释掉MBEDTLS_HAVE_TIME和MBEDTLS_HAVE_TIME_DATE证书有效期就不校验了。第二种做法有风险等于放弃了“过期证书会被拒绝”这层保护。折中方案是首次连接时从服务端响应头拿到时间写回 RTC之后正常校验。这个逻辑要写点代码但安全性会好很多。第三个是收发回调。mbedTLS 不关心你用 TCP、4G 模组还是串口透传它只要求两个函数static int net_send(void *ctx, const unsigned char *buf, size_t len) { /* 把 buf 写入 socket 或串口返回实际写入长度 */ } static int net_recv(void *ctx, unsigned char *buf, size_t len) { /* 读取最多 len 字节返回实际读到长度超时要返回 MBEDTLS_ERR_SSL_TIMEOUT */ } mbedtls_ssl_set_bio(ssl, ctx, net_send, net_recv, NULL);这里有个坑我印象深刻net_recv返回 0 不是“没数据”而是“连接关闭”。如果你的 socket 是非阻塞的读不到数据返回 0mbedTLS 会认为对端关了连接直接握手失败。正确做法是非阻塞读取返回MBEDTLS_ERR_SSL_WANT_READ让 mbedTLS 知道“现在还没数据等会儿再试”。同理发送缓冲区满了要返回MBEDTLS_ERR_SSL_WANT_WRITE。这两个返回值搞错了握手八成过不去。4. Keil4 工程配置与编译排错实录4.1 添加文件、路径和关键宏具体操作路径我写细一点因为这步最容易被漏右键Target或者用Project → Manage → Components新建一个 Group命名mbedtls。把library下裁好的.c文件全部加进这个 Group。文件多的时候按住 Shift 一次选完别一个一个加。打开Options for Target → C/C在Include Paths里加两条..\mbedtls\include和..\mbedtls\include\mbedtls。第一条是给mbedtls/xxx.h这种写法用的第二条给内部#include xxx.h用的两条都加省得出问题。在Define框里填上配置文件名MBEDTLS_CONFIG_FILEmbedtls_config.h引号一定要有没有引号宏展开会变成裸标识符报“未定义”。勾上C99 Mode。MDK4 里在C/C选项卡的中间位置有个复选框勾上以后编译器会加--c99。如果之前没加过一定要确认没有把net_sockets.c加进来这个文件一加就会报sys/socket.h找不到。4.2 MicroLIB、优化等级、编译时间怎么权衡MicroLIB 这个选项值得单独说。勾上它有几个好处代码小一点、启动快一点、不用做半主机重定向。坏处是某些函数缺失。mbedTLS 用到的snprintf、memcpy、memset在 MicroLIB 里都有所以我一般勾上。但有个例外如果你的工程里还要用浮点打印printf(%f)MicroLIB 不支持那就不能勾。我在一个工程里因为要打印 RSSI 的小数被迫关掉 MicroLIB然后就得自己实现_sys_exit、_ttywrch这些桩函数还挺烦。优化等级上-O0好调试但体积大-O1是个甜点-O2体积更小但单步调试时代码会跳来跳去。我的建议调试阶段用-O0或-O1出货前改-O2对比一下体积。曾经有个工程从-O0切到-O2Flash 从 96KB 降到 71KB效果很明显。编译时间的问题要提前有心理准备。Keil4 的单线程编译加上 mbedTLS 那些巨型源文件第一次编译花三五分钟很正常。我一般会把-j多核编译打开MDK4 后期版本支持能快不少。4.3 编译报错逐个击破这部分是纯经验我按出现频率排序错误一cannot open source input file mbedtls/xxx.h头文件路径没加对或者加了但层级不对。检查一下Include Paths里是不是加了mbedtls/include而不是mbedtls。这个错误看着简单但我见过因为路径里带了个..\..少一级折腾半小时的。错误二#error MBEDTLS_SSL_CLI_C defined, but not all prerequisites依赖没开全。mbedTLS 的依赖检查很明确#error后面会列出缺哪个宏照着补就行。这个其实是最友好的错误。错误三error: #20: identifier int64_t is undefinedC99 没开。勾上 C99 Mode 就好或者Misc Controls里手动加--c99。错误四L6915E: Library reports error: __use_no_semihosting was requested, but _ttywrch was referenced这是链接冲突。你开了“不使用半主机”但库里还有函数引用了半主机接口。解决办法是开 MicroLIB或者自己实现这几个桩函数void _ttywrch(int ch) { (void)ch; } void _sys_exit(int x) { (void)x; while(1){} }错误五L6406E: No space in execution regions with .ANY selector matching xxx.o(.text)Flash 不够。这时候要做的是算账Options for Target → Target下面看编译输出的 Code RO Data RW Data 各是多少。如果 Code 已经 90KB 而芯片只有 128KB那就得回头裁剪。最快的裁剪路径是换 ECDSA 证书、关 RSA、关掉 TLS 1.0/1.1、关MBEDTLS_DEBUG_C。错误六编译过了运行 HardFault 在mbedtls_ssl_setup几乎百分百是堆不够。检查启动文件的栈大小和malloc可用空间。用内存池的方案就是看池子开够没有——一个完整 TLS 客户端会话含证书大概需要 20~28KB 池空间。5. 跑通验证从算法自检到一次真实握手5.1 先证明算法层没问题很多人上来就接网络做握手一通-1之后就懵了根本分不清是算法层错了还是传输层错了。正确的顺序是自底向上验证。第一步跑 mbedTLS 自带的自检函数。开MBEDTLS_SELF_TEST宏然后int ret; ret mbedtls_aes_self_test(1); /* 参数非 0 表示打印细节 */ if (ret ! 0) { /* 算法层有问题先解决这个 */ } ret mbedtls_sha256_self_test(1); ret mbedtls_ecp_self_test(1);这些自检用的是内置标准测试向量能通过就说明算法实现本身没问题问题肯定在后面。这一步花两分钟能省后面两小时。第二步测随机数。随机数不对的表现很隐蔽——算法都对但握手就是过不去或者加密结果每次不一样。写个循环打印 32 字节反复看unsigned char buf[32]; mbedtls_ctr_drbg_random(ctr_drbg, buf, sizeof(buf));跑两次如果两次结果一样同一复位周期内说明熵源没接上或者种子是固定的。这里要注意同一个ctr_drbg上下文连续取两次结果本来就应该不一样因为 ctr_drbg 内部有计数器推进。如果一样那肯定是代码写错了比如重复初始化了同一个上下文。5.2 把收发回调接上完成一次握手算法层验证通过后接传输层。我建议第一次先用 PC 上的模拟服务端方便抓包看哪里断了。初始化顺序不能乱我列一下完整流程mbedtls_entropy_context entropy; mbedtls_ctr_drbg_context ctr_drbg; mbedtls_ssl_context ssl; mbedtls_ssl_config conf; mbedtls_x509_crt cacert; mbedtls_entropy_init(entropy); mbedtls_ctr_drbg_init(ctr_drbg); mbedtls_ssl_init(ssl); mbedtls_ssl_config_init(conf); mbedtls_x509_crt_init(cacert); /* 1. 种随机数 */ mbedtls_entropy_add_source(entropy, my_entropy_source, NULL, 32, MBEDTLS_ENTROPY_SOURCE_STRONG); mbedtls_ctr_drbg_seed(ctr_drbg, mbedtls_entropy_func, entropy, (const unsigned char *)dev_seed, 8); /* 2. 加载 CA 证书DER 格式的静态数组 */ mbedtls_x509_crt_parse(cacert, ca_der, ca_der_len); /* 3. 配置 */ mbedtls_ssl_config_defaults(conf, MBEDTLS_SSL_IS_CLIENT, MBEDTLS_SSL_TRANSPORT_STREAM, MBEDTLS_SSL_PRESET_DEFAULT); mbedtls_ssl_conf_authmode(conf, MBEDTLS_SSL_VERIFY_REQUIRED); mbedtls_ssl_conf_ca_chain(conf, cacert, NULL); mbedtls_ssl_conf_rng(conf, mbedtls_ctr_drbg_random, ctr_drbg); /* 4. 强制 TLS 1.2避免协商到老版本 */ mbedtls_ssl_conf_min_version(conf, MBEDTLS_SSL_MAJOR_VERSION_3, MBEDTLS_SSL_MINOR_VERSION_3); /* 5. 绑定 */ mbedtls_ssl_setup(ssl, conf); mbedtls_ssl_set_hostname(ssl, your-endpoint); mbedtls_ssl_set_bio(ssl, net_ctx, net_send, net_recv, NULL); /* 6. 握手 */ while ((ret mbedtls_ssl_handshake(ssl)) ! 0) { if (ret ! MBEDTLS_ERR_SSL_WANT_READ ret ! MBEDTLS_ERR_SSL_WANT_WRITE) { break; /* 真错了 */ } }这里有几个必须遵守的规矩其一MBEDTLS_SSL_VERIFY_REQUIRED这个模式一定要用。设成VERIFY_NONE就等于不验证服务端身份中间人随便插加密也就成了摆设。见过为了“先跑通”改成 NONE 然后忘了改回来直接出货的这种事故不新鲜。其二mbedtls_ssl_set_hostname必须调用。它不只是为了发 SNI更重要的是证书里的域名要和这个值比对不设的话域名校验形同虚设。其三握手返回WANT_READ/WANT_WRITE时不要重头来继续循环调就行状态机自己会记住进度。有次同事在WANT_READ之后把整个 ssl 上下文重新初始化了握手永远停在第一步。5.3 实测的资源占用和性能数据这部分是纯实测仅供参考具体数字随配置变化很大配置组合FlashRAM会话期握手耗时72MHzAES-GCM ECDHE-ECDSA P-256约 55KB约 12KB约 900msAES-GCM ECDHE-RSA RSA2048 验签约 78KB约 16KB约 2600ms上一行 TLS1.0/1.1 兼容约 86KB约 16KB同上从数据能看出来两个结论RSA 的代价主要在 CPU 时间上Flash 也多 20 多 KBECDSA 完胜所以选服务端证书类型的时候能选 ECDSA 就选 ECDSA。如果服务端只能给 RSA 证书那就接受这 2 秒多的握手时间或者用会话恢复session ticket把第二次之后的握手压到几百毫秒。会话恢复这块值得提一句。开MBEDTLS_SSL_SESSION_TICKETS握手成功后存下mbedtls_ssl_get_session下次重连时先mbedtls_ssl_set_session再握手能省掉完整的密钥交换流程。对电池供电的设备来说省这点电挺实在。6. 踩坑记录与排查速查表6.1 我遇到过的几个典型故障故障一握手一直返回-0x2700这个错误码对应证书验证失败。排查顺序是先看是不是时间不对没接 RTC 时最常见再看 CA 证书有没有加载对最后看set_hostname的值和证书里的 CN/SAN 是否匹配。我遇到过一次是证书链不完整——只放了叶子证书没放中间 CA服务端不给中间证书验证就断了。解决办法是把中间 CA 也拼进cacert里mbedtls_x509_crt_parse是支持一次解析多张的。故障二连上了握手成功但收到数据就断问题在记录层。我遇到的是MBEDTLS_SSL_IN_CONTENT_LEN调到了 2048服务端发来 3000 多字节直接超限。表现是mbedtls_ssl_read返回MBEDTLS_ERR_SSL_INVALID_RECORD或者干脆卡住。调大这个值就通了。所以调小缓冲区要在握手成功后做实际数据压测不能只看握手过不过。故障三随机数池一直报MBEDTLS_ERR_ENTROPY_NO_SOURCES_DEFINED熵源没添加成功。mbedtls_entropy_add_source的第四个参数是阈值表示“至少收集多少字节才认为熵够”。这个值设得太大比如 256而你的熵源每次只能给 4 字节就会一直凑不够。设成 32 或者干脆设成 1 加WEAK标记都行按你的熵源质量定。故障四编译通过链接报一堆Undefined symbol mbedtls_xxx文件加少了。这种错误的特点是符号名直接告诉你是哪个模块比如mbedtls_ecp_mul没定义就是缺ecp.c。但有时候会间接报错比如缺ecp_curves.c时报的是曲线参数符号未定义。看符号名去猜模块比翻文档快。故障五跑一段时间后内存溢出崩溃这是碎片问题。mbedTLS 每次会话会malloc/free若干次长时间反复连接断开标准库堆会碎。改用内存池方案或者做成“一次初始化长期复用”的模式——上下文不销毁只重连。后者更实用我现在的工程都是这个模式。6.2 排查速查表现象最可能原因快速验证方法编译报缺头文件Include Paths 层级不对检查是否加了include和include/mbedtls两条编译报 C99 语法错没勾 C99打开 C99 Mode 或加--c99链接报半主机错误未开 MicroLIB 且缺桩函数开 MicroLIB或补_ttywrch运行 HardFault 在 setup堆或池子不够打印剩余堆扩到 24KB 以上握手返回-0x2700证书验证失败查时间、CA、hostname 三项握手卡住不动recv 返回值语义错非阻塞应返回WANT_READ握手成功但读数据错缓冲区太小看IN_CONTENT_LEN是否小于服务端分片随机数报无熵源熵阈值设太大看add_source第 4 个参数长时间跑崩溃堆碎片换内存池或复用上下文Flash 超配置太肥砍 RSA、砍 TLS1.0、砍调试6.3 体积和稳定性的几个实招先说体积。除了前面提到的裁文件还有几个宏能明显瘦身MBEDTLS_AES_ROM_TABLES打开把 AES 的 S 盒和乘法表放到 Flash 常量区省 512 字节 RAM。MBEDTLS_ECP_FIXED_POINT_OPTIM关了能省一点代码但会慢。MBEDTLS_DEBUG_C只在调试期开正式版一定关——这东西带着一堆字符串能占好几 KB。再说稳定性。我总结的做法是**“三不”**不在中断里调 mbedTLS、不在握手期间做长耗时操作、不让多个任务同时用一个 ssl 上下文。裸机上没有锁一旦两个地方同时往 ssl 上下文里写状态机就乱了。还有一个容易被忽略的点时钟精度。mbedTLS 有些地方依赖超时判断如果你的net_recv里用的是粗粒度延时比如HAL_Delay握手时可能误判超时。我一般用自己的毫秒计数器net_recv里按实际耗时判断超过 10 秒才返回超时。另外提醒一句证书不要硬编码成 PEM 字符串放在代码里。PEM 是 Base64 编码的比 DER 大三分之一还多占 RAM 解析。用工具转成 DER 后用数组导出体积小、解析快。如果一定要用 PEM记得开MBEDTLS_PEM_PARSE_C。我个人在这套组合上折腾了很多轮最深的体会是顺序比技巧重要。先定版本再裁文件然后配宏接着编过最后自检、握手、压测一步都别跳。每跳一步后面排查的难度都是翻倍的。另外一定要在工程里留一份“能跑通的最小配置”改坏的时候退回去比一个一个宏去猜快得多。mbedTLS 这库设计得其实挺规矩报错信息也够清楚只要不一次性改太多东西出问题基本都是能定位的。
项目标题已经点得很具体STM32 上加 mbedTLS而且是在 Keil4 这种“上年纪”的 IDE 里加。这事儿听着像个体力活实际上真正费时间的不是敲代码而是版本选错、配置写崩、编译报一堆看不懂的错、跑起来一个-1甩你脸上。我在几个小容量 MCU 工程里反复折腾过这套组合踩坑踩得比较全下面把这些东西一次讲透——从为什么这么选、源码怎么裁、配置文件每个宏在算什么账到编译报错和握手失败的排查路径都按能直接抄作业的方式写。1. 先把需求捋清楚为什么是 mbedTLS为什么卡在 Keil41.1 老工程要联网绕不开的三件事设备要往服务端传数据只要走公网基本就绕不开三件事身份要能验证、数据要能加密、完整性要能校验。裸 TCP 传明文中间任何一跳都能看、能改、能重放产品一旦出门就是隐患。所以哪怕是个 64KB Flash 的小板子只要联网就得考虑 TLS。但单片机做 TLS 和 PC 上做 TLS 完全是两个难度。PC 上一个 OpenSSL 链接过去就完事单片机这里要面对三个硬约束Flash 装不下、RAM 装不下、没有操作系统帮忙。一个完整的 TLS 栈在桌面端动辄几 MB塞进 STM32 根本不可能必须找那种“能拆开、只拿需要的零件”的库。mbedTLS 就是靠这个吃饭的——它的设计思路是模块化加编译期裁剪不要的功能在config.h里一关连代码都不参与编译最后体积能压到几十 KB 级别。另一个现实问题是 Keil4。很多老项目、教学工程、还有一堆历史遗留的.uvproj就是用 MDK4 建的换 IDE 意味着整个工程结构、启动文件、链接脚本都要重弄成本比想象中高。所以现实做法往往是不动工程只往里加库。这就要接受 Keil4 自带 ARMCC 5 编译器的一些限制比如对 C99 的支持是“勾选式”的、部分标准头文件缺失、内联汇编写法和 GCC 不一样。这些限制会在后面每一步都跳出来提醒你。1.2 mbedTLS 的模块化结构为什么适合单片机我把 mbedTLS 的结构理解成四层从下往上层次主要文件作用能否裁剪基础算法层aes.csha256.csha1.cmd.cgcm.c对称加密、哈希、AEAD按需能去掉一半公钥层bignum.crsa.cecp.cecdsa.cecdh.c大数运算、签名验签、密钥交换ECC 和 RSA 可二选一证书层x509_crt.cpk.cpkparse.casn1parse.c解析证书、提取公钥只在需要验证服务端时用协议层ssl_tls.cssl_cli.cssl_ciphersuites.c握手状态机、记录层必须但可以只留客户端这个分层的好处是裁剪边界非常清晰。比如你只做本地数据加密存储不上网那ssl_*和x509_*全部不要只留aes.csha256.c代码量能压到 10KB 以内。反过来要连服务器就必须把协议层和证书层带上那体积自然就上去了。有一点必须提前说清楚mbedTLS 的“模块化”不等于“无依赖”。ssl_tls.c会依赖ctr_drbg.c做随机数依赖entropy.c收集熵依赖platform.c做内存和打印的抽象还依赖你自己实现的收发回调。所以哪怕配置文件只开了 TLS编译时也会连带着拉进来一堆基础文件这是正常的别慌。1.3 Keil4 的编译器特性直接决定了版本怎么选Keil4 的 ARMCC 5 有三个特点会直接影响 mbedTLS 的选型第一默认按 C90 编译。虽然可以勾 C99但 C90 模式下//注释、变量声明位置、long long这些都会报错。mbedTLS 从 2.x 开始大量用了 C99 特性所以 C99 必须开没有商量余地。第二内联汇编的支持范围窄。mbedTLS 的bn_mul.h里有一堆针对 GCC 和 x86 的内联汇编优化ARMCC 走不通。所以MBEDTLS_HAVE_ASM这个宏在 Keil4 上必须关掉让大数运算走纯 C 实现。代价是 RSA 运算慢一些但换来的是能编译过值。第三标准库是精简版。MicroLIB 砍掉了一堆东西time()、gmtime()、文件 IO、locale 全都没有。mbedTLS 里 X.509 的时间校验要用mbedtls_time_t熵源收集要用到平台抽象这些都得自己接。综合这三点我的结论是选 mbedTLS 2.x 系列不要碰 3.x。3.x 把密码学接口全面转向 PSA Crypto头文件依赖和初始化流程都变了对 ARMCC 5 的兼容性更差老工程接进去成本翻倍。2.x 系列在这方面成熟得多社区里跑通的例子也多。2. 动手前的准备版本、目录与源码裁剪2.1 版本怎么挑2.16、2.25、2.28 的差别2.x 系列里我实际用过的三个版本差别还是挺明显的版本C99 依赖编译难度推荐场景2.16.0较低最省心老工程、小 Flash、只求跑通2.25.0中等一般需要 TLS 1.3 部分特性、较新密码套件2.28.0较高稍麻烦长期维护、需要安全更新我一般建议新手从 2.16 起步原因是它内部代码风格更“老派”变量声明位置靠前对 C90 的容忍度反而更高就算你忘了勾 C99 也有可能编译过大半。等你把整个流程跑通了再考虑升到 2.28 拿安全补丁。版本还有个细节下载下来的是完整仓库里面programs/、tests/、visualc/这些目录完全不要往工程里加。只取include/和library/两个目录。我第一次搞的时候图省事把整个文件夹拖进去Keil4 直接卡死索引半天没反应。2.2 只留用得上的文件一份能直接抄的清单下面这份清单是做TLS 1.2 客户端 证书校验 ECDHE 密钥交换 AES-GCM 加密的最小集合我按用途分了组必须添加核心骨架 aes.c 对称加密 gcm.c AEAD 模式TLS 1.2 里最常用 sha256.c 握手过程中的 PRF 和完整性 md.c 消息摘要封装 ctr_drbg.c 伪随机数生成器 entropy.c 熵池 entropy_poll.c 熵源轮询裸机上会被替换 platform.c 平台抽象 platform_util.c bignum.c 大数运算底座 ecp.c ECC 曲线运算 ecp_curves.c 曲线参数表 ecdh.c 密钥交换 ssl_tls.c 协议核心 ssl_cli.c 客户端状态机 ssl_ciphersuites.c 密码套件表 error.c 错误码转字符串调试必留 按需添加要看服务端配置 rsa.c 服务端用 RSA 证书时必须 rsa_internal.c pk.c 公钥封装 pkparse.c 公钥解析 pk_wrap.c pkcs1.c pkcs5.c ecdsa.c 服务端用 ECDSA 证书时必须 x509.c 证书管理 x509_crt.c 证书解析要验证服务端必留 asn1parse.c DER 解析 asn1write.c oid.c OID 映射 base64.c pem.c 如果证书以 PEM 文本形式存储 可以不要 ssl_srv.c 做服务端才要 net_sockets.c 裸机不能用一定要排除 timing.c 依赖 gettimeofday裸机不要 threading.c 无操作系统不要 fs_io 相关 不要这张表的价值在于每多一个文件编译时间和链接体积就多一截。ssl_tls.c一个文件编译在 Keil4 上要几十秒全量编译一次能等好几分钟。裁到位以后一次全编译一两分钟就完事了。2.3 目录怎么摆Keil4 才不会乱我踩过的第一个坑就是目录太深。Keil4 对路径长度和中文路径非常敏感路径里出现空格、中文、甚至过深的层级都可能让编译器找不到头文件。我现在的固定摆法是这样Project/ ├── app/ 自己的业务代码 ├── mbedtls/ │ ├── include/ │ │ ├── mbedtls/ 库自带的头文件 │ │ └── mbedtls_config.h 我自己改过的配置 │ └── library/ 上面裁剪出来的 .c 文件 ├── drivers/ 外设驱动 └── mdk/ Keil 工程文件放这里关键点把修改过的配置文件放在工程目录下不要直接改include/mbedtls/config.h。原因很实在——将来升级库版本直接覆盖library和include/mbedtls就行自己的配置不受影响。用MBEDTLS_CONFIG_FILE宏指向自己的文件这个后面会讲。还有一个细节整个工程路径里绝对不能有中文和空格。这不是迷信Keil4 在某些系统区域设置下处理中文路径会直接把路径截断报“cannot open source input file”你还以为是文件名写错了找半天。3. 配置文件是整套东西的大脑这部分最值钱3.1 从模板开始改别从零写mbedTLS 的config.h有上千行全是#define和#if嵌套。从零写不现实正确做法是复制一份官方模板然后按“先全关、再按需开”的思路改。具体操作顺序是这样先把模板里所有MBEDTLS_XXX_C的代表模块宏注释掉只留#define MBEDTLS_PLATFORM_C #define MBEDTLS_AES_C #define MBEDTLS_SHA256_C #define MBEDTLS_MD_C #define MBEDTLS_CTR_DRBG_C #define MBEDTLS_ENTROPY_C #define MBEDTLS_SSL_TLS_C #define MBEDTLS_SSL_CLI_C然后编一次。能编过就说明骨架通了再一个个往上加每加一组编一次。这个“小步加法”是我最推荐的策略比一次开一堆然后面对 30 条报错强一百倍。加宏的时候有个规律要记住宏之间是有依赖链的。比如开了MBEDTLS_SSL_CLI_C就必须开MBEDTLS_SSL_TLS_C开了MBEDTLS_SSL_TLS_C就必须有MBEDTLS_MD_C和一个可用的哈希算法开了MBEDTLS_X509_CRT_PARSE_C就必须有MBEDTLS_PK_C、MBEDTLS_ASN1_PARSE_C、MBEDTLS_OID_C。少一个编译期就会用#error明确告诉你缺什么顺着提示补就行不要猜。3.2 内存账要提前算这是最容易翻车的地方很多人以为 mbedTLS 是小库随手往 20KB RAM 的板子上一放结果初始化就 HardFault。问题出在两个 16KB 的收发缓冲区上。mbedTLS 的 SSL 上下文里默认MBEDTLS_SSL_MAX_CONTENT_LEN是 16384 字节输入和输出各一份。这两块内存在mbedtls_ssl_setup时分配如果你的堆只有几 KB直接崩。算一笔账以 2.16 为例改过配置后项目默认值建议值说明MBEDTLS_SSL_IN_CONTENT_LEN163844096单方向最大分片调小要服务器支持MBEDTLS_SSL_OUT_CONTENT_LEN163842048发送方向数据量通常小MBEDTLS_MPI_MAX_SIZE10242562048 位 RSA 够用省大数缓冲区MBEDTLS_ECP_MAX_BITS521256只用 P-256 曲线就够MBEDTLS_ECP_WINDOW_SIZE42 或 3影响 ECC 速度和 RAM是此消彼长把IN_CONTENT_LEN调到 4096 有个前提服务端得接受更小的最大分片长度。TLS 里有max_fragment_length扩展客户端发出去服务端同意了才行。如果服务端不支持握手阶段可能因为分片太大失败。我在测试环境里遇到过调回 16384 就通了所以这个值不是想调就能调得配合实际服务端验证。还有一个常被忽略的点栈。mbedtls_ssl_handshake整个调用链很深里面有本地大数组RSA 验签和大数运算也在栈上放临时变量。实测下来主栈至少给到 4KB用 ECDSA 证书加 ECDHE 交换时大概 2.5KB 就够了但用 RSA-2048 验签的时候峰值能到 3.5KB。启动文件里Stack_Size默认 0x4001KB这个必须改改成 0x1000 起步。如果实在想要“不用堆”的方案可以开内存池#define MBEDTLS_MEMORY_BUFFER_ALLOC_C #define MBEDTLS_PLATFORM_MEMORY然后自己给一块静态数组static unsigned char heap_buf[24 * 1024] __attribute__((aligned(8))); void crypto_init(void) { mbedtls_memory_buffer_alloc_init(heap_buf, sizeof(heap_buf)); }这块必须在mbedtls_ssl_setup之前初始化否则内部calloc会走到标准库的堆上。用内存池的好处是 RAM 占用变成编译期可算的固定值跑起来不会因为碎片越跑越崩坏处是这块 24KB 直接被吃掉得看你板子剩多少。3.3 三个必须自己写的适配层随机数、时间、收发这可能是整套流程里最“非文档”的部分因为裸机上这三个东西都没有现成的。第一个是硬件随机数。mbedTLS 的熵池需要真正的物理熵源软件伪随机不够。STM32 部分型号自带 RNG 外设可以直接接进去#define MBEDTLS_ENTROPY_HARDWARE_ALT int mbedtls_hardware_poll(void *data, unsigned char *output, size_t len, size_t *olen) { (void)data; uint32_t rnd; *olen 0; for (size_t i 0; i len; i 4) { while (RNG_GetFlagStatus(RNG_FLAG_DRDY) RESET) {} rnd RNG_GetRandomNumber(); size_t n (len - i) 4 ? (len - i) : 4; memcpy(output i, rnd, n); *olen n; } return 0; }没有 RNG 外设的型号比如 F103 系列就得另想办法可以用内部 ADC 采噪声、可以用外部加密芯片、也可以在产线上烧一个唯一密钥做种子再混入计数器。最后这种严格来说不算真随机但在很多场景下够用前提是每个设备种子不同。种子一样的话随机数序列完全一样安全性直接归零这点必须说清楚。第二个是时间。X.509 证书有有效期验证时需要当前时间。裸机没有 RTC 就没法给两种处理有 RTC 的板子定义MBEDTLS_PLATFORM_TIME_ALT自己实现mbedtls_platform_set_time把 RTC 转成 Unix 时间戳。没有 RTC注释掉MBEDTLS_HAVE_TIME和MBEDTLS_HAVE_TIME_DATE证书有效期就不校验了。第二种做法有风险等于放弃了“过期证书会被拒绝”这层保护。折中方案是首次连接时从服务端响应头拿到时间写回 RTC之后正常校验。这个逻辑要写点代码但安全性会好很多。第三个是收发回调。mbedTLS 不关心你用 TCP、4G 模组还是串口透传它只要求两个函数static int net_send(void *ctx, const unsigned char *buf, size_t len) { /* 把 buf 写入 socket 或串口返回实际写入长度 */ } static int net_recv(void *ctx, unsigned char *buf, size_t len) { /* 读取最多 len 字节返回实际读到长度超时要返回 MBEDTLS_ERR_SSL_TIMEOUT */ } mbedtls_ssl_set_bio(ssl, ctx, net_send, net_recv, NULL);这里有个坑我印象深刻net_recv返回 0 不是“没数据”而是“连接关闭”。如果你的 socket 是非阻塞的读不到数据返回 0mbedTLS 会认为对端关了连接直接握手失败。正确做法是非阻塞读取返回MBEDTLS_ERR_SSL_WANT_READ让 mbedTLS 知道“现在还没数据等会儿再试”。同理发送缓冲区满了要返回MBEDTLS_ERR_SSL_WANT_WRITE。这两个返回值搞错了握手八成过不去。4. Keil4 工程配置与编译排错实录4.1 添加文件、路径和关键宏具体操作路径我写细一点因为这步最容易被漏右键Target或者用Project → Manage → Components新建一个 Group命名mbedtls。把library下裁好的.c文件全部加进这个 Group。文件多的时候按住 Shift 一次选完别一个一个加。打开Options for Target → C/C在Include Paths里加两条..\mbedtls\include和..\mbedtls\include\mbedtls。第一条是给mbedtls/xxx.h这种写法用的第二条给内部#include xxx.h用的两条都加省得出问题。在Define框里填上配置文件名MBEDTLS_CONFIG_FILEmbedtls_config.h引号一定要有没有引号宏展开会变成裸标识符报“未定义”。勾上C99 Mode。MDK4 里在C/C选项卡的中间位置有个复选框勾上以后编译器会加--c99。如果之前没加过一定要确认没有把net_sockets.c加进来这个文件一加就会报sys/socket.h找不到。4.2 MicroLIB、优化等级、编译时间怎么权衡MicroLIB 这个选项值得单独说。勾上它有几个好处代码小一点、启动快一点、不用做半主机重定向。坏处是某些函数缺失。mbedTLS 用到的snprintf、memcpy、memset在 MicroLIB 里都有所以我一般勾上。但有个例外如果你的工程里还要用浮点打印printf(%f)MicroLIB 不支持那就不能勾。我在一个工程里因为要打印 RSSI 的小数被迫关掉 MicroLIB然后就得自己实现_sys_exit、_ttywrch这些桩函数还挺烦。优化等级上-O0好调试但体积大-O1是个甜点-O2体积更小但单步调试时代码会跳来跳去。我的建议调试阶段用-O0或-O1出货前改-O2对比一下体积。曾经有个工程从-O0切到-O2Flash 从 96KB 降到 71KB效果很明显。编译时间的问题要提前有心理准备。Keil4 的单线程编译加上 mbedTLS 那些巨型源文件第一次编译花三五分钟很正常。我一般会把-j多核编译打开MDK4 后期版本支持能快不少。4.3 编译报错逐个击破这部分是纯经验我按出现频率排序错误一cannot open source input file mbedtls/xxx.h头文件路径没加对或者加了但层级不对。检查一下Include Paths里是不是加了mbedtls/include而不是mbedtls。这个错误看着简单但我见过因为路径里带了个..\..少一级折腾半小时的。错误二#error MBEDTLS_SSL_CLI_C defined, but not all prerequisites依赖没开全。mbedTLS 的依赖检查很明确#error后面会列出缺哪个宏照着补就行。这个其实是最友好的错误。错误三error: #20: identifier int64_t is undefinedC99 没开。勾上 C99 Mode 就好或者Misc Controls里手动加--c99。错误四L6915E: Library reports error: __use_no_semihosting was requested, but _ttywrch was referenced这是链接冲突。你开了“不使用半主机”但库里还有函数引用了半主机接口。解决办法是开 MicroLIB或者自己实现这几个桩函数void _ttywrch(int ch) { (void)ch; } void _sys_exit(int x) { (void)x; while(1){} }错误五L6406E: No space in execution regions with .ANY selector matching xxx.o(.text)Flash 不够。这时候要做的是算账Options for Target → Target下面看编译输出的 Code RO Data RW Data 各是多少。如果 Code 已经 90KB 而芯片只有 128KB那就得回头裁剪。最快的裁剪路径是换 ECDSA 证书、关 RSA、关掉 TLS 1.0/1.1、关MBEDTLS_DEBUG_C。错误六编译过了运行 HardFault 在mbedtls_ssl_setup几乎百分百是堆不够。检查启动文件的栈大小和malloc可用空间。用内存池的方案就是看池子开够没有——一个完整 TLS 客户端会话含证书大概需要 20~28KB 池空间。5. 跑通验证从算法自检到一次真实握手5.1 先证明算法层没问题很多人上来就接网络做握手一通-1之后就懵了根本分不清是算法层错了还是传输层错了。正确的顺序是自底向上验证。第一步跑 mbedTLS 自带的自检函数。开MBEDTLS_SELF_TEST宏然后int ret; ret mbedtls_aes_self_test(1); /* 参数非 0 表示打印细节 */ if (ret ! 0) { /* 算法层有问题先解决这个 */ } ret mbedtls_sha256_self_test(1); ret mbedtls_ecp_self_test(1);这些自检用的是内置标准测试向量能通过就说明算法实现本身没问题问题肯定在后面。这一步花两分钟能省后面两小时。第二步测随机数。随机数不对的表现很隐蔽——算法都对但握手就是过不去或者加密结果每次不一样。写个循环打印 32 字节反复看unsigned char buf[32]; mbedtls_ctr_drbg_random(ctr_drbg, buf, sizeof(buf));跑两次如果两次结果一样同一复位周期内说明熵源没接上或者种子是固定的。这里要注意同一个ctr_drbg上下文连续取两次结果本来就应该不一样因为 ctr_drbg 内部有计数器推进。如果一样那肯定是代码写错了比如重复初始化了同一个上下文。5.2 把收发回调接上完成一次握手算法层验证通过后接传输层。我建议第一次先用 PC 上的模拟服务端方便抓包看哪里断了。初始化顺序不能乱我列一下完整流程mbedtls_entropy_context entropy; mbedtls_ctr_drbg_context ctr_drbg; mbedtls_ssl_context ssl; mbedtls_ssl_config conf; mbedtls_x509_crt cacert; mbedtls_entropy_init(entropy); mbedtls_ctr_drbg_init(ctr_drbg); mbedtls_ssl_init(ssl); mbedtls_ssl_config_init(conf); mbedtls_x509_crt_init(cacert); /* 1. 种随机数 */ mbedtls_entropy_add_source(entropy, my_entropy_source, NULL, 32, MBEDTLS_ENTROPY_SOURCE_STRONG); mbedtls_ctr_drbg_seed(ctr_drbg, mbedtls_entropy_func, entropy, (const unsigned char *)dev_seed, 8); /* 2. 加载 CA 证书DER 格式的静态数组 */ mbedtls_x509_crt_parse(cacert, ca_der, ca_der_len); /* 3. 配置 */ mbedtls_ssl_config_defaults(conf, MBEDTLS_SSL_IS_CLIENT, MBEDTLS_SSL_TRANSPORT_STREAM, MBEDTLS_SSL_PRESET_DEFAULT); mbedtls_ssl_conf_authmode(conf, MBEDTLS_SSL_VERIFY_REQUIRED); mbedtls_ssl_conf_ca_chain(conf, cacert, NULL); mbedtls_ssl_conf_rng(conf, mbedtls_ctr_drbg_random, ctr_drbg); /* 4. 强制 TLS 1.2避免协商到老版本 */ mbedtls_ssl_conf_min_version(conf, MBEDTLS_SSL_MAJOR_VERSION_3, MBEDTLS_SSL_MINOR_VERSION_3); /* 5. 绑定 */ mbedtls_ssl_setup(ssl, conf); mbedtls_ssl_set_hostname(ssl, your-endpoint); mbedtls_ssl_set_bio(ssl, net_ctx, net_send, net_recv, NULL); /* 6. 握手 */ while ((ret mbedtls_ssl_handshake(ssl)) ! 0) { if (ret ! MBEDTLS_ERR_SSL_WANT_READ ret ! MBEDTLS_ERR_SSL_WANT_WRITE) { break; /* 真错了 */ } }这里有几个必须遵守的规矩其一MBEDTLS_SSL_VERIFY_REQUIRED这个模式一定要用。设成VERIFY_NONE就等于不验证服务端身份中间人随便插加密也就成了摆设。见过为了“先跑通”改成 NONE 然后忘了改回来直接出货的这种事故不新鲜。其二mbedtls_ssl_set_hostname必须调用。它不只是为了发 SNI更重要的是证书里的域名要和这个值比对不设的话域名校验形同虚设。其三握手返回WANT_READ/WANT_WRITE时不要重头来继续循环调就行状态机自己会记住进度。有次同事在WANT_READ之后把整个 ssl 上下文重新初始化了握手永远停在第一步。5.3 实测的资源占用和性能数据这部分是纯实测仅供参考具体数字随配置变化很大配置组合FlashRAM会话期握手耗时72MHzAES-GCM ECDHE-ECDSA P-256约 55KB约 12KB约 900msAES-GCM ECDHE-RSA RSA2048 验签约 78KB约 16KB约 2600ms上一行 TLS1.0/1.1 兼容约 86KB约 16KB同上从数据能看出来两个结论RSA 的代价主要在 CPU 时间上Flash 也多 20 多 KBECDSA 完胜所以选服务端证书类型的时候能选 ECDSA 就选 ECDSA。如果服务端只能给 RSA 证书那就接受这 2 秒多的握手时间或者用会话恢复session ticket把第二次之后的握手压到几百毫秒。会话恢复这块值得提一句。开MBEDTLS_SSL_SESSION_TICKETS握手成功后存下mbedtls_ssl_get_session下次重连时先mbedtls_ssl_set_session再握手能省掉完整的密钥交换流程。对电池供电的设备来说省这点电挺实在。6. 踩坑记录与排查速查表6.1 我遇到过的几个典型故障故障一握手一直返回-0x2700这个错误码对应证书验证失败。排查顺序是先看是不是时间不对没接 RTC 时最常见再看 CA 证书有没有加载对最后看set_hostname的值和证书里的 CN/SAN 是否匹配。我遇到过一次是证书链不完整——只放了叶子证书没放中间 CA服务端不给中间证书验证就断了。解决办法是把中间 CA 也拼进cacert里mbedtls_x509_crt_parse是支持一次解析多张的。故障二连上了握手成功但收到数据就断问题在记录层。我遇到的是MBEDTLS_SSL_IN_CONTENT_LEN调到了 2048服务端发来 3000 多字节直接超限。表现是mbedtls_ssl_read返回MBEDTLS_ERR_SSL_INVALID_RECORD或者干脆卡住。调大这个值就通了。所以调小缓冲区要在握手成功后做实际数据压测不能只看握手过不过。故障三随机数池一直报MBEDTLS_ERR_ENTROPY_NO_SOURCES_DEFINED熵源没添加成功。mbedtls_entropy_add_source的第四个参数是阈值表示“至少收集多少字节才认为熵够”。这个值设得太大比如 256而你的熵源每次只能给 4 字节就会一直凑不够。设成 32 或者干脆设成 1 加WEAK标记都行按你的熵源质量定。故障四编译通过链接报一堆Undefined symbol mbedtls_xxx文件加少了。这种错误的特点是符号名直接告诉你是哪个模块比如mbedtls_ecp_mul没定义就是缺ecp.c。但有时候会间接报错比如缺ecp_curves.c时报的是曲线参数符号未定义。看符号名去猜模块比翻文档快。故障五跑一段时间后内存溢出崩溃这是碎片问题。mbedTLS 每次会话会malloc/free若干次长时间反复连接断开标准库堆会碎。改用内存池方案或者做成“一次初始化长期复用”的模式——上下文不销毁只重连。后者更实用我现在的工程都是这个模式。6.2 排查速查表现象最可能原因快速验证方法编译报缺头文件Include Paths 层级不对检查是否加了include和include/mbedtls两条编译报 C99 语法错没勾 C99打开 C99 Mode 或加--c99链接报半主机错误未开 MicroLIB 且缺桩函数开 MicroLIB或补_ttywrch运行 HardFault 在 setup堆或池子不够打印剩余堆扩到 24KB 以上握手返回-0x2700证书验证失败查时间、CA、hostname 三项握手卡住不动recv 返回值语义错非阻塞应返回WANT_READ握手成功但读数据错缓冲区太小看IN_CONTENT_LEN是否小于服务端分片随机数报无熵源熵阈值设太大看add_source第 4 个参数长时间跑崩溃堆碎片换内存池或复用上下文Flash 超配置太肥砍 RSA、砍 TLS1.0、砍调试6.3 体积和稳定性的几个实招先说体积。除了前面提到的裁文件还有几个宏能明显瘦身MBEDTLS_AES_ROM_TABLES打开把 AES 的 S 盒和乘法表放到 Flash 常量区省 512 字节 RAM。MBEDTLS_ECP_FIXED_POINT_OPTIM关了能省一点代码但会慢。MBEDTLS_DEBUG_C只在调试期开正式版一定关——这东西带着一堆字符串能占好几 KB。再说稳定性。我总结的做法是**“三不”**不在中断里调 mbedTLS、不在握手期间做长耗时操作、不让多个任务同时用一个 ssl 上下文。裸机上没有锁一旦两个地方同时往 ssl 上下文里写状态机就乱了。还有一个容易被忽略的点时钟精度。mbedTLS 有些地方依赖超时判断如果你的net_recv里用的是粗粒度延时比如HAL_Delay握手时可能误判超时。我一般用自己的毫秒计数器net_recv里按实际耗时判断超过 10 秒才返回超时。另外提醒一句证书不要硬编码成 PEM 字符串放在代码里。PEM 是 Base64 编码的比 DER 大三分之一还多占 RAM 解析。用工具转成 DER 后用数组导出体积小、解析快。如果一定要用 PEM记得开MBEDTLS_PEM_PARSE_C。我个人在这套组合上折腾了很多轮最深的体会是顺序比技巧重要。先定版本再裁文件然后配宏接着编过最后自检、握手、压测一步都别跳。每跳一步后面排查的难度都是翻倍的。另外一定要在工程里留一份“能跑通的最小配置”改坏的时候退回去比一个一个宏去猜快得多。mbedTLS 这库设计得其实挺规矩报错信息也够清楚只要不一次性改太多东西出问题基本都是能定位的。
国庆期间自制 AI 代码工具：使用体验分享)
