Q群：
电话：
邮箱：
地址：
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测试示例。
配置指南
Menuconfig配置
在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
OneTLS支持DTLS1.3协议栈吗？
答：当前RFC DTLS1.3协议标准暂未截稿，但OneTLS已经支持DTLS1.3标准到draft38版本，OneTLS的DTLS部分暂不开源，如您有需要，请联系OneOS团队。
OneTLS支持服务端吗？
答：由于嵌入式设备上对资源敏感，且一般场景下物联网设备都只作为客户端，故OneTLS只设计实现客户端部分。
OneTLS可以和哪些开源SSL/TLS对接？
答：目前OneTLS已经与OpenSSL、wolfssl、nss、mbedtls实现了对接测试。
OneTLS支持PKI体系吗？
答：考虑协议栈的轻量以及对硬件资源消耗，目前OneTLS支持psk模式的握手，后续将加入对PKI体系的支持。
