本文介绍设备端SDK的接口和适配说明。

如果您的硬件或设备已经完成了ID²与设备端底层硬件的适配,请跳过此文档,直接对接ID²接口。ID²设备端接口说明,请参见设备端API

设备端安全SDK集成了阿里云IoT在设备端的安全框架和安全组件。通过统一的OSA和HAL接口,支持适配不同的系统和平台。目前支持常见RTOS系统,Android,Linux和AliOS Things系统。

如果您希望在更多的设备类型上集成和使用这套安全SDK,请单击IoT安全-咨询联系阿里云IoT安全团队。

适用范围

  • 硬件厂商、物联网开发者需要为某一款硬件或设备适配ID²。
  • 设备使用常见RTOS系统,Android,Linux或AliOS Things系统。
  • 使用SE、SIM、KM或TEE其中任意一种安全载体。

适配说明

  • OS适配

    若使用AliOS Things,则已经完成OS适配,仅需完成其他接口适配。

    若使用第三方OS,可根据应用和场景选择相应的OS接口适配。其中基础接口必须适配;多线程场景必须适配多线程接口;网络操作场景必须适配网络接口。

  • 平台配置
    从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的开启和关闭。
    1

OS适配接口

基础接口

  • void ls_osa_print(const char *fmt, …)
    • 功能:打印函数,用于向串口或其他标准,输出打印日志或调试信息。
    • 参数说明:
      名称 数据类型 描述
      fmt const char * 格式化字符串。
      void * 可变参数列表。
    • 返回值:实际写入缓冲区的字符串长度。
  • int ls_osa_snprintf(char *str, size_t size, const char *fmt, ...)
    • 功能:打印函数,向内存缓冲区格式化构建一个字符串。
    • 参数说明:
      名称 数据类型 描述
      str char * 指向字符串缓冲的指针。
      size size_t 缓冲区的长度。
      fmt const char * 格式化字符串。
      void * 可变参数列表。
    • 返回值:实际写入缓冲区的字符串长度。
  • void *ls_osa_malloc(size_t size)
    • 功能:申请一块堆内存。
    • 参数说明:
      名称 数据类型 描述
      size size_t 申请内存的字节大小。
    • 返回值:指向申请内存首地址的指针。失败时返回NULL。
  • void *ls_osa_calloc(size_t nmemb, size_t size)
    • 功能:分配nmemb个长度为size的连续堆内存,且内存数据置为0。
    • 参数说明:
      名称 数据类型 描述
      nmemb size_t 内存块的数量。
      size size_t 单个内存的字节长度。
    • 返回值:指向申请内存首地址的指针。失败时返回NULL。
  • void ls_osa_free(void *ptr)
    • 功能:释放参数ptr指向的一块堆内存。
    • 参数说明:
      名称 数据类型 描述
      ptr void * 指向要释放的堆内存的地址。
  • void ls_osa_msleep(unsigned int msec)
    • 功能:睡眠函数,是当前执行线程睡眠指定的毫秒数。
    • 参数说明:
      名称 数据类型 描述
      msec unsigned int 线程挂起的时间,单位为毫秒。
  • long long ls_osa_get_time_ms(void)
    • 功能:获取当前系统时间戳的大小。
    • 参数说明:void。
    • 返回值:系统的时间戳大小(以毫秒为单位)。

多线程接口

  • int ls_osa_mutex_create(void **mutex)
    • 功能: 创建一个互斥量,用于多线程下的同步访问。
    • 参数说明:
      名称 数据类型 描述
      mutex void ** 指向创建互斥量的句柄。
    • 返回值:成功= 0; 失败< 0。
  • void ls_osa_mutex_destroy(void *mutex)
    • 功能:销毁互斥量的句柄。
    • 参数说明:
      名称 数据类型 描述
      mutex void * 互斥量的句柄。
  • int ls_osa_mutex_lock(void *mutex)
    • 功能:锁住一个互斥量。
    • 参数说明:
      名称 数据类型 描述
      mutex void * 互斥量的句柄。
    • 返回值:成功= 0; 失败< 0。
  • int ls_osa_mutex_unlock(void *mutex)
    • 功能:解锁一个互斥量。
    • 参数说明:
      名称 数据类型 描述
      mutex void * 互斥量的句柄。
    • 返回值:成功= 0; 失败< 0。

网络接口

  • 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。
  • void ls_osa_net_disconnect(int fd)
    • 功能:断开网络连接,并释放相应资源。
    • 参数说明:
      名称 数据类型 描述
      fd int 网络连接的句柄。
  • 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。
  • 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

  • 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)。如果输入*id_len小于实际的device id的长度, 将*id_len置为device id的实际长度,同时返回-1。
    • 返回值:成功=0;失败=-1。
    • 示例代码
      #define DEV_ID "12345678"
      #define DEV_ID_LEN 8
      
      int ls_hal_get_dev_id(uint8_t *dev_id, uint32_t *id_len)
      {
          int ret = 0;
      
          if (*id_len < DEV_ID_LEN) {
              if (*id_len != 0) {
                  ls_osa_print("short buffer id len is %d\n", *id_len);
              }
              *id_len = DEV_ID_LEN;
              return -1;
          }
      
          if (!dev_id) {
              return -1;
          }
      
          memcpy(dev_id, DEV_ID, DEV_ID_LEN);
          *id_len = DEV_ID_LEN;
      
          return ret;
      }
  • int ls_hal_open_rsvd_part(int flag)
    • 功能:根据指定的权限flag打开预留的管理分区。如不支持文件系统,直接返回0。
      说明 系统中预留至少2K的Flash存储空间,用于ID²及密钥数据的存储。正常使用和OTA升级时,数据不被擦除。
    • 参数说明:
      名称 数据类型 描述
      flag int
      • LS_HAL_READ: 打开只读。
      • LS_HAL_WRITE:打开只写。
      • LS_HAL_READ | LS_HAL_WRITE:打开读写。
    • 返回值:成功为文件句柄;失败为-1。
  • 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。
  • 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。
  • int ls_hal_close_rsvd_part(int fd)
    • 功能:关闭打开的预留分区。
    • 参数说明:
      名称 数据类型 描述
      fd int 文件句柄。没有文件系统时忽略。
    • 返回值:成功为0;失败为-1。

Secure Storage接口

  • int ls_hal_kv_init(void)
    • 功能:初始化安全存储模块。
    • 参数说明:void。
    • 返回值:成功= 0;失败< 0。
  • void ls_hal_kv_deinit(void)
    • 功能:注销安全存储模块。
    • 参数说明:void。
  • 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。
  • int ls_hal_kv_get(const char *key, void *buffer, int *buffer_len)
    • 功能:根据标识key, 从安全存储中获取对应的数据。
    • 参数说明:
      名称 数据类型 描述
      key const char * 存储数据的标识。
      buffer void * 存储数据的缓存。
      buffer_len int * 缓存长度或读取的数据长度。
    • 返回值:成功= 0;失败< 0。
  • int ls_hal_kv_del(const char *key)
    • 功能:删除安全存储中key标识的数据。
    • 参数说明:
      名称 数据类型 描述
      key const char * 存储数据的标识。
    • 返回值:成功= 0;失败< 0。