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