1# native_huks_api.h 2 3<!--Kit: Universal Keystore Kit--> 4<!--Subsystem: Security--> 5<!--Owner: @wutiantian-gitee--> 6<!--Designer: @HighLowWorld--> 7<!--Tester: @wxy1234564846--> 8<!--Adviser: @zengyawen--> 9 10## Overview 11 12Declares the APIs used to access the HUKS. 13 14**File to include**: <huks/native_huks_api.h> 15 16**Library**: libhuks_ndk.z.so 17 18**System capability**: SystemCapability.Security.Huks.Core 19 20The preceding system capability is available since API version 20. From API versions 9 to 19, the system capability is **SystemCapability.Security.Huks**. 21 22**Since**: 9 23 24**Related modules:** [HuksKeyApi](capi-hukskeyapi.md) 25 26## Summary 27 28### Functions 29 30| Name| Description| 31| -- | -- | 32| [struct OH_Huks_Result OH_Huks_GetSdkVersion(struct OH_Huks_Blob *sdkVersion)](#oh_huks_getsdkversion) | Obtains the current HUKS SDK version.| 33| [struct OH_Huks_Result OH_Huks_GenerateKeyItem(const struct OH_Huks_Blob *keyAlias,const struct OH_Huks_ParamSet *paramSetIn, struct OH_Huks_ParamSet *paramSetOut)](#oh_huks_generatekeyitem) | Generates a key.| 34| [struct OH_Huks_Result OH_Huks_ImportKeyItem(const struct OH_Huks_Blob *keyAlias,const struct OH_Huks_ParamSet *paramSet, const struct OH_Huks_Blob *key)](#oh_huks_importkeyitem) | Imports a key in plaintext.| 35| [struct 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)](#oh_huks_importwrappedkeyitem) | Imports a key in ciphertext.| 36| [struct OH_Huks_Result OH_Huks_ExportPublicKeyItem(const struct OH_Huks_Blob *keyAlias,const struct OH_Huks_ParamSet *paramSet, struct OH_Huks_Blob *key)](#oh_huks_exportpublickeyitem) | Exports the public key.| 37| [struct OH_Huks_Result OH_Huks_DeleteKeyItem(const struct OH_Huks_Blob *keyAlias,const struct OH_Huks_ParamSet *paramSet)](#oh_huks_deletekeyitem) | Deletes a key.| 38| [struct OH_Huks_Result OH_Huks_GetKeyItemParamSet(const struct OH_Huks_Blob *keyAlias,const struct OH_Huks_ParamSet *paramSetIn, struct OH_Huks_ParamSet *paramSetOut)](#oh_huks_getkeyitemparamset) | Obtains the properties of a key.| 39| [struct OH_Huks_Result OH_Huks_IsKeyItemExist(const struct OH_Huks_Blob *keyAlias,const struct OH_Huks_ParamSet *paramSet)](#oh_huks_iskeyitemexist) | Checks whether a key exists.| 40| [struct OH_Huks_Result OH_Huks_AttestKeyItem(const struct OH_Huks_Blob *keyAlias,const struct OH_Huks_ParamSet *paramSet, struct OH_Huks_CertChain *certChain)](#oh_huks_attestkeyitem) | Obtains the certificate chain of a key. This API is open only to system applications.| 41| [struct OH_Huks_Result OH_Huks_AnonAttestKeyItem(const struct OH_Huks_Blob *keyAlias,const struct OH_Huks_ParamSet *paramSet, struct OH_Huks_CertChain *certChain)](#oh_huks_anonattestkeyitem) | Obtains the certificate chain of a key.<br> This function involves time-consuming network operation. The caller can obtain the certificate chain through an asynchronous thread.| 42| [struct 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)](#oh_huks_initsession) | Initializes a key session. This function returns a session handle (mandatory) and a challenge value (optional).| 43| [struct 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)](#oh_huks_updatesession) | Adds data by segment for the key operation, performs the related key operation, and outputs the processed data.| 44| [struct 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)](#oh_huks_finishsession) | Finishes a key session.| 45| [struct OH_Huks_Result OH_Huks_AbortSession(const struct OH_Huks_Blob *handle,const struct OH_Huks_ParamSet *paramSet)](#oh_huks_abortsession) | Aborts a key session.| 46| [struct OH_Huks_Result OH_Huks_ListAliases(const struct OH_Huks_ParamSet *paramSet,struct OH_Huks_KeyAliasSet **outData)](#oh_huks_listaliases) | Obtains the key alias set.| 47| [struct OH_Huks_Result OH_Huks_WrapKey(const struct OH_Huks_Blob *keyAlias, const struct OH_Huks_ParamSet *paramSet,struct OH_Huks_Blob *wrappedKey)](#oh_huks_wrapkey) | Exports a wrapped key.| 48| [struct OH_Huks_Result OH_Huks_UnwrapKey(const struct OH_Huks_Blob *keyAlias, const struct OH_Huks_ParamSet *paramSet,struct OH_Huks_Blob *wrappedKey)](#oh_huks_unwrapkey) | Imports a wrapped key.| 49 50## Function Description 51 52### OH_Huks_GetSdkVersion() 53 54``` 55struct OH_Huks_Result OH_Huks_GetSdkVersion(struct OH_Huks_Blob *sdkVersion) 56``` 57 58**Description** 59 60Obtains the current HUKS SDK version. 61 62**Since**: 9 63 64 65**Parameters** 66 67| Name| Description| 68| -- | -- | 69| [struct OH_Huks_Blob](capi-hukstypeapi-oh-huks-blob.md) *sdkVersion | Pointer to the SDK version (string) obtained.| 70 71**Returns** 72 73| Type| Description| 74| -- | -- | 75| [struct OH_Huks_Result](capi-hukstypeapi-oh-huks-result.md) | Possible error codes (**errorCode**):<br> OH_HUKS_SUCCESS = 0: Operation successful.<br> OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT = 401: The value of **sdkVersion** or **sdkVersion->data** is **null**, or the value of **sdkVersion->size** is too small.| 76 77### OH_Huks_GenerateKeyItem() 78 79``` 80struct OH_Huks_Result OH_Huks_GenerateKeyItem(const struct OH_Huks_Blob *keyAlias,const struct OH_Huks_ParamSet *paramSetIn, struct OH_Huks_ParamSet *paramSetOut) 81``` 82 83**Description** 84 85Generates a key. 86 87**Since**: 9 88 89 90**Parameters** 91 92| Name| Description| 93| -- | -- | 94| [const struct OH_Huks_Blob](capi-hukstypeapi-oh-huks-blob.md) *keyAlias | Pointer to the alias of the key to generate. The alias must be unique in the process of the service.| 95| [const struct OH_Huks_ParamSet](capi-hukstypeapi-oh-huks-paramset.md) *paramSetIn | Pointer to the parameters for generating the key.| 96| [struct OH_Huks_ParamSet](capi-hukstypeapi-oh-huks-paramset.md) *paramSetOut | Pointer to a temporary key generated. If the generated key is not a temporary key, this parameter is a null pointer.| 97 98**Returns** 99 100| Type| Description| 101| -- | -- | 102| [struct OH_Huks_Result](capi-hukstypeapi-oh-huks-result.md) | Possible error codes (**errorCode**):<br> OH_HUKS_SUCCESS = 0: Operation successful.<br> OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT = 401: **keyAlias**, **paramSetIn**, or **paramSetOut** is invalid.<br> OH_HUKS_ERR_CODE_INTERNAL_ERROR = 12000012: A system error occurs.<br> OH_HUKS_ERR_CODE_FILE_OPERATION_FAIL = 12000004: Failed to delete or write the file.<br> OH_HUKS_ERR_CODE_INVALID_CRYPTO_ALG_ARGUMENT = 12000003: Invalid key parameter.<br> OH_HUKS_ERR_CODE_ITEM_NOT_EXIST = 12000011: The key file does not exist.<br> OH_HUKS_ERR_CODE_MISSING_CRYPTO_ALG_ARGUMENT = 12000002: Failed to obtain key arguments.<br> OH_HUKS_ERR_CODE_COMMUNICATION_FAIL = 12000005: IPC communication failed.<br> OH_HUKS_ERR_CODE_CRYPTO_FAIL = 12000006: The encryption engine failed.<br> OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY = 12000014: Insufficient memory.<br> OH_HUKS_ERR_CODE_CALL_SERVICE_FAILED = 12000015: Failed to connect to the user IAM.<br> OH_HUKS_ERR_CODE_DEVICE_PASSWORD_UNSET = 12000016: No device password is set.<br> OH_HUKS_ERR_CODE_FEATURE_NOT_SUPPORTED = 12000001: This feature is not supported currently.<br> OH_HUKS_ERR_CODE_KEY_ALREADY_EXIST = 12000017 (new in API version 20): A key with the same name already exists.| 103 104### OH_Huks_ImportKeyItem() 105 106``` 107struct OH_Huks_Result OH_Huks_ImportKeyItem(const struct OH_Huks_Blob *keyAlias,const struct OH_Huks_ParamSet *paramSet, const struct OH_Huks_Blob *key) 108``` 109 110**Description** 111 112Imports a key in plaintext. 113 114**Since**: 9 115 116 117**Parameters** 118 119| Name| Description| 120| -- | -- | 121| [const struct OH_Huks_Blob](capi-hukstypeapi-oh-huks-blob.md) *keyAlias | Pointer to the alias of the key to import. The alias must be unique in the process of the service.| 122| [const struct OH_Huks_ParamSet](capi-hukstypeapi-oh-huks-paramset.md) *paramSet | Pointer to the properties of the key to import.| 123| [const struct OH_Huks_Blob](capi-hukstypeapi-oh-huks-blob.md) *key | Pointer to the data of the key to import, complying with the format requirements of HUKS. For details, see [native_huks_type.h](capi-native-huks-type-h.md).| 124 125**Returns** 126 127| Type| Description| 128| -- | -- | 129| [struct OH_Huks_Result](capi-hukstypeapi-oh-huks-result.md) | Possible error codes (**errorCode**):<br> OH_HUKS_SUCCESS = 0: Operation successful.<br> OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT = 401: **keyAlias**, **paramSet**, or **key** is invalid.<br> OH_HUKS_ERR_CODE_INTERNAL_ERROR = 12000012: A system error occurs.<br> OH_HUKS_ERR_CODE_FILE_OPERATION_FAIL = 12000004: Failed to delete or write the file.<br> OH_HUKS_ERR_CODE_INVALID_CRYPTO_ALG_ARGUMENT = 12000003: Invalid key parameter.<br> OH_HUKS_ERR_CODE_MISSING_CRYPTO_ALG_ARGUMENT = 12000002: Failed to obtain key arguments.<br> OH_HUKS_ERR_CODE_COMMUNICATION_FAIL = 12000005: IPC communication failed.<br> OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY = 12000014: Insufficient memory.<br> OH_HUKS_ERR_CODE_CALL_SERVICE_FAILED = 12000015: Failed to connect to the user IAM.<br> OH_HUKS_ERR_CODE_FEATURE_NOT_SUPPORTED = 12000001: This feature is not supported currently.<br> OH_HUKS_ERR_CODE_KEY_ALREADY_EXIST = 12000017 (new in API version 20): A key with the same name already exists.| 130 131### OH_Huks_ImportWrappedKeyItem() 132 133``` 134struct 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) 135``` 136 137**Description** 138 139Imports a key in ciphertext. 140 141**Since**: 9 142 143 144**Parameters** 145 146| Name| Description| 147| -- | -- | 148| [const struct OH_Huks_Blob](capi-hukstypeapi-oh-huks-blob.md) *keyAlias | Pointer to the alias of the key to import. The alias must be unique in the process of the service.| 149| [const struct OH_Huks_Blob](capi-hukstypeapi-oh-huks-blob.md) *wrappingKeyAlias | Pointer to the alias of the key used for key agreement, which generates a shared secret to decrypt the key to import.| 150| [const struct OH_Huks_ParamSet](capi-hukstypeapi-oh-huks-paramset.md) *paramSet | Pointer to the parameters for importing the key in ciphertext.| 151| [const struct OH_Huks_Blob](capi-hukstypeapi-oh-huks-blob.md) *wrappedKeyData | Pointer to the data of the key to import, complying with the format requirements of HUKS. For details, see [OH_Huks_AlgSuite](capi-native-huks-type-h.md#oh_huks_algsuite).| 152 153**Returns** 154 155| Type| Description| 156| -- | -- | 157| [struct OH_Huks_Result](capi-hukstypeapi-oh-huks-result.md) | Possible error codes (**errorCode**):<br> OH_HUKS_SUCCESS = 0: Operation successful.<br> OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT = 401: **keyAlias**, **wrappingKeyAlias**, **paramSet**, or **wrappedKeyData** is invalid.<br> OH_HUKS_ERR_CODE_INTERNAL_ERROR = 12000012: A system error occurs.<br> OH_HUKS_ERR_CODE_FILE_OPERATION_FAIL = 12000004: Failed to delete or write the file.<br> OH_HUKS_ERR_CODE_INVALID_CRYPTO_ALG_ARGUMENT = 12000003: Invalid key parameter.<br> OH_HUKS_ERR_CODE_MISSING_CRYPTO_ALG_ARGUMENT = 12000002: Failed to obtain key arguments.<br> OH_HUKS_ERR_CODE_COMMUNICATION_FAIL = 12000005: IPC communication failed.<br> OH_HUKS_ERR_CODE_CRYPTO_FAIL = 12000006: The encryption engine failed.<br> OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY = 12000014: Insufficient memory.<br> OH_HUKS_ERR_CODE_CALL_SERVICE_FAILED = 12000015: Failed to connect to the user IAM.<br> OH_HUKS_ERR_CODE_FEATURE_NOT_SUPPORTED = 12000001: This feature is not supported currently.<br> OH_HUKS_ERR_CODE_KEY_ALREADY_EXIST = 12000017 (new in API version 20): A key with the same name already exists.| 158 159### OH_Huks_ExportPublicKeyItem() 160 161``` 162struct OH_Huks_Result OH_Huks_ExportPublicKeyItem(const struct OH_Huks_Blob *keyAlias,const struct OH_Huks_ParamSet *paramSet, struct OH_Huks_Blob *key) 163``` 164 165**Description** 166 167Exports the public key. 168 169**Since**: 9 170 171 172**Parameters** 173 174| Name| Description| 175| -- | -- | 176| [const struct OH_Huks_Blob](capi-hukstypeapi-oh-huks-blob.md) *keyAlias | Pointer to the alias of the public key to export. It must be the same as the alias used for generating the key.| 177| [const struct OH_Huks_ParamSet](capi-hukstypeapi-oh-huks-paramset.md) *paramSet | Pointer to the parameters for exporting the public key.| 178| [struct OH_Huks_Blob](capi-hukstypeapi-oh-huks-blob.md) *key | Pointer to the public key exported.| 179 180**Returns** 181 182| Type| Description| 183| -- | -- | 184| [struct OH_Huks_Result](capi-hukstypeapi-oh-huks-result.md) | Possible error codes (**errorCode**):<br> OH_HUKS_SUCCESS = 0: Operation successful.<br> OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT = 401: **keyAlias**, **paramSet**, or **key** is invalid.<br> OH_HUKS_ERR_CODE_INTERNAL_ERROR = 12000012: A system error occurs.<br> OH_HUKS_ERR_CODE_ITEM_NOT_EXIST = 12000011: The key file does not exist.<br> OH_HUKS_ERR_CODE_INVALID_CRYPTO_ALG_ARGUMENT = 12000003: Invalid key parameter.<br> OH_HUKS_ERR_CODE_MISSING_CRYPTO_ALG_ARGUMENT = 12000002: Failed to obtain key arguments.<br> OH_HUKS_ERR_CODE_COMMUNICATION_FAIL = 12000005: IPC communication failed.<br> OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY = 12000014: Insufficient memory.<br> OH_HUKS_ERR_CODE_FEATURE_NOT_SUPPORTED = 12000001: This feature is not supported currently.| 185 186### OH_Huks_DeleteKeyItem() 187 188``` 189struct OH_Huks_Result OH_Huks_DeleteKeyItem(const struct OH_Huks_Blob *keyAlias,const struct OH_Huks_ParamSet *paramSet) 190``` 191 192**Description** 193 194Deletes a key. 195 196**Since**: 9 197 198 199**Parameters** 200 201| Name| Description| 202| -- | -- | 203| [const struct OH_Huks_Blob](capi-hukstypeapi-oh-huks-blob.md) *keyAlias | Pointer to the alias of the key to delete. It must be the same as the alias used for generating the key.| 204| [const struct OH_Huks_ParamSet](capi-hukstypeapi-oh-huks-paramset.md) *paramSet | Pointer to the parameters for deleting the key. By default, this parameter is a null pointer. The default key storage level is [OH_HUKS_AUTH_STORAGE_LEVEL_CE](capi-native-huks-type-h.md#oh_huks_authstoragelevel).| 205 206**Returns** 207 208| Type| Description| 209| -- | -- | 210| [struct OH_Huks_Result](capi-hukstypeapi-oh-huks-result.md) | Possible error codes (**errorCode**):<br> OH_HUKS_SUCCESS = 0: Operation successful.<br> OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT = 401: **keyAlias** or **paramSet** is invalid.<br> OH_HUKS_ERR_CODE_INTERNAL_ERROR = 12000012: A system error occurs.<br> OH_HUKS_ERR_CODE_INVALID_CRYPTO_ALG_ARGUMENT = 12000003: Invalid key parameter.<br> OH_HUKS_ERR_CODE_ITEM_NOT_EXIST = 12000011: The key file does not exist.<br> OH_HUKS_ERR_CODE_MISSING_CRYPTO_ALG_ARGUMENT = 12000002: Failed to obtain key arguments.<br> OH_HUKS_ERR_CODE_COMMUNICATION_FAIL = 12000005: IPC communication failed.<br> OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY = 12000014: Insufficient memory.| 211 212### OH_Huks_GetKeyItemParamSet() 213 214``` 215struct OH_Huks_Result OH_Huks_GetKeyItemParamSet(const struct OH_Huks_Blob *keyAlias,const struct OH_Huks_ParamSet *paramSetIn, struct OH_Huks_ParamSet *paramSetOut) 216``` 217 218**Description** 219 220Obtains the properties of a key. 221 222**Since**: 9 223 224 225**Parameters** 226 227| Name| Description| 228| -- | -- | 229| [const struct OH_Huks_Blob](capi-hukstypeapi-oh-huks-blob.md) *keyAlias | Pointer to the alias of the target key.| 230| [const struct OH_Huks_ParamSet](capi-hukstypeapi-oh-huks-paramset.md) *paramSetIn | Pointer to the tag required for obtaining the properties. By default, this parameter is a null pointer.| 231| [struct OH_Huks_ParamSet](capi-hukstypeapi-oh-huks-paramset.md) *paramSetOut | Pointer to the key properties obtained.| 232 233**Returns** 234 235| Type| Description| 236| -- | -- | 237| [struct OH_Huks_Result](capi-hukstypeapi-oh-huks-result.md) | Possible error codes (**errorCode**):<br> OH_HUKS_SUCCESS = 0: Operation successful.<br> OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT = 401: **keyAlias**, **paramSetIn**, or **paramSetOut** is invalid.<br> OH_HUKS_ERR_CODE_INTERNAL_ERROR = 12000012: A system error occurs.<br> OH_HUKS_ERR_CODE_INVALID_CRYPTO_ALG_ARGUMENT = 12000003: Invalid key parameter.<br> OH_HUKS_ERR_CODE_ITEM_NOT_EXIST = 12000011: The key file does not exist.<br> OH_HUKS_ERR_CODE_MISSING_CRYPTO_ALG_ARGUMENT = 12000002: Failed to obtain key arguments.<br> OH_HUKS_ERR_CODE_COMMUNICATION_FAIL = 12000005: IPC communication failed.<br> OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY = 12000014: Insufficient memory.<br> OH_HUKS_ERR_CODE_FEATURE_NOT_SUPPORTED = 12000001: This feature is not supported currently.| 238 239### OH_Huks_IsKeyItemExist() 240 241``` 242struct OH_Huks_Result OH_Huks_IsKeyItemExist(const struct OH_Huks_Blob *keyAlias,const struct OH_Huks_ParamSet *paramSet) 243``` 244 245**Description** 246 247Checks whether a key exists. 248 249**Since**: 9 250 251 252**Parameters** 253 254| Name| Description| 255| -- | -- | 256| [const struct OH_Huks_Blob](capi-hukstypeapi-oh-huks-blob.md) *keyAlias | Pointer to the alias of the key to check.| 257| [const struct OH_Huks_ParamSet](capi-hukstypeapi-oh-huks-paramset.md) *paramSet | Pointer to the parameters for checking the key. By default, this parameter is a null pointer.| 258 259**Returns** 260 261| Type| Description| 262| -- | -- | 263| [struct OH_Huks_Result](capi-hukstypeapi-oh-huks-result.md) | Possible error codes (**errorCode**):<br> OH_HUKS_SUCCESS = 0: Operation successful.<br> OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT = 401: **keyAlias** or **paramSet** is invalid.<br> OH_HUKS_ERR_CODE_INTERNAL_ERROR = 12000012: A system error occurs.<br> OH_HUKS_ERR_CODE_INVALID_CRYPTO_ALG_ARGUMENT = 12000003: Invalid key parameter.<br> OH_HUKS_ERR_CODE_ITEM_NOT_EXIST = 12000011: The key file does not exist.<br> OH_HUKS_ERR_CODE_MISSING_CRYPTO_ALG_ARGUMENT = 12000002: Failed to obtain key arguments.<br> OH_HUKS_ERR_CODE_COMMUNICATION_FAIL = 12000005: IPC communication failed.<br> OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY = 12000014: Insufficient memory.| 264 265### OH_Huks_AttestKeyItem() 266 267``` 268struct OH_Huks_Result OH_Huks_AttestKeyItem(const struct OH_Huks_Blob *keyAlias,const struct OH_Huks_ParamSet *paramSet, struct OH_Huks_CertChain *certChain) 269``` 270 271**Description** 272 273Obtains the certificate chain of a key. This API is open only to system applications. 274 275**Required permissions**: ohos.permission.ATTEST_KEY (available only for system applications) 276 277**Since**: 9 278 279 280**Parameters** 281 282| Name| Description| 283| -- | -- | 284| [const struct OH_Huks_Blob](capi-hukstypeapi-oh-huks-blob.md) *keyAlias | Pointer to the alias of the target key.| 285| [const struct OH_Huks_ParamSet](capi-hukstypeapi-oh-huks-paramset.md) *paramSet | Pointer to the parameters for obtaining the certificate chain.| 286| [struct OH_Huks_CertChain](capi-hukstypeapi-oh-huks-certchain.md) *certChain | Pointer to the certificate chain obtained.| 287 288**Returns** 289 290| Type| Description| 291| -- | -- | 292| [struct OH_Huks_Result](capi-hukstypeapi-oh-huks-result.md) | Possible error codes (**errorCode**):<br> OH_HUKS_SUCCESS = 0: Operation successful.<br> OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT = 401: **keyAlias**, **paramSet**, or **certChain** is invalid.<br> OH_HUKS_ERR_CODE_INTERNAL_ERROR = 12000012: A system error occurs.<br> OH_HUKS_ERR_CODE_INVALID_CRYPTO_ALG_ARGUMENT = 12000003: Invalid key parameter.<br> OH_HUKS_ERR_CODE_ITEM_NOT_EXIST = 12000011: The key file does not exist.<br> OH_HUKS_ERR_CODE_MISSING_CRYPTO_ALG_ARGUMENT = 12000002: Failed to obtain key arguments.<br> OH_HUKS_ERR_CODE_COMMUNICATION_FAIL = 12000005: IPC communication failed.<br> OH_HUKS_ERR_CODE_CRYPTO_FAIL = 12000006: The encryption engine failed.<br> OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY = 12000014: Insufficient memory.<br> OH_HUKS_ERR_CODE_FEATURE_NOT_SUPPORTED = 12000001: This feature is not supported currently.<br> OH_HUKS_ERR_CODE_PERMISSION_FAIL = 201: Permission check failed. Request the permission first.| 293 294### OH_Huks_AnonAttestKeyItem() 295 296``` 297struct OH_Huks_Result OH_Huks_AnonAttestKeyItem(const struct OH_Huks_Blob *keyAlias,const struct OH_Huks_ParamSet *paramSet, struct OH_Huks_CertChain *certChain) 298``` 299 300**Description** 301 302Obtains the certificate chain of a key.<br> This function involves time-consuming network operation. The caller can obtain the certificate chain through an asynchronous thread. 303 304**Since**: 11 305 306 307**Parameters** 308 309| Name| Description| 310| -- | -- | 311| [const struct OH_Huks_Blob](capi-hukstypeapi-oh-huks-blob.md) *keyAlias | Pointer to the alias of the target key.| 312| [const struct OH_Huks_ParamSet](capi-hukstypeapi-oh-huks-paramset.md) *paramSet | Pointer to the parameters for obtaining the certificate chain.| 313| [struct OH_Huks_CertChain](capi-hukstypeapi-oh-huks-certchain.md) *certChain | Pointer to the certificate chain obtained.| 314 315**Returns** 316 317| Type| Description| 318| -- | -- | 319| [struct OH_Huks_Result](capi-hukstypeapi-oh-huks-result.md) | Possible error codes (**errorCode**):<br> OH_HUKS_SUCCESS = 0: Operation successful.<br> OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT = 401: **keyAlias**, **paramSet**, or **certChain** is invalid.<br> OH_HUKS_ERR_CODE_INTERNAL_ERROR = 12000012: A system error occurs.<br> OH_HUKS_ERR_CODE_INVALID_CRYPTO_ALG_ARGUMENT = 12000003: Invalid key parameter.<br> OH_HUKS_ERR_CODE_ITEM_NOT_EXIST = 12000011: The key file does not exist.<br> OH_HUKS_ERR_CODE_MISSING_CRYPTO_ALG_ARGUMENT = 12000002: Failed to obtain key arguments.<br> OH_HUKS_ERR_CODE_COMMUNICATION_FAIL = 12000005: IPC communication failed.<br> OH_HUKS_ERR_CODE_CRYPTO_FAIL = 12000006: The encryption engine failed.<br> OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY = 12000014: Insufficient memory.<br> OH_HUKS_ERR_CODE_FEATURE_NOT_SUPPORTED = 12000001: This feature is not supported currently.<br> OH_HUKS_ERR_CODE_PERMISSION_FAIL = 201: Permission check failed. Request the permission first.| 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 327**Description** 328 329Initializes a key session. This function returns a session handle (mandatory) and a challenge value (optional). 330 331**Since**: 9 332 333 334**Parameters** 335 336| Name| Description| 337| -- | -- | 338| [const struct OH_Huks_Blob](capi-hukstypeapi-oh-huks-blob.md) *keyAlias | Pointer to the alias of the key to be operated.| 339| [const struct OH_Huks_ParamSet](capi-hukstypeapi-oh-huks-paramset.md) *paramSet | Pointer to the parameters for the initialization operation.| 340| [struct OH_Huks_Blob](capi-hukstypeapi-oh-huks-blob.md) *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| [struct OH_Huks_Blob](capi-hukstypeapi-oh-huks-blob.md) *token | Pointer to the token used for key access control.| 342 343**Returns** 344 345| Type| Description| 346| -- | -- | 347| [struct OH_Huks_Result](capi-hukstypeapi-oh-huks-result.md) | Possible error codes (**errorCode**):<br> OH_HUKS_SUCCESS = 0: Operation successful.<br> OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT = 401: **keyAlias**, **paramSet**, **handle**, or **token** is invalid.<br> OH_HUKS_ERR_CODE_INTERNAL_ERROR = 12000012: A system error occurs.<br> OH_HUKS_ERR_CODE_INVALID_CRYPTO_ALG_ARGUMENT = 12000003: Invalid key parameter.<br> OH_HUKS_ERR_CODE_ITEM_NOT_EXIST = 12000011: The key file does not exist.<br> OH_HUKS_ERR_CODE_MISSING_CRYPTO_ALG_ARGUMENT = 12000002: Failed to obtain key arguments.<br> OH_HUKS_ERR_CODE_COMMUNICATION_FAIL = 12000005: IPC communication failed.<br> OH_HUKS_ERR_CODE_SESSION_LIMIT = 12000010: Hit the session limit.<br> OH_HUKS_ERR_CODE_CRYPTO_FAIL = 12000006: The encryption engine failed.<br> OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY = 12000014: Insufficient memory.<br> OH_HUKS_ERR_CODE_FEATURE_NOT_SUPPORTED = 12000001: This feature is not supported currently.| 348 349**Reference** 350 351[OH_Huks_UpdateSession](#oh_huks_updatesession) 352 353[OH_Huks_FinishSession](#oh_huks_finishsession) 354 355[OH_Huks_AbortSession](#oh_huks_abortsession) 356 357 358### OH_Huks_UpdateSession() 359 360``` 361struct 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) 362``` 363 364**Description** 365 366Adds data by segment for the key operation, performs the related key operation, and outputs the processed data. 367 368**Since**: 9 369 370 371**Parameters** 372 373| Name| Description| 374| -- | -- | 375| [const struct OH_Huks_Blob](capi-hukstypeapi-oh-huks-blob.md) *handle | Pointer to the key session handle, which is returned by [OH_Huks_InitSession](#oh_huks_initsession).| 376| [const struct OH_Huks_ParamSet](capi-hukstypeapi-oh-huks-paramset.md) *paramSet | Pointer to the parameters required for the key operation.| 377| [const struct OH_Huks_Blob](capi-hukstypeapi-oh-huks-blob.md) *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.| 378| [struct OH_Huks_Blob](capi-hukstypeapi-oh-huks-blob.md) *outData | Pointer to the output data.| 379 380**Returns** 381 382| Type| Description| 383| -- | -- | 384| [struct OH_Huks_Result](capi-hukstypeapi-oh-huks-result.md) | Possible error codes (**errorCode**):<br> OH_HUKS_SUCCESS = 0: Operation successful.<br> OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT = 401: **handle**, **paramSet**, **inData**, or **outData** is invalid.<br> OH_HUKS_ERR_CODE_INTERNAL_ERROR = 12000012: A system error occurs.<br> OH_HUKS_ERR_CODE_INVALID_CRYPTO_ALG_ARGUMENT = 12000003: Invalid key parameter.<br> OH_HUKS_ERR_CODE_ITEM_NOT_EXIST = 12000011: The key file or the handle does not exist.<br> OH_HUKS_ERR_CODE_MISSING_CRYPTO_ALG_ARGUMENT = 12000002: Failed to obtain key arguments.<br> OH_HUKS_ERR_CODE_COMMUNICATION_FAIL = 12000005: IPC communication failed.<br> OH_HUKS_ERR_CODE_CREDENTIAL_NOT_EXIST = 12000013: The certificate does not exist.<br> OH_HUKS_ERR_CODE_CRYPTO_FAIL = 12000006: The encryption engine failed.<br> OH_HUKS_ERR_CODE_KEY_AUTH_VERIFY_FAILED = 12000008: Failed to verify the access token.<br> OH_HUKS_ERR_CODE_KEY_AUTH_PERMANENTLY_INVALIDATED = 12000007: Failed to verify the access token information.<br> OH_HUKS_ERR_CODE_KEY_AUTH_TIME_OUT = 12000009: The verification of the access token times out.<br> OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY = 12000014: Insufficient memory.<br> OH_HUKS_ERR_CODE_DEVICE_PASSWORD_UNSET = 12000016: No device password is set.<br> OH_HUKS_ERR_CODE_FEATURE_NOT_SUPPORTED = 12000001: This feature is not supported currently.| 385 386**Reference** 387 388[OH_Huks_InitSession](#oh_huks_initsession) 389 390[OH_Huks_FinishSession](#oh_huks_finishsession) 391 392[OH_Huks_AbortSession](#oh_huks_abortsession) 393 394 395### OH_Huks_FinishSession() 396 397``` 398struct 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) 399``` 400 401**Description** 402 403Finishes a key session. 404 405**Since**: 9 406 407 408**Parameters** 409 410| Name| Description| 411| -- | -- | 412| [const struct OH_Huks_Blob](capi-hukstypeapi-oh-huks-blob.md) *handle | Pointer to the key session handle, which is returned by [OH_Huks_InitSession](#oh_huks_initsession).| 413| [const struct OH_Huks_ParamSet](capi-hukstypeapi-oh-huks-paramset.md) *paramSet | Pointer to the parameters required for the key operation.| 414| [const struct OH_Huks_Blob](capi-hukstypeapi-oh-huks-blob.md) *inData | Pointer to the data to be passed in.| 415| [struct OH_Huks_Blob](capi-hukstypeapi-oh-huks-blob.md) *outData | Pointer to the output data.| 416 417**Returns** 418 419| Type| Description| 420| -- | -- | 421| [struct OH_Huks_Result](capi-hukstypeapi-oh-huks-result.md) | Possible error codes (**errorCode**):<br> OH_HUKS_SUCCESS = 0: Operation successful.<br> OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT = 401: **handle**, **paramSet**, **inData**, or **outData** is invalid.<br> OH_HUKS_ERR_CODE_INTERNAL_ERROR = 12000012: A system error occurs.<br> OH_HUKS_ERR_CODE_INVALID_CRYPTO_ALG_ARGUMENT = 12000003: Invalid key parameter.<br> OH_HUKS_ERR_CODE_ITEM_NOT_EXIST = 12000011: The key file or the handle does not exist.<br> OH_HUKS_ERR_CODE_MISSING_CRYPTO_ALG_ARGUMENT = 12000002: Failed to obtain key arguments.<br> OH_HUKS_ERR_CODE_COMMUNICATION_FAIL = 12000005: IPC communication failed.<br> OH_HUKS_ERR_CODE_CREDENTIAL_NOT_EXIST = 12000013: The certificate does not exist.<br> OH_HUKS_ERR_CODE_CRYPTO_FAIL = 12000006: The encryption engine failed.<br> OH_HUKS_ERR_CODE_KEY_AUTH_VERIFY_FAILED = 12000008: Failed to verify the access token.<br> OH_HUKS_ERR_CODE_KEY_AUTH_PERMANENTLY_INVALIDATED = 12000007: Failed to verify the access token information.<br> OH_HUKS_ERR_CODE_KEY_AUTH_TIME_OUT = 12000009: The verification of the access token times out.<br> OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY = 12000014: Insufficient memory.<br> OH_HUKS_ERR_CODE_DEVICE_PASSWORD_UNSET = 12000016: No device password is set.<br> OH_HUKS_ERR_CODE_FEATURE_NOT_SUPPORTED = 12000001: This feature is not supported currently.<br> OH_HUKS_ERR_CODE_KEY_ALREADY_EXIST = 12000017 (new in API version 20): A key with the same name already exists.| 422 423**Reference** 424 425[OH_Huks_InitSession](#oh_huks_initsession) 426 427[OH_Huks_UpdateSession](#oh_huks_updatesession) 428 429[OH_Huks_AbortSession](#oh_huks_abortsession) 430 431 432### OH_Huks_AbortSession() 433 434``` 435struct OH_Huks_Result OH_Huks_AbortSession(const struct OH_Huks_Blob *handle,const struct OH_Huks_ParamSet *paramSet) 436``` 437 438**Description** 439 440Aborts a key session. 441 442**Since**: 9 443 444 445**Parameters** 446 447| Name| Description| 448| -- | -- | 449| [const struct OH_Huks_Blob](capi-hukstypeapi-oh-huks-blob.md) *handle | Pointer to the key session handle, which is returned by [OH_Huks_InitSession](#oh_huks_initsession).| 450| [const struct OH_Huks_ParamSet](capi-hukstypeapi-oh-huks-paramset.md) *paramSet | Pointer to the parameters for aborting the key session. By default, this parameter is a null pointer.| 451 452**Returns** 453 454| Type| Description| 455| -- | -- | 456| [struct OH_Huks_Result](capi-hukstypeapi-oh-huks-result.md) | Possible error codes (**errorCode**):<br> OH_HUKS_SUCCESS = 0: Operation successful.<br> OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT = 401: **handle**, **paramSet**, **inData**, or **outData** is invalid.<br> OH_HUKS_ERR_CODE_INTERNAL_ERROR = 12000012: A system error occurs.<br> OH_HUKS_ERR_CODE_INVALID_CRYPTO_ALG_ARGUMENT = 12000003: Invalid key parameter.<br> OH_HUKS_ERR_CODE_ITEM_NOT_EXIST = 12000011: The key file or the handle does not exist.<br> OH_HUKS_ERR_CODE_MISSING_CRYPTO_ALG_ARGUMENT = 12000002: Failed to obtain key arguments.<br> OH_HUKS_ERR_CODE_COMMUNICATION_FAIL = 12000005: IPC communication failed.<br> OH_HUKS_ERR_CODE_CREDENTIAL_NOT_EXIST = 12000013: The certificate does not exist.<br> OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY = 12000014: Insufficient memory.| 457 458**Reference** 459 460[OH_Huks_InitSession](#oh_huks_initsession) 461 462[OH_Huks_UpdateSession](#oh_huks_updatesession) 463 464[OH_Huks_FinishSession](#oh_huks_finishsession) 465 466 467### OH_Huks_ListAliases() 468 469``` 470struct OH_Huks_Result OH_Huks_ListAliases(const struct OH_Huks_ParamSet *paramSet,struct OH_Huks_KeyAliasSet **outData) 471``` 472 473**Description** 474 475Obtains the key alias set. 476 477**Since**: 20 478 479 480**Parameters** 481 482| Name| Description| 483| -- | -- | 484| [const struct OH_Huks_ParamSet](capi-hukstypeapi-oh-huks-paramset.md) *paramSet | Pointer to the parameters for obtaining the key alias set. By default, this parameter is a null pointer.| 485| [struct OH_Huks_KeyAliasSet](capi-hukstypeapi-oh-huks-keyaliasset.md) **outData | Pointer to the output data.| 486 487**Returns** 488 489| Type| Description| 490| -- | -- | 491| [struct OH_Huks_Result](capi-hukstypeapi-oh-huks-result.md) | Possible error codes (**errorCode**):<br> OH_HUKS_SUCCESS = 0: Operation successful.<br> OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT = 401: **paramSet** or **outData** is invalid.<br> OH_HUKS_ERR_CODE_INTERNAL_ERROR = 12000012: A system error occurs.<br> OH_HUKS_ERR_CODE_COMMUNICATION_FAIL = 12000005: IPC communication failed.<br> OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY = 12000014: Insufficient memory.| 492 493### OH_Huks_WrapKey() 494 495``` 496struct OH_Huks_Result OH_Huks_WrapKey(const struct OH_Huks_Blob *keyAlias, const struct OH_Huks_ParamSet *paramSet,struct OH_Huks_Blob *wrappedKey) 497``` 498 499**Description** 500 501Exports a wrapped key. 502 503**Since**: 20 504 505 506**Parameters** 507 508| Name| Description| 509| -- | -- | 510| [const struct OH_Huks_Blob](capi-hukstypeapi-oh-huks-blob.md) *keyAlias | Pointer to the alias of the key to export.| 511| [const struct OH_Huks_ParamSet](capi-hukstypeapi-oh-huks-paramset.md) *paramSet | Pointer to the parameters for encrypting the exported key.| 512| [struct OH_Huks_Blob](capi-hukstypeapi-oh-huks-blob.md) *wrappedKey | Pointer to the wrapped key to export.| 513 514**Returns** 515 516| Type| Description| 517| -- | -- | 518| [struct OH_Huks_Result](capi-hukstypeapi-oh-huks-result.md) | Possible error codes (**errorCode**):<br> OH_HUKS_SUCCESS = 0: Operation successful.<br> OH_HUKS_ERR_CODE_NOT_SUPPORTED_API = 801: The API is not supported.<br> OH_HUKS_ERR_CODE_FILE_OPERATION_FAIL = 12000004: Failed to delete or write the file.<br> OH_HUKS_ERR_CODE_COMMUNICATION_FAIL = 12000005: IPC communication failed.<br> OH_HUKS_ERR_CODE_CRYPTO_FAIL = 12000011: The key file does not exist.<br> OH_HUKS_ERR_CODE_INTERNAL_ERROR = 12000012: A system error occurs.<br> OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY = 12000014: Insufficient memory.<br> OH_HUKS_ERR_CODE_INVALID_ARGUMENT = 12000018: The key alias, parameter set, or wrapped key is invalid.| 519 520### OH_Huks_UnwrapKey() 521 522``` 523struct OH_Huks_Result OH_Huks_UnwrapKey(const struct OH_Huks_Blob *keyAlias, const struct OH_Huks_ParamSet *paramSet,struct OH_Huks_Blob *wrappedKey) 524``` 525 526**Description** 527 528Imports a wrapped key. 529 530**Since**: 20 531 532 533**Parameters** 534 535| Name| Description| 536| -- | -- | 537| [const struct OH_Huks_Blob](capi-hukstypeapi-oh-huks-blob.md) *keyAlias | Pointer to the alias of the key to import. The alias must be unique in the service process. Otherwise, the key will be overwritten.| 538| [const struct OH_Huks_ParamSet](capi-hukstypeapi-oh-huks-paramset.md) *paramSet | Pointer to the parameters for encrypting the imported key.| 539| [struct OH_Huks_Blob](capi-hukstypeapi-oh-huks-blob.md) *wrappedKey | Pointer to the wrapped key to import.| 540 541**Returns** 542 543| Type| Description| 544| -- | -- | 545| [struct OH_Huks_Result](capi-hukstypeapi-oh-huks-result.md) | Possible error codes (**errorCode**):<br> OH_HUKS_SUCCESS = 0: Operation successful.<br> OH_HUKS_ERR_CODE_NOT_SUPPORTED_API = 801: The API is not supported.<br> OH_HUKS_ERR_CODE_FILE_OPERATION_FAIL = 12000004: Failed to delete or write the file.<br> OH_HUKS_ERR_CODE_COMMUNICATION_FAIL = 12000005: IPC communication failed.<br> OH_HUKS_ERR_CODE_INTERNAL_ERROR = 12000012: A system error occurs.<br> OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY = 12000014: Insufficient memory.<br> OH_HUKS_ERR_CODE_CALL_SERVICE_FAILED = 12000015: Failed to connect to the user IAM.<br> OH_HUKS_ERR_CODE_INVALID_ARGUMENT = 12000018: The key alias, parameter set, or wrapped key is invalid.| 546