使用ID²-KM将设备接入自建的物联网系统

1. 术语

1. Soft-KM（Key Management）密钥管理，由阿里提供的软件安全沙箱，基于软件加固和虚拟化技术提供对密钥（IoT ID²）的安全保护。

2. OSA（Operation System Abstractor Layer）操作系统抽象层，定义内存申请和释放、日志打印、系统时间、网络通信等接口，非遵循POSIX标准的OS，需重新适配这些接口。

3. HAL（Hardware Abstractor Layer）硬件抽象层，根据设备硬件特性，完成对加解密算法、设备唯一ID、密钥管理和数据安全存储的接口适配。

4. ID² OTP（One-Time Provisioning）一次性烧录，也称ID²空发，指设备在第一次联网时，通过网络请求，下发ID²数据烧录到设备中。

5. TLS（Transport Layer Security）安全传输层协议， 用于两个通信实体之间，保护通信数据的私密性和完整性。

6. IoT（Internet of things）物联网，基于互联网实现万物互联。

2. ID²产品架构

1. ID²控制中心：

• ID²的Web控制台，提供对ID²产线灌装、ID²产品和配额申请、以及ID²使用统计的管理。

2. ID²服务中心：

• ID²在云端的应用，提供ID²的各种安全能力，包括ID²密钥安全分发、设备认证、基于ID²的安全连接协议等；同时，提供各种能力的云端接口，支持业务平台的二次开发，支持不同的安全业务需求和场景。

3. ID² Client SDK（ID²设备端SDK）：

• ID²在设备端的功能组件和软件开发框架，可支持不同操作系统和不同硬件，为IoT设备提供基于ID²的端到端的设备认证、数据加解密等各种安全能力。

3. ID²接入流程

3.1 概述

• 客户自建服务的方式，ID²通过云端和设备端接口的方式，提供基于ID²的设备认证和会话密钥加密下发，应用数据通过下发的会话密钥进行加密传输。

• ID²对接步骤如下：

3.2 购买ID²授权：

1. 单机购买链接 - 购买ID²认证授权。

2. 选择地域和可用区、规格、购买数量和有效期：

3.3 创建产品：

1. 登录IoT安全产品控制台控制台，在左侧导航栏，选择入门 > IoT设备身份认证，单击独立使用卡片的开始接入按钮。

2. 在配置产品页面创建新产品&分配ID²授权，然后单击下一步按钮。

• 选择产品：请选择创建新产品，并输入产品名称。

• ID²有效期：请选择1年、3年、或5年。

• 分配ID²授权数量：请输入ID²授权数量，最小值为1，最大值为1000。

3. 在查看配置信息页面，记录下ProductKey、ProductSecret。

• ProductKey：设备所属产品的ProductKey。

• ProductSecret：由IoT设备身份认证颁发的产品密钥，与 ProductKey 成对出现。

3.4 选择设备认证算法：

IoT设备身份认证支持国际算法（AES-128、AES-192、AES-256）和国密算法（SM1、SM2、SM4-128），能满足企业不同安全等级的需求。

说明

国密算法SM1需要配合ID²安全芯片使用，SM2用于业务数据完整性校验和加密。

创建的ID²产品默认选择的设备认证算法是AES-128；如需选择其他设备认证算法，请按如下步骤操作：

• 在查看配置信息页面，单击设备认证算法后的更换按钮，查看支持的密钥类型（如SM4-128），并确认。

• 在查看配置信息页面，记录下实例ID、ProductKey、ProductSecret。

• 实例ID：阿里云物联网平台的实例标识。企业实例ID是字符串，公共实例ID是符号“-”。

• ProductKey：设备所属产品的ProductKey。

• ProductSecret：由IoT设备身份认证颁发的产品密钥，与 ProductKey 成对出现

3.5 集成云端SDK

3.5.1 阿里云账号的AccessKey

• AccessKey是调用阿里云API的身份凭证，请参见获取AccessKey。

• 需要注意的是AccessKey的归属账号必须与创建产品时的账号保持一致。

3.5.2 下载云端SDK

1. 登录IoT安全产品控制台控制台，在左侧导航栏，选择文档与工具，在IoT设备身份认证云端SDK中单击立即下载右侧的复制按钮获取最新的下载地址，在云端环境执行命令获取云端SDK。

wget https://id2-schip-online.oss-cn-shanghai.aliyuncs.com/static_resources/id2_server_sdk/ID2_Server_SDK.tar

2. 在云端环境执行命令tar -xvf ID2_Server_SDK.tar 完成解压，执行命令cd <解压SDK后的目录>。设备端SDK的目录说明见表格内容：

3.5.3 集成云端SDK

1. 添加Maven项目依赖，引入阿里云Java SDK公共包。

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-java-sdk-core</artifactId>
    <version>4.5.6</version>
</dependency>

2. 导入云端SDK中的lib/aliyun-java-sdk-id2-1.1.4.jar到项目工程中，初始化云端SDK。

public static String ACCESS_KEY = null;
public static String ACCESS_SECRET = null;

public static String REGION_ID = "cn-shanghai";
public static String END_POINT = "id2." + REGION_ID + ".aliyuncs.com";

// Load ACCESS_KEY and ACCESS_SECRET From Config File
loadConfigProperties("xxx.conf");

IClientProfile profile = DefaultProfile.getProfile(REGION_ID, ACCESS_KEY, ACCESS_SECRET);
DefaultProfile.addEndpoint(REGION_ID, PRODUCT_CODE, END_POINT);
client = new DefaultAcsClient(profile);

3. 发起调用，ID²云端SDK为每个API封装了一个类，命名为${API名称}+"Request"，如VerifyRequest，用于API的调用请求，ID²云端API列表请参考服务端API。

• ID²空发

OtpGetId2Request request = new OtpGetId2Request();
request.setDeviceAuthCode(authCode);
request.setApiVersion(1.1.2);

OtpGetId2Response response = client.getAcsResponse(request);

• 获取ID²认证挑战字

GetServerRandomRequest request = new GetServerRandomRequest();
request.setId2(id2Id);
request.setApiVersion(1.1.2);

GetServerRandomResponse response = client.getAcsResponse(request);
System.out.println("GetServerRadom requestId:" + response.getRequestId());

• ID²设备认证和业务密钥加密

VerifyAndEncryptRequest request = new VerifyAndEncryptRequest();
request.setApiVersion(1.1.2);
request.setProductKey(productKey);
request.setId2(id2Id);
request.setAuthCode(authCode);
request.setData(keyInfo);

VerifyAndEncryptResponse response = client.getAcsResponse(request);
System.out.println("VerifyAndEncrypt requestId:" + response.getRequestId());

4. 应用集成ID²云端SDK的示例代码，请参考demos/ID2SPMessage

3.6 集成设备端SDK：

3.6.1 ID²设备端SDK框架：

1. iTLS：轻量的安全连接协议TLS，基于ID²完成TLS的握手认证和密钥协议，提供应用数据的加密传输。

2. ID²：IoT设备认证和数据加密的对外接口，上层应用/协议基于此接口进行开发。

3. KM：密钥管理模块，支持不同形式的载体：

   1. Soft-KM：软件沙箱，基于软件加固和虚拟化技术提供对ID²密钥的安全保护。

      2. SE（Secure Element）：安全芯片，基于物理防护机制，提供对ID²密钥的安全保护，通过AT指令对设备提供ID²的运算指令。

4. Crypto：提供统一的加解密算法接口。

5. OSA：操作系统适配接口，厂商需根据使用的OS，重新进行接口适配。

6. HAL：硬件适配接口，提供算法库和Soft-KM的适配接口，厂商需根据选择的硬件平台，重新进行接口适配。

3.6.2 下载设备端SDK：

1. 登录IoT安全产品控制台，在左侧导航栏，选择文档与工具，在IoT设备身份认证设备端SDK中单击立即下载右侧的复制按钮获取最新的下载地址，执行命令获取设备端SDK。

wget https://id2-schip-online.oss-cn-shanghai.aliyuncs.com/static_resources/id2_client_sdk/ID2_Client_SDK.tar

2. 执行命令tar -xvf ID2_Client_SDK.tar完成解压，执行命令cd <解压SDK后的目录>。设备端SDK的目录说明见表格内容：

3.6.3 集成设备端SDK：

调用设备端ID²的接口，完成ID²空发，ID²设备认证和数据加密等功能，工作原理图如下：

• ID²空发：

• 通过ID²产品的ProductSecret，生成ID²的空发认证码（AuthCode），发送到云端调用ID²服务端的接口，完成ID²的申请和下发

• ID²设备认证和数据加密：

• 基于挑战字认证方式，通过在设备端调用ID² SDK生成ID²的设备认证码，发送到云端调用ID²的云端SDK，完成ID²的设备认证和会话密钥的加密；然后，在设备端调用ID² SDK的解密接口，完成会话密钥的解密

使用自有的应用，完成如下的集成工作：

1. 设备硬件及系统层集成，详情请参考ID²安全Agent适配接口

• OSA接口适配：实现src/osa/ls_osa.c中的接口，参考目录下__DEMO__的实现。

• HAL接口适配：实现src/hal/km/demo/ls_hal_km.c中的接口，通过hal_test测试用例验证（成功日志： “HAL KM Test Pass”），参考目录下__DEMO__的实现。

1. 设备应用层集成，详情请参考设备端API

• 设备应用首先调用ID²的初始化函数，完成设备端SDK的初始化。

{
    int ret;

     ret = id2_client_init();
     if (ret != IROT_SUCCESS) {
        ls_osa_print("id2 client init fail, %d\n", ret);
        return -1;
     }
}

• 获取ID²设备端的烧录状态：

  • 如ID²已烧录（is_prov == true），退出ID²空发流程

{
    int ret = 0;
    bool is_prov = false;

    ret = id2_client_get_prov_stat(&is_prov);
    if (ret != IROT_SUCCESS) {
        ls_osa_print("id2 client get prov stat fail, %d\n", ret);
        return -1;
    } 
}

• 生成ID²设备端的空发认证码。

{
    int ret = 0;
    uint8_t auth_code[ID2_MAX_AUTH_CODE_LEN] = {0};
    uint32_t auth_code_len = ID2_MAX_AUTH_CODE_LEN;

    ret = id2_client_get_otp_auth_code(
              (uint8_t *)product_secret, (int)strlen(product_secret),
               auth_code, &auth_code_len);
    if (ret != IROT_SUCCESS) {
        ls_osa_print("id2_client_get_otp_auth_code fail, %d\n", ret);
        return -1;
    }
}

• ID²空发的网络请求和响应。

  • authCode：ID²空发认证码的Base64编码

  • otpData：ID²云端下发的空发数据（Base64格式）

# ID²空发请求：
{commandId:xxx, authCode: xxx}

# ID2空发响应：
{commandId:xxx, otpData: xxx}

• 存储ID²密钥到设备安全存储区。

{
    int ret = 0;

    ret = id2_client_load_otp_data(otp_data, otp_len);
    if (ret != IROT_SUCCESS) {
        ls_osa_print("id2 load otp data fail, %d\n", ret);
        return -1;
    }
}

• 获取设备端的ID² ID。

{
    int ret = 0;
    uint8_t id2_id[ID2_ID_MAX_LEN + 1] = {0};
    uint32_t id2_id_len = ID2_ID_MAX_LEN;

    ret = id2_client_get_id(id2_id, &id2_id_len);
    if (ret != IROT_SUCCESS) {
        ls_osa_print("id2 client get id fail, %d\n", ret);
        return -1;
    }
}{
    int ret = 0;
    uint8_t id2_id[ID2_ID_MAX_LEN + 1] = {0};
    uint32_t id2_id_len = ID2_ID_MAX_LEN;

    ret = id2_client_get_id(id2_id, &id2_id_len);
    if (ret != IROT_SUCCESS) {
        ls_osa_print("id2 client get id fail, %d\n", ret);
        return -1;
    }
}

• ID²认证挑战字的网络请求和响应。

# ID²认证挑战字的请求：
{commandId:xxx, Id2Id: xxx}

# ID2认证挑战字的响应：
{commandId:xxx, challenge: xxx}

• 获取设备端的ID²认证码。

{
    int ret = 0;
    uint8_t auth_code[ID2_MAX_AUTH_CODE_LEN] = {0};
    uint32_t auth_code_len = ID2_MAX_AUTH_CODE_LEN;

    ret = id2_client_get_challenge_auth_code(
              challenge, NULL, 0, auth_code, &auth_code_len);
    if (ret != IROT_SUCCESS) {
        ls_osa_print("id2 client get challenge auth code fail, %d\n", ret);
        return -1;
    }
}

• 设备端认证和数据加密的网络请求和响应。

  • cipherData：ID²云端下发的加密数据

# ID²设备认证和数据加密的请求：
{commandId:xxx, productKey:xxx, Id2Id:xxx, authCode:xxx}

# ID2设备认证和数据加密的响应：
{commandId:xxx, cipherData: xxx}

• 解密ID²云端加密下发的数据。

{
    int ret = 0;

    ret = id2_client_decrypt(cipher_data, cipher_len, cipher_data, &cipher_len);
    if (ret != IROT_SUCCESS) {
        ls_osa_print("id2 client decrypt fail\n");
        return -1;
    }
}

• 应用集成ID²设备SDK的示例代码，请参考demos/spdemo

1. 设备端SDK的编译：

• 在ID² SDK的根目录，执行命令vi ./make.settings打开文件, 修改CONFIG_LS_ID2_KEY_TYPE的值

  • 同ID²产品选择的认证算法保持相同

• 执行命令“make clean & make plat=xxx”进行编译

  • Linux x86_64默认使用系统中的GCC作为编译工具，且默认指定“plat=x86_64”参数

  • 如要编译其他架构，如armhf，在make.rules中配置编译工具，运行编译命令“make clean & make plat=armhf”

3.7 业务数据加密

1. 方式一：运行设备端自有的应用和自建的SP Server，进行ID²认证和加密，以及业务数据加密的调试。

2. 方式二：使用演示示例：

• 部署EMQX物联网平台，详情参见EMQX安装和部署

  • 本节描述在Ubuntu 22.04上通过Docker部署EMQX物联网平台的示例

  • 安装和启动Docker工具：

# Install Docker
curl -fsSL get.docker.com -o get-docker.sh
sudo sh get-docker.sh --mirror Aliyun

# Start Docker
sudo systemctl enable docker
sudo systemctl start docker

# Get Docker Version
docker -v

• 使用Docker安装EMQX物联网平台：

# Get emqx-5.1.3 docker image
docker pull emqx/emqx:5.1.3

# Start docker emqx instance
docker run -d --name emqx -p 1883:1883 emqx/emqx:5.1.3

# Get docker instance info
docker ps

• 部署云端演示示例，在ID²云端SDK根目录，配置vi demos/ID2SPMessage/Id2SpDemo.conf文件中的AccessKey和AccessSecret信息。

• 执行命令cd demos/ID2SPMessage，执行命令java -jar Id2SpDemo.jar启动云端演示示例。

• 在ID²设备端SDK目录，执行命令vi tools/ls_sp_demo.sh填写如下参数：

  • HostAddr：云端演示示例的IP地址，localhost代表本机网络。

  • ProductKey：ID²产品的ProductKey。

  • ProductSecret：ID²产品的ProductSecret。

  • PublishData：设备端应用上报的业务数据，建议不超过1024字节。

• 执行命令./tools/ls_sp_demo.sh运行设备端演示示例，查看设备端打印的日志。

  • 在设备端日志中，可以看到完成ID²的设备认证，以及通过ID²加密下发SP Key Info；设备端通过ID²设备端接口解密后，获得明文的Key ID和Data

  • 在设备端日志中，可看到由SPKey加密下发的业务数据（“SP Server Subscribed Cipher Data”）；通过在调用SPKey解密后，可得到明文的下行业务数据（“SP_Server_Hello”）

• 在云端查看打印的日志。

  • 可看到由SPKey加密的业务数据（"Device Published Cipher Data"）

  • 使用SPKey解密后，可得到正确的上行业务数据（“SP_Client_Hello”）

3. 查看设备状态：

• 登录产品控制台，在左侧导航栏，选择资产>设备，查看设备状态为正常，安全状态为安全。