2026/7/19大约 5 分钟常用组件组件加密TLSmbedtls
7.3.1 MBED TLS 加密组件
📚 本节导读
学习时长: 约 45 分钟
难度级别: ⭐⭐⭐⭐☆
前置知识: 计算机网络基础、SSL/TLS 协议原理
🎯 学习目标
- 理解 MBED TLS 的架构设计及在 OneOS 中的集成方式
- 掌握 mbedtls_ssl_context 和 mbedtls_ssl_config 两大核心结构体
- 掌握 TLS 客户端初始化、握手、数据收发、关闭的标准流程
- 了解 DTLS 协议及其与 TLS 的差异
- 了解密码学模块（AES、RSA、SHA256、ECDH 等）
- 能够使用 MBED TLS 实现安全的 MQTT over TLS 通信
一、概述
MBED TLS（原名 PolarSSL）是 ARM 公司开源的轻量级 SSL/TLS 安全库，专为嵌入式系统设计。OneOS 集成了 mbedTLS v2.16.8，位于 components/security/mbedtls/mbedtls-v2.16.8/。
MBED TLS 的核心功能包括：
- TLS/DTLS 协议：支持 TLS 1.0/1.1/1.2 和 DTLS 1.0/1.2
- X.509 证书管理：证书解析、验证、CRL 检查
- 密码学算法：AES、DES、RSA、ECDSA、ECDH、SHA-1/256/512、HMAC 等
- 随机数生成：CTR_DRBG 密码学安全伪随机数生成器
- 硬件加速：支持硬件加密引擎加速
二、核心数据结构
2.1 mbedtls_ssl_context —— SSL 会话上下文
SSL/TLS 连接的核心上下文，存储会话状态、协商参数、缓冲区等。
typedef struct mbedtls_ssl_context mbedtls_ssl_context;关键字段访问方式：
| 字段 | 访问方式 | 说明 |
|---|---|---|
conf | mbedtls_ssl_setup() 绑定 | 关联的 SSL 配置 |
state | 内部状态机 | 当前 SSL 连接状态 |
major_ver / minor_ver | mbedtls_ssl_get_version() | 协商后的协议版本 |
session | mbedtls_ssl_get_session() | 协商后的会话信息 |
p_bio | mbedtls_ssl_set_bio() | 底层 IO 上下文 |
2.2 mbedtls_ssl_config —— SSL 配置结构体
typedef struct mbedtls_ssl_config mbedtls_ssl_config;关键配置项及对应 API：
| 配置项 | 设置 API | 说明 |
|---|---|---|
endpoint | mbedtls_ssl_config_defaults() | MBEDTLS_SSL_IS_CLIENT / MBEDTLS_SSL_IS_SERVER |
transport | mbedtls_ssl_config_defaults() | MBEDTLS_SSL_TRANSPORT_STREAM / MBEDTLS_SSL_TRANSPORT_DATAGRAM |
authmode | mbedtls_ssl_conf_authmode() | 认证模式设置 |
key_cert | mbedtls_ssl_conf_own_cert() | 自己的证书链和私钥 |
ca_chain | mbedtls_ssl_conf_ca_chain() | 信任的 CA 证书链 |
read_timeout | mbedtls_ssl_conf_read_timeout() | 读超时（毫秒） |
f_rng / p_rng | mbedtls_ssl_conf_rng() | 随机数生成回调 |
三、核心 API 详解
/* 初始化 */
void mbedtls_ssl_init(mbedtls_ssl_context *ssl);
void mbedtls_ssl_config_init(mbedtls_ssl_config *conf);
int mbedtls_ssl_config_defaults(mbedtls_ssl_config *conf, int endpoint, int transport, int preset);
int mbedtls_ssl_setup(mbedtls_ssl_context *ssl, const mbedtls_ssl_config *conf);
/* 证书与密钥 */
int mbedtls_ssl_conf_own_cert(mbedtls_ssl_config *conf, mbedtls_x509_crt *own_cert, mbedtls_pk_context *pk_key);
void mbedtls_ssl_conf_ca_chain(mbedtls_ssl_config *conf, mbedtls_x509_crt *ca_chain, mbedtls_x509_crl *ca_crl);
int mbedtls_ssl_set_hostname(mbedtls_ssl_context *ssl, const char *hostname);
/* 通信与握手 */
void mbedtls_ssl_set_bio(mbedtls_ssl_context *ssl, void *p_bio, mbedtls_ssl_send_t *f_send, mbedtls_ssl_recv_t *f_recv, mbedtls_ssl_recv_timeout_t *f_recv_timeout);
int mbedtls_ssl_handshake(mbedtls_ssl_context *ssl);
int mbedtls_ssl_read(mbedtls_ssl_context *ssl, unsigned char *buf, size_t len);
int mbedtls_ssl_write(mbedtls_ssl_context *ssl, const unsigned char *buf, size_t len);
int mbedtls_ssl_close_notify(mbedtls_ssl_context *ssl);
void mbedtls_ssl_free(mbedtls_ssl_context *ssl);四、TLS 客户端标准流程
1. 初始化所有上下文
├── mbedtls_net_init() / mbedtls_ssl_init()
├── mbedtls_ssl_config_init() / mbedtls_x509_crt_init()
├── mbedtls_ctr_drbg_init() / mbedtls_entropy_init()
2. 播种随机数生成器
└── mbedtls_ctr_drbg_seed()
3. 加载 CA 证书
└── mbedtls_x509_crt_parse()
4. 建立 TCP 连接
└── mbedtls_net_connect()
5. 配置 SSL
├── mbedtls_ssl_config_defaults()
├── mbedtls_ssl_conf_authmode()
├── mbedtls_ssl_conf_ca_chain()
├── mbedtls_ssl_conf_rng()
├── mbedtls_ssl_setup()
├── mbedtls_ssl_set_hostname()
└── mbedtls_ssl_set_bio()
6. 执行 TLS 握手（循环调用直到成功）
└── mbedtls_ssl_handshake()
7. 验证服务器证书
└── mbedtls_ssl_get_verify_result()
8. 安全数据收发
├── mbedtls_ssl_write()
└── mbedtls_ssl_read()
9. 关闭连接并释放资源
├── mbedtls_ssl_close_notify()
└── 依次 free 所有上下文五、错误处理
常用错误码：
| 错误码 | 含义 |
|---|---|
MBEDTLS_ERR_SSL_WANT_READ | 需等待底层可读（非错误，需重试） |
MBEDTLS_ERR_SSL_WANT_WRITE | 需等待底层可写（非错误，需重试） |
MBEDTLS_ERR_SSL_TIMEOUT | 操作超时 |
MBEDTLS_ERR_SSL_PEER_CLOSE_NOTIFY | 对端关闭连接 |
MBEDTLS_ERR_SSL_PEER_VERIFY_FAILED | 对端证书验证失败 |
MBEDTLS_ERR_SSL_ALLOC_FAILED | 内存分配失败 |
注意：
MBEDTLS_ERR_SSL_WANT_READ和MBEDTLS_ERR_SSL_WANT_WRITE并非真正错误，表示非阻塞操作需重试。
六、密码学算法模块
| 模块 | 编译宏 | 功能 |
|---|---|---|
| AES | MBEDTLS_AES_C | 对称加密，支持 CBC/GCM/CCM |
| RSA | MBEDTLS_RSA_C | 非对称加密/签名/验签 |
| ECDSA | MBEDTLS_ECDSA_C | 椭圆曲线数字签名 |
| ECDH | MBEDTLS_ECDH_C | 椭圆曲线密钥交换 |
| SHA-256 | MBEDTLS_SHA256_C | SHA-256 哈希 |
| SHA-512 | MBEDTLS_SHA512_C | SHA-512 哈希 |
| CTR_DRBG | MBEDTLS_CTR_DRBG_C | 安全随机数生成 |
| X.509 | MBEDTLS_X509_CRT_PARSE_C | 证书解析 |
七、Kconfig 配置
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
SECURITY_USING_MBEDTLS | bool | n | 启用 MBED TLS |
MBEDTLS_SSL_MAX_CONTENT_LEN | int | 4096 | SSL 最大片段长度 |
MBEDTLS_SSL_PROTO_DTLS | bool | n | 启用 DTLS 支持 |
MBEDTLS_DEBUG_C | bool | n | 启用调试功能 |
MBEDTLS_SSL_SRV_C | bool | n | 启用服务端代码 |
MBEDTLS_HAVE_TIME | bool | n | 系统支持时间函数 |
📝 本节小结
MBED TLS 是 ARM 开源的轻量级 TLS 库，OneOS 集成 v2.16.8 版本。核心要点：
- 标准 TLS 客户端流程 9 步完成安全连接
MBEDTLS_ERR_SSL_WANT_READ/WRITE不是错误，需循环重试- 模块化设计，可按需裁剪密码学算法
- 通过
MBEDTLS_PLATFORM_ALT适配 OneOS 平台接口
🔗 相关链接
📂 平台适配层源码参考
MBED TLS 通过 ALT 机制将平台相关功能（线程安全、定时器、熵源、时间、网络）适配到 OneOS：
| 文件 | 功能 | 说明 |
|---|---|---|
| threading_alt.h | 线程互斥锁类型定义 | 将 os_mutex_id 适配为 mbedtls_threading_mutex_t |
| threading_alt.c | 线程互斥锁实现 | init/free/lock/unlock 四接口，使用 OneOS 互斥量 |
| timing_alt.h | 定时器数据结构 | 定义 mbedtls_timing_delay_context 延时上下文 |
| timing_alt.c | 定时器实现 | tick→ms 转换，DTLS 重传定时器，hardclock 调试接口 |
| entropy_hardware_alt.c | 硬件熵源 | 使用系统 tick 播种伪随机数生成器 |
| gmtime_r_alt.c | 时间函数适配 | 将 gmtime_r 映射到 POSIX 标准，用于证书有效期验证 |
| net_sockets.c | 网络套接字适配 | TCP/UDP 连接、数据收发、阻塞/非阻塞、超时控制 |