1# HuksKeyApi 2 3 4## Overview 5 6Defines the OpenHarmony Universal KeyStore (HUKS) capabilities, including key management and cryptography operations, provided for applications. Applications can call the HUKS functions to import or generate keys. 7 8**System capability**: SystemCapability.Security.Huks 9 10**Since**: 9 11 12 13## Summary 14 15 16### File 17 18| Name| Description| 19| -------- | -------- | 20| [native_huks_api.h](native__huks__api_8h.md) | Declares the functions used to access 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 key in ciphertext. | 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 the 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. This function returns a session 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 and processes data by segment for a 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| 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) | Lists key aliases. | 42 43 44## Function Description 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**Description** 53Aborts a key session. 54 55**Since**: 9 56 57**Parameters** 58 59| Name| Description| 60| -------- | -------- | 61| handle | Pointer to the key session handle, which is returned by [OH_Huks_InitSession](#oh_huks_initsession). | 62| paramSet | Pointer to the parameters for aborting the key session. By default, this parameter is a null pointer. | 63 64**Returns** 65 66Returns [OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise. 67 68**See** 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**Description** 83Obtains the certificate chain of a key. 84 85<!--RP1--><!--RP1End--> 86 87**Since**: 11 88 89**Parameters** 90 91| Name| Description| 92| -------- | -------- | 93| keyAlias | Pointer to the alias of the target key. | 94| paramSet | Pointer to the parameters for obtaining the certificate chain. | 95| certChain | Pointer to the certificate chain obtained. | 96 97**Returns** 98 99Returns [OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise. 100 101**NOTE** 102 103This function involves time-consuming network operation. The caller can obtain the certificate chain through an asynchronous thread. 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**Description** 113Obtains the certificate chain of a key. 114 115**Required permissions** 116ohos.permission.ATTEST_KEY (for system applications only) 117 118**Since**: 9 119 120**Parameters** 121 122| Name| Description| 123| -------- | -------- | 124| keyAlias | Pointer to the alias of the target key. | 125| paramSet | Pointer to the parameters for obtaining the certificate chain. | 126| certChain | Pointer to the certificate chain obtained. | 127 128**Returns** 129 130Returns [OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise. 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**Description** 139Deletes a key. 140 141**Since**: 9 142 143**Parameters** 144 145| Name| Description| 146| -------- | -------- | 147| keyAlias | Pointer to the alias of the key to delete. It must be the same as the alias used for generating the key. | 148| paramSet | Pointer to the properties of the key to delete. If this parameter is not specified, the key of the [OH_HUKS_AUTH_STORAGE_LEVEL_CE](_huks_type_api.md#OH_Huks_AuthStorageLevel) level is deleted by default.| 149 150**Returns** 151 152Returns [OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise. 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**Description** 161Exports a public key. 162 163**Since**: 9 164 165**Parameters** 166 167| Name| Description| 168| -------- | -------- | 169| keyAlias | Pointer to the alias of the public key to export. It must be the same as the alias used for generating the key. | 170| paramSet | Pointer to the parameters for exporting the public key. | 171| key | Pointer to the public key exported. | 172 173**Returns** 174 175Returns [OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise. 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**Description** 184Finishes a key session. 185 186**Since**: 9 187 188**Parameters** 189 190| Name| Description| 191| -------- | -------- | 192| handle | Pointer to the key session handle, which is returned by [OH_Huks_InitSession](#oh_huks_initsession). | 193| paramSet | Pointer to the parameters required for the key operation. | 194| inData | Pointer to the data to be passed in. | 195| outData | Pointer to the output data. | 196 197**Returns** 198 199Returns [OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise. 200 201**See** 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**Description** 216Generates a key. 217 218**Since**: 9 219 220**Parameters** 221 222| Name| Description| 223| -------- | -------- | 224| keyAlias | Pointer to the alias of the key to generate. The alias must be unique in the process of the service. | 225| paramSetIn | Pointer to the parameters for generating the key. | 226| paramSetOut | Pointer to a temporary key generated. If the generated key is not a temporary key, this parameter is a null pointer. | 227 228**Returns** 229 230Returns [OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise. 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**Description** 239Obtains the properties of a key. 240 241**Since**: 9 242 243**Parameters** 244 245| Name| Description| 246| -------- | -------- | 247| keyAlias | Pointer to the alias of the target key. | 248| paramSetIn | Pointer to the tag required for obtaining the properties. By default, this parameter is a null pointer. | 249| paramSetOut | Pointer to the key properties obtained. | 250 251**Returns** 252 253Returns [OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise. 254 255 256### OH_Huks_GetSdkVersion() 257 258``` 259struct OH_Huks_Result OH_Huks_GetSdkVersion (struct OH_Huks_Blob * sdkVersion) 260``` 261**Description** 262Obtains the current HUKS SDK version. 263 264**Since**: 9 265 266**Parameters** 267 268| Name| Description| 269| -------- | -------- | 270| sdkVersion | Pointer to the SDK version (string) obtained. | 271 272**Returns** 273 274Returns [OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise. 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**Description** 283Imports a key in plaintext. 284 285**Since**: 9 286 287**Parameters** 288 289| Name| Description| 290| -------- | -------- | 291| keyAlias | Pointer to the alias of the key to import. The alias must be unique in the process of the service. | 292| paramSet | Pointer to the properties of the key to import. | 293| key | Pointer to the key to import. The key data must be of the [HuksTypeApi](_huks_type_api.md) type. | 294 295**Returns** 296 297Returns [OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise. 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**Description** 306Imports a key in ciphertext. 307 308**Since**: 9 309 310**Parameters** 311 312| Name| Description| 313| -------- | -------- | 314| keyAlias | Pointer to the alias of the key to import. The alias must be unique in the process of the service. | 315| wrappingKeyAlias | Pointer to the alias of the key used for key agreement, which generates a shared secret to decrypt the key to import. | 316| paramSet | Pointer to the parameters for importing the key in ciphertext. | 317| wrappedKeyData | Pointer to the encrypted key to import. The data must be of the [OH_Huks_AlgSuite](_huks_type_api.md#oh_huks_algsuite) type.| 318 319**Returns** 320 321Returns [OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise. 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**Description** 330Initializes a key session. This function returns a handle (mandatory) and a challenge value (optional). 331 332**Since**: 9 333 334**Parameters** 335 336| Name| Description| 337| -------- | -------- | 338| keyAlias | Pointer to the alias of the target key. | 339| paramSet | Pointer to the parameters for the initialization operation. | 340| handle | 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). | 341| token | Pointer to the token used for key access control. | 342 343**Returns** 344 345Returns [OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise. 346 347**See** 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**Description** 362Checks whether a key exists. 363 364**Since**: 9 365 366**Parameters** 367 368| Name| Description| 369| -------- | -------- | 370| keyAlias | Pointer to the alias of the key to check. | 371| paramSet | Pointer to the parameters for checking the key. By default, this parameter is a null pointer. | 372 373**Returns** 374 375Returns [OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the key exists. 376 377Returns [OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ITEM_NOT_EXIST](_huks_type_api.md#oh_huks_errcode) if the key does not exist. 378Returns other errors in other cases. 379 380 381### OH_Huks_ListAliases() 382 383``` 384struct OH_Huks_Result OH_Huks_ListAliases (const struct OH_Huks_ParamSet * paramSet, struct OH_Huks_KeyAliasSet ** outData ) 385``` 386**Description** 387Lists key aliases. 388 389**Since**: 12 390 391**Parameters** 392 393| Name| Description| 394| -------- | -------- | 395| paramSet | Pointer to the parameters for listing the key aliases. By default, this parameter is a null pointer. | 396| outData | pointer to the key aliases obtained. | 397 398**Returns** 399 400Returns [OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise. 401 402 403### OH_Huks_UpdateSession() 404 405``` 406struct 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 ) 407``` 408**Description** 409Adds and processes data by segment for a key operation, and outputs the processed data. 410 411**Since**: 9 412 413**Parameters** 414 415| Name| Description| 416| -------- | -------- | 417| handle | Pointer to the key session handle, which is returned by [OH_Huks_InitSession](#oh_huks_initsession). | 418| paramSet | Pointer to the parameters required for the key operation. | 419| inData | Pointer to the data to be processed. If there is a large amount of data to be processed, you can call this function multiple times to process data by segment. | 420| outData | Pointer to the output data. | 421 422**Returns** 423 424Returns [OH_HUKS_SUCCESS](_huks_type_api.md#oh_huks_errcode) if the operation is successful; returns an error code otherwise. 425 426**See** 427 428[OH_Huks_InitSession](#oh_huks_initsession) 429 430[OH_Huks_FinishSession](#oh_huks_finishsession) 431 432[OH_Huks_AbortSession](#oh_huks_abortsession) 433