OpenHarmony解读之设备认证：数据接收管理-获取HiChain实例(1)

一、概述

在OpenHarmony中，设备认证模块作为安全子系统的子模块，负责设备间可信关系的建立、维护、使用、撤销等全生命周期的管理，实现可信设备间的互信认证和安全会话密钥协商，是搭载OpenHarmony的设备进行可信互联的基础平台能力。
在上一篇博客OpenHarmony深度解读之分布式软总线：HiChain机制部分源码解析中提到，HiChain机制是OpenHarmony实现设备互联安全的一种协议机制，接下来的博客将沿着之前的逻辑接着往下分析，重点针对本端接收到的数据包进行更进一步的解析，即进入到真正的设备认证模块的消息解析。在之前进行数据包字段解析之后，字段Module的值在MODULE_HICHAIN到MODULE_AUTH_SDK之间时，将会进入到HiChain机制处理阶段，本文重点介绍HiChain实例的获取阶段，即设备认证的准备阶段。

二、源码分析

这一模块的源码位于：/base/security/deviceauth。

1. HiChain实例的获取主要是在hichain.c文件的get_instance函数中实现的，下面我们一起来详细分析一下这个函数：

/*
函数功能：获取hichain实例
函数参数：
    identity：会话基本信息
    type：hichain设备类型
    call_back：hichain回调函数
函数返回值：
    成功：返回hichain结构体地址
    失败：返回NULL
*/
DLL_API_PUBLIC hc_handle get_instance(const struct session_identity *identity, enum hc_type type,
    const struct hc_call_back *call_back)
{
    LOGI("Begin get instance");
    if (check_identity(identity) != HC_OK) {//检查hc的基本信息是否符合规范
        LOGE("Identity error");
        return NULL;
    }
    if (check_call_back(call_back) != HC_OK) {//检查callback结构体的函数指针是否为空
        LOGE("Call back error");
        return NULL;
    }

#if !(defined(_CUT_STS_) || defined(_CUT_STS_SERVER_) || defined(_CUT_EXCHANGE_) || defined(_CUT_EXCHANGE_SERVER_))
    int32_t ret = key_info_init();//初始化密钥信息
    if (ret != HC_OK) {
        LOGE("Call key info init failed, status=%d", ret);
        return NULL;
    }
#endif

    struct hichain *hichain = (struct hichain *)MALLOC(sizeof(struct hichain));//定义一个hichain实例并为其申请空间
    if (hichain == NULL) {//申请内存失败
        LOGE("Alloc memory failed");
        return NULL;
    }
    (void)memset_s(hichain, sizeof(*hichain), 0, sizeof(*hichain));//清空该实例空间
    //初始化该hichain实例对象的相关属性
    hichain->identity = *identity;//hichain基本信息
    hichain->type = type;//hichain设备类型
    hichain->state = INIT_STATE;//hichain状态为初始化
    hichain->last_state = INIT_STATE;//hichain最终状态
    hichain->cb = *call_back;//hichain回调函数

#if !(defined(_CUT_STS_) || defined(_CUT_STS_SERVER_) || defined(_CUT_EXCHANGE_) || defined(_CUT_EXCHANGE_SERVER_))
    build_self_lt_key_pair(hichain);//创建自己的long store/term密钥对
#endif

    LOGI("Get instance success");
    return hichain;
}

2. 在get_instance函数中，首先检查HC的会话标识信息和回调函数是否有效，通过函数check_identity和check_call_back实现，具体源码分析如下：

/*检查hc的基本信息是否符合规范*/
static int32_t check_identity(const struct session_identity *identity)
{
    check_ptr_return_val(identity, HC_INPUT_ERROR);//健壮性检查identity是否为空
    if (identity->package_name.length > HC_PACKAGE_NAME_BUFF_LEN) {//如果会话包的名称长度大于名称缓冲区的大小，则返回错误
        LOGE("Package name length error, %u > %u", identity->package_name.length, HC_PACKAGE_NAME_BUFF_LEN);
        return HC_INPUT_ERROR;
    }
    if (identity->service_type.length > HC_SERVICE_TYPE_BUFF_LEN) {//如果服务类型的长度大于预留缓冲区大小，则返回错误
        LOGE("Service type length error, %u > %u", identity->service_type.length, HC_SERVICE_TYPE_BUFF_LEN);
        return HC_INPUT_ERROR;
    }
    return HC_OK;
}
/*检查callback函数是否为空*/
static int32_t check_call_back(const struct hc_call_back *call_back)
{
    check_ptr_return_val(call_back, HC_INPUT_ERROR);//检查call_back是否为空，若为空则直接返回错误码
    check_ptr_return_val(call_back->transmit, HC_INPUT_ERROR);//检查transmit是否为空，若为空则直接返回错误码
    check_ptr_return_val(call_back->get_protocol_params, HC_INPUT_ERROR);//检查get_protocol_params是否为空，若为空则直接返回错误码
    check_ptr_return_val(call_back->set_session_key, HC_INPUT_ERROR);//检查set_session_key是否为空，若为空则直接返回错误码
    check_ptr_return_val(call_back->set_service_result, HC_INPUT_ERROR);//检查set_service_result是否为空，若为空则直接返回错误码
    check_ptr_return_val(call_back->confirm_receive_request, HC_INPUT_ERROR);//检查confirm_receive_request是否为空，若为空则直接返回错误码
    return HC_OK;
}

#define check_ptr_return_val(d_ptr, d_val) \//检查参数d_ptr是否为空
    do { \
        if ((d_ptr) == NULL) { \//若为空
            return (d_val); \//则直接返回参数d_val
        } \
    } while (0)

3. 接着在函数key_info_init中进行初始化密钥信息，具体函数分析如下：

/*
函数功能：初始化密钥信息
函数参数：无
函数返回值：
    成功：返回成功码
    失败：返回失败码
*/
int32_t key_info_init(void)
{
    int32_t hks_status = hks_init();//hks初始化
#if (defined(_SUPPORT_SEC_CLONE_) || defined(_SUPPORT_SEC_CLONE_SERVER_))
    return hks_status;
#else
    if (hks_status == 0) {//如果hks状态为0，则直接返回成功
        return ERROR_CODE_SUCCESS;
    } else if ((hks_status == HKS_ERROR_INVALID_KEY_FILE) || (hks_status == HKS_ERROR_READ_FILE_FAIL)) {//如果hks状态为"无效密钥文件错误"和"读文件失败错误"
        LOGE("Key info init failed, status=%d", hks_status);
        hks_status = hks_refresh_key_info();//hks机制刷新密钥信息和根密钥信息
        if (hks_status == 0) {//如果刷新之后状态为0，则返回成功
            return ERROR_CODE_SUCCESS;
        }
        LOGE("Key info refresh failed, status=%u", hks_status);//如果刷新失败，则返回失败码
        return ERROR_CODE_FAILED;
    }

    return ERROR_CODE_FAILED;
#endif
}

三、小结

本文重点介绍了hichain实例获取的部分内容，如初始信息检查，密钥信息的初始化等，其余内容将在下篇博客中进行介绍。