TLS

NetLeaf TLS/SSL 扩展库

概述

netleaf_tls 是 NetLeaf 的 TLS/SSL 加密扩展库，基于内置的 mbedTLS 2.28.10 LTS 源码实现。作为独立的基础扩展库，它可被其他协议模块（如 MQTT、HTTP 等）通过 NL扩展系统调用。

架构说明

flowchart TD
    TLS["netleaf_tls.dll<br/>TLS/SSL 基础扩展库<br/>———————<br/>• mbedtls 内置源码 (third-party/mbedtls/)<br/>• 通用 TLS/SSL 功能<br/>• 可作为标准库被其他模块调用"]
    MQTT["netleaf_mqtt.dll<br/>MQTT 协议扩展库<br/>———————<br/>• netleaf_mqtt.c (MQTT 核心功能)<br/>• netleaf_mqtt_tls.c (MQTT TLS 功能)<br/>• 依赖 netleaf_tls (可选)"]
    TLS -->|可被调用| MQTT

Loading

关键说明：

• netleaf_tls.dll 是独立的 TLS/SSL 基础扩展库
• MQTT TLS 功能包含在 netleaf_mqtt.dll 中，不是独立的模块
• 其他协议模块（如未来的 HTTP、FTP 等）也可以调用 netleaf_tls.dll 的功能
• 通过 CMake 的 BUILD_TLS 选项控制是否编译 TLS 功能

依赖项

• mbedTLS 2.28.10 LTS（已内置于 third-party/mbedtls/）
• 无需单独安装 mbedTLS

API 概览

模块信息

// 获取 TLS 模块信息
nl_module_info_t* nl_tls_get_module_info(void);

// 初始化 TLS 模块
int nl_tls_init(void);

// 获取版本
const char* nl_tls_version(void);

// 检查可用性
int nl_tls_is_available(void);

上下文管理

// 创建 TLS 上下文
nl_tls_ctx_t* nl_tls_create(void);

// 销毁 TLS 上下文
void nl_tls_destroy(nl_tls_ctx_t* ctx);

配置

// 配置 TLS 上下文
int nl_tls_configure(nl_tls_ctx_t* ctx, const nl_tls_config_t* cfg);

// 设置验证选项
int nl_tls_set_verify(nl_tls_ctx_t* ctx, int verify_peer);

配置结构:

typedef struct nl_tls_config {
    const char*          ca_file;       // CA证书文件路径
    const char*          ca_path;       // CA证书目录路径
    const char*          cert_file;     // 客户端证书文件
    const char*          key_file;      // 客户端私钥文件
    const char*          key_pass;      // 私钥密码
    int                  verify_peer;   // 验证对端证书(0或1)
    int                  client_auth;   // 要求客户端认证(0或1)
    nl_tls_protocol_t    min_proto;     // 最低协议版本
    nl_tls_protocol_t    max_proto;     // 最高协议版本
} nl_tls_config_t;

SSL 握手

// 执行 TLS 握手
int nl_tls_handshake(nl_tls_ctx_t* ctx, int sock);

数据传输

// 通过 TLS 发送数据
int nl_tls_send(nl_tls_ctx_t* ctx, const void* buf, size_t len);

// 通过 TLS 接收数据
int nl_tls_recv(nl_tls_ctx_t* ctx, void* buf, size_t len);

// 优雅关闭 TLS 连接
int nl_tls_close(nl_tls_ctx_t* ctx);

状态查询

// 检查 TLS 连接是否活跃
int nl_tls_is_active(const nl_tls_ctx_t* ctx);

// 获取对端证书信息
const char* nl_tls_get_peer_cert(nl_tls_ctx_t* ctx);

// 获取错误信息
const char* nl_tls_strerror(int err);

结果码

typedef enum {
    NL_TLS_OK             =  0,
    NL_TLS_ERROR          = -1,
    NL_TLS_BAD_CA         = -2,
    NL_TLS_BAD_CERT       = -3,
    NL_TLS_BAD_KEY        = -4,
    NL_TLS_ALLOC_FAIL     = -5,
    NL_TLS_HANDSHAKE      = -6,
    NL_TLS_READ           = -7,
    NL_TLS_WRITE          = -8,
    NL_TLS_NOT_INIT       = -9,
    NL_TLS_INVALID_STATE  = -10,
    NL_TLS_UNKNOWN_ERROR  = -99
} nl_tls_result_t;

使用示例

基本 TLS 连接

#include "netleaf_tls.h"
#include <stdio.h>
#include <sys/socket.h>

int main() {
    // 初始化 TLS 模块
    nl_tls_init();
    
    // 创建套接字
    int sock = socket(AF_INET, SOCK_STREAM, 0);
    
    // 连接到服务器
    struct sockaddr_in addr = {0};
    addr.sin_family = AF_INET;
    addr.sin_port = htons(443);
    inet_pton(AF_INET, "93.184.216.34", &addr.sin_addr);
    connect(sock, (struct sockaddr*)&addr, sizeof(addr));
    
    // 创建 TLS 上下文
    nl_tls_ctx_t* ctx = nl_tls_create();
    
    // 配置证书验证
    nl_tls_config_t cfg = {
        .ca_file = "ca.crt",
        .verify_peer = 1
    };
    nl_tls_configure(ctx, &cfg);
    
    // 执行握手
    int ret = nl_tls_handshake(ctx, sock);
    if (ret != NL_TLS_OK) {
        printf("Handshake failed: %s\n", nl_tls_strerror(ret));
        return 1;
    }
    
    // 发送 HTTPS 请求
    const char* request = "GET / HTTP/1.1\r\nHost: example.com\r\n\r\n";
    nl_tls_send(ctx, request, strlen(request));
    
    // 接收响应
    char buffer[4096];
    int bytes = nl_tls_recv(ctx, buffer, sizeof(buffer) - 1);
    buffer[bytes] = '\0';
    printf("%s\n", buffer);
    
    // 清理
    nl_tls_close(ctx);
    nl_tls_destroy(ctx);
    close(sock);
    
    return 0;
}

MQTT over TLS 示例

#include "netleaf_mqtt.h"
#include "netleaf_mqtt_tls.h"
#include <stdio.h>

void on_connect(int rc, void* userdata) {
    printf("MQTT connected with result: %d\n", rc);
}

void on_message(const char* topic, const void* payload, size_t len, void* userdata) {
    printf("Received [%s]: %.20s...\n", topic, payload);
}

int main() {
    // 创建 MQTT 客户端
    nl_mqtt_client_t* client = nl_mqtt_create();
    
    // 连接选项
    nl_mqtt_connect_opts_t opts = {
        .client_id = "netleaf_client_001",
        .keep_alive = 60,
        .clean_session = 1
    };
    
    // 使用 TLS 连接（端口 8883）
    nl_mqtt_connect(client, "broker.hivemq.com", 8883, &opts, on_connect);
    nl_mqtt_subscribe(client, "netleaf/#", &(nl_mqtt_sub_opts_t){.qos = 1}, on_message, NULL);
    
    // 事件循环
    while (1) {
        nl_mqtt_maintain(client, 1000);
    }
    
    nl_mqtt_destroy(client);
    return 0;
}

构建配置

CMake 选项

# 启用 TLS 构建
cmake -B build -DBUILD_TLS=ON

# 同时启用 MQTT + TLS
cmake -B build -DBUILD_TLS=ON -DBUILD_MQTT=ON

构建脚本

# Windows
build_tls.bat

# Linux/macOS
./build_tls.sh

支持的协议版本

• TLS 1.0 ⚠️（已废弃，不推荐）
• TLS 1.1 ⚠️（已废弃，不推荐）
• TLS 1.2 ✅（推荐的最低版本）
• TLS 1.3 ✅（推荐）

⚠️ 安全提示（不推荐 TLS 1.0 / 1.1） TLS 1.0 与 TLS 1.1 已被 RFC 8996 正式废弃且不再安全，不建议使用。 本模块（netleaf_tls）作为独立的 TLS 扩展库统一负责 NetLeaf 的 TLS 能力；保留 TLS 1.0/1.1 仅为兼容老旧对端， 实际使用请将 min_proto 设置为 NL_TLS_PROTO_TLS1_2 或更高。

开源项目来源

本模块基于以下开源项目：

项目	用途	许可证	仓库链接
mbedTLS	TLS/SSL 加密库	Apache 2.0 / GPL v2.0	Mbed-TLS/mbedTLS

注意事项

1. 证书文件路径：确保证书文件路径正确，建议使用绝对路径
2. 随机数生成：TLS 握手需要安全的随机数，已内置 entropy + CTR-DRBG
3. 线程安全：单个 TLS 上下文不保证线程安全，多线程使用请各自创建独立上下文
4. 错误处理：始终检查函数返回值，使用 nl_tls_strerror() 获取错误详情

相关文档

• API 参考 - 完整 API 列表
• 功能特性 - TLS 功能介绍
• 示例代码 - 使用示例