[C++知识库]Huks模块之hks_client.c代码评注

一：综述

该模块主要用来对接应用层，其函数调度与hks_access.c密切相关，主要是在调用hks_access.c函数之前进行检查工作，如判断密钥的有效性、参数列表的有效性、密钥类型是否支持相关算法等等。

二：模块功能

1.获取版本信息

主要功能：将版本信息写入给定的内存地址中
传参：记录版本信息的地址
返回值：无
函数调度：主要是一些c语言内置函数，并无对hks其他模块函数的调度。

void hks_get_sdk_version(struct hks_blob* sdk_version)
{
    if (sdk_version == NULL)//判断传入的版本信息是否为空
        return;
    const size_t version_len = strlen(HKS_SDK_VERSION);//计算存储着版本号字符串的长度
    if ((sdk_version->data != NULL) && (sdk_version->size > version_len)) {
        //如果版本号不为空并且版本号大小大于版本号字符串长度，则将版本号字符串写入传进的记录着版本信息的目标地址
        if (memcpy_s(sdk_version->data, sdk_version->size, HKS_SDK_VERSION, version_len) != EOK) {
            log_error("memcpy_s fail");
            return;
        }
        sdk_version->data[version_len] = '\0';//在字符串末尾添加\0，标识字符串结尾。
        sdk_version->size = (uint32_t)version_len + 1;//
    }
}

2.密钥的生成

功能：通过给定密钥参数生成密钥，并用给定的密钥别名为之命名
传参：密钥别名，密钥参数
返回值：标志完成或未完成的status
函数调度：hks_access.c中的生成密钥函数

HKS_DLL_API_PUBLIC int32_t hks_generate_key(const struct hks_blob* key_alias,
    const struct hks_key_param* key_param)
{
#ifdef _CUT_AUTHENTICATE_
    return HKS_ERROR_NOT_SUPPORTED;
//检查是否有权限
#else
    HKS_TRACE_IN;
    hks_if_status_error_return(hks_is_valid_auth_id(key_param));
    //传参：判断是否为授权id
    
    hks_if_status_error_return(hks_is_valid_alias(key_alias));
    //判断是否为有效别名
    if (key_param->key_type != HKS_KEY_TYPE_EDDSA_KEYPAIR_ED25519)
        return HKS_ERROR_NOT_SUPPORTED;
    //仅支持type为HKS_KEY_TYPE_EDDSA_KEYPAIR_ED25519的生成
    return hks_access_generate_key(key_alias, key_param);
    //调用access中的生成密钥函数
    
#endif
}

3.非对称密钥的生成

功能：生成公钥与私钥
传参：密钥参数，私钥，公钥
返回值：标志生成完成或失败的标识
函数调度：hks_access.c模块中的生成密钥函数

//生成非对称密钥
//传参：密钥参数，私钥，公钥
HKS_DLL_API_PUBLIC int32_t hks_generate_asymmetric_key(
    const struct hks_key_param* key_param, struct hks_blob* pri_key,
    struct hks_blob* pub_key)
{
#ifdef _CUT_AUTHENTICATE_
    return HKS_ERROR_NOT_SUPPORTED;
#else
    HKS_TRACE_IN;//进入hks模块
    hks_if_true_return_error((key_param == NULL), HKS_ERROR_NULL_POINTER);
    //检查是否为有效参数
    if (key_param->key_type != HKS_KEY_TYPE_ECC_KEYPAIR_CURVE25519)
        return HKS_ERROR_NOT_SUPPORTED;
    //如果密钥类型不是HKS_KEY_TYPE_ECC_KEYPAIR_CURVE25519，则不支持生成操作。
    if (key_param->key_mode != hks_alg_ecdh(HKS_ALG_SELECT_RAW))
        return HKS_ERROR_NOT_SUPPORTED;
    //如果密钥参数的模式不是hks_alg_ecdh(HKS_ALG_SELECT_RAW)，则不支持后续操作。
    if ((pri_key == NULL) || (pri_key->data == NULL) || (pub_key == NULL) ||
        (pub_key->data == NULL))
       //如果私钥或公钥为空指针或其data指针为空，返回空指针错误
        return HKS_ERROR_NULL_POINTER;
    return hks_access_generate_key_ex(key_param, pri_key, pub_key);
    //调用access中的生成一对非对称密钥函数
    //传参：密钥参数，私钥，公钥
#endif
}

4.公钥的导入

功能：导入公钥
传参：公钥别名，公钥参数，公钥
函数返回值：status标志该步骤完成与否
函数调度：hks_access.c模块中的导入密钥操作

HKS_DLL_API_PUBLIC int32_t hks_import_public_key(
    const struct hks_blob* key_alias,
    const struct hks_key_param* key_param, const struct hks_blob* key)
{
#ifdef _CUT_AUTHENTICATE_
    return HKS_ERROR_NOT_SUPPORTED;
#else
    HKS_TRACE_IN;
    hks_if_status_error_return(hks_is_valid_auth_id(key_param));
    //检查是否为错误权限
    int32_t status = hks_is_valid_alias(key_alias);
    //检查是否为有效公钥别名
    if (status != HKS_STATUS_OK)
        return status;
    if (key_param->key_type != HKS_KEY_TYPE_EDDSA_PUBLIC_KEY_ED25519)
        return HKS_ERROR_NOT_SUPPORTED;
    //检查公钥类型是否支持ED25519公钥加密方式
    hks_if_true_return_error((key == NULL), HKS_ERROR_NULL_POINTER);
    if ((key->data == NULL) || (key->size != CRYPTO_PUBLIC_KEY_BYTES))
        return HKS_ERROR_INVALID_PUBLIC_KEY;
    //判断公钥是否为空，或大小是否不支持加密
    return hks_access_import_key(key_alias, key_param, key);
    //调用hks_access.c中的导入密钥函数
#endif
}

5.密钥的删除

//传参：密钥别名
//函数调度：hks_access_delete_key
//函数返回：status标志该步骤完成

HKS_DLL_API_PUBLIC int32_t hks_delete_key(const struct hks_blob* key_alias)
{
#ifdef _CUT_AUTHENTICATE_
    return HKS_ERROR_NOT_SUPPORTED;
#else
    
    int32_t status = hks_is_valid_alias(key_alias);
    //检查密钥别名是否有效
    if (status != HKS_STATUS_OK)
        return status;
    //如果无效则不可进行删除
    return hks_access_delete_key(key_alias);
    //调用hks_access.c中的删除密钥功能
#endif
}

6.判断密钥是否存在

//传参：密钥别名
//函数调度：hks_access_is_key_exist
//函数返回：标志密钥是否存在的status变量

HKS_DLL_API_PUBLIC int32_t hks_is_key_exist(const struct hks_blob* key_alias)
{
#ifdef _CUT_AUTHENTICATE_
    return HKS_ERROR_NOT_SUPPORTED;
#else
    int32_t status = hks_is_valid_alias(key_alias);
    
    if (status != HKS_STATUS_OK)
        return status;
    //判断密钥别名是否有效，有效则调用判断密钥是否存在
    status = hks_access_is_key_exist(key_alias);
    return status;
#endif
}

7.非对称签名

//功能：非对称签名
//传参：密钥别名，密钥参数列表，哈希，签名
//函数调度： hks_access_sign

HKS_DLL_API_PUBLIC int32_t hks_asymmetric_sign(
    const struct hks_blob* key_alias,
    const struct hks_key_param* key_param, const struct hks_blob* hash,
    struct hks_blob* signature)
{
#ifdef _CUT_AUTHENTICATE_
    return HKS_ERROR_NOT_SUPPORTED;
#else
    int32_t status = hks_is_valid_alias(key_alias);
    //判断密钥是否有效
    hks_if_status_error_return(status);
    //判断依赖步骤是否为错误返回
    hks_if_true_return_error(((key_param == NULL) || (hash == NULL) ||
        (signature == NULL)), HKS_ERROR_NULL_POINTER);
    //判断参数表，哈希，签名是否为空
    if ((key_param->key_type != HKS_KEY_TYPE_EDDSA_KEYPAIR_ED25519) ||
        ((key_param->key_usage & HKS_KEY_USAGE_SIGN) == 0))
        return HKS_ERROR_NOT_SUPPORTED;
    //检查密钥类型是否支持ED25519算法
    //判断参数是否与有效标识一致
    if ((hash->data == NULL) || (hash->size <= 0))
        return HKS_ERROR_INVALID_ARGUMENT;
    //判断哈希是否为空或大小为负，即判断哈希是否有效
    if ((signature->data == NULL) ||
        (signature->size < HKS_SIGNATURE_MIN_SIZE))
        return HKS_ERROR_BUFFER_TOO_SMALL;
    //判断签名内容是否为空，签名大小是否小于hks最小签名尺寸
    //返回：缓存区太小

    return hks_access_sign(key_alias, key_param, hash, signature);
    //调用hks_access.c中的签名函数，返回完成标记status
#endif
}