全部产品
云市场

设备端SDK 适配手册

更新时间:2019-05-05 15:55:01

此手册适用于:

  • 硬件厂商、物联网开发者需要为某一款硬件/设备适配ID²。
  • 设备使用了Android,Linux,AliOS Things系统。
  • 使用了任一种安全载体:SE、SIM、KM、TEE。
  • 如果您的硬件/设备已经完成了ID²与设备端底层硬件的适配,请直接跳过此文档;请直接对接ID²的接口。ID²设备端接口说明参见:设备端对接 API

安全SDK适配说明

设备端安全SDK是打包集成了阿里云IoT在设备端的安全框架和安全组件,通过统一的OSA和HAL接口,以便适配到不同的系统和平台。目前已经支持Android,Linux,AliOS Things,如果厂商希望在更多的设备类型上集成和使用这套安全SDK,请与我们联系

一、OS适配接口:

基础功能:

1,void ls_osa_print(const char *fmt, …)

  • 功能:打印函数,用于向串口或其他标准输出打印日志或调试信息。
  • 参数:
名称 数据类型 描述
fmt const char * 格式化字符串
void * 可变参数列表

2,int ls_osa_snprintf(char str, size_t size, const char fmt, …)

  • 功能:打印函数,向内存缓冲区格式化构建一个字符串。
  • 参数:
名称 数据类型 描述
str char * 指向字符串缓冲的指针
size size_t 缓冲区的长度
fmt const char * 格式化字符串
void * 可变参数列表
  • 返回值:实际写入缓冲区的字符串长度。


3,void *ls_osa_malloc(size_t size)

  • 功能:申请一块堆内存。
  • 参数:
名称 数据类型 描述
size size_t 申请内存的字节大小
  • 返回值:指向申请内存首地址的指针,失败返回NULL。


4,void *ls_osa_calloc(size_t nmemb, size_t size)

  • 功能:分配nmemb个长度为size的连续堆内存,且内存数据置为0。
  • 参数:
名称 数据类型 描述
nmemb size_t 内存块的数量
size size_t 单个内存的字节长度
  • 返回值:指向申请内存首地址的指针,失败返回NULL。


5,void ls_osa_free(void *ptr)

  • 功能: 释放参数ptr指向的一块堆内存。
  • 参数:
名称 数据类型 描述
ptr void * 指向要释放的堆内存的地址

6,void ls_osa_msleep(unsigned int msec)

  • 功能:睡眠函数,使当前执行线程睡眠指定的毫秒数。
  • 参数:
名称 数据类型 描述
msec unsigned int 线程挂起的时间,单位毫秒


7,long long ls_osa_get_time_ms(void)

  • 功能:获取当前系统的时间戳大小。
  • 参数:void
  • 返回值:系统的时间戳大小(以毫秒为单位)。

多线程:

1,int ls_osa_mutex_create(void **mutex)

  • 功能: 创建一个互斥量,用于多线程下的同步访问。
  • 参数:
名称 数据类型 描述
mutex void ** 指向创建互斥量的句柄
  • 返回值:成功:= 0

    1. 失败:< 0<br />


    2,void ls_osa_mutex_destroy(void *mutex)

  • 功能:销毁互斥量的句柄。

  • 参数:
名称 数据类型 描述
mutex void * 互斥量的句柄


3,int ls_osa_mutex_lock(void *mutex)

  • 功能:锁住一个互斥量。
  • 参数:
名称 数据类型 描述
mutex void * 互斥量的句柄
  • 返回值:

成功:= 0
失败:< 0

4,int ls_osa_mutex_unlock(void *mutex)

  • 功能:解锁一个互斥量。
  • 参数:
名称 数据类型 描述
mutex void * 互斥量的句柄
  • 返回值:

成功:= 0
失败:< 0

网络操作:

1,int ls_osa_net_connect(const char host, const char port, int type)

  • 功能:创建由host:port指定的特定类型的网络连接。
  • 参数:
名称 数据类型 描述
host const char * 连接的主机地址
port const char* 连接的端口号
type int 网络类型,LS_NET_TYPE_XXX
  • 返回值:

成功:网络连接的句柄
失败:-1
2,void ls_osa_net_disconnect(int fd)

  • 功能:断开网络连接,并释放相应资源。
  • 参数:
名称 数据类型 描述
fd int 网络连接的句柄


3,int ls_osa_net_send(int fd, unsigned char buf, size_t len, int ret_orig)

  • 功能:发送数据到指定的网络中。
  • 参数:
名称 数据类型 描述
fd int 网络连接的句柄
buf unsigned char* 发送数据的内存
len size_t 发送数据的字节长度
ret_orig int * 接口返回失败时,指向具体的错误码
  • 返回值:

成功:实际发送数据的长度
失败:-1
4,int ls_osa_net_recv(int fd, unsigned char buf, size_t len, int timeout, int ret_orig)

  • 功能:在指定的时间内,从网络中读取最多len字节的数据。
  • 参数:
名称 数据类型 描述
fd int 网络连接的句柄
buf unsigned char* 接收数据的内存
len size_t 内存的最大长度
timeout int 读取数据的时间值,0代码阻塞
ret_orig int * 接口返回失败时,指向具体的错误码
  • 返回值:

成功:实际接收数据的长度
失败:-1

二、HAL适配接口

Soft-KM:

1,int ls_hal_get_dev_id(uint8_t dev_id, uint32_t id_len)

  • 功能:获取设备唯一ID。
  • 参数:
名称 数据类型 描述
dev_id uint8_t * 存储设备唯一ID的内存
id_len uint32_t * 内存的长度(in),设备ID的实际长度(out)
  • 返回值:

成功:= 0
失败:-1
2,int ls_hal_open_rsvd_part(int flag)

  • 功能:根据指定的权限(flag)打开预留的管理分区;如不支持文件系统,直接返回0。
  • 参数:
名称 数据类型 描述
flag int 分区的读写权限
  • 返回值:

成功:文件句柄
失败:-1
3,int ls_hal_write_rsvd_part(int fd, uint32_t offset, void *data, uint32_t data_len)

  • 功能:向指定的分区中,写入data_len字节的数据。
  • 参数:
名称 数据类型 描述
fd int 文件句柄;或者忽略(没有文件系统)
offset uint32_t 写数据的偏移量
data void * 写入的数据
data_len data_len 写入数据的长度(字节)
  • 返回值:

成功:= 0
失败:-1
4,int ls_hal_read_rsvd_part(int fd, uint32_t offset, void *buffer, uint32_t read_len)

  • 功能:从指定的分区中,读取read_len字节的数据。
  • 参数:
名称 数据类型 描述
fd int 文件句柄;或者忽略(没有文件系统)
offset uint32_t 读数据的偏移量
buffer void * 读取数据的缓存
read_len data_len 读取数据的长度(字节)
  • 返回值:

成功:= 0
失败:-1
5,int ls_hal_close_rsvd_part(int fd)

  • 功能:关闭打开的预留分区。
  • 参数:
名称 数据类型 描述
fd int 文件句柄;或者忽略(没有文件系统)
  • 返回值:

成功:= 0
失败:-1

Secure Storage:

1,int ls_hal_kv_init(void)

  • 功能:初始化安全存储模块。
  • 参数:void
  • 返回值:

成功:= 0
失败:< 0
2,void ls_hal_kv_deinit(void)

  • 功能:注销安全存储模块。
  • 参数:void


3,int ls_hal_kv_set(const char key, const void value, int len, int sync)

  • 功能:设置一组key-value到安全存储中。
  • 参数:
名称 数据类型 描述
key const char * 存储数据的标识
value const void * 存储的数据
len int 存储数据的长度(字节)
sync int 同步/异步
  • 返回值:

成功:= 0
失败:< 0
4,int ls_hal_kv_get(const char key, void buffer, int *buffer_len)

  • 功能:根据标识(key), 从安全存储中获取对应的数据。
  • 参数:
名称 数据类型 描述
key const char * 存储数据的标识
buffer void * 存储数据的缓存
buffer_len int * 缓存长度/读取的数据长度
  • 返回值:

成功:= 0
失败:< 0
5,int ls_hal_kv_del(const char *key)

  • 功能:删除安全存储中key标识的数据。
  • 参数:
名称 数据类型 描述
key const char * 存储数据的标识
  • 返回值:

成功:= 0
失败:< 0

三、适配说明

OS适配:

在AliOS Things中,已经完成OS的适配;在第三方OS上,可根据应用/场景选择相应的OS接口适配,其中基础功能(必须),多线程(多线程场景)和网络操作(使用iTLS安全连接)。

平台配置:

AliOS Things 2.1.0版本开始,Link Security SDK的配置统一提取到平台的aos.mk中,
如mk3080(board/mk3080/aos.mk):

其中:
CONFIG_LS_DEBUG: 控制模块调试信息的开启和关闭。
CONFIG_LS_ID2_OTP:控制ID2空发的开启和关闭,其中SE不支持空发,配置无效。
CONFIG_LS_KM_SE: 控制SE KM的开启和关闭。
CONFIG_LS_KM_TEE: 控制TEE KM的开启和关闭。