返回值
@@ -502,23 +581,27 @@ HUKS Core的初始化，包括锁，加密算法库，authtoken key和根密钥
- - -
-#### HuksHdiGetKeyProperties
+#### checkkeyvalidity
**接口描述**
获取密钥属性。
**接口原型**
-int32_t HuksHdiGetKeyProperties(const struct HksParamSet *paramSet, const struct HksBlob *key);
+int32_t CheckKeyValidity(struct IHuks *self, const struct HuksParamSet *paramSet,
+ const struct HuksBlob *encKey);
参数说明
- const struct HksParamSet *paramSet
- 空对象
+ struct IHuks *self
+ HUKS HDI函数指针结构体指针
+
+ const struct HuksParamSet *paramSet
+ 用于校验密钥完整性接口的参数，默认传空
- const struct HksBlob *key
- 要获取属性的密钥
+ const struct HuksBlob *encKey
+ 待校验密钥完整性的密钥材料
@@ -533,26 +616,30 @@ HUKS Core的初始化，包括锁，加密算法库，authtoken key和根密钥
- - -
-#### HuksHdiAttestKey
+#### AttestKey
**接口描述**
获取密钥证书。
**接口原型**
-int32_t (*HuksHdiAttestKey)(const struct HksBlob *key, const struct HksParamSet *paramSet, struct HksBlob *certChain);
+int32_t AttestKey(struct IHuks *self, const struct HuksBlob *encKey, const struct HuksParamSet *paramSet,
+ struct HuksBlob *certChain);
参数说明
- const struct HksBlob *key
- 要获取证书的密钥
+ struct IHuks *self
+ HUKS HDI函数指针结构体指针
- const struct HksParamSet *paramSet
- 获取证书操作的参数
+ const struct HuksBlob *encKey
+ 要获取证书的密钥对材料密文
- struct HksBlob *certChain
- 出参，存放证书
+ const struct HuksParamSet *paramSet
+ 获取密钥证书操作的参数，如challenge等
+
+ struct HuksBlob *certChain
+ 出参，存放证书链，格式参考上述[证书链格式](#证书链格式)
@@ -575,25 +662,29 @@ HUKS Core的初始化，包括锁，加密算法库，authtoken key和根密钥
- - -
-#### HuksHdiExportChipsetPlatformPublicKey
+#### ExportChipsetPlatformPublicKey
**接口描述**
导出芯片平台级密钥对的公钥。
**接口原型**
-int32_t (*HuksHdiExportChipsetPlatformPublicKey)(const struct HksBlob *salt, enum HksChipsetPlatformDecryptScene scene, struct HksBlob *publicKey);
+int32_t ExportChipsetPlatformPublicKey(struct IHuks *self, const struct HuksBlob *salt,
+ enum HuksChipsetPlatformDecryptScene scene, struct HuksBlob *publicKey);
参数说明
- const struct HksBlob *salt
+ struct IHuks *self
+ HUKS HDI函数指针结构体指针
+
+ const struct HuksBlob *salt
用来派生芯片平台密钥对时的派生因子
- enum HksChipsetPlatformDecryptScene scene
+ enum HuksChipsetPlatformDecryptScene scene
业务预期进行芯片平台解密的场景
- struct HksBlob *publicKey
+ struct HuksBlob *publicKey
出参为ECC P256的x y轴值裸数据，各32字节
@@ -618,25 +709,29 @@ HUKS Core的初始化，包括锁，加密算法库，authtoken key和根密钥
- - -
-#### HuksHdiUpgradeKey
+#### UpgradeKey
**接口描述**
升级密钥文件。当密钥文件版本号小于最新版本号时，触发该升级能力。
**接口原型**
-int32_t (*HuksHdiUpgradeKey)(const struct HksBlob *oldKey, const struct HksParamSet *paramSet, struct HksBlob *newKey);
+int32_t UpgradeKey(struct IHuks *self, const struct HuksBlob *encOldKey, const struct HuksParamSet *paramSet,
+ struct HuksBlob *encNewKey);
参数说明
- const struct HksBlob *oldKey
+ struct IHuks *self
+ HUKS HDI函数指针结构体指针
+
+ const struct HuksBlob *encOldKey
待升级的密钥文件数据
- const struct HksParamSet *paramSet
+ const struct HuksParamSet *paramSet
升级密钥文件数据的参数
- struct HksBlob *newKey
+ struct HuksBlob *newKey
出参，升级后的密钥文件数据
@@ -652,26 +747,379 @@ HUKS Core的初始化，包括锁，加密算法库，authtoken key和根密钥
- - -
+- - -
+
+#### GenerateRandom
+
+**接口描述**
+
+生成安全随机数
+
+**接口原型**
+int32_t GenerateRandom(struct IHuks *self, const struct HuksParamSet *paramSet, struct HuksBlob *random);
+
+
+ 参数说明
+
+ struct IHuks *self
+ HUKS HDI函数指针结构体指针
+
+ const struct HuksParamSet *paramSet
+ 待生成安全随机数的参数，如长度
+
+ struct HuksBlob *random
+ 出参，随机数
+
+
+
+
+
+ 返回值
+
+ - HKS_SUCCESS：成功
+
+ - 其他：失败
+
+
+- - -
+
+- - -
+
+#### Sign
+
+**接口描述**
+
+对数据进行签名
+
+**接口原型**
+int32_t Sign(struct IHuks *self, const struct HuksBlob *encKey, const struct HuksParamSet *paramSet,
+ const struct HuksBlob *srcData, struct HuksBlob *signature);
+
+
+ 参数说明
+
+ struct IHuks *self
+ HUKS HDI函数指针结构体指针
+
+ const struct HuksBlob *encKey
+ 用于签名的密钥对材料（密文）
+
+ const struct HuksParamSet *paramSet
+ 用于签名的参数，如摘要模式
+
+ const struct HuksBlob *srcData
+ 用于签名的数据
+
+ struct HuksBlob *signature
+ 出参，数据签名
+
+
+
+
+
+ 返回值
+
+ - HKS_SUCCESS：成功
+
+ - 其他：失败
+
+
+- - -
+
+- - -
+
+#### Verify
+
+**接口描述**
+
+对数据签名进行验签
+
+**接口原型**
+int32_t Verify(struct IHuks *self, const struct HuksBlob *encKey, const struct HuksParamSet *paramSet,
+ const struct HuksBlob *srcData, const struct HuksBlob *signature);
+
+
+ 参数说明
+
+ struct IHuks *self
+ HUKS HDI函数指针结构体指针
+
+ const struct HuksBlob *encKey
+ 用于验签的密钥对材料（密文）
+
+ const struct HuksParamSet *paramSet
+ 用于验签的参数，如摘要模式
+
+ const struct HuksBlob *srcData
+ 待验签的数据
+
+ const struct HuksBlob *signature
+ 用于验签的签名
+
+
+
+
+
+ 返回值
+
+ - HKS_SUCCESS：成功
+
+ - 其他：失败
+
+
+- - -
+
+- - -
+
+#### Encrypt
+
+**接口描述**
+
+对数据进行单次加密，相比密钥会话接口，该接口需满足一次调用即可完成加密操作
+
+**接口原型**
+int32_t Encrypt(struct IHuks *self, const struct HuksBlob *encKey, const struct HuksParamSet *paramSet,
+ const struct HuksBlob *plainText, struct HuksBlob *cipherText);
+
+
+ 参数说明
+
+ struct IHuks *self
+ HUKS HDI函数指针结构体指针
+
+ const struct HuksBlob *encKey
+ 用于加密的密钥材料（密文）
+
+ const struct HuksParamSet *paramSet
+ 用于加密的密钥参数，如密钥工作模式、填充模式等
+
+ const struct HuksBlob *plainText
+ 待加密的数据明文
+
+ const struct HuksBlob *cipherText
+ 加密后的数据密文
+
+
+
+
+
+ 返回值
+
+ - HKS_SUCCESS：成功
+
+ - 其他：失败
+
+
+- - -
+
+- - -
+
+#### Decrypt
+
+**接口描述**
+
+对数据进行单次解密，相比密钥会话接口，该接口需要满足一次调用完成解密操作
+
+**接口原型**
+int32_t Decrypt(struct IHuks *self, const struct HuksBlob *encKey, const struct HuksParamSet *paramSet,
+ const struct HuksBlob *cipherText, struct HuksBlob *plainText);
+
+
+ 参数说明
+
+ struct IHuks *self
+ HUKS HDI函数指针结构体指针
+
+ const struct HuksBlob *encKey
+ 用于解密的密钥材料（密文）
+
+ const struct HuksParamSet *paramSet
+ 用于解密的密钥参数，如密钥工作模式、填充模式等
+
+ const struct HuksBlob *cipherText
+ 待解密的数据密文
+
+ const struct HuksBlob *plainText
+ 解密后的数据明文
+
+
+
+
+
+ 返回值
+
+ - HKS_SUCCESS：成功
+
+ - 其他：失败
+
+
+- - -
+
+- - -
+
+#### AgreeKey
+
+**接口描述**
+
+对密钥进行协商，相比密钥会话接口，该接口需要满足一次调用完成密钥协商操作
+
+**接口原型**
+int32_t AgreeKey(struct IHuks *self, const struct HuksParamSet *paramSet,
+ const struct HuksBlob *encPrivateKey, const struct HuksBlob *peerPublicKey, struct HuksBlob *agreedKey);
+
+
+ 参数说明
+
+ struct IHuks *self
+ HUKS HDI函数指针结构体指针
+
+ const struct HuksParamSet *paramSet
+ 用于协商的参数，如协商密钥的长度
+
+ const struct HuksBlob *encPrivateKey
+ 用于协商的密钥对材料（密文）
+
+ const struct HuksBlob *peerPublicKey
+ 用于协商密钥对公钥（明文）
+
+ struct HuksBlob *agreedKey
+ 出参，协商出的密钥明文
+
+
+
+
+
+ 返回值
+
+ - HKS_SUCCESS：成功
+
+ - 其他：失败
+
+
+- - -
+
+- - -
+
+#### DeriveKey
+
+**接口描述**
+
+对密钥进行派生，相比密钥会话接口，该接口需要满足一次调用完成密钥派生操作
+
+**接口原型**
+int32_t DeriveKey(struct IHuks *self, const struct HuksParamSet *paramSet, const struct HuksBlob *encKdfKey,
+ struct HuksBlob *derivedKey);
+
+
+ 参数说明
+
+ struct IHuks *self
+ HUKS HDI函数指针结构体指针
+
+ const struct HuksParamSet *paramSet
+ 用于密钥派生的参数，如派生密钥的长度
+
+ const struct HuksBlob *encKdfKey
+ 用于派生的密钥材料（密文）
+
+ struct HuksBlob *derivedKey
+ 出参，派生出的密钥（明文）
+
+
+
+
+
+ 返回值
+
+ - HKS_SUCCESS：成功
+
+ - 其他：失败
+
+
+- - -
+
+- - -
+
+#### mac
+
+**接口描述**
+
+根据密钥生成消息认证码
+
+**接口原型**
+int32_t Mac(struct IHuks *self, const struct HuksBlob *encKey, const struct HuksParamSet *paramSet,
+ const struct HuksBlob *srcData, struct HuksBlob *mac);
+
+
+ 参数说明
+
+ struct IHuks *self
+ HUKS HDI函数指针结构体指针
+
+ const struct HuksBlob *encKey
+ 用于生成消息认证码的密钥材料（密文）
+
+ const struct HuksParamSet *paramSet
+ 用于生成消息认证码的参数
+
+ const struct HuksBlob *srcData
+ 消息数据
+
+ struct HuksBlob *mac
+ 出参，消息认证码
+
+
+
+
+
+ 返回值
+
+ - HKS_SUCCESS：成功
+
+ - 其他：失败
+
+
+- - -
### 开发步骤
-HDI接口到HUKS Core的适配在以下目录中：
+#### 代码目录
+
+HDI接口的适配在以下目录中：
```undefined
-// base/security/user_auth/services/huks_standard/huks_engine/main
+//drivers_peripheral/huks
├── BUILD.gn # 编译脚本
-├── core_dependency # 实现依赖
+├── hdi_service # 实现依赖，通过dloppen方式引用libhuks_engine_core_standard.z.so(软实现的HUKS Core，仅用于参考)
+ ├── huks_sa_type.h # HUKS服务层的数据结构定义
+ ├── huks_sa_hdi_struct.h # libhuks_engine_core_standard.z.so中函数指针结构体的定义
+ ├── huks_hdi_template.h # HUKS服务层和HDI接口数据结构的转化适配
+ ├── huks_hdi_service.c # HUKS直通式HDI服务层的接口实现
+ └── huks_hdi_passthrough_adapter.c # HUKS直通式HDI服务层到软实现HUKS Core的适配层
+└── test # HUKS HDI接口unittest和fuzztest
+ ├── BUILD.gn # 编译脚本
+ ├── fuzztest # fuzz测试
+ └── unittest # 单元测试
+```
+
+HUKS Core软实现的代码在以下目录中：
+
+```undefined
+//base/security/huks/services/huks_standard/huks_engine
+├── BUILD.gn # 编译脚本
+├── core_dependency # HUKS Core依赖
└── core # HUKS Core层的软实现
├── BUILD.gn # 编译脚本
├── include
└── src
├── hks_core_interfaces.c # HDI到HUKS Core的适配层
- └── hks_core_service.c # 具体实现
+ └── hks_core_service.c # HUKS Core详细实现
└── ... #其他功能代码
```
-关于HUKS Core接口的具体实现，开发者必须采用三段式。以下是三段式的开发步骤以及HUKS CORE的代码示例，开发者应参考以下代码实现所有的Hdi接口。
-其他HUKS Core接口的代码可以参考[hks_core_service.c](https://gitee.com/openharmony/security_huks/blob/master/services/huks_standard/huks_engine/main/core/src/hks_core_service.c)文件。
+#### 适配样例
+
+下文以HUKS Core中的密钥会话Init\Update\Finish接口适配作为一个样例，介绍基本流程。详细代码参考[HUKS源码目录](https://gitee.com/openharmony/security_huks)
1. 创建一个句柄，通过这个句柄在session中存储密钥操作相关的信息，使得外部可以通过这个句柄分多次进行同一密钥操作。
@@ -679,8 +1127,8 @@ HDI接口到HUKS Core的适配在以下目录中：
//三段式Init接口
- int32_t HksCoreInit(const struct HksBlob *key, const struct HksParamSet *paramSet, struct HksBlob *handle,
- struct HksBlob *token)
+ int32_t HksCoreInit(const struct HuksBlob *key, const struct HuksParamSet *paramSet, struct HuksBlob *handle,
+ struct HuksBlob *token)
{
HKS_LOG_D("HksCoreInit in Core start");
uint32_t pur = 0;
@@ -749,8 +1197,8 @@ HDI接口到HUKS Core的适配在以下目录中：
```c
//三段式Update接口
- int32_t HksCoreUpdate(const struct HksBlob *handle, const struct HksParamSet *paramSet, const struct HksBlob *inData,
- struct HksBlob *outData)
+ int32_t HksCoreUpdate(const struct HuksBlob *handle, const struct HuksParamSet *paramSet, const struct HuksBlob *inData,
+ struct HuksBlob *outData)
{
HKS_LOG_D("HksCoreUpdate in Core start");
uint32_t pur = 0;
@@ -781,7 +1229,7 @@ HDI接口到HUKS Core的适配在以下目录中：
uint32_t size = HKS_ARRAY_SIZE(g_hksCoreUpdateHandler);
for (i = 0; i < size; i++) {
if (g_hksCoreUpdateHandler[i].pur == pur) {
- struct HksBlob appendInData = { 0, NULL };
+ struct HuksBlob appendInData = { 0, NULL };
ret = HksCoreAppendAuthInfoBeforeUpdate(keyNode, pur, paramSet, inData, &appendInData);
if (ret != HKS_SUCCESS) {
HKS_LOG_E("before update: append auth info failed");
@@ -815,8 +1263,8 @@ HDI接口到HUKS Core的适配在以下目录中：
```c
//三段式Finish接口
- int32_t HksCoreFinish(const struct HksBlob *handle, const struct HksParamSet *paramSet, const struct HksBlob *inData,
- struct HksBlob *outData)
+ int32_t HksCoreFinish(const struct HuksBlob *handle, const struct HuksParamSet *paramSet, const struct HuksBlob *inData,
+ struct HuksBlob *outData)
{
HKS_LOG_D("HksCoreFinish in Core start");
uint32_t pur = 0;
@@ -848,7 +1296,7 @@ HDI接口到HUKS Core的适配在以下目录中：
for (i = 0; i < size; i++) {
if (g_hksCoreFinishHandler[i].pur == pur) {
uint32_t outDataBufferSize = (outData == NULL) ? 0 : outData->size;
- struct HksBlob appendInData = { 0, NULL };
+ struct HuksBlob appendInData = { 0, NULL };
ret = HksCoreAppendAuthInfoBeforeFinish(keyNode, pur, paramSet, inData, &appendInData);
if (ret != HKS_SUCCESS) {
HKS_LOG_E("before finish: append auth info failed");