Huks模块之hks_api.c代码评注

最新推荐文章于 2024-09-20 16:56:42 发布

清三皮

最新推荐文章于 2024-09-20 16:56:42 发布

阅读量821

点赞数

文章标签： c语言 harmonyos

本文链接：https://blog.csdn.net/weixin_50294842/article/details/121063899

版权

文章目录

模块功能
1 HksGetSdkVersion
3 HksRefreshKeyInfo
4 HksGenerateKey
5 HksImportKey
7 HksDeleteKey
9 HksKeyExist
10 HksGenerateRandom
11 HksSign
12 HksEncrypt
13 HksDecrypt
14 HksDeriveKey
15 HksGetKeyInfoList
16 HksAttestKey
17 HksGetCertificateChain

模块功能

对使用者client提供hks相关功能接口，包括获取版本信息、加密解密、获取密钥参数集、生成删除密钥、导入导出密钥、密钥的哈希算法、添加密钥的数字签名等等。
本文件与hks_client_ipc.h联系紧密，在进行一些判空排错后调用该文件的函数实现相关功能。
同时也频繁调用hks_param.h中的函数，比如获取参数表等等。

1 HksGetSdkVersion

功能：获取软件版本
传参：存储版本号的地址
返回值：操作成功或失败，
过程：
1 如果version地址为空或地址内数据地址为空则返回空指针错误；
2 如果version地址大小小于版本号长度则返回错误状态；
3 将版本号写进地址（传参指定）中，如果写入失败则返回错误状态，如果成功则在数组结尾添加’\0’结束标志，并根据数组长度设置size大小，返回成功标志。

HKS_API_EXPORT int32_t HksGetSdkVersion(struct HksBlob *sdkVersion)
{
    if ((sdkVersion == NULL) || (sdkVersion->data == NULL)) {
        return HKS_ERROR_NULL_POINTER;
    }
    uint32_t versionLen = strlen(HKS_SDK_VERSION);
    if (sdkVersion->size < (versionLen + 1)) {
        return HKS_ERROR_INVALID_ARGUMENT;
    }
    if (memcpy_s(sdkVersion->data, sdkVersion->size, HKS_SDK_VERSION, versionLen) != EOK) {
        return HKS_ERROR_BAD_STATE;
    }
    sdkVersion->data[versionLen] = '\0';
    sdkVersion->size = versionLen;
    return HKS_SUCCESS;
}
2 HksInitialize
功能：Hks初始化
函数调度：调用 HksClientInitialize()
返回值：初始化结果标志
过程：如果定义了_CUT_AUTHENTICATE_则调用初始化函数，如果未定义则返回hks_success

HKS_API_EXPORT int32_t HksInitialize(void)
{
#ifndef _CUT_AUTHENTICATE_
    HKS_LOG_I("enter initialize");
    int32_t ret = HksClientInitialize();
    HKS_LOG_I("leave initialize, result = %d", ret);
    return ret;
#else
    return HKS_SUCCESS;
#endif
}

3 HksRefreshKeyInfo

功能：更新密钥信息
函数调度：定义在hks_client_ipc.h中的HksClientRefreshKeyInfo()
返回值：更新密钥信息操作结束标志

HKS_API_EXPORT int32_t HksRefreshKeyInfo(void)
{
#ifndef _CUT_AUTHENTICATE_
    HKS_LOG_I("enter refresh key info");
    int32_t ret = HksClientRefreshKeyInfo();
    HKS_LOG_I("leave refresh key info, result = %d", ret);
    return ret;
#else
    return HKS_ERROR_NOT_SUPPORTED;
#endif
}

4 HksGenerateKey

功能：生成密钥操作
传参：密钥别名、密钥参数信息
函数调度： HksGetParam与HksClientGenerateKey
返回值：操作结束标志ret

HKS_API_EXPORT int32_t HksGenerateKey(const struct HksBlob *keyAlias,
    const struct HksParamSet *paramSetIn, struct HksParamSet *paramSetOut)
{
#ifdef HKS_SUPPORT_API_GENERATE_KEY
    HKS_LOG_I("enter generate key");
    struct HksParam *storageFlag = NULL;//声明存储标志地址
    int32_t ret = HksGetParam(paramSetIn, HKS_TAG_KEY_STORAGE_FLAG, &storageFlag);//获取参数，存入存储参数的地址中。
    if ((ret == HKS_SUCCESS) && (storageFlag->uint32Param == HKS_STORAGE_TEMP)) {
        //判断是否成功写入，并且存储地址内param变量为临时标志
        if ((paramSetIn == NULL) || (paramSetOut == NULL)) {
            return HKS_ERROR_NULL_POINTER;
        }
        //判断参数列表是否为空
        ret = HksLocalGenerateKey(paramSetIn, paramSetOut);
        //根据参数列表生成密钥
        HKS_LOG_I("leave generate temp key, result = %d", ret);
        //提示生成临时密钥操作结束
        return ret;
    }
    /* generate persistent keys */
    if ((paramSetIn == NULL) || (keyAlias == NULL)) {
        return HKS_ERROR_NULL_POINTER;
    }
    //判断参数列表与密钥别名是否为空
    ret = HksClientGenerateKey(keyAlias, paramSetIn, paramSetOut);
    HKS_LOG_I("leave generate persistent key, result = %d", ret);
    return ret;
#else//将各种类型强制转换为void型，防止warning
    (void)keyAlias;
    (void)paramSetIn;
    (void)paramSetOut;
    return HKS_ERROR_NOT_SUPPORTED;
#endif
}

5 HksImportKey

功能：导入密钥
传参：密钥别名、参数集、密钥地址
函数调度：HksClientImportKey

HKS_API_EXPORT int32_t HksImportKey(const struct HksBlob *keyAlias,
    const struct HksParamSet *paramSet, const struct HksBlob *key)
{
#ifdef HKS_SUPPORT_API_IMPORT
    HKS_LOG_I("enter import key");
    if ((keyAlias == NULL) || (paramSet == NULL) || (key == NULL)) {
        return HKS_ERROR_NULL_POINTER;
    }
    //判断别名、参数集、密钥是否为空
    int32_t ret = HksClientImportKey(keyAlias, paramSet, key);
    //调用HksClientImportKey，根据别名、参数集、密钥信息来导入密钥
    HKS_LOG_I("leave import key, result = %d", ret);
    return ret;
#else
    (void)keyAlias;
    (void)paramSet;
    (void)key;
    return HKS_ERROR_NOT_SUPPORTED;
#endif
}
6 HksExportPublicKey
功能：导出公钥
传参：公钥别名、公钥参数集、密钥存储地址
函数调度：HksClientExportPublicKey
返回值：公钥导出的操作完成标志

HKS_API_EXPORT int32_t HksExportPublicKey(const struct HksBlob *keyAlias,
    const struct HksParamSet *paramSet, struct HksBlob *key)
{
#ifdef HKS_SUPPORT_API_EXPORT
    HKS_LOG_I("enter export public key");
    if ((keyAlias == NULL) || (key == NULL)) {
        return HKS_ERROR_NULL_POINTER;
    }
    //判断公钥别名与公钥目标导出地址是否为空
    int32_t ret = HksClientExportPublicKey(keyAlias, paramSet, key);
    HKS_LOG_I("leave export public key, result = %d", ret);
    return ret;
#else//如果不支持导出，则将传入的密钥别名、参数集、密钥强制转换成void类型，去除编译警告。
    (void)keyAlias;
    (void)paramSet;
    (void)key;
    return HKS_ERROR_NOT_SUPPORTED;
    //返回不支持操作
#endif
}

7 HksDeleteKey

功能：删除密钥
传参：密钥别名、密钥参数集
函数调度 HksClientDeleteKey(keyAlias, paramSet);
返回值：操作结果标志

HKS_API_EXPORT int32_t HksDeleteKey(const struct HksBlob *keyAlias, const struct HksParamSet *paramSet)
{
#ifdef HKS_SUPPORT_API_DELETE_KEY
    HKS_LOG_I("enter delete key");
    if (keyAlias == NULL) {
        return HKS_ERROR_NULL_POINTER;
    }
    //判断密钥别名是否为空
    int32_t ret = HksClientDeleteKey(keyAlias, paramSet);
    HKS_LOG_I("leave delete key, result = %d", ret);
    return ret;
#else//如果不支持删除密钥操作，则将两个类型的指针强制转换为void类型，去除编译警告
    (void)keyAlias;
    (void)paramSet;
    return HKS_ERROR_NOT_SUPPORTED;
#endif
}
8 HksGetKeyParamSet
功能：获取密钥参数集
传参：密钥别名、密钥参数集导入地址与源地址

HKS_API_EXPORT int32_t HksGetKeyParamSet(const struct HksBlob *keyAlias,
    const struct HksParamSet *paramSetIn, struct HksParamSet *paramSetOut)
{
#ifdef HKS_SUPPORT_API_GET_KEY_PARAM_SET
    HKS_LOG_I("enter get key paramset");
    (void)paramSetIn;//将指针类型强制转换为void类型，去除编译警告
    if ((keyAlias == NULL) || (paramSetOut == NULL)) {
        return HKS_ERROR_NULL_POINTER;
    }
    //判断密钥别名与源地址参数集是否为空
    int32_t ret = HksClientGetKeyParamSet(keyAlias, paramSetOut);
    HKS_LOG_I("leave get key paramset, result = %d", ret);
    return ret;
#else
    (void)keyAlias;
    (void)paramSetIn;
    (void)paramSetOut;
    return HKS_ERROR_NOT_SUPPORTED;
#endif
}

9 HksKeyExist

功能：判断给定密钥是否存在
传参：密钥别名、密钥参数集
函数调度 HksClientKeyExist(keyAlias, paramSet);
返回值：int型操作结果标志或报错

HKS_API_EXPORT int32_t HksKeyExist(const struct HksBlob *keyAlias, const struct HksParamSet *paramSet)
{
#ifdef HKS_SUPPORT_API_KEY_EXIST
    HKS_LOG_I("enter check key exist");
    if (keyAlias == NULL) {
        return HKS_ERROR_NULL_POINTER;
    }
    //检查密钥别名地址是否为空
    int32_t ret = HksClientKeyExist(keyAlias, paramSet);
    HKS_LOG_I("leave check key exist, result = %d", ret);
    return ret;
#else
    (void)keyAlias;
    (void)paramSet;
    return HKS_ERROR_NOT_SUPPORTED;
#endif
}

10 HksGenerateRandom

生成随机数
传参：参数集，随机数存放地址
函数调度：HksClientGenerateRandom(random, paramSet);
返回值：生成结果标志

HKS_API_EXPORT int32_t HksGenerateRandom(const struct HksParamSet *paramSet, struct HksBlob *random)
{
#ifdef HKS_SUPPORT_API_GENERATE_RANDOM
    HKS_LOG_I("enter generate random");
    if (random == NULL) {
        return HKS_ERROR_NULL_POINTER;
    }
    //判断存储随机数的地址是否为空
    int32_t ret = HksClientGenerateRandom(random, paramSet);
    HKS_LOG_I("leave generate random, result = %d", ret);
    return ret;
#else
    (void)paramSet;
    (void)random;
#endif
}

11 HksSign

对数据与密钥添加数字签名
传参：密钥、参数表、源数据、数字签名存储地址
函数调度：HksClientSign(key, paramSet, srcData, signature);
返回值：数字签名添加结束标志，或报错“不支持的操作”

HKS_API_EXPORT int32_t HksSign(const struct HksBlob *key, const struct HksParamSet *paramSet,
    const struct HksBlob *srcData, struct HksBlob *signature)
{
#ifdef HKS_SUPPORT_API_SIGN_VERIFY//判断是否支持数字签名认证
    HKS_LOG_I("enter sign");
    if ((key == NULL) || (paramSet == NULL) || (srcData == NULL) || (signature == NULL)) {
        return HKS_ERROR_NULL_POINTER;
    }
    int32_t ret = HksClientSign(key, paramSet, srcData, signature);
    HKS_LOG_I("leave sign, result = %d", ret);
    return ret;
#else//如果不支持数字签名认证则将传参强制类型转换为void型
    (void)key;
    (void)paramSet;
    (void)srcData;
    (void)signature;
    return HKS_ERROR_NOT_SUPPORTED;
#endif
}

12 HksEncrypt

功能：加密
传参：密钥，密钥参数集，明文，密文存储地址
函数调度：HksGetParam(paramSet, HKS_TAG_IS_KEY_ALIAS, &isKeyAlias);
HksLocalEncrypt(key, paramSet, plainText, cipherText);
返回值：int类型操作结束标志

HKS_API_EXPORT int32_t HksEncrypt(const struct HksBlob *key, const struct HksParamSet *paramSet,
    const struct HksBlob *plainText, struct HksBlob *cipherText)
{
#ifdef HKS_SUPPORT_API_CIPHER
    HKS_LOG_I("enter encrypt");
    if ((key == NULL) || (paramSet == NULL) || (plainText == NULL) || (cipherText == NULL)) {
        return HKS_ERROR_NULL_POINTER;
    }
    //判断密钥、参数集、明文、密文存储地址不为空
    struct HksParam *isKeyAlias = NULL;
    int32_t ret = HksGetParam(paramSet, HKS_TAG_IS_KEY_ALIAS, &isKeyAlias);
    //调用获取参数集的函数
    if ((ret == HKS_SUCCESS) && (!isKeyAlias->boolParam)) {
        //判断获取参数集是否成功
        ret = HksLocalEncrypt(key, paramSet, plainText, cipherText);
        //调用加密函数
        //传参：密钥、参数集、明文、密文
        HKS_LOG_I("leave encrypt with plain key, result = %d", ret);
        return ret;
    }
#ifndef _CUT_AUTHENTICATE_
    ret = HksClientEncrypt(key, paramSet, plainText, cipherText);
    //调用client中的加密函数
    HKS_LOG_I("leave encrypt with persistent key, result = %d", ret);
    return ret;
#else
    return HKS_ERROR_NOT_SUPPORTED;
#endif
#else//强制类型转换，防止warning出现
    (void)key;
    (void)paramSet;
    (void)plainText;
    (void)cipherText;
    return HKS_ERROR_NOT_SUPPORTED;
#endif
}

13 HksDecrypt

功能：hks解密
传参：密钥，参数集，密文，明文存储地址
函数调度：HksLocalDecrypt(key, paramSet, cipherText, plainText);

HKS_API_EXPORT int32_t HksDecrypt(const struct HksBlob *key, const struct HksParamSet *paramSet,
    const struct HksBlob *cipherText, struct HksBlob *plainText)
{
#ifdef HKS_SUPPORT_API_CIPHER
    HKS_LOG_I("enter decrypt");
    if ((key == NULL) || (paramSet == NULL) || (cipherText == NULL) || (plainText == NULL)) {
        return HKS_ERROR_NULL_POINTER;
    }
    //判断密钥、参数集、密文、明文地址是否为空
    struct HksParam *isKeyAlias = NULL;
    int32_t ret = HksGetParam(paramSet, HKS_TAG_IS_KEY_ALIAS, &isKeyAlias);
    //获取参数集，存储在给定的paramset地址中
    if ((ret == HKS_SUCCESS) && (!isKeyAlias->boolParam)) {
        //判断获取参数是否成功，判断密钥与别名是否对应
        ret = HksLocalDecrypt(key, paramSet, cipherText, plainText);
        HKS_LOG_I("leave decrypt with plain key, result = %d", ret);
        return ret;//操作结果标志
    }
#ifndef _CUT_AUTHENTICATE_
    ret = HksClientDecrypt(key, paramSet, cipherText, plainText);
    HKS_LOG_I("leave decrypt with persistent key, result = %d", ret);
    return ret;
#else
    return HKS_ERROR_NOT_SUPPORTED;
#endif
#else
    (void)key;
    (void)paramSet;
    (void)plainText;
    (void)cipherText;
    return HKS_ERROR_NOT_SUPPORTED;
#endif
}

14 HksDeriveKey

功能：根据给定的密钥参数集与主要密钥派生密钥
传参：参数集、主要密钥、派生密钥
函数调度： HksGetParam(paramSet, HKS_TAG_IS_KEY_ALIAS, &isKeyAlias);HksLocalDeriveKey(paramSet, mainKey, derivedKey);
返回值：操作结果标志或报错信息

HKS_API_EXPORT int32_t HksDeriveKey(const struct HksParamSet *paramSet, const struct HksBlob *mainKey,
    struct HksBlob *derivedKey)
{
#ifdef HKS_SUPPORT_API_DERIVE_KEY
    HKS_LOG_I("enter derive key");
    if ((paramSet == NULL) || (mainKey == NULL) || (derivedKey == NULL)) {
        return HKS_ERROR_NULL_POINTER;
    }
    //判断参数集、主要密钥、派生密钥地址是否为空
    struct HksParam *isKeyAlias = NULL;
    int32_t ret = HksGetParam(paramSet, HKS_TAG_IS_KEY_ALIAS, &isKeyAlias);
    //获取密钥参数集、密钥别名
    if ((ret == HKS_SUCCESS) && (!isKeyAlias->boolParam)) {
        //如果获取成功则进行派生密钥操作
        ret = HksLocalDeriveKey(paramSet, mainKey, derivedKey);
        HKS_LOG_I("leave derive key with plain key, result = %d", ret);
        return ret;
    }
#ifndef _CUT_AUTHENTICATE_
    ret = HksClientDeriveKey(paramSet, mainKey, derivedKey);
    HKS_LOG_I("leave derive key with persistent key, result = %d", ret);
    return ret;
#else
    return HKS_ERROR_NOT_SUPPORTED;
#endif
#else
    (void)paramSet;
    (void)mainKey;
    (void)derivedKey;
    return HKS_ERROR_NOT_SUPPORTED;
#endif
}

15 HksGetKeyInfoList

功能：获取密钥信息列表
传参：参数集、密钥信息列表、列表内信息条总数
函数调度： HksClientGetKeyInfoList(keyInfoList, listCount);
返回值：操作结束标志

HKS_API_EXPORT int32_t HksGetKeyInfoList(const struct HksParamSet *paramSet,
    struct HksKeyInfo *keyInfoList, uint32_t *listCount)
{
#ifdef HKS_SUPPORT_API_GET_KEY_INFO_LIST
    HKS_LOG_I("enter get key info list");
    (void)paramSet;
    if ((keyInfoList == NULL) || (listCount == NULL)) {
        return HKS_ERROR_NULL_POINTER;
    }
    //判断密钥信息列表与记录列表信息总数的指针是否为空
    int32_t ret = HksClientGetKeyInfoList(keyInfoList, listCount);
    HKS_LOG_I("leave get key info list, result = %d", ret);
    return ret;
#else
    (void)paramSet;
    (void)keyInfoList;
    (void)listCount;
    return HKS_ERROR_NOT_SUPPORTED;
#endif
}

16 HksAttestKey

公证密钥
传参：密钥别名，参数表，证书链
函数调度：HksClientAttestKey(keyAlias, paramSet, certChain);
返回值：公证密钥操作结果标志

HKS_API_EXPORT int32_t HksAttestKey(const struct HksBlob *keyAlias, const struct HksParamSet *paramSet,
    struct HksCertChain *certChain)
{
#ifdef HKS_SUPPORT_API_ATTEST_KEY
    HKS_LOG_I("enter attest key");
    if ((keyAlias == NULL) || (paramSet == NULL) || (certChain == NULL)) {
        return HKS_ERROR_NULL_POINTER;
    }
    //判断密钥别名、参数表、证书链是否为空
    int32_t ret = HksClientAttestKey(keyAlias, paramSet, certChain);
    HKS_LOG_I("leave attest key, result = %d", ret);
    return ret;
#else
    (void)keyAlias;
    (void)paramSet;
    (void)certChain;
    return HKS_ERROR_NOT_SUPPORTED;
#endif
}

17 HksGetCertificateChain

功能：获取证书链
传参：密钥别名、参数集、证书链
函数调度：HksClientGetCertificateChain(keyAlias, paramSet, certChain);
返回值 int类型的操作结果标志，或报错

HKS_API_EXPORT int32_t HksGetCertificateChain(const struct HksBlob *keyAlias, const struct HksParamSet *paramSet,
    struct HksCertChain *certChain)
{
#ifdef HKS_SUPPORT_API_GET_CERTIFICATE_CHAIN
    HKS_LOG_I("enter get certificate chain");
    if ((keyAlias == NULL) || (paramSet == NULL) || (certChain == NULL)) {
        return HKS_ERROR_NULL_POINTER;
    }
    //判断密钥别名、参数集、证书链地址是否为空
    int32_t ret = HksClientGetCertificateChain(keyAlias, paramSet, certChain);
    HKS_LOG_I("leave get certificate chain, result = %d", ret);
    return ret;
#else
    (void)keyAlias;
    (void)paramSet;
    (void)certChain;
    return HKS_ERROR_NOT_SUPPORTED;
#endif
}