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