设备取证

API 列表

以下是API 列表及简要说明 (详见 components/das/aiot_das_api.h)

API 使用概述

DAS 模块用于发现 IoT 设备上的安全风险, API 的使用流程如下:

• 首先参考 aiot_mqtt_api.h 的说明, 保证成功建立与物联网平台的 MQTT 连接
• 调用 aiot_das_init 函数初始化 DAS 会话, 获取会话句柄
• 调用 aiot_das_setopt 函数配置 DAS 会话的参数。常用配置项见 aiot_das_setopt 函数的具体说明
• 创建新线程，定时调用 aiot_das_stepping 函数，步进驱动 DAS 取证服务并上报风险事件
• 程序退出的时候，调用 aiot_das_deinit 函数销毁 DAS 实例。

初始化 DAS 实例

初始化 DAS 核心服务，并返回 DAS 的实例句柄，用于后续相关函数调用。 函数原型

void *aiot_das_init(void);
			

参数无。 返回值若初始化成功，则返回 DAS 的 实例句柄。若初始化失败，则返回 NULL 。

配置 DAS 实例

对 DAS 实例进行额外的配置，目前支持绑定 MQTT 上云通道、设置系统固件版本号。 函数原型

typedef enum {
    AIOT_DASOPT_MQTT_HANDLE,
    AIOT_DASOPT_SET_FIRMWARE_VERSION,
    AIOT_DASOPT_MAX,
} aiot_das_option_t;

int32_t aiot_das_setopt(void *handle, aiot_das_option_t option, void *data);
			

参数handle：由 aiot_das_init 函数返回的 DAS 实例句柄。option：aiot_das_option_t 枚举类型。取值如下：

• AIOT_DASOPT_MQTT_HANDLE：此时，data 的值为 MQTT 的实例句柄；如不设置，DAS 则无法和云端通信。
• AIOT_DASOPT_SET_FIRMWARE_VERSION：此时，data 的值为字符串类型的系统固件版本号信息；如不设置，则默认版本号为 0.0.0 。
• AIOT_DASOPT_MAX：option 取值若大于等于此值，都表示参数错误。

data：根据 option 取值的不同而内容不同，详见上述 option 参数说明。 返回值函数调用成功，返回 STATE_SUCCESS。函数调用失败，返回 负数 。

步进取证

DAS 需要定期步进才能采集安全事件，并上报的云端。在实际使用中，可单独创建一个线程，每隔一段时间（推荐100毫秒）定期调用 DAS 步进函数。 函数原型

int32_t aiot_das_stepping(void *handle);
			

参数handle：由 aiot_das_init 函数返回的 DAS 句柄。 返回值函数调用成功，返回 STATE_SUCCESS。函数调用失败，返回 负数 。

注销 DAS 实例

在进程退出之前，需要调用 DAS 反初始化函数以释放 DAS 占用的系统资源。 函数原型

int32_t aiot_das_deinit(void **handle)
			

参数handle：由 aiot_das_init 函数返回的 DAS 句柄的地址。注意是 void ** 类型。 返回值函数调用成功，返回 STATE_SUCCESS。函数调用失败，返回 负数 。

例程讲解

现对照 demos/das_basic_demo.c 例程程, 分步骤讲解如何使用 API。

这个例程适用于 Linux 这类支持 pthread 的 POSIX 设备, 它演示了用 DAS SDK 配合 MQTT 连接的使用方法。

1. 初始化 MQTT 实例，并创建两个线程：
   • 一个线程用于保活长连接
   • 一个线程用于接收消息, 并在有消息到达时进入默认的数据回调, 在连接状态变化时进入事件回调
2. 初始化 DAS 实例，并绑定 MQTT 实例、设置固件版本号。
3. 开始 DAS 循环步进。
4. 销货 DAS 和 MQTT 实例。

PS. 需要用户关注或修改的部分, 已经用 TODO 在注释中标明。

设置设备密钥

例程使用的设备密钥是测试使用的, 所以客户在体验时请替换如下的TODO部分, 传入设备真实的设备密钥信息。

/* TODO: 替换为自己设备的三元组 */
char *product_key       = "a13FN5TplKq";
char *device_name       = "soc_basic_demo";
char *device_secret     = "Vew7vR7JyMcRuEEHdpplGCCZz3xqNkRy";
			

初始化 MQTT

初始化 MQTT 并建立连接。

/* 创建1个MQTT客户端实例并内部初始化默认参数 */
mqtt_handle = aiot_mqtt_init();
....
/* 与服务器建立MQTT连接 */
res = aiot_mqtt_connect(mqtt_handle);
			

创建子线程

以下代码创建1个子线程, 专门用于保活设备与云平台之间的长连接

/* 创建一个单独的线程, 专用于执行aiot_mqtt_process, 它会自动发送心跳保活, 以及重发QoS1的未应答报文 */
g_mqtt_process_thread_running = 1;
res = pthread_create(&g_mqtt_process_thread, NULL, demo_mqtt_process_thread, mqtt_handle);
			

以下代码创建1个子线程, 专门用于接收从云平台推送下来的MQTT消息

/* 创建一个单独的线程用于执行aiot_mqtt_recv, 它会循环收取服务器下发的MQTT消息, 并在断线时自动重连 */
g_mqtt_recv_thread_running = 1;
res = pthread_create(&g_mqtt_recv_thread, NULL, demo_mqtt_recv_thread, mqtt_handle);
			

DAS 初始化并绑定 MQTT

/* 建立MQTT连接, 并开启保活线程和接收线程 */
res = demo_mqtt_start(&mqtt_handle);
if (res < 0) {
    printf("demo_mqtt_start failed\n");
    return -1;
}

/* 创建1个das客户端实例并内部初始化默认参数 */
das_handle = aiot_das_init();
if (das_handle == NULL) {
    demo_mqtt_stop(&mqtt_handle);
    printf("aiot_das_init failed\n");
    return -1;
}

res = aiot_das_setopt(das_handle, AIOT_DASOPT_MQTT_HANDLE, mqtt_handle);
if (res < STATE_SUCCESS) {
    printf("aiot_das_setopt AIOT_DASOPT_MQTT_HANDLE failed, res: -0x%04X\n", -res);
    aiot_das_deinit(&das_handle);
    demo_mqtt_stop(&mqtt_handle);
    return -1;
}

res = aiot_das_setopt(das_handle, AIOT_DASOPT_SET_FIRMWARE_VERSION, (void *)"mzf_firmware_version");
if (res < STATE_SUCCESS) {
    printf("aiot_das_setopt AIOT_DASOPT_SET_FIRMWARE_VERSION failed, res: -0x%04X\n", -res);
}
			

DAS 循环步进

DAS 需要定期步进才能采集安全事件，并上报的云端。在实际使用中，可单独创建一个线程，每隔一段时间（推荐100毫秒）定期调用 DAS 步进函数。

while (1) {
    aiot_das_stepping(das_handle);
    sleep(1);
}
			

注销 DAS 和 MQTT 实例

res = aiot_das_deinit(&das_handle);
res = demo_mqtt_stop(&mqtt_handle);
			

编译并允许 DAS Demo

在 Linux 系统上，terminal 定位到 SDK 目录下，编译并允许 DAS demo。

make
sudo ./output/das-basic-demo
			

如果一切顺利，如下是 DAS demo 输出的上报信息日志。

[LK-030A] > 08 01 18 C8 CD EF DD AC  2E 22 7E 0A 37 64 61 73 | ........."~.7das
[LK-030A] > 3A 31 2E 32 2E 30 2C 70  72 6F 66 69 6C 65 3A 72 | :1.2.0,profile:r
[LK-030A] > 74 6F 73 7C 4C 4B 2C 66  69 72 6D 77 61 72 65 3A | tos|LK,firmware:
[LK-030A] > 6D 7A 66 5F 66 69 72 6D  77 61 72 65 5F 76 65 72 | mzf_firmware_ver
[LK-030A] > 73 69 6F 6E 12 13 6F 73  3A 72 74 6F 73 2C 61 72 | sion..os:rtos,ar
[LK-030A] > 63 68 3A 78 38 36 5F 36  34 1A 2E 6E 65 74 66 6C | ch:x86_64..netfl
[LK-030A] > 6F 77 3A 31 30 2E 36 35  2E 30 2E 32 30 31 7C 35 | ow:10.65.0.201|5
[LK-030A] > 33 7C 33 30 2E 34 32 2E  38 33 2E 31 32 7C 34 34 | 3|30.42.83.12|44
[LK-030A] > 37 39 37 7C 32 7C 75 64  70                      | 797|2|udp