1# HuksKeyApi 2 3 4## 概述 5 6描述HUKS向应用提供密钥库能力,包括密钥管理及密钥的密码学操作等功能。 管理的密钥可以由应用导入或者由应用调用HUKS接口生成。 7 8**系统能力:** SystemCapability.Security.Huks 9 10**起始版本:** 9 11 12 13## 汇总 14 15 16### 文件 17 18| 名称 | 描述 | 19| -------- | -------- | 20| [native_huks_api.h](native__huks__api_8h.md) | 声明用于访问HUKS的API。<br>**引用文件**:<huks/native_huks_api.h> <br>**库**:libhuks_ndk.z.so | 21 22 23### 函数 24 25| 名称 | 描述 | 26| -------- | -------- | 27| struct [OH_Huks_Result](_o_h___huks___result.md) [OH_Huks_GetSdkVersion](#oh_huks_getsdkversion) (struct [OH_Huks_Blob](_o_h___huks___blob.md) \*sdkVersion) | 获取当前Huks sdk版本号。 | 28| struct [OH_Huks_Result](_o_h___huks___result.md) [OH_Huks_GenerateKeyItem](#oh_huks_generatekeyitem) (const struct [OH_Huks_Blob](_o_h___huks___blob.md) \*keyAlias, const struct [OH_Huks_ParamSet](_o_h___huks___param_set.md) \*paramSetIn, struct [OH_Huks_ParamSet](_o_h___huks___param_set.md) \*paramSetOut) | 生成密钥。 | 29| struct [OH_Huks_Result](_o_h___huks___result.md) [OH_Huks_ImportKeyItem](#oh_huks_importkeyitem) (const struct [OH_Huks_Blob](_o_h___huks___blob.md) \*keyAlias, const struct [OH_Huks_ParamSet](_o_h___huks___param_set.md) \*paramSet, const struct [OH_Huks_Blob](_o_h___huks___blob.md) \*key) | 导入明文密钥。 | 30| struct [OH_Huks_Result](_o_h___huks___result.md) [OH_Huks_ImportWrappedKeyItem](#oh_huks_importwrappedkeyitem) (const struct [OH_Huks_Blob](_o_h___huks___blob.md) \*keyAlias, const struct [OH_Huks_Blob](_o_h___huks___blob.md) \*wrappingKeyAlias, const struct [OH_Huks_ParamSet](_o_h___huks___param_set.md) \*paramSet, const struct [OH_Huks_Blob](_o_h___huks___blob.md) \*wrappedKeyData) | 导入密文密钥。 | 31| struct [OH_Huks_Result](_o_h___huks___result.md) [OH_Huks_ExportPublicKeyItem](#oh_huks_exportpublickeyitem) (const struct [OH_Huks_Blob](_o_h___huks___blob.md) \*keyAlias, const struct [OH_Huks_ParamSet](_o_h___huks___param_set.md) \*paramSet, struct [OH_Huks_Blob](_o_h___huks___blob.md) \*key) | 导出公钥。 | 32| struct [OH_Huks_Result](_o_h___huks___result.md) [OH_Huks_DeleteKeyItem](#oh_huks_deletekeyitem) (const struct [OH_Huks_Blob](_o_h___huks___blob.md) \*keyAlias, const struct [OH_Huks_ParamSet](_o_h___huks___param_set.md) \*paramSet) | 删除密钥。 | 33| struct [OH_Huks_Result](_o_h___huks___result.md) [OH_Huks_GetKeyItemParamSet](#oh_huks_getkeyitemparamset) (const struct [OH_Huks_Blob](_o_h___huks___blob.md) \*keyAlias, const struct [OH_Huks_ParamSet](_o_h___huks___param_set.md) \*paramSetIn, struct [OH_Huks_ParamSet](_o_h___huks___param_set.md) \*paramSetOut) | 获取密钥的属性集。 | 34| struct [OH_Huks_Result](_o_h___huks___result.md) [OH_Huks_IsKeyItemExist](#oh_huks_iskeyitemexist) (const struct [OH_Huks_Blob](_o_h___huks___blob.md) \*keyAlias, const struct [OH_Huks_ParamSet](_o_h___huks___param_set.md) \*paramSet) | 判断密钥是否存在。 | 35| struct [OH_Huks_Result](_o_h___huks___result.md) [OH_Huks_AttestKeyItem](#oh_huks_attestkeyitem) (const struct [OH_Huks_Blob](_o_h___huks___blob.md) \*keyAlias, const struct [OH_Huks_ParamSet](_o_h___huks___param_set.md) \*paramSet, struct [OH_Huks_CertChain](_o_h___huks___cert_chain.md) \*certChain) | 获取密钥证书链。 | 36| struct [OH_Huks_Result](_o_h___huks___result.md) [OH_Huks_AnonAttestKeyItem](#oh_huks_anonattestkeyitem) (const struct [OH_Huks_Blob](_o_h___huks___blob.md) \*keyAlias, const struct [OH_Huks_ParamSet](_o_h___huks___param_set.md) \*paramSet, struct [OH_Huks_CertChain](_o_h___huks___cert_chain.md) \*certChain) | 获取密钥证书链。 | 37| struct [OH_Huks_Result](_o_h___huks___result.md) [OH_Huks_InitSession](#oh_huks_initsession) (const struct [OH_Huks_Blob](_o_h___huks___blob.md) \*keyAlias, const struct [OH_Huks_ParamSet](_o_h___huks___param_set.md) \*paramSet, struct [OH_Huks_Blob](_o_h___huks___blob.md) \*handle, struct [OH_Huks_Blob](_o_h___huks___blob.md) \*token) | 初始化密钥会话接口,并获取一个句柄(必选)和挑战值(可选)。 | 38| struct [OH_Huks_Result](_o_h___huks___result.md) [OH_Huks_UpdateSession](#oh_huks_updatesession) (const struct [OH_Huks_Blob](_o_h___huks___blob.md) \*handle, const struct [OH_Huks_ParamSet](_o_h___huks___param_set.md) \*paramSet, const struct [OH_Huks_Blob](_o_h___huks___blob.md) \*inData, struct [OH_Huks_Blob](_o_h___huks___blob.md) \*outData) | 分段添加密钥操作的数据并进行相应的密钥操作,输出处理数据。 | 39| struct [OH_Huks_Result](_o_h___huks___result.md) [OH_Huks_FinishSession](#oh_huks_finishsession) (const struct [OH_Huks_Blob](_o_h___huks___blob.md) \*handle, const struct [OH_Huks_ParamSet](_o_h___huks___param_set.md) \*paramSet, const struct [OH_Huks_Blob](_o_h___huks___blob.md) \*inData, struct [OH_Huks_Blob](_o_h___huks___blob.md) \*outData) | 结束密钥会话并进行相应的密钥操作,输出处理数据。 | 40| struct [OH_Huks_Result](_o_h___huks___result.md) [OH_Huks_AbortSession](#oh_huks_abortsession) (const struct [OH_Huks_Blob](_o_h___huks___blob.md) \*handle, const struct [OH_Huks_ParamSet](_o_h___huks___param_set.md) \*paramSet) | 取消密钥会话。 | 41 42 43## 函数说明 44 45 46### OH_Huks_AbortSession() 47 48``` 49struct OH_Huks_Result OH_Huks_AbortSession (const struct OH_Huks_Blob * handle, const struct OH_Huks_ParamSet * paramSet ) 50``` 51**描述** 52取消密钥会话。 53 54**起始版本:** 9 55 56**参数:** 57 58| 名称 | 描述 | 59| -------- | -------- | 60| handle | 密钥会话句柄,通过[OH_Huks_InitSession](#oh_huks_initsession)接口生成的。 | 61| paramSet | 取消密钥会话需要的输入参数集(默认传空)。 | 62 63**返回:** 64 65返回[OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode)时接口使用成功,其他时为错误。 66 67**参见:** 68 69[OH_Huks_InitSession](#oh_huks_initsession) 70 71[OH_Huks_UpdateSession](#oh_huks_updatesession) 72 73[OH_Huks_FinishSession](#oh_huks_finishsession) 74 75 76### OH_Huks_AnonAttestKeyItem() 77 78``` 79struct OH_Huks_Result OH_Huks_AnonAttestKeyItem (const struct OH_Huks_Blob * keyAlias, const struct OH_Huks_ParamSet * paramSet, struct OH_Huks_CertChain * certChain ) 80``` 81**描述** 82获取密钥证书链。 83 84**起始版本:** 11 85 86**参数:** 87 88| 名称 | 描述 | 89| -------- | -------- | 90| keyAlias | 要获取证书的密钥的别名。 | 91| paramSet | 获取密钥证书需要的参数。 | 92| certChain | 存放输出的密钥证书链。 | 93 94**返回:** 95 96返回[OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode)时获取成功,其他时为错误。 97 98**注解:** 99 100这是一个涉及网络的耗时接口,调用方可以通过异步线程获取证书链。 101 102 103### OH_Huks_AttestKeyItem() 104 105``` 106struct OH_Huks_Result OH_Huks_AttestKeyItem (const struct OH_Huks_Blob * keyAlias, const struct OH_Huks_ParamSet * paramSet, struct OH_Huks_CertChain * certChain ) 107``` 108 109**描述** 110获取密钥证书链。 111 112**需要权限:** 113ohos.permission.ATTEST_KEY 114 115**起始版本:** 9 116 117**参数:** 118 119| 名称 | 描述 | 120| -------- | -------- | 121| keyAlias | 要获取证书的密钥的别名。 | 122| paramSet | 获取密钥证书需要的参数。 | 123| certChain | 存放输出的密钥证书链。 | 124 125**返回:** 126 127返回[OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode)时获取成功,其他时为错误。 128 129 130### OH_Huks_DeleteKeyItem() 131 132``` 133struct OH_Huks_Result OH_Huks_DeleteKeyItem (const struct OH_Huks_Blob * keyAlias, const struct OH_Huks_ParamSet * paramSet ) 134``` 135**描述** 136删除密钥。 137 138**起始版本:** 9 139 140**参数:** 141 142| 名称 | 描述 | 143| -------- | -------- | 144| keyAlias | 待删除密钥的别名,应与密钥生成时使用的别名相同。 | 145| paramSet | 删除密钥需要属性参数(默认传空)。 | 146 147**返回:** 148 149返回[OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode)时接口使用成功,其他时为错误。 150 151 152### OH_Huks_ExportPublicKeyItem() 153 154``` 155struct OH_Huks_Result OH_Huks_ExportPublicKeyItem (const struct OH_Huks_Blob * keyAlias, const struct OH_Huks_ParamSet * paramSet, struct OH_Huks_Blob * key ) 156``` 157**描述** 158导出公钥。 159 160**起始版本:** 9 161 162**参数:** 163 164| 名称 | 描述 | 165| -------- | -------- | 166| keyAlias | 待导出公钥的密钥别名,应与所用密钥生成时使用的别名相同。 | 167| paramSet | 导出公钥需要的属性参数。 | 168| key | 存放导出的公钥。 | 169 170**返回:** 171 172返回[OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode)时接口使用成功,其他时为错误。 173 174 175### OH_Huks_FinishSession() 176 177``` 178struct OH_Huks_Result OH_Huks_FinishSession (const struct OH_Huks_Blob * handle, const struct OH_Huks_ParamSet * paramSet, const struct OH_Huks_Blob * inData, struct OH_Huks_Blob * outData ) 179``` 180**描述** 181结束密钥会话并进行相应的密钥操作,输出处理数据。 182 183**起始版本:** 9 184 185**参数:** 186 187| 名称 | 描述 | 188| -------- | -------- | 189| handle | 密钥会话句柄,通过[OH_Huks_InitSession](#oh_huks_initsession)接口生成的。 | 190| paramSet | 密钥操作对应的输入参数集。 | 191| inData | 要处理的输入数据。 | 192| outData | 经过对应的密钥操作后输出的数据。 | 193 194**返回:** 195 196返回[OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode)时接口使用成功,其他时为错误。 197 198**参见:** 199 200[OH_Huks_InitSession](#oh_huks_initsession) 201 202[OH_Huks_UpdateSession](#oh_huks_updatesession) 203 204[OH_Huks_AbortSession](#oh_huks_abortsession) 205 206 207### OH_Huks_GenerateKeyItem() 208 209``` 210struct OH_Huks_Result OH_Huks_GenerateKeyItem (const struct OH_Huks_Blob * keyAlias, const struct OH_Huks_ParamSet * paramSetIn, struct OH_Huks_ParamSet * paramSetOut ) 211``` 212**描述** 213生成密钥。 214 215**起始版本:** 9 216 217**参数:** 218 219| 名称 | 描述 | 220| -------- | -------- | 221| keyAlias | 给要生成的密钥的别名,需要保证业务所在进程内唯一,否则会发生覆盖。 | 222| paramSetIn | 生成密钥的属性信息的参数集。 | 223| paramSetOut | 生成密钥为临时类型时,存放着密钥数据;非临时类型可为空。 | 224 225**返回:** 226 227返回[OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode)时接口使用成功,其他时为错误。 228 229 230### OH_Huks_GetKeyItemParamSet() 231 232``` 233struct OH_Huks_Result OH_Huks_GetKeyItemParamSet (const struct OH_Huks_Blob * keyAlias, const struct OH_Huks_ParamSet * paramSetIn, struct OH_Huks_ParamSet * paramSetOut ) 234``` 235**描述** 236获取密钥的属性集。 237 238**起始版本:** 9 239 240**参数:** 241 242| 名称 | 描述 | 243| -------- | -------- | 244| keyAlias | 要获取参数集的密钥别名。 | 245| paramSetIn | 要获取参数集需要的属性TAG(默认传空)。 | 246| paramSetOut | 获取到的输出参数集。 | 247 248**返回:** 249 250返回[OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode)时获取成功,其他时为失败。 251 252 253### OH_Huks_GetSdkVersion() 254 255``` 256struct OH_Huks_Result OH_Huks_GetSdkVersion (struct OH_Huks_Blob * sdkVersion) 257``` 258**描述** 259获取当前Huks sdk版本号。 260 261**起始版本:** 9 262 263**参数:** 264 265| 名称 | 描述 | 266| -------- | -------- | 267| sdkVersion | 用于存放获取到的版本信息(字符串格式)。 | 268 269**返回:** 270 271返回[OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode)时接口使用成功,其他时为错误。 272 273 274### OH_Huks_ImportKeyItem() 275 276``` 277struct OH_Huks_Result OH_Huks_ImportKeyItem (const struct OH_Huks_Blob * keyAlias, const struct OH_Huks_ParamSet * paramSet, const struct OH_Huks_Blob * key ) 278``` 279**描述** 280导入明文密钥。 281 282**起始版本:** 9 283 284**参数:** 285 286| 名称 | 描述 | 287| -------- | -------- | 288| keyAlias | 待导入密钥的别名,需要保证业务所在进程内唯一,否则会发生覆盖。 | 289| paramSet | 待导入密钥的属性参数。 | 290| key | 待导入密钥数据,需符合Huks的格式要求,具体见[HuksTypeApi](_huks_type_api.md)。 | 291 292**返回:** 293 294返回[OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode)时接口使用成功,其他时为错误。 295 296 297### OH_Huks_ImportWrappedKeyItem() 298 299``` 300struct OH_Huks_Result OH_Huks_ImportWrappedKeyItem (const struct OH_Huks_Blob * keyAlias, const struct OH_Huks_Blob * wrappingKeyAlias, const struct OH_Huks_ParamSet * paramSet, const struct OH_Huks_Blob * wrappedKeyData ) 301``` 302**描述** 303导入密文密钥。 304 305**起始版本:** 9 306 307**参数:** 308 309| 名称 | 描述 | 310| -------- | -------- | 311| keyAlias | 待导入密钥的别名,需要保证业务所在进程内唯一,否则会发生覆盖。 | 312| wrappingKeyAlias | 密钥别名,该对应密钥用于密钥协商出密钥解密待导入密钥。 | 313| paramSet | 待导入加密密钥的属性参数。 | 314| wrappedKeyData | 需要导入的加密的密钥数据,需要符合Huks定义的格式,具体见[OH_Huks_AlgSuite](_huks_type_api.md#oh_huks_algsuite) | 315 316**返回:** 317 318返回[OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode)时接口使用成功,其他时为错误。 319 320 321### OH_Huks_InitSession() 322 323``` 324struct OH_Huks_Result OH_Huks_InitSession (const struct OH_Huks_Blob * keyAlias, const struct OH_Huks_ParamSet * paramSet, struct OH_Huks_Blob * handle, struct OH_Huks_Blob * token ) 325``` 326**描述** 327初始化密钥会话接口,并获取一个句柄(必选)和挑战值(可选)。 328 329**起始版本:** 9 330 331**参数:** 332 333| 名称 | 描述 | 334| -------- | -------- | 335| keyAlias | 操作的密钥的别名。 | 336| paramSet | 初始化操作的密钥参数集合。 | 337| handle | 密钥会话的句柄,后续其他操作时传入该句柄,包括[OH_Huks_UpdateSession](#oh_huks_updatesession), [OH_Huks_FinishSession](#oh_huks_finishsession), [OH_Huks_AbortSession](#oh_huks_abortsession)。 | 338| token | 存放安全访问控制时传回的token | 339 340**返回:** 341 342返回[OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode)时接口使用成功,其他时为错误。 343 344**参见:** 345 346[OH_Huks_UpdateSession](#oh_huks_updatesession) 347 348[OH_Huks_FinishSession](#oh_huks_finishsession) 349 350[OH_Huks_AbortSession](#oh_huks_abortsession) 351 352 353### OH_Huks_IsKeyItemExist() 354 355``` 356struct OH_Huks_Result OH_Huks_IsKeyItemExist (const struct OH_Huks_Blob * keyAlias, const struct OH_Huks_ParamSet * paramSet ) 357``` 358**描述** 359判断密钥是否存在。 360 361**起始版本:** 9 362 363**参数:** 364 365| 名称 | 描述 | 366| -------- | -------- | 367| keyAlias | 要查找的密钥的别名。 | 368| paramSet | 查询密钥需要的属性TAG(默认传空)。 | 369 370**返回:** 371 372返回[OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode)时密钥存在, 373 374返回[OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ITEM_NOT_EXIST](_huks_type_api.md#oh_huks_errcode)不存在,返回其他错误在其他情况。 375 376 377### OH_Huks_UpdateSession() 378 379``` 380struct OH_Huks_Result OH_Huks_UpdateSession (const struct OH_Huks_Blob * handle, const struct OH_Huks_ParamSet * paramSet, const struct OH_Huks_Blob * inData, struct OH_Huks_Blob * outData ) 381``` 382**描述** 383分段添加密钥操作的数据并进行相应的密钥操作,输出处理数据。 384 385**起始版本:** 9 386 387**参数:** 388 389| 名称 | 描述 | 390| -------- | -------- | 391| handle | 密钥会话句柄,通过[OH_Huks_InitSession](#oh_huks_initsession)接口生成的。 | 392| paramSet | 密钥操作对应的输入参数集。 | 393| inData | 要处理的输入数据,如果数据过大,可分片多次调用。 | 394| outData | 经过对应的密钥操作后输出的数据。 | 395 396**返回:** 397 398返回[OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode)时接口使用成功,其他时为错误。 399 400**参见:** 401 402[OH_Huks_InitSession](#oh_huks_initsession) 403 404[OH_Huks_FinishSession](#oh_huks_finishsession) 405 406[OH_Huks_AbortSession](#oh_huks_abortsession) 407