设备厂商使用说明

使用流程

设备厂商使用函谷基础服务的流程:

  1. 请您先申请试用并照实填写申请表。填写完后三个工作日内您将得到回复是否审核通过。
  2. 审核通过后,将同时为您开启函谷线上管理控制台的权限,您可以在管理控制台上下单。
  3. 下单成功后,您就可以按照文档的提示,做设备端和服务端的调试。

在设备端,设备厂商需要完成的工作:

准备工作

设备系统的抽象层

为了适配不同的设备操作系统,设备端HISK SDK定义了设备系统抽象层HAL(Host Abstract Level),抽象层需要由设备厂商根据设备硬件系统自行实现。

基础类型定义,根据目标系统类型分别定义无符号8位类型、16位类型、32位类型,例如:

unsigned char U8
unsigned short U16
unsigned long U32

内存分配/释放/复制/初始化接口实现

void *hal_memory_malloc();
void hal_memory_free(void *ptr);
void hal_memory_set(void *ptr, U16 value, U16 len);
void hal_memory_copy(void *dest, void *source, U16 len);

日志打印

void hal_log(const char *fmt, ...);

序列号数据获取/存储

U32 hal_get_counter();
long hal_set_counter(U32 update_counter);

设备端HISK SDK

函谷HISK SDK以静态库和头文件的方式提供,因此设备厂商需要提供以下交叉编译的信息:

  • 设备硬件信息
  • 编译工具链
  • 编译选项以及编译参数
  • 安全载体种类以及具体型号

安全载体接口抽象层

百度智能云IoT为不同的安全载体厂商制定了统一的安全载体抽象层接口,供函谷HISK SDK调用,安全载体的抽象层接口需要由安全载体厂商和设备厂商共同完成。

  • 安全载体厂商完成抽象接口层的逻辑实现,并提供静态库和头文件或者源码给设备厂商,SE驱动部分抽象成接口
  • 设备厂商完成安全载体抽象接口驱动程序实现以及安全载体的硬件适配。

函谷HISK SDK的交付

设备厂商通过注册并通过审核之后,百度智能云IoT会提供设备厂商HISK SDK的静态库、SDK头文件、样例代码和测试工具函数。

函谷HISK SDK接口调试

百度智能云IoT提供接口调试工具用以设备端测试安全载体的相关接口。

  • 设备厂商根据设备目标系统实现HAL抽象层,使用头文件编译链接HISK SDK静态库和安全载体厂商的静态库或者源码
  • 设备厂商依次调用以下测试函数

    test_hisk_get_active_data();  // 获取激活数据
    test_hisk_get_id();           // 获取唯一设备ID
    test_hisk_encrypt();          // 获取测试加密数据
    test_hisk_decrypt(U8 *data);  // 此接口的参数,再将test_hisk_get_id()返回值提供给百度智能云之后,由百度智能云提供。
    test_hisk_get_auth_code();    // 测试获取认证码
    
  • 设备厂商反馈测试函数的输出,由百度智能云IoT确认结果是否成功

函谷HISK SDK接口说明

HISK SDK封装了底层安全载体、接口的操作细节,设备端应用只需要调用HISK SDK接口进行相关的操作。设备首次使用时需要先调用获取激活数据接口,执行激活流程。激活成功后才能进行其他接口的访问。

预定义类型

原类型 typedef 类型
unsigned char U8
unsigned short U16
unsigned long U32

获取激活数据接口

方法 接口说明
U16 hisk_get_active_data(U8 *data, U16 *data_len); 获取激活数据

请求参数

参数名称 参数类型 输入/输出 说明
data U8 * in/out 入参为存放激活数据字串buf的起始地址,出参时buf中存储激活数据,buf长度为256字节
data_len U16 * in/out 入参为激活数据的buf长度,出参为激活数据的实际长度

返回参数

类型 说明
U16 方法执行结果,0 表示成功,失败参考设备错误码

加密接口

方法 接口说明
U16 hisk_encrypt(U8 *in_data, U16 in_data_len, U8 *out_data, U16 *out_data_len); 加密数据

请求参数

参数名称 参数类型 输入/输出 说明
in_data U8 * in 存放输入的数据起始地址
in_data_len U16 in 输入的数据长度,长度不超过113个字节
out_data U8 * in/out 入参为存放输出的数据buf起始地址,出参时buf中存储处理的数据,buf长度为256字节
out_data_len U16 * in/out 入参为参数out_data的buf长度,出参为实际长度

返回参数

类型 说明
U16 方法执行结果,0 表示成功,失败参考设备错误码

解密接口

方法 接口说明
U16 hisk_decrypt(U8 *in_data, U16 in_data_len, U8 *out_data, U16 *out_data_len); 解密数据

请求参数

参数名称 参数类型 输入/输出 说明
in_data U8 * in 存放输入的数据起始地址,数据如果是base64编码,需要先进行base64解码
in_data_len U16 in 输入的数据长度,长度为256字节
out_data U8 * in/out 入参为存放输出的数据buf起始地址,出参时buf中存储处理的数据,buf长度为113字节
out_data_len U16 * in/out 入参为参数out_data的buf长度,出参为实际长度

返回参数

类型 说明
U16 方法执行结果,0 表示成功,失败参考设备错误码

获取设备ID

方法 接口说明
U16 hisk_get_id(U8 *id, U16 id_len); 获取设备唯一ID

请求参数

参数名称 参数类型 输入/输出 说明
id U8 * in/out 入参为存放设备ID字串的buf起始地址,出参时buf中存储设备ID,长度为16字节
id_len const U16 in 设备ID的长度

返回参数

类型 说明
U16 方法执行结果,0 表示成功,失败参考设备错误码

获取设备认证码接口

方法 接口说明
U16 hisk_get_auth_code(U8 *challenge, U16 challenge_len, U8 *extra, U16 extra_length,const U8 sig_encode_type, U8 *data, U16 *data_len) 获取设备认证码

请求参数

参数名称 参数类型 输入/输出 说明
challenge U8 * in 存放输入的认证码的挑战码的起始地址
challenge_len U16 in 输入的挑战码的长度
extra U8 * in 存放输入的额外数据的起始地址,可以为null
extra_length U16 * in 输入的额外数据的长度,可以为0
sig_encode_type const U8 in 签名的编码格式,目前仅支持base64格式类型(0x00)
data U8 * in/out 入参为存放输出的数据buf起始地址,出参时buf中存储处理的数据,buf长度至少为227字节
data_len U16 * in/out 入参为参数out_data的buf长度,出参为实际长度

返回参数

类型 说明
U16 方法执行结果,0 表示成功,失败参考设备错误码

设备错误码

返回值 描述
0x0 执行正确
0xEE 未知错误
0xFF 解密数据过长
0xFE 加密数据过长
0xFD Buff长度错误
0xFC 内存分配错误
0xFB 签名验证错误
0xFA 序号验证错误
0xF9 参数错误
0xF8 未知安全载体类型

函谷HISK SDK使用方式

目前函谷需要配合百度IoT智能家居平台使用。具体查看百度IoT智能家居介绍

在百度IoT智能家居中使用函谷安全的流程具体见如下:

百度IoT智能家居产品注册

设备厂商首先需要注册登录百度智能云,并在智能家居平台进行相关的产品注册和设备生成,具体操作可参考智能家居操作指南,因为设备需要使用函谷安全功能,故需要特别注意:在基本信息填写的过程中,对 “是否含SE安全芯片” 单选项,需要勾选 “”,如下图所示,其它步骤同智能家居文档的介绍。

移植百度IoT智能家居SDK

如果设备厂商使用HISK SDK的设备具有联网功能,则其需要移植百度IoT智能家居的SDK,SDK的地址为:https://github.com/baidu/iot-edge-c-sdk,文档地址为:https://github.com/baidu/iot-edge-c-sdk/tree/master/iothub_client/samples/iot_smarthome_client_sample。如果设备不具有联网能力,则无需适配移植此SDK,但若其通过网关等设备进行联网,则其对应的网关设备需要进行此SDK的移植和适配。

安全载体适配

设备厂商在注册完成后,通过提交工单与函谷安全的人员联系,获取(购买)对应安全载体厂商的芯片(样片),并获取对应芯片的驱动和芯片相关的SDK,然后进行相关芯片集成和HISK SDK的移植和适配。

联网集成

当设备厂商完成硬件上芯片的集成,以及相关SDK适配后,在本地测试成功后,即可以开始进行相关的联网能力的集成。联网能力的集成涉及多个端的集成和开发,包括:设备(本身),设备对应的App,百度IoT智能家居平台,设备厂商后端服务等。

具体接入过程描述如下:

  1. 产品属性设置

    设备厂商根据设备的属性在对应智能家居平台里注册的产品里设置相关属性。如下图所示:

  2. 设备激活

    在设备完成配网后,保证设备具有联网能力,设备需要先通过激活后,设备才能联上智能家居云端。这个激活过程通常可以通过设备对应的App以及设备厂商自己的云端服务协同对此设备设备进行激活。具体的激活流程如下:

    注意:配网需要设备厂商自己实现

    通用步骤可以参考:

    1. 手机App请求添加设备,获取激活认证信息
    2. 设备发送激活认证信息给手机App,此步骤中,设备需要调用HISK SDK获取设备激活数据。
    3. App将用户信息、设备激活认证信息发送给厂商后端服务平台进行设备激活
    4. 厂商后端服务平台用对应设备的激活认证信息请求智能家居平台对对应设备进行激活。(此步骤中,激活接口中的se参数通过HISK SDK中的hisk_get_active_data 接口获取)
    5. 智能家居平台返回激活结果给厂商后端服务平台
    6. 厂商后端服务平台返回激活结果给手机App
    7. 手机App返回激活结果设备

    注意:步骤4,5为必须,其余步骤厂商可依据具体场景自行调整。

  3. 安全传输

    设备完成激活后,即可以正常开始使用函谷的安全能力同百度IoT智能家居平台进行安全通信。如下图所示:

    此过程中,被加密的数据值为设备的各个属性值,与智能家居平台里设置的各个属性相互对应。在HISK 数据加密步骤也即调用SDK 中的 hisk_encrypt ,当设备收到云端传过来的数据后,HISK 数据解密也即调用 SDK 的 hisk_decrypt。设备与智能家居平台的数据格式具体请参照智能家居平台的数据格式说明。

  4. 云端服务对接

    设备厂商的服务端当需要获取设备数据,或者对设备进行反控时,可以通过智能家居平台的API接口获取,具体可以见智能家居平台API接口描述

常见问题

目标系统抽象层的counter接口有什么用?

counter接口用以在相关接口中增加序号机制,用以防止重放攻击。

counter接口为什么由设备厂商提供?

counter数据会存储在设备硬件上,可以由设备厂商来决定counter数据存储的位置,因为不同的硬件设备的生命周期并不相同,由设备厂商来决定存储位置,可以最大优化硬件的使用寿命。