1. 项目概述：为什么嵌入式开发者需要关注BearSSL？

如果你在嵌入式领域摸爬滚打过几年，尤其是在资源受限的MCU上折腾过TLS/SSL，那你大概率经历过这样的痛苦：想用OpenSSL，发现它动辄几兆的库体积，RAM占用也吃不消；想用mbedTLS，感觉它的API设计有点绕，配置起来选项繁多；自己手搓一个？光是理解那些密码学协议和国密标准就够喝一壶了，更别提实现和维护的安全风险。

今天要聊的BearSSL，就是在这种背景下，一个被严重低估的“小而美”的解决方案。它不是要取代谁，而是在一个非常精准的赛道上做到了极致：为那些对代码体积、内存占用和可移植性有严苛要求的嵌入式系统，提供一个足够安全、足够精简、足够透明的TLS实现。我第一次接触它是在一个STM32F103（俗称“蓝屏”）的项目上，当时Flash只有128KB，RAM只有20KB，却要实现一个安全的MQTT over TLS连接。在尝试了各种“轻量级”库都宣告失败后，BearSSL成了最后的救命稻草，并且完美地完成了任务。

简单来说，BearSSL是一个用ANSI C编写的TLS/SSL库，它的核心设计哲学是**“可审计性”和“最小化”**。这意味着，它的代码结构清晰，没有复杂的抽象层，你可以清楚地知道每一行代码在做什么；同时，它通过模块化设计，允许你只编译你需要的密码套件和功能，从而将最终的二进制体积压缩到极致。对于物联网设备、工控模块、穿戴设备等场景，这种特性无疑是极具吸引力的。

2. BearSSL的核心设计哲学与架构拆解

2.1 “可审计性”优先：代码即文档

与许多追求功能大而全的库不同，BearSSL将“可审计性”放在首位。创始人Thomas Pornin本身就是一位知名的密码学家和安全研究员，他坚信一个安全库首先得让人能看懂、能验证。因此，BearSSL的代码风格极其“朴素”：

• 极少的宏和抽象：你很少会看到层层封装的函数指针和复杂的对象继承。加解密操作、哈希函数、大数运算，大多以清晰的函数调用形式呈现。这对于嵌入式开发者来说是个福音，因为调试时你能轻松地单步跟进，知道问题出在哪一层。
• 完整的算法实现：BearSSL没有依赖外部的密码学库（如OpenSSL的libcrypto）。从AES、SHA到RSA、ECC，所有算法都是自己实现的。这样做的好处是，整个库的边界非常清晰，没有“黑盒”，便于进行安全审计和代码审查。我在做产品安全认证时，这一点帮了大忙，评审方可以清晰地追溯每一个密码学操作的源头。
• 详尽的注释：代码中的注释不仅解释了“做什么”，还经常解释“为什么这么做”，甚至包括一些算法选择的权衡和已知的侧信道攻击防范措施。这几乎相当于内置了一本密码学实践指南。

2.2 模块化与“最小化”：按需裁剪的艺术

这是BearSSL最吸引嵌入式开发者的特性。库被设计成一系列独立的、可选的模块。在编译时，你可以通过定义宏来精确控制包含哪些功能。

核心模块包括：

1. 密码套件（Cipher Suites）：这是大头。TLS握手后使用的加密组合，例如TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256。BearSSL允许你只启用你项目需要的那么一两个套件。如果你的设备只连某个特定的云平台，而该平台只支持ECDHE-RSA-AES128-GCM-SHA256，那你就可以只编译这一个套件，其他几十个套件的代码都不会进入你的二进制文件。
2. 签名算法：RSA、ECDSA。同样可以只选需要的密钥长度和曲线（如只支持P-256曲线）。
3. 哈希函数：SHA-1、SHA-256、SHA-384等。虽然SHA-1已不推荐用于签名，但某些旧协议可能还需要。
4. TLS协议特性：是否支持会话恢复（Session Resumption）、是否支持ALPN（应用层协议协商，用于HTTP/2）、是否支持SNI（服务器名称指示）等。

实操心得：如何做裁剪决策？我的经验是，先明确你的通信对端（服务器）支持哪些密码套件。用openssl s_client或者在线工具测试一下目标服务器。然后，在BearSSL的编译配置中（通常是修改config.h或通过编译器宏），只启用那些匹配的、且安全等级足够的套件。一个常见的、安全的精简配置是：启用ECDHE密钥交换、RSA或ECDSA签名、AES-128-GCM加密和SHA-256哈希。这样可以覆盖绝大多数现代云服务。

注意：过度裁剪有风险。如果你只编译了一个非常特定的密码套件，而未来服务器端升级了加密策略，你的设备可能就无法连接了。因此，对于需要长期部署、有OTA升级能力的设备，建议保留2-3个不同算法家族（如一个基于RSA，一个基于ECDSA）的备选套件。

2.3 与众不同的API设计：面向连接，而非面向配置

如果你熟悉OpenSSL或mbedTLS的“上下文（Context）”配置模式，BearSSL的API可能会让你觉得有点“返璞归真”。它不鼓励你创建一个复杂的配置对象，然后往里面填各种参数。相反，它的API更接近于“为当前这个连接，按需提供所需的数据”。

核心数据结构是br_ssl_client_context和br_ssl_server_context。初始化一个客户端连接，你需要：

1. 初始化上下文结构体。
2. 配置一个“引擎”（Engine），它包含了所有算法实现的函数指针。通常使用库提供的默认全功能引擎br_ssl_client_init_full，或者使用你自己裁剪后生成的引擎。
3. 重置连接，并指定目标主机名和端口。

在这个过程中，你没有单独去配置“支持哪些密码套件”、“用哪个随机数生成器”。这些要么在引擎里定死了（编译时决定），要么由库内部以更安全、更简洁的方式处理。

这种设计的好处是：API调用链非常短，状态清晰，不容易出现配置遗漏或冲突。带来的挑战是：如果你需要动态地改变某些行为（比如在运行时切换证书），可能不如其他库那么灵活。但对于绝大多数嵌入式场景，连接参数在设备生命周期内是固定的，这种简单性反而是优势。

3. 实战：从零开始，在嵌入式平台上集成BearSSL客户端

光说不练假把式。我们以一个典型的场景为例：在一个基于FreeRTOS和LwIP的STM32 MCU上，实现一个HTTPS客户端，去获取某个API的JSON数据。

3.1 环境准备与库的获取裁剪

首先，从官方Git仓库（bearssl.org）下载源码。BearSSL的源码结构非常干净，就是一堆.c和.h文件，没有复杂的构建系统。你可以直接把这些文件拖进你的IDE工程里。

关键一步：裁剪配置。我们不使用现成的config.h，而是自己定义编译宏。在你的IDE或Makefile的全局编译选项中，添加宏定义。以下是一个针对现代Web服务器的安全最小配置示例：

// 在你的项目预编译宏中定义 BR_DO_BUILD BR_USE_UNIX_TIME=1 // 如果你有系统时间源 BR_USE_URANDOM=1 // 如果你有熵源（如硬件RNG） // 选择算法和套件（示例，根据你的服务器调整） BR_SSL_CLIENT_ONLY=1 // 我们只做客户端 BR_USE_AES_SMALL=1 // 使用节省空间的AES实现（稍慢） BR_CTGRY_AES_SMALL=1 BR_CTGRY_SHA256=1 BR_CTGRY_MD5SHA1=1 // 为了TLS 1.0/1.1兼容性，有时需要 BR_CTGRY_ECC=1 BR_CTGRY_RSA=1 // 启用具体的密码套件 BR_ENABLE_CIPHERSUITE_TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256=1 BR_ENABLE_CIPHERSUITE_TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256=1 // 可以再启用一个CBC模式的作为后备（如果服务器不支持GCM） BR_ENABLE_CIPHERSUITE_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256=1 // 启用所需的曲线和RSA密钥长度 BR_MAX_EC_SIZE=528 // 支持到P-521曲线 BR_MAX_RSA_SIZE=4096 // 支持4096位RSA密钥

定义好这些宏后，编译工程，你会发现最终链接进来的BearSSL代码体积可能只有20-40KB（Flash），RAM占用在初始化后大约需要2-5KB的上下文空间，外加收发数据缓冲区。

3.2 连接建立与握手过程详解

BearSSL的I/O模型是非阻塞、显式缓冲的。这意味着你需要自己管理网络数据的收发，并告诉库“现在有数据可读”或“现在可以发送数据”。

核心步骤拆解：

1. 初始化与引擎安装：

   #include “bearssl.h” static br_ssl_client_context ssl_ctx; // SSL上下文 static br_x509_minimal_context x509_ctx; // 用于证书验证的上下文 static unsigned char io_buf[BR_SSL_BUFSIZE_BIDI]; // 双向I/O缓冲区，大小可调（如1600字节） void ssl_client_init(const char *server_name) { // 1. 初始化X509验证引擎（精简模式，只做基本验证） br_x509_minimal_init(&x509_ctx, &br_sha256_vtable, NULL, 0); // 设置信任锚（Trust Anchor）。这是关键！你需要把服务器CA证书的DER格式内容放进来。 // 这里假设你有一个硬编码的CA证书数组 `my_trust_anchor_der` br_x509_minimal_set_trust_anchors(&x509_ctx, &my_trust_anchor_der, 1); // 2. 初始化SSL客户端上下文 // 使用“全功能”客户端引擎（但已经被我们的编译宏裁剪过了） br_ssl_client_init_full(&ssl_ctx, &x509_ctx, server_name, 0); // 3. 重置连接状态，绑定I/O缓冲区 br_ssl_engine_set_buffer(&ssl_ctx.eng, io_buf, sizeof(io_buf), 1); // 1表示双向 }

   关键点解析：br_ssl_client_init_full这个函数名有点误导，它并不是指“全功能”，而是指使用库内建的、你已通过宏启用的算法列表来构建引擎。server_name参数用于SNI扩展，必须填写，否则可能无法连接某些云服务（如AWS IoT Core）。

2. 实现I/O适配层：这是将BearSSL与你的网络栈（这里是LwIP）连接起来的关键。你需要实现两个核心动作：send和recv，但要以BearSSL的方式调用。

   // 假设我们有一个已连接的TCP socket: `net_conn` int ssl_io_poll(void) { br_ssl_engine_state *eng = &ssl_ctx.eng; int last_state = BR_SSL_CLOSED; while (1) { int state = br_ssl_engine_current_state(eng); if (state == BR_SSL_CLOSED) { return -1; // 连接关闭或出错 } if (state == BR_SSL_SENDAPP || state == BR_SSL_SENDREC) { // 引擎有数据要发送（可能是握手消息，也可能是应用数据） unsigned char *buf; size_t len; buf = br_ssl_engine_sendrec_buf(eng, &len); // 获取待发送数据指针 if (len > 0) { int sent = lwip_write(net_conn, buf, len); // 调用LwIP发送 if (sent > 0) { br_ssl_engine_sendrec_ack(eng, sent); // 告知引擎已发送成功 } else if (errno != EAGAIN && errno != EWOULDBLOCK) { return -1; // 发送失败 } } } if (state == BR_SSL_RECVAPP || state == BR_SSL_RECVREC) { // 引擎可以接收数据（从网络读数据喂给引擎） unsigned char *buf; size_t len; buf = br_ssl_engine_recvrec_buf(eng, &len); // 获取接收缓冲区指针 if (len > 0) { int received = lwip_read(net_conn, buf, len); // 调用LwIP读取 if (received > 0) { br_ssl_engine_recvrec_ack(eng, received); // 告知引擎收到数据 } else if (received == 0) { return -1; // 连接被对端关闭 } else if (errno != EAGAIN && errno != EWOULDBLOCK) { return -1; // 读取失败 } } } // 关键：状态可能因刚才的I/O操作而改变，如果状态没变且没有进展，就退出循环，避免忙等。 if (state == br_ssl_engine_current_state(eng) && state != last_state) { last_state = state; continue; } // 如果引擎状态变为 BR_SSL_APPLICATION，说明握手完成！ if (br_ssl_engine_current_state(eng) == BR_SSL_APPLICATION) { return 0; // 成功 } // 否则，可能是暂时没有网络数据，退出循环，等下次socket可读/可写事件再来 break; } return 1; // 进行中 }

   这个ssl_io_poll函数是你的主循环。在建立TCP连接后，你需要在一个循环或RTOS任务中反复调用它，直到它返回0（握手成功）或负数（失败）。它本质上是实现了TLS协议的状态机推进。

3. 发送与接收应用数据：握手完成后，状态变为BR_SSL_APPLICATION。此时，你不能直接用lwip_write/read了，必须通过BearSSL的API来收发加密数据。

   • 发送数据：

     size_t ssl_send(const void *data, size_t len) { size_t sent = 0; while (sent < len) { unsigned char *buf; size_t alen; buf = br_ssl_engine_sendapp_buf(&ssl_ctx.eng, &alen); // 获取应用发送缓冲区 if (alen == 0) { // 缓冲区满，需要先推动引擎发送（即调用一次ssl_io_poll） if (ssl_io_poll() <= 0) return sent; // 出错或关闭 continue; } size_t clen = (len - sent) < alen ? (len - sent) : alen; memcpy(buf, (const unsigned char*)data + sent, clen); br_ssl_engine_sendapp_ack(&ssl_ctx.eng, clen); // 确认数据已放入缓冲区 sent += clen; // 放入缓冲区后，同样需要推动引擎将数据加密并发送出去 ssl_io_poll(); } return sent; }

   • 接收数据：

     size_t ssl_recv(void *data, size_t len, int timeout_ms) { unsigned char *buf; size_t alen; // 先检查引擎的应用接收缓冲区里是否有解密好的数据 buf = br_ssl_engine_recvapp_buf(&ssl_ctx.eng, &alen); if (alen > 0) { size_t clen = len < alen ? len : alen; memcpy(data, buf, clen); br_ssl_engine_recvapp_ack(&ssl_ctx.eng, clen); // 确认数据已取走 return clen; } // 如果没有数据，则需要推动I/O，等待网络数据并解密 // 这里可以加入超时逻辑，循环调用ssl_io_poll，直到有数据或超时 // ... return 0; // 超时或无数据 }

3.3 证书验证：安全连接的基石

很多人会为了“省事”跳过证书验证，这在产品中是绝对禁止的，等同于明文传输。BearSSL的证书验证默认是开启的，并且需要我们提供“信任锚”。

如何准备信任锚？

1. 找到你的服务器证书的根CA证书（或中间CA证书）。例如，如果你的服务器用的是Let‘s Encrypt证书，你需要下载ISRG Root X1证书。
2. 将该证书从PEM格式转换为DER格式（二进制）。可以使用OpenSSL命令：openssl x509 -in root_ca.pem -outform DER -out root_ca.der。
3. 将root_ca.der文件的内容，以C数组的形式嵌入到你的固件中。有很多在线工具或脚本（如xxd -i命令）可以完成这个转换。

   static const unsigned char my_trust_anchor_der[] = { 0x30, 0x82, 0x03, 0x21, 0x30, 0x82, 0x02, 0x09, // ... 漫长的DER数据 }; static const br_x509_trust_anchor my_trust_anchor = { { (unsigned char *)my_trust_anchor_der, sizeof(my_trust_anchor_der) }, 0, // 标志位，0表示证书是CA证书 };

4. 在初始化br_x509_minimal_context时，通过br_x509_minimal_set_trust_anchors函数设置这个锚点。

验证过程：握手时，服务器会发送它的证书链。BearSSL的X509引擎会使用你提供的信任锚去验证这个链的签名是否有效，同时检查证书中的主机名（CN或SAN）是否与你连接时使用的server_name匹配。任何一步失败，连接都会中止。

实操心得：证书更新。硬编码CA证书带来了更新问题。一种高级做法是，在设备首次启动或定期地，通过一个预设的、硬编码的“初始信任锚”（例如设备厂商自己的CA）安全地连接到更新服务器，下载最新的公共CA证书，并安全地存储在Flash的某个区域。后续连接再使用这个动态更新的证书库。BearSSL支持在运行时更换信任锚列表，这为实现此功能提供了可能。

4. 进阶话题与性能调优

4.1 内存与速度的权衡

BearSSL提供了同一算法的多种实现，例如AES：

• br_aes_big.c: 使用大型查表法，速度最快，但代码体积大（约8KB）。
• br_aes_small.c: 使用紧凑的字节操作，代码体积小（约3KB），但速度慢。
• br_aes_ct.c: 使用常量时间操作，能抵抗某些侧信道攻击，速度和体积介于两者之间。

如何选择？在编译宏中，通过定义BR_USE_AES_SMALL=1或BR_USE_AES_BIG=1来选择。我的经验法则是：如果Flash空间极其紧张（<256KB），选SMALL；如果对连接建立速度有要求（比如需要快速重连），且Flash有富余，选BIG或CT。

4.2 会话恢复（Session Resumption）

TLS握手是一个CPU密集型操作，尤其是非对称加密计算。为了提升重连速度，可以使用会话恢复。BearSSL支持两种：

1. Session ID(TLS 1.2)：服务器在第一次握手后会返回一个Session ID，客户端可以保存它。下次连接时发送这个ID，如果服务器还存有会话状态，就可以跳过密钥交换，直接恢复。
2. Session Ticket(RFC 5077)：服务器加密一个包含会话信息的“票证”给客户端，客户端下次直接出示票证。这种方式对服务器无状态要求，更友好。

启用方法：在编译时定义BR_ENABLE_SESSION_TICKETS=1或BR_ENABLE_SESSION_ID=1。在代码中，你需要实现回调函数来保存和恢复会话数据（通常是存到Flash或外部EEPROM中）。这能显著提升设备从睡眠中唤醒后重连的速度。

4.3 与常见协议栈的集成：HTTP、MQTT

BearSSL只负责TLS层，上层应用协议需要你自己处理。好消息是，集成起来很直观。

• HTTPS：本质上就是HTTP over TLS。你实现一个简单的HTTP客户端（解析Host头，构造GET /path HTTP/1.1\r\nHost: ...这样的请求），然后将原本调用send()和recv()的地方，替换成我们上面实现的ssl_send()和ssl_recv()即可。注意，HTTP响应体的读取可能需要处理分块传输编码（Chunked Encoding）。
• MQTT over TLS (MQTTS)：同样，使用一个轻量级的MQTT客户端库（如Eclipse Paho的嵌入式C版本，或你自己实现一个最小实现）。在建立TCP连接后，插入BearSSL的握手和加密层。MQTT客户端的network_read和network_write回调函数，指向ssl_recv和ssl_send函数。这样，MQTT库对网络层无感知，所有数据都自动被TLS加解密。

5. 常见问题排查与调试技巧

即使按照步骤来，集成过程中也难免踩坑。这里记录几个我遇到过的典型问题及排查思路。

5.1 连接失败：握手阶段问题

问题现象：ssl_io_poll总是返回-1，或者状态机卡住不动。

排查步骤：

1. 检查基础网络：首先确认你的裸TCP连接（不加密）是否能通。用ping和telnet或netcat测试目标端口。
2. 启用BearSSL调试输出：在编译时定义宏BR_DEBUG=1。这会在库内部关键节点打印调试信息到标准错误（stderr）。你需要实现一个br_debug_printf函数，将输出重定向到你的串口。调试信息会显示握手进行到了哪一步（如“ClientHello”, “ServerHello”, “Certificate”），卡在哪一步就对症下药。
3. 核对密码套件：这是最常见的原因。确保你编译BearSSL时启用的密码套件，服务器端也支持。查看服务器支持的套件列表（用openssl s_client -connect host:port -cipher ‘ALL’），并与你的编译宏对比。新手常犯的错误是只启用了ECDSA套件，但服务器用的是RSA证书。
4. 检查SNI：确保调用br_ssl_client_init_full时传入了正确的主机名（域名）。对于使用虚拟主机的Web服务器，没有SNI会导致握手失败。
5. 检查系统时间和熵源：证书验证需要正确的系统时间来判断是否过期。如果你的设备没有RTC，或者时间未同步，可能导致验证失败。同样，TLS需要加密随机数，确保你的熵源（如BR_USE_URANDOM指向的硬件RNG或软件熵池）是有效的。

5.2 证书验证失败

问题现象：握手能进行到“Certificate”阶段，但随后失败，调试信息可能提示“unknown CA”或“bad certificate”。

排查步骤：

1. 确认信任锚：双击检查你嵌入的CA证书DER数组是否正确、完整。可以用一个简单的PC端测试程序，加载同样的证书去连接服务器，验证证书链。
2. 检查证书链：服务器的证书可能不是由你直接信任的根CA签发，而是由一个中间CA签发。你需要将整个信任链（根CA+中间CA）都作为信任锚提供给BearSSL。br_x509_minimal_set_trust_anchors函数可以接受一个锚点数组。
3. 主机名不匹配：服务器证书的“Common Name”或“Subject Alternative Names”字段必须包含你连接时使用的主机名。比如你用IP地址连接，但证书里只有域名，验证就会失败。

5.3 内存不足与稳定性问题

问题现象：设备运行一段时间后死机、复位，或者处理大流量数据时出错。

排查步骤：

1. I/O缓冲区大小：BR_SSL_BUFSIZE_BIDI定义了内部I/O缓冲区的大小。默认值可能不适合你的网络MTU。如果发送的数据包经常被分片，可以适当调大。但注意，这个缓冲区是双向的，且占用RAM。建议从2048开始测试，用Wireshark抓包观察TLS记录层分片情况。
2. 栈空间：BearSSL的函数调用深度不深，但一些内部缓冲区（如证书解析时的临时缓冲区）可能会在栈上分配。确保你的RTOS任务或线程有足够的栈空间（建议至少2-4KB）。
3. 阻塞操作：确保你的lwip_read/write（或其他的socket操作）是非阻塞的，并且在数据未就绪时立即返回EAGAIN或EWOULDBLOCK。如果它们阻塞了，会卡住整个TLS状态机，导致看门狗超时。我们的ssl_io_poll函数设计就是基于非阻塞I/O的。

5.4 性能瓶颈分析

如果你觉得连接建立太慢：

1. 算法选择：RSA密钥交换比ECDHE慢得多。确保你启用了TLS_ECDHE_*套件。ECC签名验证也比RSA快。
2. 熵源速度：在初始化阶段，生成随机数需要熵。如果硬件RNG速度慢，或者软件熵池积累不够，会拖慢握手。可以尝试在系统启动时提前初始化好熵源。
3. 会话恢复：如前所述，务必启用并正确实现会话恢复功能，对于频繁重连的设备，性能提升是数量级的。

集成BearSSL的过程，是一个对TLS协议和嵌入式系统资源管理加深理解的过程。它不像一些高度封装的SDK那样开箱即用，但这份“透明”和“可控”，正是我们在开发对安全性和可靠性有严苛要求的嵌入式产品时所珍视的。当你看到设备在几十KB的内存限制下，稳定地跑起一个经过完整证书验证的TLS 1.2连接时，那种成就感是使用现成大型库无法比拟的。它让你真正地掌控了设备通信的安全基石。