全部文档
概述 硬件支持 快速开发指南 内核 驱动 通用组件 专业组件 常见问题

OneTLS安全通信组件

简介

OneTLS是一套轻量级的SSL/TLS库,支持最新的TLS1.3和DTLS1.3标准(draft 38),向用户提供了简单易用的操作接口,为物联网通信安全提供了保障。

目录结构

源码位于$OS_ROOT/components/security/onetls

目录 说明
crypto 密码库
tls tls源文件
tests 测试示例

API列表

接口 说明
onetls_version 获取OneTLS协议栈版本
onetls_new_ctx 新建会话管理上下文
onetls_del_ctx 释放会话管理上下文
onetls_shutdown 断开握手连接
onetls_set_socket 绑定socket句柄到会话管理对象
onetls_set_psk_callback 配置psk的回调
onetls_set_outband_psk_hint 配置带外psk
onetls_connect 发起握手连接
onetls_send_early_data 发送早期应用数据
onetls_send 发送应用数据
onetls_recv 接收应用数据
onetls_pending 检测缓冲区是否有数据
onetls_flush 刷新缓冲区
onetls_socket_timeout 配置socket超时时间
onetls_key_update 密钥更新
onetls_set_nst_callback 设置票据的接收回调
onetls_set_ticket 设置票据参数
onetls_get_export_key 密钥导出

onetls_version

该函数用于获取协议栈版本,其函数原型如下:

const char *onetls_version(void);
参数 说明
返回 说明
字符串 onetls版本号

onetls_new_ctx

该函数用于新建会话管理上下文,其函数原型如下:

onetls_ctx *onetls_new_ctx(uint8_t mode);
参数 说明
mode 安全通信协议模式:0->tls;1->dtls
返回 说明
onetls_ctx 会话管理对象指针

onetls_del_ctx

该函数用于释放会话管理上下文,其函数原型如下:

void onetls_del_ctx(onetls_ctx *ctx);
参数 说明
ctx 会话管理对象指针
返回 说明

onetls_shutdown

该函数用于断开握手连接,其函数原型如下:

void onetls_shutdown(onetls_ctx *ctx);
参数 说明
ctx 会话管理对象指针
返回 说明

onetls_set_socket

该函数用于绑定socket句柄到会话管理对象,其函数原型如下:

void onetls_set_socket(onetls_ctx *ctx, int recv_fd, int send_fd);
参数 说明
ctx 会话管理对象指针
recv_fd 接收句柄
send_fd 发送句柄
返回 说明

onetls_set_psk_callback

该函数用于配置psk的回调,其函数原型如下:

void onetls_set_psk_callback(onetls_ctx *ctx, onetls_psk_callback cb);
参数 说明
ctx 会话管理对象指针
cb 获取psk的回调函数
返回 说明

onetls_set_outband_psk_hint

该函数用于配置带外psk,其函数原型如下:

uint32_t onetls_set_outband_psk_hint(onetls_ctx *ctx, uint8_t *hint, uint32_t hint_len);
参数 说明
ctx 会话管理对象指针
hint psk identity
hint_len psk identity长度
返回 说明
0 成功
非0 失败

onetls_connect

该函数用于发起握手连接,其函数原型如下:

uint32_t onetls_connect(onetls_ctx *ctx);
参数 说明
ctx 会话管理对象指针
返回 说明
0 成功
非0 失败

onetls_send_early_data

该函数用于发送早期应用数据,其函数原型如下:

uint32_t onetls_send_early_data(onetls_ctx *ctx, const uint8_t *out, uint32_t out_len, uint32_t *send_len);
参数 说明
ctx 会话管理对象指针
out 待发送的数据缓存
out_len 待发送的数据长度
send_len 实际发送的数据长度
返回 说明
0 成功
非0 失败

onetls_send

该函数用于发送应用数据,其函数原型如下:

uint32_t onetls_send(onetls_ctx *ctx, uint8_t *out, uint32_t out_len, uint32_t *send_len);
参数 说明
ctx 会话管理对象指针
out 待发送的数据缓存
out_len 待发送的数据长度
send_len 实际发送的数据长度
返回 说明
0 成功
非0 失败

onetls_recv

该函数用于接收应用数据,其函数原型如下:

uint32_t onetls_recv(onetls_ctx *ctx, uint8_t *in, uint32_t in_len, uint32_t *recv_len);
参数 说明
ctx 会话管理对象指针
in 接收数据缓存
in_len 接收数据缓存长度
recv_len 实际接收的数据长度
返回 说明
0 成功
非0 失败

onetls_pending

该函数用于检测缓冲区是否有数据,其函数原型如下:

uint32_t onetls_pending(onetls_ctx *ctx);
参数 说明
ctx 会话管理对象指针
返回 说明
0 缓冲区空
非0 缓冲区非空

onetls_flush

该函数用于刷新缓冲区,其函数原型如下:

uint32_t onetls_flush(onetls_ctx *ctx);
参数 说明
ctx 会话管理对象指针
返回 说明
0 成功
非0 失败

onetls_socket_timeout

该函数用于配置socket超时时间,其函数原型如下:

uint32_t onetls_socket_timeout(onetls_ctx *ctx, uint32_t ms);
参数 说明
ctx 会话管理对象指针
ms 超时时间,毫秒
返回 说明
0 成功
非0 失败

onetls_key_update

该函数用于密钥更新,其函数原型如下:

uint32_t onetls_key_update(onetls_ctx *ctx, void *data, uint8_t k);
参数 说明
ctx 会话管理对象指针
k 更新密钥的方式:0->只发送方向;1->双向
返回 说明
0 成功
非0 失败

onetls_set_nst_callback

该函数用于设置票据的接收回调,其函数原型如下:

void onetls_set_nst_callback(onetls_ctx *ctx, onetls_nst_callback cb);
参数 说明
ctx 会话管理对象指针
cb 回调函数
返回 说明

onetls_set_ticket

该函数用于设置票据参数,其函数原型如下:

uint32_t onetls_set_ticket(onetls_ctx *ctx, const uint8_t *ticket, uint32_t ticket_len);
参数 说明
ctx 会话管理对象指针
ticket 票据数据
ticket_len 票据数据长度
返回 说明
0 成功
非0 失败

onetls_get_export_key

该函数用于密钥导出,其函数原型如下:

uint32_t onetls_get_export_key(onetls_ctx *ctx, const char *label, const uint8_t *in, uint32_t in_len, uint8_t *out, uint32_t out_size, uint32_t *out_len);
参数 说明
ctx 会话管理对象指针
label 标签
in 输入数据
in_len 输入数据长度
out 导出密钥数据缓存
out_size 导出密钥数据缓存长度
out_len 导出密钥数据实际长度
返回 说明
0 成功
非0 失败

使用示例

开发者可以参考tests目录下的tls测试示例。

配置指南

在OneOS的SDK根目录下打开\projects\xxxxx文件夹,右键启动OneOS-Cube 工具,在命令行输入 menuconfig 打开可视化配置界面,选择"Components → Security → OneTLS"选项。其中第一项用于使能OneTLS安全通信协议栈,该组件使能后配置其他项。

(Top) → Components→ Security→ OneTLS
[*] Enable onetls
         Select Cipher --->
        Select Elliptoc Curve Groups --->
[*] Enable onetls debug
(1024) The max record packet length
[*] Support resumption
[*] Support 0-RTT
[ ] Enable tls tests demo
  • Enable onetls:使能OneTLS安全通信协议栈。
  • Select Cipher:密码算法套件,至少使能一种。
  • Select Elliptic Curve Groups:椭圆曲线列表,至少使能一种。
  • Enable onetls debug:调试模式使能,可以控制日志打印、断言、Dump等调测功能。
  • The max record paket length:最大记录层报文长度,范围512-16384字节。
  • Support resumption:支持会话恢复使能。
  • Support 0-RTT:支持0-RTT数据使能。
  • Enable tls tests demo:tls测试参考示例。

使用GCC编译

基于上述配置,在OneOS-Cube 工具命令行输入 scons即用GCC进行编译,通过固件下载工具(如ST芯片较常使用的ST Utilities工具等)进行烧录。

使用ARM CC编译

基于上述配置,在OneOS-Cube 工具命令行输入 scons --ide=mdk5即可自动构建MDK工程,使用MDK5进行编译、烧录及调试。

FAQ

  1. OneTLS支持DTLS1.3协议栈吗?

    答:当前RFC DTLS1.3协议标准暂未截稿,但OneTLS已经支持DTLS1.3标准到draft38版本,OneTLS的DTLS部分暂不开源,如您有需要,请联系OneOS团队。

  2. OneTLS支持服务端吗?

    答:由于嵌入式设备上对资源敏感,且一般场景下物联网设备都只作为客户端,故OneTLS只设计实现客户端部分。

  3. OneTLS可以和哪些开源SSL/TLS对接?

    答:目前OneTLS已经与OpenSSL、wolfssl、nss、mbedtls实现了对接测试。

  4. OneTLS支持PKI体系吗?

    答:考虑协议栈的轻量以及对硬件资源消耗,目前OneTLS支持psk模式的握手,后续将加入对PKI体系的支持。

results matching ""

    No results matching ""