1. 从一次签名失败说起:为什么要自己裁 mbedtls
板子上要加一段 RSA 签名验签,代码开发工具链里直接塞完整 mbedtls,编译能过,链接却报了一屏 undefined reference;换了个配置再编,签名接口又返回 FEATURE_UNAVAILABLE。最后查下来不是算法写错,而是配置宏没开全、三个静态库的链接顺序反了。这类问题在资源受限的嵌入式环境里很常见:完整库太大,裁剪后的库又缺模块,X.509 证书解析和 RSA 签名验签各自依赖一串宏,漏一个就在运行期翻车。这篇按配置、编译、链接、调用的顺序,把 mbedtls 裁到只剩签名验签和证书解析所需的最小集合,参数怎么设、哪一步容易错,都摊开写。适合已经会写 C、要在实际工程里落地签名校验的人。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 代码开发工具裁剪:mbedtls 配置宏与最小库集合
2.1 先定分层:PK 抽象层还是直沉 RSA 层
mbedtls 里同一件事有两套入口。一套是 mbedtls_pk_* 这组,密钥上下文用 mbedtls_pk_context 表示,里面可以装 RSA 也可以装 EC,签名验签走 mbedtls_pk_sign / mbedtls_pk_verify;另一套是 mbedtls_rsa_*,直接操作 mbedtls_rsa_context,能精确控制 padding 细节、盐长度、MGF1 哈希这些参数。
我这份工程的主路径走 PK 层,特殊参数才下沉到 RSA 层。原因很实际:X.509 证书解析完之后,mbedtls_x509_crt 结构体里内嵌的就是一个 mbedtls_pk_context,也就是 crt.pk,验签时直接把 &crt.pk 传进去就完事。如果一开始就把代码写死到 RSA 层,后面证书里换成了 EC 公钥,取 mbedtls_pk_rsa(&crt.pk) 这一步就会拿到空指针,错误信息还会因为空指针解引用变得莫名其妙。
先看一个写死 RSA 层的反面写法:
c复制/* 不推荐:默认证书里一定是 RSA 公钥 */
mbedtls_rsa_context *rsa = mbedtls_pk_rsa(&crt.pk);
if (rsa == NULL) {
/* 证书换 EC 后这里会进来,但调用栈已经很难看了 */
return -1;
}
ret = mbedtls_rsa_pkcs1_verify(rsa, MBEDTLS_MD_SHA256,
hash_len, hash, sig);
这段代码在纯 RSA 证书上能跑,但把密钥类型和验签路径绑死了。mbedtls_pk_rsa 只在 crt.pk 实际装的是 RSA 密钥时返回有效指针,换成 EC 就返回空。正确的骨架是让 PK 层自己分派:
c复制/* 推荐:验签入口只认 PK 上下文,密钥类型由证书决定 */
ret = mbedtls_pk_verify(&crt.pk, MBEDTLS_MD_SHA256,
hash, 0, sig, sig_len);
参数里 MBEDTLS_MD_SHA256 是摘要算法,hash 是提前算好的摘要缓冲区,hash_len 传 0 表示由库按摘要算法自己取长度。这样证书里是 RSA 还是 EC,调用方不用改。只有需要调 PSS 盐长度、MGF1 哈希这类 PK 层不暴露的参数时,我才用 mbedtls_pk_rsa 取出 RSA 上下文再下沉,而且取完必须判空。
分层定下来之后,裁剪范围就清楚了:PK 层、RSA 算法、ASN.1 解析、摘要、随机源、X.509 证书解析,这几块一个都不能少。
2.2 配置头文件里必须点亮的宏与漏开的后果
配置头文件里把下面这些宏打开。我这份工程用的是 mbedtls_config.h,老分支可能叫 config.h,名字不重要,重要的是宏要成组出现,不能只开一半。
c复制/* 最小签名验签集合:少一个都可能在链接或运行期翻车 */
#define MBEDTLS_PK_C
#define MBEDTLS_PK_PARSE_C
#define MBEDTLS_RSA_C
#define MBEDTLS_PKCS1_V15
#define MBEDTLS_PKCS1_V21
#define MBEDTLS_MD_C
#define MBEDTLS_SHA256_C
#define MBEDTLS_BIGNUM_C
#define MBEDTLS_OID_C
#define MBEDTLS_ASN1_PARSE_C
#define MBEDTLS_ASN1_WRITE_C
#define MBEDTLS_ENTROPY_C
#define MBEDTLS_CTR_DRBG_C
#define MBEDTLS_AES_C
/* 证书解析单独一组,和签名验签不是同一个开关 */
#define MBEDTLS_X509_CRT_PARSE_C
#define MBEDTLS_X509_USE_C
#define MBEDTLS_BASE64_C
#define MBEDTLS_PEM_PARSE_C
#define MBEDTLS_ERROR_C
第一组是签名验签的底座。MBEDTLS_PK_C 是 PK 抽象层本体,不开连 mbedtls_pk_context 类型都拿不到;MBEDTLS_PK_PARSE_C 负责解析 PEM/DER 私钥公钥,不开的话 mbedtls_pk_parse_key 直接未声明;MBEDTLS_RSA_C 让 PK 层能装 RSA 密钥。MBEDTLS_PKCS1_V15 和 MBEDTLS_PKCS1_V21 分别对应 v1.5 和 PSS 填充,注意 PSS 那个是 V21,不是 V2_1,拼错等于没开,签名接口会返回 FEATURE_UNAVAILABLE。
MBEDTLS_BIGNUM_C 是 RSA 运算的底座,缺它必挂;MBEDTLS_OID_C 和 MBEDTLS_ASN1_PARSE_C 负责证书里的算法标识与结构解析;MBEDTLS_ASN1_WRITE_C 用于拼接 DigestInfo,v1.5 签名少了它也会失败。随机源那组 MBEDTLS_ENTROPY_C、MBEDTLS_CTR_DRBG_C、MBEDTLS_AES_C 是 PSS 签名和加密私钥解析的前置条件。
第二组是证书解析。MBEDTLS_X509_CRT_PARSE_C 和 MBEDTLS_X509_USE_C 不开,就无法从证书取公钥;MBEDTLS_BASE64_C 和 MBEDTLS_PEM_PARSE_C 不开,读 PEM 文件会返回 NO_HEADER_FOOTER。MBEDTLS_ERROR_C 虽然跟功能无关,但我建议一直开着,排查阶段一个有意义的错误字符串,比对着 -0x4380 查表快得多。
最容易漏的是 MBEDTLS_CTR_DRBG_C 依赖 MBEDTLS_AES_C 这一条。DRBG 默认拿 AES-256 当分组密码,AES_C 一关,mbedtls_ctr_drbg_seed 直接返回失败,而失败位置在初始化阶段,离真正的签名逻辑隔了二十行,看堆栈时很容易误判成随机源硬件的问题。
2.3 从完整库到最小集合:关掉测试和示例程序
宏配好之后,编库时不要把测试套件和示例程序一起编。mbedtls 自带的测试程序编起来很慢,做裁剪验证时完全不需要。
bash复制# 只产库文件,测试和示例程序全关,能省掉大半编译时间
cmake -S mbedtls -B build-mbedtls \
-DCMAKE_BUILD_TYPE=Release \
-DENABLE_TESTING=Off \
-DENABLE_PROGRAMS=Off
cmake --build build-mbedtls -j"$(nproc)"
-DCMAKE_BUILD_TYPE=Release 开优化,嵌入式产物一般都用 Release 验证尺寸;-DENABLE_TESTING=Off 和 -DENABLE_PROGRAMS=Off 分别关掉测试与示例,这两个开关是编译时间的大头。-j"$(nproc)" 按 CPU 核数并行编译,Windows 下没有 nproc,换成实际核数或者直接 -j。
编完之后产物在 build-mbedtls/library/ 下,三个静态库:libmbedtls.a、libmbedx509.a、libmbedcrypto.a。这三个库之间是有依赖方向的:TLS 层依赖 X.509,X.509 依赖 crypto。裁剪时只用到后两个,但链接顺序仍然按这个依赖方向摆,下一章会具体写。
3. 代码开发工具链接:三个静态库的依赖顺序与 Makefile
3.1 三个静态库的依赖方向与链接顺序
链接时被依赖的库必须写在后面,顺序写反了就是一堆 undefined reference。这不是玄学,静态链接器从左到右扫描,先看到的库如果引用了后面库里的符号,扫描到后面时还能补上;反过来,后面的库引用了前面已经扫过的库,链接器不会回头再找。
make复制MBEDTLS_DIR := ./mbedtls
CFLAGS := -O2 -Wall -I$(MBEDTLS_DIR)/include
LDFLAGS := -L$(MBEDTLS_DIR)/build-mbedtls/library
# 顺序不能调:依赖方在前,被依赖方在后
LDLIBS := -lmbedtls -lmbedx509 -lmbedcrypto
sign_demo: sign_demo.c
$(CC) $(CFLAGS) $< -o $@ $(LDFLAGS) $(LDLIBS)
verify_demo: verify_demo.c
$(CC) $(CFLAGS) $< -o $@ $(LDFLAGS) $(LDLIBS)
LDLIBS 里 -lmbedtls 在最前,-lmbedx509 居中,-lmbedcrypto 在最后,对应 TLS → X.509 → crypto 的依赖方向。只做签名验签和证书解析时,-lmbedtls 其实可以省掉,但留着不会错,而且后面要加 TLS 通信时不用再改链接行。CFLAGS 里的 -Wall 建议保留,裁剪阶段很多宏缺失会先以隐式声明警告的形式出现。
如果链接报 undefined reference to mbedtls_pk_verify,先看 LDLIBS 顺序,再看是不是把 -lmbedcrypto 漏了。PK 层和 RSA 运算的符号大量落在 crypto 库里,只链 libmbedtls.a 是不够的。
3.2 Makefile 里 include 与 library 路径的边界
CFLAGS 只加了 include 路径,没有加 library 路径。有些老工程会把 library/ 也加进去,然后在代码里 #include "rsa.h",这样写能过编译,但等于绕开了公开头文件,后续升级分支时必然翻车。
公开 API 一律走 mbedtls/xxx.h:
c复制/* 正确:公开头文件路径 */
#include "mbedtls/pk.h"
#include "mbedtls/x509_crt.h"
#include "mbedtls/error.h"
/* 不推荐:直接把库内部头文件目录加进 include 路径 */
/* #include "rsa.h" */
mbedtls/pk.h、mbedtls/x509_crt.h 这些是稳定接口,库内部结构变化时它们会保持兼容;直接包含 rsa.h 这类内部头文件,等于把代码绑死在某一个分支的目录结构上。裁剪阶段为了省事这么写,后面换版本时改起来很痛苦。
另外,头文件和库必须来自同一份源码。常见翻车是改了配置头文件、只重新编了库,应用侧用的还是旧头文件,结果结构体大小对不上,运行到 mbedtls_pk_init 就崩。改宏之后,库和依赖它的应用一起重编,不要只编一半。
3.3 交叉编译和裸机堆内存的两个前置条件
交叉编译时把 CC 换成工具链前缀,其余不变。静态库没有运行时依赖,真正要留意的是板子上有没有 malloc。mbedtls 的 RSA 运算会在堆上分配大数缓冲区,纯裸机环境需要先确认堆区够大,或者打开 MBEDTLS_MEMORY_BUFFER_ALLOC_C 换成静态内存池。
c复制/* 裸机没有 malloc 时,用静态内存池接住 mbedtls 的分配 */
#define MBEDTLS_MEMORY_BUFFER_ALLOC_C
#define MBEDTLS_PLATFORM_MEMORY
打开这两个宏之后,还需要在初始化阶段把一块静态缓冲区交给 mbedtls_memory_buffer_alloc_init。这块缓冲区的大小要按最大 RSA 密钥长度和并发上下文数量估,估小了会在签名过程中返回 ALLOC_FAILED,而且报错位置在运算深处,不如启动时直接打印剩余空间来得直观。
如果板子有 RTOS 和堆管理,也可以直接用系统堆,但要确认堆碎片不会在长时间运行后把签名拖垮。我一般会在启动时做一次签名验签自测,把峰值堆用量打出来,再决定是扩堆还是换静态池。
4. 签名验签落地:PK 层调用、PSS/v1.5 与证书取公钥
4.1 密钥加载:PEM/DER 与 PK 上下文
密钥加载走 mbedtls_pk_parse_key,PEM 和 DER 都吃,带密码保护的私钥把密码传进去。下面这段是签名侧的最小骨架,读文件的动作留在调用方,key_buf 可以来自文件系统,也可以直接来自 flash 里的常量区。
c复制#include "mbedtls/pk.h"
#include "mbedtls/sha256.h"
static int sign_with_pk(const unsigned char *msg, size_t msg_len,
const unsigned char *key_buf, size_t key_len,
unsigned char *sig, size_t *sig_len)
{
mbedtls_pk_context pk;
unsigned char hash[32];
int ret;
mbedtls_pk_init(&pk);
/* 第四个参数是密码,无密码传 NULL;第五个参数是密码长度 */
ret = mbedtls_pk_parse_key(&pk, key_buf, key_len, NULL, 0);
if (ret != 0) {
goto cleanup;
}
ret = mbedtls_sha256(msg, msg_len, hash, 0);
if (ret != 0) {
goto cleanup;
}
/* 主路径走 PK 层,证书换 EC 时这段不用重写 */
ret = mbedtls_pk_sign(&pk, MBEDTLS_MD_SHA256, hash, 0,
sig, *sig_len, sig_len, NULL, NULL);
cleanup:
mbedtls_pk_free(&pk);
return ret;
}
mbedtls_pk_parse_key 的第二个和第三个参数是密钥缓冲区及长度,第四个和第五个是密码及长度。无密码私钥传 NULL, 0 即可。mbedtls_sha256 的最后一个参数传 0 表示输出标准 SHA-256,不传 is224。mbedtls_pk_sign 里 MBEDTLS_MD_SHA256 告诉 PK 层用哪种摘要做 DigestInfo 拼接,hash 是摘要缓冲区,后面的 0 是摘要长度偏移,由库按算法自己算。
mbedtls_pk_sign 的最后两个参数是随机源回调和上下文。v1.5 签名可以传 NULL, NULL,PSS 签名需要随机源,必须传有效的 f_rng 和 p_rng。如果这里传空又开了 PSS,运行时会返回参数错误,而不是编译错误。
4.2 签名路径:v1.5 与 PSS 该在哪一层选
v1.5 和 PSS 是两种填充方式,宏分别是 MBEDTLS_PKCS1_V15 和 MBEDTLS_PKCS1_V21。v1.5 兼容老系统多,PSS 的盐长度随机、安全性更好。PK 层签名接口不给你细调盐长度和 MGF1 哈希,需要下沉到 mbedtls_rsa_* 才能改这些参数。
选择上我一般这样定:对外对接的老系统只认 v1.5,那就走 PK 层默认路径,代码最简单;新系统要求 PSS,且对盐长度没有特殊要求,也走 PK 层,把随机源传进去;只有协议明确规定了盐长度或 MGF1 哈希时,才用 mbedtls_pk_rsa 取出 RSA 上下文下沉。下沉之后要判空,并且把 mbedtls_rsa_set_padding 这类调用集中在一个函数里,不要散落在业务代码中。
验签侧比签名侧简单,因为验签不需要随机源。PK 层验签只认公钥和摘要,v1.5 与 PSS 的分派由密钥类型和填充标志决定。下面这段是证书验签的骨架:
c复制#include "mbedtls/x509_crt.h"
#include "mbedtls/pk.h"
static int verify_with_cert(const unsigned char *hash, size_t hash_len,
const unsigned char *sig, size_t sig_len,
const char *cert_path)
{
mbedtls_x509_crt crt;
int ret;
mbedtls_x509_crt_init(&crt);
/* 解析 PEM 证书;DER 用 mbedtls_x509_crt_parse 直接喂 buffer */
ret = mbedtls_x509_crt_parse_file(&crt, cert_path);
if (ret != 0) {
goto cleanup;
}
/* crt.pk 就是 mbedtls_pk_context,不要先 mbedtls_pk_rsa 写死 */
ret = mbedtls_pk_verify(&crt.pk, MBEDTLS_MD_SHA256,
hash, 0, sig, sig_len);
cleanup:
mbedtls_x509_crt_free(&crt);
return ret;
}
mbedtls_x509_crt_parse_file 是读文件的便捷入口,等价于把文件内容读进 buffer 再调 mbedtls_x509_crt_parse。crt.pk 的类型就是 mbedtls_pk_context,直接传给 mbedtls_pk_verify,由库根据证书里的公钥类型分派 RSA 或 EC。hash 是待验签数据的摘要,hash_len 传 0 让库按 MBEDTLS_MD_SHA256 取长度。
4.3 证书解析:从 crt.pk 取公钥做验签
证书解析依赖 MBEDTLS_X509_CRT_PARSE_C、MBEDTLS_X509_USE_C、MBEDTLS_BASE64_C、MBEDTLS_PEM_PARSE_C 这一组宏。少开 BASE64_C 或 PEM_PARSE_C,mbedtls_x509_crt_parse_file 会返回 NO_HEADER_FOOTER,看起来像文件格式错误,实际是解码模块没编进去。
证书链的校验和签名验签是两件事。mbedtls_x509_crt_verify 做的是证书链、有效期、用途这些校验,签名验签只关心公钥和摘要。实际工程里我一般先做证书链校验,确认证书可信,再用 crt.pk 做业务数据的验签。两步分开写,报错也好定位:链校验失败看 verify_flags,签名验签失败看 mbedtls_pk_verify 的返回值。
时间校验在嵌入式环境里容易翻车。板子没有 RTC 或者时间没同步时,证书有效期校验会失败,但错误码可能和签名失败混在一起。我的做法是把证书链校验和业务验签的返回值分别打印,时间没就绪时先跳过有效期校验,只做公钥验签,等时间同步后再补一次完整校验。
5. 踩坑排查:五个把签名验签卡住的细节
5.1 编译报 mbedtls_pk_context 未知、mbedtls_pk_parse_key 未声明
现象是编译到 mbedtls_pk_context pk; 这一行报类型未知,或者调用 mbedtls_pk_parse_key 时提示隐式声明。原因基本是 MBEDTLS_PK_C 或 MBEDTLS_PK_PARSE_C 没打开,头文件里对应的类型和函数声明被条件编译掉了。
解决方法是把这两个宏补进配置头文件,然后重新编库。只改应用侧的头文件没用,因为库里的符号也没编进去,链接阶段还会再报一次。改完宏之后,库和应用一起重编,别只编一半。
5.2 签名接口返回 FEATURE_UNAVAILABLE
现象是 mbedtls_pk_sign 返回 FEATURE_UNAVAILABLE,代码逻辑看起来没问题。原因通常是 MBEDTLS_PKCS1_V15 或 MBEDTLS_PKCS1_V21 没开,或者 PSS 的宏拼成了 MBEDTLS_PKCS1_V2_1。宏名拼错不会报编译错误,只会让对应分支静默失效。
解决方法是逐个核对宏名,v1.5 是 MBEDTLS_PKCS1_V15,PSS 是 MBEDTLS_PKCS1_V21。如果走 PSS,还要确认随机源回调和上下文传了有效值,传空也会在运行期报参数错误。
5.3 mbedtls_ctr_drbg_seed 初始化失败,报错位置离签名很远
现象是程序启动时 mbedtls_ctr_drbg_seed 返回失败,堆栈停在随机数初始化,看起来和签名验签无关。原因是 MBEDTLS_CTR_DRBG_C 打开了,但底座的 MBEDTLS_AES_C 没开。DRBG 默认拿 AES-256 当分组密码,AES 一关,种子函数直接失败。
解决方法是将 MBEDTLS_ENTROPY_C、MBEDTLS_CTR_DRBG_C、MBEDTLS_AES_C 三个宏一起打开。只开 DRBG 不开 AES 是最常见的组合错误,因为报错位置在初始化阶段,很容易误判成硬件随机源的问题。
5.4 链接报一屏 undefined reference
现象是编译通过,链接时大量 undefined reference to mbedtls_pk_verify、mbedtls_rsa_pkcs1_verify 之类。原因有两个:三个静态库的顺序反了,或者漏链了 libmbedcrypto.a。静态链接器从左到右扫描,被依赖的库必须写在后面。
解决方法是把 LDLIBS 固定成 -lmbedtls -lmbedx509 -lmbedcrypto,顺序不要调。如果只做签名验签和证书解析,-lmbedtls 可以省,但 -lmbedx509 和 -lmbedcrypto 不能少。改完顺序还报错,就检查是不是库根本没编出来,去 build-mbedtls/library/ 下确认三个 .a 文件存在。
5.5 读 PEM 返回 NO_HEADER_FOOTER,或证书换 EC 后取 RSA 上下文为空
前者的现象是 mbedtls_x509_crt_parse_file 返回 NO_HEADER_FOOTER,原因通常是 MBEDTLS_BASE64_C 或 MBEDTLS_PEM_PARSE_C 没开,也可能是文件本身是 DER 格式却按 PEM 读。解决方法是补齐这两个宏,并确认文件头有 -----BEGIN CERTIFICATE-----。后者的现象是证书换成 EC 公钥后,mbedtls_pk_rsa(&crt.pk) 返回空指针,原因是代码写死在 RSA 层。解决方法是验签主路径改回 mbedtls_pk_verify(&crt.pk, ...),让 PK 层按证书里的密钥类型分派,只有确实要调 PSS 盐长度时才下沉,且下沉前必须判空。
6. 进阶验证:用错误码和最小用例把裁剪结果钉死
裁剪完的库最怕的是“编译过了、运行时才缺功能”。我的做法是先加一个统一的错误打印函数,把每个 mbedtls 返回值都转成可读字符串,再接一个最小签名验签用例做启动自检。
c复制#include "mbedtls/error.h"
#include <stdio.h>
static void print_mbedtls_error(const char *tag, int ret)
{
char buf[128];
if (ret == 0) {
return;
}
/* MBEDTLS_ERROR_C 打开后,错误码才能转成有意义的字符串 */
mbedtls_strerror(ret, buf, sizeof(buf));
printf("%s: -0x%04X %s\n", tag, (unsigned int)-ret, buf);
}
这个函数的关键在于 MBEDTLS_ERROR_C 必须打开,否则 mbedtls_strerror 只回一句 ERROR,排查时等于没有信息。-0x%04X 把返回值按负数十六进制打印,和文档里的错误码对得上,比如 -0x4380 这种,查起来比十进制快。
最小用例我一般放在启动阶段跑一次:用固定的私钥签一段固定字符串,再用对应证书验签,两步都通过才把业务标志置位。这样配置宏漏开、链接顺序错误、随机源缺失这几类问题会在启动时暴露,而不是等到第一次业务请求才翻车。
还有一条习惯:每次改配置头文件,都把 build-mbedtls/library/ 下三个库的修改时间打出来,确认库真的重编了。有次我只改了应用侧的头文件,库还是旧的,结构体布局对不上,运行到 mbedtls_pk_init 直接崩,查了半天才发现是增量编译没触发库重建。从那以后我每次改宏都强制走一遍完整重编,再跑最小签名验签用例,确认通过才继续写业务。希望帮到你。
