1# HuksKeyApi 2 3 4## Overview 5 6Describes the OpenHarmony Universal KeyStore (HUKS) capabilities, including key management and cryptography operations, provided for applications. The keys managed by HUKS can be imported by applications or generated by calling the HUKS APIs. 7 8**System capability**: SystemCapability.Security.Huks 9 10**Since**: 9 11 12 13## Summary 14 15 16### Files 17 18| Name| Description| 19| -------- | -------- | 20| [native_huks_api.h](native__huks__api_8h.md) | Declares the APIs used to access the HUKS.<br>**File to include**: <huks/native_huks_api.h><br>**Library**: libhuks_ndk.z.so | 21 22 23### Functions 24 25| Name| Description| 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) | Obtains the current HUKS SDK version. | 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) | Generates a key. | 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) | Imports a key in plaintext. | 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) | Imports a wrapped (encrypted) key. | 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) | Exports a public 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) | Deletes a key. | 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) | Obtains the properties of a key. | 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) | Checks whether a key exists. | 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) | Obtains the certificate chain of a key. | 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) | Obtains the certificate chain of a key. | 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) | Initializes a key session to obtain a handle (mandatory) and a challenge value (optional). | 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) | Adds data by segment for the key operation, performs the related key operation, and outputs the processed data. | 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) | Finishes a key session. | 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) | Aborts a key session. | 41 42 43## Function Description 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**Description** 52Aborts a key session. 53 54**Since**: 9 55 56**Parameters** 57 58| Name| Description| 59| -------- | -------- | 60| handle | Indicates the pointer to the key session handle, which is generated by [OH_Huks_InitSession](#oh_huks_initsession). | 61| paramSet | Indicates the pointer to the parameters required for aborting the key session. By default, this parameter is a null pointer. | 62 63**Returns** 64 65Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise. 66 67**See** 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**Description** 82Obtains the certificate chain of a key. 83 84**Since**: 11 85 86**Parameters** 87 88| Name| Description| 89| -------- | -------- | 90| keyAlias | Indicates the pointer to the alias of the target key. | 91| paramSet | Indicates the pointer to the parameters required for obtaining the certificate chain. | 92| certChain | Indicates the pointer to the certificate chain obtained. | 93 94**Returns** 95 96Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise. 97 98**NOTE** 99 100This API involves time-consuming network operation. The caller can obtain the certificate chain through an asynchronous thread. 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**Description** 110Obtains the certificate chain of a key. 111 112**Required permissions** 113ohos.permission.ATTEST_KEY 114 115**Since**: 9 116 117**Parameters** 118 119| Name| Description| 120| -------- | -------- | 121| keyAlias | Indicates the pointer to the alias of the target key. | 122| paramSet | Indicates the pointer to the parameters required for obtaining the certificate chain. | 123| certChain | Indicates the pointer to the certificate chain obtained. | 124 125**Returns** 126 127Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise. 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**Description** 136Deletes a key. 137 138**Since**: 9 139 140**Parameters** 141 142| Name| Description| 143| -------- | -------- | 144| keyAlias | Indicates the pointer to the alias of the key to delete. It must be the same as the alias used for generating the key. | 145| paramSet | Indicates the pointer to the parameters required for deleting the key. By default, this parameter is a null pointer. | 146 147**Returns** 148 149Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise. 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**Description** 158Exports a public key. 159 160**Since**: 9 161 162**Parameters** 163 164| Name| Description| 165| -------- | -------- | 166| keyAlias | Indicates the pointer to the alias of the public key to export. It must be the same as the alias used for generating the key. | 167| paramSet | Indicates the pointer to the parameters required for exporting the public key. | 168| key | Indicates the pointer to the public key exported. | 169 170**Returns** 171 172Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise. 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**Description** 181Finishes a key session. 182 183**Since**: 9 184 185**Parameters** 186 187| Name| Description| 188| -------- | -------- | 189| handle | Indicates the pointer to the key session handle, which is generated by [OH_Huks_InitSession](#oh_huks_initsession). | 190| paramSet | Indicates the pointer to the parameters required for the key operation. | 191| inData | Indicates the pointer to the data to be passed in. | 192| outData | Indicates the pointer to the output data. | 193 194**Returns** 195 196Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise. 197 198**See** 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**Description** 213Generates a key. 214 215**Since**: 9 216 217**Parameters** 218 219| Name| Description| 220| -------- | -------- | 221| keyAlias | Indicates the pointer to the alias of the key to generate. The alias must be unique in the process of the service. | 222| paramSetIn | Indicates the pointer to the parameters for generating the key. | 223| paramSetOut | Indicates the pointer to a temporary key generated. If the generated key is not of a temporary type, this parameter is a null pointer. | 224 225**Returns** 226 227Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise. 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**Description** 236Obtains the properties of a key. 237 238**Since**: 9 239 240**Parameters** 241 242| Name| Description| 243| -------- | -------- | 244| keyAlias | Indicates the pointer to the alias of the target key. | 245| paramSetIn | Indicates the pointer to the tag required for obtaining the properties. By default, this parameter is a null pointer. | 246| paramSetOut | Indicates the pointer to the key properties obtained. | 247 248**Returns** 249 250Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise. 251 252 253### OH_Huks_GetSdkVersion() 254 255``` 256struct OH_Huks_Result OH_Huks_GetSdkVersion (struct OH_Huks_Blob * sdkVersion) 257``` 258**Description** 259Obtains the current HUKS SDK version. 260 261**Since**: 9 262 263**Parameters** 264 265| Name| Description| 266| -------- | -------- | 267| sdkVersion | Indicates the pointer to the SDK version (string) obtained. | 268 269**Returns** 270 271Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise. 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**Description** 280Imports a key in plaintext. 281 282**Since**: 9 283 284**Parameters** 285 286| Name| Description| 287| -------- | -------- | 288| keyAlias | Indicates the pointer to the alias of the key to import. The alias must be unique in the process of the service. | 289| paramSet | Indicates the pointer to the properties of the key to import. | 290| key | Indicates the pointer to the key to import. The key data must be in format defined in [HuksTypeApi](_huks_type_api.md). | 291 292**Returns** 293 294Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise. 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**Description** 303Imports a wrapped (encrypted) key. 304 305**Since**: 9 306 307**Parameters** 308 309| Name| Description| 310| -------- | -------- | 311| keyAlias | Indicates the pointer to the alias of the key to import. The alias must be unique in the process of the service. | 312| wrappingKeyAlias | Indicates the pointer to the alias of the wrapping key, which is obtained through key agreement and used to decrypt the key to import. | 313| paramSet | Indicates the pointer to the parameters for importing the wrapped key. | 314| wrappedKeyData | Indicates the pointer to the wrapped key to import. The data must be in the format defined in [OH_Huks_AlgSuite](_huks_type_api.md#oh_huks_algsuite).| 315 316**Returns** 317 318Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise. 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**Description** 327Initializes a key session to obtain a handle (mandatory) and a challenge value (optional). 328 329**Since**: 9 330 331**Parameters** 332 333| Name| Description| 334| -------- | -------- | 335| keyAlias | Indicates the pointer to the alias of the target key. | 336| paramSet | Indicates the pointer to the parameters for the initialization operation. | 337| handle | Indicates the pointer to the handle of the key session. This handle is required for subsequent operations of the same key, including [OH_Huks_UpdateSession](#oh_huks_updatesession), [OH_Huks_FinishSession](#oh_huks_finishsession), and [OH_Huks_AbortSession](#oh_huks_abortsession). | 338| token | Indicates the pointer to the token used for key access control. | 339 340**Returns** 341 342Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise. 343 344**See** 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**Description** 359Checks whether a key exists. 360 361**Since**: 9 362 363**Parameters** 364 365| Name| Description| 366| -------- | -------- | 367| keyAlias | Indicates the pointer to the alias of the key to check. | 368| paramSet | Indicates the pointer to the parameters required for checking the key. By default, this parameter is a null pointer. | 369 370**Returns** 371 372Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the key exists. 373 374Returns [OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ITEM_NOT_EXIST](_huks_type_api.md#oh_huks_errcode) if the key does not exist. 375 376Returns other errors in other cases. 377 378 379### OH_Huks_UpdateSession() 380 381``` 382struct 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 ) 383``` 384**Description** 385Adds data by segment for the key operation, performs the related key operation, and outputs the processed data. 386 387**Since**: 9 388 389**Parameters** 390 391| Name| Description| 392| -------- | -------- | 393| handle | Indicates the pointer to the key session handle, which is generated by [OH_Huks_InitSession](#oh_huks_initsession). | 394| paramSet | Indicates the pointer to the parameters required for the key operation. | 395| inData | Indicates the pointer to the data to be processed. This API can be called multiple times to process large data by segment. | 396| outData | Indicates the pointer to the output data. | 397 398**Returns** 399 400Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise. 401 402**See** 403 404[OH_Huks_InitSession](#oh_huks_initsession) 405 406[OH_Huks_FinishSession](#oh_huks_finishsession) 407 408[OH_Huks_AbortSession](#oh_huks_abortsession) 409