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\@syscap SystemCapability.Security.Huks 9 10**Since:** 119 12 13 14## Summary 15 16 17### Files 18 19| Name | Description | 20| -------- | -------- | 21| [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> | 22 23 24### Functions 25 26| Name | Description | 27| -------- | -------- | 28| [OH_Huks_GetSdkVersion](#oh_huks_getsdkversion) (struct [OH_Huks_Blob](_o_h___huks___blob.md) \*sdkVersion) | Obtains the current HUKS SDK version. | 29| [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. | 30| [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. | 31| [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 key. | 32| [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. | 33| [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. | 34| [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 attributes of a key. | 35| [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. | 36| [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) | Obtain the key certificate chain. | 37| [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) \*challenge) | Initializes the key session interface and obtains a handle (mandatory) and challenge value (optional). | 38| [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| [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) | Ends the key session. | 40| [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 49``` 50struct OH_Huks_Result OH_Huks_AbortSession (const struct OH_Huks_Blob * handle, const struct OH_Huks_ParamSet * paramSet ) 51``` 52**Description**<br> 53Aborts a key session. 54 55 **Parameters** 56 57| Name | Description | 58| -------- | -------- | 59| handle | Indicates the pointer to the key session handle, which is generated by [OH_Huks_InitSession](#oh_huks_initsession). | 60| paramSet | Indicates the pointer to the parameters required for aborting the key session. By default, this parameter is a null pointer. | 61 62**Returns** 63 64Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md) if the operation is successful; returns an error code otherwise. 65 66 **See** 67 68[OH_Huks_InitSession](#oh_huks_initsession) 69 70[OH_Huks_UpdateSession](#oh_huks_updatesession) 71 72[OH_Huks_FinishSession](#oh_huks_finishsession) 73 74 75### OH_Huks_AttestKeyItem() 76 77 78``` 79struct OH_Huks_Result OH_Huks_AttestKeyItem (const struct OH_Huks_Blob * keyAlias, const struct OH_Huks_ParamSet * paramSet, struct OH_Huks_CertChain * certChain ) 80``` 81**Description**<br> 82Obtain the key certificate chain. 83 84 **Parameters** 85 86| Name | Description | 87| -------- | -------- | 88| keyAlias | Indicates the pointer to the alias of the target key. | 89| paramSet | Indicates the pointer to the parameters required for obtaining the key certificate. | 90| certChain | Indicates the pointer to the key certificate chain obtained. | 91 92**Returns** 93 94Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md) if the operation is successful; returns an error code otherwise. 95 96 97### OH_Huks_DeleteKeyItem() 98 99 100``` 101struct OH_Huks_Result OH_Huks_DeleteKeyItem (const struct OH_Huks_Blob * keyAlias, const struct OH_Huks_ParamSet * paramSet ) 102``` 103**Description**<br> 104Deletes a key. 105 106 **Parameters** 107 108| Name | Description | 109| -------- | -------- | 110| keyAlias | Indicates the pointer to the alias of the key to delete. The alias must be the same as the alias for the key generated. | 111| paramSet | Indicates the pointer to the parameters required for deleting the key. By default, this parameter is a null pointer. | 112 113**Returns** 114 115Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md) if the operation is successful; returns an error code otherwise. 116 117 118### OH_Huks_ExportPublicKeyItem() 119 120 121``` 122struct OH_Huks_Result OH_Huks_ExportPublicKeyItem (const struct OH_Huks_Blob * keyAlias, const struct OH_Huks_ParamSet * paramSet, struct OH_Huks_Blob * key ) 123``` 124**Description**<br> 125Exports a public key. 126 127 **Parameters** 128 129| Name | Description | 130| -------- | -------- | 131| keyAlias | Indicates the pointer to the alias of the public key to export. The alias must be the same as the alias for the key generated. | 132| paramSet | Indicates the pointer to the parameters required for exporting the public key. | 133| key | Indicates the pointer to the public key exported. | 134 135**Returns** 136 137Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md) if the operation is successful; returns an error code otherwise. 138 139 140### OH_Huks_FinishSession() 141 142 143``` 144struct 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 ) 145``` 146**Description**<br> 147Ends the key session. 148 149 **Parameters** 150 151| Name | Description | 152| -------- | -------- | 153| handle | Indicates the pointer to the key session handle, which is generated by [OH_Huks_InitSession](#oh_huks_initsession). | 154| paramSet | Indicates the pointer to the parameters required for the key operation. | 155| inData | Indicates the pointer to the data to be processed. | 156| outData | Indicates the pointer to the output data. | 157 158**Returns** 159 160Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md) if the operation is successful; returns an error code otherwise. 161 162 **See** 163 164[OH_Huks_InitSession](#oh_huks_initsession) 165 166[OH_Huks_UpdateSession](#oh_huks_updatesession) 167 168[OH_Huks_AbortSession](#oh_huks_abortsession) 169 170 171### OH_Huks_GenerateKeyItem() 172 173 174``` 175struct OH_Huks_Result OH_Huks_GenerateKeyItem (const struct OH_Huks_Blob * keyAlias, const struct OH_Huks_ParamSet * paramSetIn, struct OH_Huks_ParamSet * paramSetOut ) 176``` 177**Description**<br> 178Generates a key. 179 180 **Parameters** 181 182| Name | Description | 183| -------- | -------- | 184| keyAlias | Indicates the pointer to the alias of the key to generate. The alias must be unique in the process of the service. Otherwise, the key will be overwritten. | 185| paramSetIn | Indicates the pointer to the parameter set for generating the key. | 186| 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. | 187 188**Returns** 189 190Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md) if the operation is successful; returns an error code otherwise. 191 192 193### OH_Huks_GetKeyItemParamSet() 194 195 196``` 197struct OH_Huks_Result OH_Huks_GetKeyItemParamSet (const struct OH_Huks_Blob * keyAlias, const struct OH_Huks_ParamSet * paramSetIn, struct OH_Huks_ParamSet * paramSetOut ) 198``` 199**Description**<br> 200Obtains the attributes of a key. 201 202 **Parameters** 203 204| Name | Description | 205| -------- | -------- | 206| keyAlias | Indicates the pointer to the alias of the target key. | 207| paramSetIn | Indicates the pointer to the attribute tag required for obtaining the attributes. By default, this parameter is a null pointer. | 208| paramSetOut | Indicates the pointer to the attributes obtained. | 209 210**Returns** 211 212Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md) if the operation is successful; returns an error code otherwise. 213 214 215### OH_Huks_GetSdkVersion() 216 217 218``` 219struct OH_Huks_Result OH_Huks_GetSdkVersion (struct OH_Huks_Blob * sdkVersion) 220``` 221**Description**<br> 222Obtains the current HUKS SDK version. 223 224 **Parameters** 225 226| Name | Description | 227| -------- | -------- | 228| sdkVersion | Indicates the pointer to the SDK version (in string format) obtained. | 229 230**Returns** 231 232Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md) if the operation is successful; returns an error code otherwise. 233 234 235### OH_Huks_ImportKeyItem() 236 237 238``` 239struct OH_Huks_Result OH_Huks_ImportKeyItem (const struct OH_Huks_Blob * keyAlias, const struct OH_Huks_ParamSet * paramSet, const struct OH_Huks_Blob * key ) 240``` 241**Description**<br> 242Imports a key in plaintext. 243 244 **Parameters** 245 246| Name | Description | 247| -------- | -------- | 248| keyAlias | Indicates the pointer to the alias of the key to import. The alias must be unique in the process of the service. Otherwise, the key will be overwritten. | 249| paramSet | Indicates the pointer to the parameters of the key to import. | 250| key | Indicates the pointer to the key to import. The key must be in the format required by the HUKS. For details, see [HuksTypeApi](_huks_type_api.md). | 251 252**Returns** 253 254Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md) if the operation is successful; returns an error code otherwise. 255 256 257### OH_Huks_ImportWrappedKeyItem() 258 259 260``` 261struct 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 ) 262``` 263**Description**<br> 264Imports a wrapped key. 265 266 **Parameters** 267 268| Name | Description | 269| -------- | -------- | 270| keyAlias | Indicates the pointer to the alias of the key to import. The alias must be unique in the process of the service. Otherwise, the key will be overwritten. | 271| 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. | 272| paramSet | Indicates the pointer to the parameters of the wrapped key to import. | 273| wrappedKeyData | Indicates the pointer to the wrapped key to import. The key must be in the format required by the HUKS. For details, see [OH_Huks_AlgSuite](_huks_type_api.md#oh_huks_algsuite). | 274 275**Returns** 276 277Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md) if the operation is successful; returns an error code otherwise. 278 279 280### OH_Huks_InitSession() 281 282 283``` 284struct 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 * challenge ) 285``` 286**Description**<br> 287Initializes the key session interface and obtains a handle (mandatory) and challenge value (optional). 288 289 **Parameters** 290 291| Name | Description | 292| -------- | -------- | 293| keyAlias | Indicates the pointer to the alias of the target key. | 294| paramSet | Indicates the pointer to the parameters for the initialization operation. | 295| handle | Indicates the pointer to the handle of the key session obtained. This handle is required for subsequent operations, including [OH_Huks_UpdateSession](#oh_huks_updatesession), [OH_Huks_FinishSession](#oh_huks_finishsession), and [OH_Huks_AbortSession](#oh_huks_abortsession). | 296| challenge | Indicates the pointer to the challenge value obtained. | 297 298**Returns** 299 300Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md) if the operation is successful; returns an error code otherwise. 301 302 **See** 303 304[OH_Huks_UpdateSession](#oh_huks_updatesession) 305 306[OH_Huks_FinishSession](#oh_huks_finishsession) 307 308[OH_Huks_AbortSession](#oh_huks_abortsession) 309 310 311### OH_Huks_IsKeyItemExist() 312 313 314``` 315struct OH_Huks_Result OH_Huks_IsKeyItemExist (const struct OH_Huks_Blob * keyAlias, const struct OH_Huks_ParamSet * paramSet ) 316``` 317**Description**<br> 318Checks whether a key exists. 319 320 **Parameters** 321 322| Name | Description | 323| -------- | -------- | 324| keyAlias | Indicates the pointer to the alias of the target key. | 325| paramSet | Indicates the pointer to the attribute tag required for checking the key. By default, this parameter is a null pointer. | 326 327**Returns** 328 329Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md) if the key exists. 330 331Returns [OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ITEM_NOT_EXIST](_huks_type_api.md) if the key does not exist. 332 333Returns any other error code for other cases. 334 335 336### OH_Huks_UpdateSession() 337 338 339``` 340struct 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 ) 341``` 342**Description**<br> 343Adds data by segment for the key operation, performs the related key operation, and outputs the processed data. 344 345 **Parameters** 346 347| Name | Description | 348| -------- | -------- | 349| handle | Indicates the pointer to the key session handle, which is generated by [OH_Huks_InitSession](#oh_huks_initsession). | 350| paramSet | Indicates the pointer to the parameters required for the key operation. | 351| inData | Indicates the pointer to the data to be processed. This API can be called multiples time to process large data by segment. | 352| outData | Indicates the pointer to the output data. | 353 354**Returns** 355 356Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md) if the operation is successful; returns an error code otherwise. 357 358 **See** 359 360[OH_Huks_InitSession](#oh_huks_initsession) 361 362[OH_Huks_FinishSession](#oh_huks_finishsession) 363 364[OH_Huks_AbortSession](#oh_huks_abortsession) 365