security_huks模块下hks_service.c代码评注（四）

本篇概述

本篇接续security_huks模块下hks_service.c代码评注（三），继续讲解hks_service下有关密钥的导入导出服务、密钥删除与判断是否存在服务以及部分与密钥安全性相关的服务函数。

代码框架

hks_service.c
├── transfer&check_service
│ └── hks_service_import_public_key
│ └── hks_service_export_public_key
│ └── hks_service_delete_key
│ └── hks_service_is_key_exist
├── security_service
│ └── hks_service_register_file_callbacks
│ └── hks_service_get_pub_key_alias_list
│ └── hks_service_key_info_init
│ └── hks_service_destroy
│ └── hks_service_refresh_key_info
│ └── hks_service_register_get_hardware_udid_callback

密钥检查服务

1. hks_service_import_public_key

函数功能：导入公钥服务
导出公钥的步骤为：首先要根据密钥别名判断密钥是否能被存储，通过调用hks_is_key_can_store（）实现，接着为密钥信息结构体赋值，填入密钥参数、密钥、保留空间，并将私有密钥置空，最后调用写入密钥存储信息函数进行密钥导入。详细代码和标注如下：

//函数功能：导入公钥服务
int32_t hks_service_import_public_key(const struct hks_blob* key_alias,
    const struct hks_key_param* key_param, const struct hks_blob* key)
{
    //判断输入密钥别名、密钥参数、以及密钥是否合规
    hks_if_true_return_error(((key_alias == NULL) || (key_param == NULL) || (key == NULL)), HKS_ERROR_NULL_POINTER);

    //根据密钥别名判断密钥是否能被存储
    if (hks_is_key_can_store(key_alias,
        HKS_LOCAL_STORAGE_KEY_MAX_NUM) != HKS_BOOL_TRUE)
        return HKS_ERROR_INSUFFICIENT_STORAGE;

    //定义密钥存储信息结构体
    struct hks_storage_key_info key_info;

    //为密钥信息结构体赋值，填入密钥参数、密钥、保留空间，并将私有密钥置空
    key_info.param = (struct hks_key_param*)key_param;
    key_info.public_key = (struct hks_blob*)key;
    key_info.private_key = NULL;
    key_info.reserve[0] = 0;
    key_info.reserve[1] = 0;

    //调用写入密钥存储信息函数进行密钥导入
    return hks_storage_write_key_info(key_alias, &key_info);
}

2. hks_service_export_public_key

函数功能：公钥导出服务
导出公钥的方法就是在检查完传参，定义并初始化密钥信息结构体后调用hks_storage_read_key_info（）函数，从key_alias对应的存储位置读取密钥信息到key_info中去，完成导出工作。详细代码及标注如下：

//函数功能：公钥导出服务
int32_t hks_service_export_public_key(const struct hks_blob* key_alias,
    struct hks_blob* key)
{
    //判断传入参数是否为空
    hks_if_true_return_error(((key_alias == NULL) || (key == NULL)), HKS_ERROR_NULL_POINTER);

    //定义密钥信息结构体
    struct hks_storage_key_info key_info;

    //密钥信息结构体初始化
    key_info.param = NULL;
    key_info.private_key = NULL;
    key_info.public_key = key;
    key_info.reserve[0] = 0;
    key_info.reserve[1] = 0;
    //从key_alias对应的存储位置读取密钥信息到key_info中去
    int32_t status = hks_storage_read_key_info(key_alias, &key_info);

    //判断系统状态看看是否成功导出
    if (status == HKS_STATUS_OK &&
        key_info.public_key->size != CRYPTO_PUBLIC_KEY_BYTES)
        return HKS_ERROR_INVALID_PUBLIC_KEY;
    return status;
}

3. hks_service_delete_key

函数功能：密钥删除服务
调用存储模块密钥信息移除服务，对应删除key_alias所代表的密钥信息。调用模块函数hks_storage_remove_key_info（）如下：

int32_t hks_storage_remove_key_info(const struct hks_blob *key_alias)
{
    if (key_alias == NULL)
        return HKS_ERROR_NULL_POINTER;

    if ((key_alias->size > HKS_ALIAS_MAX_SIZE) || (key_alias->data == NULL))
        return HKS_ERROR_INVALID_ARGUMENT;

    uint8_t *key_pos = NULL;
    int32_t status = hks_get_key_pos(key_alias, &key_pos);

    if (status != HKS_STATUS_OK)
        return status;

    if (key_pos == NULL)
        return HKS_ERROR_KEY_NOT_EXIST;
    
    //将密钥槽中的所有内容置零
    if (memset_s(key_pos, hks_get_key_slot_len(), 0,
        hks_get_key_slot_len()) != EOK)
        return HKS_ERROR_BAD_STATE;

    //减少密钥数
    status = hks_reduce_key_count();
    if (status != HKS_STATUS_OK)
        return status;

    //更新hash头
    status = hks_refresh_header_hash();
    if (status != HKS_STATUS_OK)
        return status;

    //返回将缓冲区信息写入文件后的状态
    status = hks_sync_buf_to_file();

    return status;
}

密钥删除服务函数hks_service_delete_key（）代码及注释如下：

//函数功能：密钥删除服务
int32_t hks_service_delete_key(const struct hks_blob *key_alias)
{
    //调用存储模块密钥信息移除服务，对应删除key_alias所代表的密钥信息
    return hks_storage_remove_key_info(key_alias);
}

4. hks_service_is_key_exist

函数功能：判断密钥存在性服务
该服务主要是通过调用存储部分hks_is_key_exist_in_store（）函数来判断密钥是否已被存储，详细hks_is_key_exist_in_store（）函数代码如下：

int hks_is_key_exist_in_store(const struct hks_blob *key_alias)
{
    //判断密钥别名是否合规
    int32_t status = hks_is_valid_alias(key_alias);

    if (status != HKS_STATUS_OK)
        return HKS_BOOL_FALSE;

    //定义一个密钥存在性终端标记变量
    uint8_t *key_pos = NULL;

    //调用函数hks_get_key_pos（）判断
    status = hks_get_key_pos(key_alias, &key_pos);
    if (status != HKS_STATUS_OK)
        return HKS_BOOL_FALSE;

    //通过终端标记来辨识密钥是否被存储
    if (key_pos != NULL)
        return HKS_BOOL_TRUE;

    return HKS_BOOL_FALSE;
}

函数hks_service_is_key_exist()的代码与标注如下：

//函数功能：判断密钥存在性服务
int32_t hks_service_is_key_exist(const struct hks_blob *key_alias)
{
    uint32_t size = 0;
    //从存储中获取key_alias对应的密钥大小
    int32_t status = hks_storage_get_key_size(key_alias, &size);

    if (status != HKS_STATUS_OK)
        return status;

    //调用函数hks_is_key_exist_in_store来判断密钥是否已被存储
    if ((size > 0) && (hks_is_key_exist_in_store(key_alias) ==
        HKS_BOOL_TRUE))
        return HKS_STATUS_OK;
    return HKS_ERROR_KEY_NOT_EXIST;
}

安全相关服务

1. hks_service_register_file_callbacks

函数功能：注册文件回调服务
该服务通过调用hks文件模块中注册回调函数hks_file_register_callbacks（）进行回调，函数hks_file_register_callbacks（）如下：

//HKS文件注册回调
int32_t hks_file_register_callbacks(const struct hks_file_callbacks *callbacks)
{
    hks_if_true_return_error((callbacks == NULL), HKS_ERROR_NULL_POINTER);
    hks_if_true_return_error((callbacks->read == NULL ||
        callbacks->write == NULL || callbacks->file_size == NULL),
        HKS_ERROR_NULL_POINTER);
    
    //重新生成一个g_file_callbacks文件,并把对应信息写入
    g_file_callbacks.file_size = callbacks->file_size;
    g_file_callbacks.read = callbacks->read;
    g_file_callbacks.write = callbacks->write;

    return HKS_STATUS_OK;
}

注册文件回调服务函数hks_service_register_file_callbacks（）代码及标注如下：

//函数功能：注册文件回调服务
int32_t hks_service_register_file_callbacks(
    const struct hks_file_callbacks *callbacks)
{
    if (callbacks == NULL)
        return HKS_ERROR_NULL_POINTER;

    //调用hks文件模块中注册回调函数进行回调
    return hks_file_register_callbacks(callbacks);
}

2. hks_service_get_pub_key_alias_list

函数功能：获取公钥别名列表服务
该服务通过调用storage模块中获取密钥别名列表函数hks_get_key_alias_list（）完成主服务，函数hks_get_key_alias_list（）如下：

int32_t hks_get_key_alias_list(struct hks_blob *key_alias_list,
    uint32_t *list_count)
{
    uint8_t *buffer = hks_get_buffer();

    if ((buffer == NULL) || (key_alias_list == NULL) ||
        (list_count == NULL))
        return HKS_ERROR_NULL_POINTER;

    uint8_t slot_count_loop = hks_get_slot_count_loop();
    uint8_t *tmp = buffer + hks_get_header_len();
    uint16_t slot_shift = hks_get_key_slot_len();
    uint8_t flags = 0;
    uint8_t alias_size = 0;
    uint32_t num = 0;

    for (uint8_t j = 0; j < slot_count_loop; j++) {
        hks_blob_read_uint8(&flags, tmp);
        if (flags == HKS_SLOT_PUBLIC_KEY_OCCUPY) {
            uint32_t alias_size_shift = sizeof(uint8_t) + HKS_SEALING_NONCE_SIZE;

            hks_blob_read_uint8(&alias_size, (tmp + alias_size_shift));
            uint32_t alias_shift = alias_size_shift + sizeof(uint8_t);

            if (num >= (*list_count))
                return HKS_ERROR_BUFFER_TOO_SMALL;

            if (key_alias_list[num].size < alias_size)
                return HKS_ERROR_BUFFER_TOO_SMALL;

            if (memcpy_s(key_alias_list[num].data, key_alias_list[num].size,
                tmp + alias_shift, alias_size) != EOK)
                return HKS_ERROR_BAD_STATE;

            key_alias_list[num].size = alias_size;
            ++num;
        }
        tmp += slot_shift;
    }
    *list_count = num;
    return HKS_STATUS_OK;
}

获取公钥别名列表服务函数hks_service_get_pub_key_alias_list（）如下：

//函数功能：获取公钥别名列表服务
int32_t hks_service_get_pub_key_alias_list(
    struct hks_blob *key_alias_list, uint32_t *list_count)
{
    if ((key_alias_list == NULL) || (list_count == NULL))
        return HKS_ERROR_NULL_POINTER;

    //调用storage模块中获取密钥别名列表函数完成主服务
    return hks_get_key_alias_list(key_alias_list, list_count);
}

3. hks_service_key_info_init

函数功能：密钥信息初始化服务
该服务的具体代码及标注如下：

//密钥信息初始化服务
int32_t hks_service_key_info_init(void)
{
    //日志信息冲初始化开始与结束信息要求写入
    log_info("hks init : begin");
    int32_t is_key_info_exist = HKS_BOOL_FALSE;
    int32_t status;
    //将文件载入缓冲区中
    status = hks_load_file_to_buffer(HKS_KEY_STORE_FILE_NAME, &is_key_info_exist);
    hks_if_status_error_return(status);

    //调用根密钥组件初始化函数进行初始化
    status = hks_rkc_init(NULL, is_key_info_exist);
    hks_if_status_error_return(status);
    log_info("hks init : end");
    return status;
}

4. hks_service_destroy

函数功能：空间释放服务
该服务是对存储空间的释放与内存空间的释放的封装，代码如下：

//空间释放服务
void hks_service_destroy(void)
{
    //存储空间的释放
    hks_storage_destroy();
    //内存空间的释放
    hks_rkc_destroy();
}

void hks_storage_destroy(void)
{
    hks_clean_buffer();

    int32_t status = hks_sync_buf_to_file();

    log_info("clean key store, status=%d", status);
    (void)status; /* hilink compile will replace log with {} */
    hks_free_ptr(g_storage_image_buffer);
}

void hks_rkc_destroy(void)
{
    //更改根密钥组件配置状态为已删除状态
    g_hks_rkc_cfg.state = HKS_RKC_STATE_ON_DEL;

    uint32_t i = 0;

    //安全删除密钥库文件属性名中的部分
    for (; i < HKS_RKC_KSF_NUM; ++i)
        hks_file_del_s(g_hks_rkc_cfg.ksf_attr.name[i]);

    //清除内存空间
    hks_rkc_clear_mem();
}

5. hks_service_refresh_key_info

函数功能：重置密钥信息服务
该服务的主要思路为：封装功能函数。先进行密钥信息存储的清理，随后进行内存空间的释放，最后进行根密钥组件的初始化。详细代码及标注如下：

//重置密钥信息服务
int32_t hks_service_refresh_key_info(void)
{
    //先进行密钥信息存储的清理
    int32_t status = hks_storage_clean_key_info();
    hks_if_status_error_return(status);

    //内存空间的释放
    hks_rkc_destroy();
    //根密钥组件的初始化
    status = hks_rkc_init(NULL, HKS_BOOL_FALSE);
    return status;
}

6. hks_service_register_get_hardware_udid_callback

函数功能：寄存器获取硬件udid回调服务
该服务的核心在于调用接口函数g_hks_get_hardware_udid_callback返回回调值，接口函数g_hks_get_hardware_udid_callback（）如下：

/*
 * register callback for get hardware UDID(Unique Device Identifier)
 * parameter:
 *     callback - [in]   - The callback functions for get hardware UDID.
 * return value:
 *     success or error code
 */
int32_t hks_reg_get_hardware_udid_callback(
    hks_get_hardware_udid_callback callback)
{
    if (callback == NULL) {
        log_error("invalid callback");
        return HKS_ERROR_NULL_POINTER;
    }

    g_hks_get_hardware_udid_callback = callback;

    return HKS_STATUS_OK;
}

函数hks_service_register_get_hardware_udid_callback（）代码及标注如下：

//寄存器获取硬件udid回调服务
int32_t hks_service_register_get_hardware_udid_callback(
    hks_get_hardware_udid_callback callback)
{
    //调用接口函数g_hks_get_hardware_udid_callback返回回调值
    return hks_reg_get_hardware_udid_callback(callback);
}

本篇小结

至此，hks_service.c服务部分全部代码评析结束，感谢您的学习与交流！