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## 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| [OH_Huks_GetSdkVersion](#oh_huks_getsdkversion) (struct [OH_Huks_Blob](_o_h___huks___blob.md) \*sdkVersion) | Obtains the current HUKS SDK version. | 28| [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| [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| [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| [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| [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| [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| [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| [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| [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 token (optional). | 37| [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. | 38| [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. | 39| [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. | 40 41 42## Function Description 43 44 45### OH_Huks_AbortSession() 46 47 48``` 49struct OH_Huks_Result OH_Huks_AbortSession (const struct OH_Huks_Blob * handle, const struct OH_Huks_ParamSet * paramSet ) 50``` 51**Description** 52 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** 82 83Obtains the certificate chain of a key. 84 85**Parameters** 86 87| Name| Description| 88| -------- | -------- | 89| keyAlias | Indicates the pointer to the alias of the target key. | 90| paramSet | Indicates the pointer to the parameters required for obtaining the certificate chain. | 91| certChain | Indicates the pointer to the certificate chain obtained. | 92 93**Returns** 94 95Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md) if the operation is successful; returns an error code otherwise. 96 97 98### OH_Huks_DeleteKeyItem() 99 100 101``` 102struct OH_Huks_Result OH_Huks_DeleteKeyItem (const struct OH_Huks_Blob * keyAlias, const struct OH_Huks_ParamSet * paramSet ) 103``` 104**Description** 105 106Deletes a key. 107 108**Parameters** 109 110| Name| Description| 111| -------- | -------- | 112| 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. | 113| paramSet | Indicates the pointer to the parameters required for deleting the key. By default, this parameter is a null pointer. | 114 115**Returns** 116 117Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md) if the operation is successful; returns an error code otherwise. 118 119 120### OH_Huks_ExportPublicKeyItem() 121 122 123``` 124struct OH_Huks_Result OH_Huks_ExportPublicKeyItem (const struct OH_Huks_Blob * keyAlias, const struct OH_Huks_ParamSet * paramSet, struct OH_Huks_Blob * key ) 125``` 126**Description** 127 128Exports a public key. 129 130**Parameters** 131 132| Name| Description| 133| -------- | -------- | 134| 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. | 135| paramSet | Indicates the pointer to the parameters required for exporting the public key. | 136| key | Indicates the pointer to the public key exported. | 137 138**Returns** 139 140Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md) if the operation is successful; returns an error code otherwise. 141 142 143### OH_Huks_FinishSession() 144 145 146``` 147struct 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 ) 148``` 149**Description** 150 151Finishes a key session. 152 153**Parameters** 154 155| Name| Description| 156| -------- | -------- | 157| handle | Indicates the pointer to the key session handle, which is generated by [OH_Huks_InitSession](#oh_huks_initsession). | 158| paramSet | Indicates the pointer to the parameters required for the key operation. | 159| inData | Indicates the pointer to the data to be passed in. | 160| outData | Indicates the pointer to the output data. | 161 162**Returns** 163 164Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md) if the operation is successful; returns an error code otherwise. 165 166**See** 167 168[OH_Huks_InitSession](#oh_huks_initsession) 169 170[OH_Huks_UpdateSession](#oh_huks_updatesession) 171 172[OH_Huks_AbortSession](#oh_huks_abortsession) 173 174 175### OH_Huks_GenerateKeyItem() 176 177 178``` 179struct OH_Huks_Result OH_Huks_GenerateKeyItem (const struct OH_Huks_Blob * keyAlias, const struct OH_Huks_ParamSet * paramSetIn, struct OH_Huks_ParamSet * paramSetOut ) 180``` 181**Description** 182 183Generates a key. 184 185**Parameters** 186 187| Name| Description| 188| -------- | -------- | 189| keyAlias | Indicates the pointer to the alias of the key to generate. The alias must be unique in the process of the service. | 190| paramSetIn | Indicates the pointer to the parameters for generating the key. | 191| 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. | 192 193**Returns** 194 195Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md) if the operation is successful; returns an error code otherwise. 196 197 198### OH_Huks_GetKeyItemParamSet() 199 200 201``` 202struct OH_Huks_Result OH_Huks_GetKeyItemParamSet (const struct OH_Huks_Blob * keyAlias, const struct OH_Huks_ParamSet * paramSetIn, struct OH_Huks_ParamSet * paramSetOut ) 203``` 204**Description** 205 206Obtains the properties of a key. 207 208**Parameters** 209 210| Name| Description| 211| -------- | -------- | 212| keyAlias | Indicates the pointer to the alias of the target key. | 213| paramSetIn | Indicates the pointer to the tag required for obtaining the properties. By default, this parameter is a null pointer. | 214| paramSetOut | Indicates the pointer to the key properties obtained. | 215 216**Returns** 217 218Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md) if the operation is successful; returns an error code otherwise. 219 220 221### OH_Huks_GetSdkVersion() 222 223 224``` 225struct OH_Huks_Result OH_Huks_GetSdkVersion (struct OH_Huks_Blob * sdkVersion) 226``` 227**Description** 228 229Obtains the current HUKS SDK version. 230 231**Parameters** 232 233| Name| Description| 234| -------- | -------- | 235| sdkVersion | Indicates the pointer to the SDK version (string) obtained. | 236 237**Returns** 238 239Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md) if the operation is successful; returns an error code otherwise. 240 241 242### OH_Huks_ImportKeyItem() 243 244 245``` 246struct OH_Huks_Result OH_Huks_ImportKeyItem (const struct OH_Huks_Blob * keyAlias, const struct OH_Huks_ParamSet * paramSet, const struct OH_Huks_Blob * key ) 247``` 248**Description** 249 250Imports a key in plaintext. 251 252**Parameters** 253 254| Name| Description| 255| -------- | -------- | 256| keyAlias | Indicates the pointer to the alias of the key to import. The alias must be unique in the process of the service. | 257| paramSet | Indicates the pointer to the properties of the key to import. | 258| key | Indicates the pointer to the key to import. The key data must be in format defined in [HuksTypeApi](_huks_type_api.md). | 259 260**Returns** 261 262Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md) if the operation is successful; returns an error code otherwise. 263 264 265### OH_Huks_ImportWrappedKeyItem() 266 267 268``` 269struct 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 ) 270``` 271**Description** 272 273Imports a wrapped (encrypted) key. 274 275**Parameters** 276 277| Name| Description| 278| -------- | -------- | 279| keyAlias | Indicates the pointer to the alias of the key to import. The alias must be unique in the process of the service. | 280| 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. | 281| paramSet | Indicates the pointer to the parameters for importing the wrapped key. | 282| 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).| 283 284**Returns** 285 286Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md) if the operation is successful; returns an error code otherwise. 287 288 289### OH_Huks_InitSession() 290 291 292``` 293struct 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 ) 294``` 295**Description** 296 297Initializes a key session to obtain a handle (mandatory) and a token (optional). 298 299**Parameters** 300 301| Name| Description| 302| -------- | -------- | 303| keyAlias | Indicates the pointer to the alias of the target key. | 304| paramSet | Indicates the pointer to the parameters for the initialization operation. | 305| 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). | 306| token | Indicates the pointer to the token used for key access control. | 307 308**Returns** 309 310Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md) if the operation is successful; returns an error code otherwise. 311 312**See** 313 314[OH_Huks_UpdateSession](#oh_huks_updatesession) 315 316[OH_Huks_FinishSession](#oh_huks_finishsession) 317 318[OH_Huks_AbortSession](#oh_huks_abortsession) 319 320 321### OH_Huks_IsKeyItemExist() 322 323 324``` 325struct OH_Huks_Result OH_Huks_IsKeyItemExist (const struct OH_Huks_Blob * keyAlias, const struct OH_Huks_ParamSet * paramSet ) 326``` 327**Description** 328 329Checks whether a key exists. 330 331**Parameters** 332 333| Name| Description| 334| -------- | -------- | 335| keyAlias | Indicates the pointer to the alias of the key to check. | 336| paramSet | Indicates the pointer to the parameters required for checking the key. By default, this parameter is a null pointer. | 337 338**Returns** 339 340Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md) if the key exists.<br>Returns [OH_Huks_ErrCode#OH_HUKS_ERR_CODE_ITEM_NOT_EXIST](_huks_type_api.md) if the key does not exist.<br>Returns any other error code for other cases. 341 342 343### OH_Huks_UpdateSession() 344 345 346``` 347struct 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 ) 348``` 349**Description** 350 351Adds data by segment for the key operation, performs the related key operation, and outputs the processed data. 352 353**Parameters** 354 355| Name| Description| 356| -------- | -------- | 357| handle | Indicates the pointer to the key session handle, which is generated by [OH_Huks_InitSession](#oh_huks_initsession). | 358| paramSet | Indicates the pointer to the parameters required for the key operation. | 359| inData | Indicates the pointer to the data to be processed. This API can be called multiple times to process large data by segment. | 360| outData | Indicates the pointer to the output data. | 361 362**Returns** 363 364Returns [OH_Huks_ErrCode#OH_HUKS_SUCCESS](_huks_type_api.md) if the operation is successful; returns an error code otherwise. 365 366**See** 367 368[OH_Huks_InitSession](#oh_huks_initsession) 369 370[OH_Huks_FinishSession](#oh_huks_finishsession) 371 372[OH_Huks_AbortSession](#oh_huks_abortsession) 373