native_huks_external_crypto_api.h

Overview

Defines the OpenHarmony Universal KeyStore (HUKS) APIs for external key management extensions.

File to include: <huks/native_huks_external_crypto_api.h>

Library: libhuks_external_crypto.z.so

System capability: SystemCapability.Security.Huks.CryptoExtension

Since: 22

Related modules: HuksExternalCryptoApi

Summary

Functions

Name	Description
struct OH_Huks_Result OH_Huks_RegisterProvider(const struct OH_Huks_Blob providerName, const OH_Huks_ExternalCryptoParamSet paramSet)	Registers an external key management extension provider.
struct OH_Huks_Result OH_Huks_UnregisterProvider(const struct OH_Huks_Blob providerName, const OH_Huks_ExternalCryptoParamSet paramSet)	Unregisters an external key management extension provider.
struct OH_Huks_Result OH_Huks_OpenResource(const struct OH_Huks_Blob resourceId, const OH_Huks_ExternalCryptoParamSet paramSet)	Opens a resource based on the specified resource ID. Note: The opened resource must be closed using OH_Huks_CloseResource.
struct OH_Huks_Result OH_Huks_CloseResource(const struct OH_Huks_Blob resourceId, const OH_Huks_ExternalCryptoParamSet paramSet)	Closes a resource based on the specified resource ID.
struct OH_Huks_Result OH_Huks_GetUkeyPinAuthState(const struct OH_Huks_Blob resourceId, const OH_Huks_ExternalCryptoParamSet paramSet, OH_Huks_ExternalPinAuthState *authState)	Obtains the PIN authorization state of the specified Ukey resource ID.
struct OH_Huks_Result OH_Huks_GetProperty(const struct OH_Huks_Blob resourceId, const struct OH_Huks_Blob propertyId, const OH_Huks_ExternalCryptoParamSet paramSetIn, OH_Huks_ExternalCryptoParamSet *paramSetOut)	Obtains the property information of the external key management extension provider.
struct OH_Huks_Result OH_Huks_InitExternalCryptoParamSet(OH_Huks_ExternalCryptoParamSet **paramSet)	Initializes a parameter set.
struct OH_Huks_Result OH_Huks_AddExternalCryptoParams(OH_Huks_ExternalCryptoParamSet paramSet, const OH_Huks_ExternalCryptoParam params, uint32_t paramCnt)	Adds parameters to a parameter set.
struct OH_Huks_Result OH_Huks_BuildExternalCryptoParamSet(OH_Huks_ExternalCryptoParamSet **paramSet)	Builds a parameter set.
void OH_Huks_FreeExternalCryptoParamSet(OH_Huks_ExternalCryptoParamSet **paramSet)	Destroys a parameter set and releases related memory.
struct OH_Huks_Result OH_Huks_GetExternalCryptoParam(OH_Huks_ExternalCryptoParamSet paramSet, const uint32_t tag, OH_Huks_ExternalCryptoParam *param)	Obtains a specified parameter from a parameter set.

Function Description

OH_Huks_RegisterProvider()

struct OH_Huks_Result OH_Huks_RegisterProvider(const struct OH_Huks_Blob *providerName, const OH_Huks_ExternalCryptoParamSet *paramSet)

Description

Registers an external key management extension provider.

Required permissions: ohos.permission.CRYPTO_EXTENSION_REGISTER

Since: 22

Parameters

Name	Description
const struct OH_Huks_Blob *providerName	Name of the provider.
const OH_Huks_ExternalCryptoParamSet *paramSet	Pointer to the registration parameters.

Returns

Type	Description
struct OH_Huks_Result	Possible error codes (errorCode): OH_HUKS_SUCCESS 0: Operation successful. OH_HUKS_ERR_CODE_PERMISSION_FAIL 201: Permission verification fails. Apply for the required permission first. OH_HUKS_ERR_CODE_NOT_SUPPORTED_API 801: Unsupported API. OH_HUKS_ERR_CODE_MISSING_CRYPTO_ALG_ARGUMENT 12000002: Failed to obtain the provider parameters. OH_HUKS_ERR_CODE_COMMUNICATION_FAIL 12000005: IPC communication failed. OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY 12000014: Insufficient memory. OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT 12000018: Invalid providerName or paramSet. OH_HUKS_ERR_CODE_ITEM_NOT_EXIST 12000019: The provider has been registered. OH_HUKS_ERR_CODE_EXTERNAL_ERROR 12000020: An error occurs in the dependent module. OH_HUKS_ERR_CODE_EXCEED_LIMIT 12000025: The number of providers exceeds the upper limit.

Type

Description

struct OH_Huks_Result

Possible error codes (errorCode):
OH_HUKS_SUCCESS 0: Operation successful.
OH_HUKS_ERR_CODE_PERMISSION_FAIL 201: Permission verification fails. Apply for the required permission first.
OH_HUKS_ERR_CODE_NOT_SUPPORTED_API 801: Unsupported API.
OH_HUKS_ERR_CODE_MISSING_CRYPTO_ALG_ARGUMENT 12000002: Failed to obtain the provider parameters.
OH_HUKS_ERR_CODE_COMMUNICATION_FAIL 12000005: IPC communication failed.
OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY 12000014: Insufficient memory.
OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT 12000018: Invalid providerName or paramSet.
OH_HUKS_ERR_CODE_ITEM_NOT_EXIST 12000019: The provider has been registered.
OH_HUKS_ERR_CODE_EXTERNAL_ERROR 12000020: An error occurs in the dependent module.
OH_HUKS_ERR_CODE_EXCEED_LIMIT 12000025: The number of providers exceeds the upper limit.

OH_Huks_UnregisterProvider()

struct OH_Huks_Result OH_Huks_UnregisterProvider(const struct OH_Huks_Blob *providerName, const OH_Huks_ExternalCryptoParamSet *paramSet)

Description

Unregisters an external key management extension provider.

Required permissions: ohos.permission.CRYPTO_EXTENSION_REGISTER

Since: 22

Parameters

Name	Description
const struct OH_Huks_Blob *providerName	Name of the provider.
const OH_Huks_ExternalCryptoParamSet *paramSet	Pointer to the registration parameters.

Returns

Type	Description
struct OH_Huks_Result	Possible error codes (errorCode): OH_HUKS_SUCCESS 0: Operation successful. OH_HUKS_ERR_CODE_PERMISSION_FAIL 201: Permission verification fails. Apply for the required permission first. OH_HUKS_ERR_CODE_NOT_SUPPORTED_API 801: Unsupported API. OH_HUKS_ERR_CODE_COMMUNICATION_FAIL 12000005: IPC communication failed. OH_HUKS_ERR_CODE_ITEM_NOT_EXIST 12000011: The specified provider is not found. OH_HUKS_ERR_CODE_INTERNAL_ERROR = 12000012: An internal system error occurs. The key management extension module is not loaded. OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY 12000014: Insufficient memory. OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT 12000018: Invalid providerName.

Type

Description

struct OH_Huks_Result

Possible error codes (errorCode):
OH_HUKS_SUCCESS 0: Operation successful.
OH_HUKS_ERR_CODE_PERMISSION_FAIL 201: Permission verification fails. Apply for the required permission first.
OH_HUKS_ERR_CODE_NOT_SUPPORTED_API 801: Unsupported API.
OH_HUKS_ERR_CODE_COMMUNICATION_FAIL 12000005: IPC communication failed.
OH_HUKS_ERR_CODE_ITEM_NOT_EXIST 12000011: The specified provider is not found.
OH_HUKS_ERR_CODE_INTERNAL_ERROR = 12000012: An internal system error occurs. The key management extension module is not loaded.
OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY 12000014: Insufficient memory.
OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT 12000018: Invalid providerName.

OH_Huks_OpenResource()

struct OH_Huks_Result OH_Huks_OpenResource(const struct OH_Huks_Blob *resourceId, const OH_Huks_ExternalCryptoParamSet *paramSet)

Description

Opens a resource based on the specified resource ID.
Note: The opened resource must be closed using OH_Huks_CloseResource.

Since: 22

Parameters

Name	Description
const struct OH_Huks_Blob *resourceId	Resource ID of the specified provider.
const OH_Huks_ExternalCryptoParamSet *paramSet	Pointer to the handle operation parameters.

Returns

Type	Description
struct OH_Huks_Result	Possible error codes (errorCode): OH_HUKS_SUCCESS 0: Operation successful. OH_HUKS_ERR_CODE_NOT_SUPPORTED_API 801: Unsupported API. OH_HUKS_ERR_CODE_COMMUNICATION_FAIL 12000005: IPC communication failed. OH_HUKS_ERR_CODE_CRYPTO_FAIL 12000006: Ukey driver error. OH_HUKS_ERR_CODE_ITEM_NOT_EXIST 12000011: The cached resource handle is not found. Open the resource based on the resource ID first. OH_HUKS_ERR_CODE_INTERNAL_ERROR 12000012: An internal system error occurs. The processing function is not found. OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY 12000014: Insufficient memory. OH_HUKS_ERR_CODE_KEY_ALREADY_EXIST 12000017: The resource is already open. OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT 12000018: Invalid resourceId or paramSet. OH_HUKS_ERR_CODE_EXTERNAL_ERROR 12000020: Provider execution fails. OH_HUKS_ERR_CODE_BUSY 12000024: The provider or Ukey is busy. OH_HUKS_ERR_CODE_EXCEED_LIMIT 12000025: The number of opened resources exceeds the limit.

Type

Description

struct OH_Huks_Result

Possible error codes (errorCode):
OH_HUKS_SUCCESS 0: Operation successful.
OH_HUKS_ERR_CODE_NOT_SUPPORTED_API 801: Unsupported API.
OH_HUKS_ERR_CODE_COMMUNICATION_FAIL 12000005: IPC communication failed.
OH_HUKS_ERR_CODE_CRYPTO_FAIL 12000006: Ukey driver error.
OH_HUKS_ERR_CODE_ITEM_NOT_EXIST 12000011: The cached resource handle is not found. Open the resource based on the resource ID first.
OH_HUKS_ERR_CODE_INTERNAL_ERROR 12000012: An internal system error occurs. The processing function is not found.
OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY 12000014: Insufficient memory.
OH_HUKS_ERR_CODE_KEY_ALREADY_EXIST 12000017: The resource is already open.
OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT 12000018: Invalid resourceId or paramSet.
OH_HUKS_ERR_CODE_EXTERNAL_ERROR 12000020: Provider execution fails.
OH_HUKS_ERR_CODE_BUSY 12000024: The provider or Ukey is busy.
OH_HUKS_ERR_CODE_EXCEED_LIMIT 12000025: The number of opened resources exceeds the limit.

OH_Huks_CloseResource()

struct OH_Huks_Result OH_Huks_CloseResource(const struct OH_Huks_Blob *resourceId, const OH_Huks_ExternalCryptoParamSet *paramSet)

Description

Closes a resource based on the specified resource ID.

Since: 22

Parameters

Name	Description
const struct OH_Huks_Blob *resourceId	Resource ID of the specified provider.
const OH_Huks_ExternalCryptoParamSet *paramSet	Pointer to the handle operation parameters.

Returns

Type	Description
struct OH_Huks_Result	Possible error codes (errorCode): OH_HUKS_SUCCESS 0: Operation successful. OH_HUKS_ERR_CODE_NOT_SUPPORTED_API 801: Unsupported API. OH_HUKS_ERR_CODE_COMMUNICATION_FAIL 12000005: IPC communication failed. OH_HUKS_ERR_CODE_CRYPTO_FAIL 12000006: Ukey driver error. OH_HUKS_ERR_CODE_INTERNAL_ERROR 12000012: An internal system error occurs. The processing function is not found. OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY 12000014: Insufficient memory. OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT 12000018: Invalid resourceId or paramSet. OH_HUKS_ERR_CODE_EXTERNAL_ERROR 12000020: Provider execution fails. OH_HUKS_ERR_CODE_BUSY 12000024: The provider or Ukey is busy.

Type

Description

struct OH_Huks_Result

OH_Huks_GetUkeyPinAuthState()

struct OH_Huks_Result OH_Huks_GetUkeyPinAuthState(const struct OH_Huks_Blob *resourceId, const OH_Huks_ExternalCryptoParamSet *paramSet, OH_Huks_ExternalPinAuthState *authState)

Description

Obtains the PIN authorization state of the specified Ukey resource ID.

Since: 22

Parameters

Name	Description
const struct OH_Huks_Blob *resourceId	Resource ID of the specified provider.
const OH_Huks_ExternalCryptoParamSet *paramSet	Pointer to the PIN authorization parameters.
bool *authState	Whether a specified index is authorized.

Returns

Type	Description
struct OH_Huks_Result	Possible error codes (errorCode): OH_HUKS_SUCCESS 0: Operation successful. OH_HUKS_ERR_CODE_NOT_SUPPORTED_API 801: Unsupported API. OH_HUKS_ERR_CODE_COMMUNICATION_FAIL 12000005: IPC communication failed. OH_HUKS_ERR_CODE_CRYPTO_FAIL 12000006: Ukey driver error. OH_HUKS_ERR_CODE_ITEM_NOT_EXIST 12000011: The specified resource ID is invalid. OH_HUKS_ERR_CODE_INTERNAL_ERROR 12000012: An internal system error occurs. The processing function is not found. OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY 12000014: Insufficient memory. OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT 12000018: Invalid resourceId or paramSet. OH_HUKS_ERR_CODE_EXTERNAL_ERROR 12000020: Provider execution fails. OH_HUKS_ERR_CODE_BUSY 12000024: The provider or Ukey is busy.

Type

Description

struct OH_Huks_Result

Possible error codes (errorCode):
OH_HUKS_SUCCESS 0: Operation successful.
OH_HUKS_ERR_CODE_NOT_SUPPORTED_API 801: Unsupported API.
OH_HUKS_ERR_CODE_COMMUNICATION_FAIL 12000005: IPC communication failed.
OH_HUKS_ERR_CODE_CRYPTO_FAIL 12000006: Ukey driver error.
OH_HUKS_ERR_CODE_ITEM_NOT_EXIST 12000011: The specified resource ID is invalid.
OH_HUKS_ERR_CODE_INTERNAL_ERROR 12000012: An internal system error occurs. The processing function is not found.
OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY 12000014: Insufficient memory.
OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT 12000018: Invalid resourceId or paramSet.
OH_HUKS_ERR_CODE_EXTERNAL_ERROR 12000020: Provider execution fails.
OH_HUKS_ERR_CODE_BUSY 12000024: The provider or Ukey is busy.

OH_Huks_GetProperty()

struct OH_Huks_Result OH_Huks_GetProperty(const struct OH_Huks_Blob *resourceId, const struct OH_Huks_Blob *propertyId, const OH_Huks_ExternalCryptoParamSet *paramSetIn, OH_Huks_ExternalCryptoParamSet **paramSetOut)

Description

Obtains the property information of the external key management extension provider.

Since: 22

Parameters

Name	Description
const struct OH_Huks_Blob *resourceId	Resource ID of the specified provider.
const struct OH_Huks_Blob *propertyId	Name of the property function defined by GMT 0016-2023.
const OH_Huks_ExternalCryptoParamSet *paramSetIn	Pointer to the input operation parameters.
OH_Huks_ExternalCryptoParamSet **paramSetOut	Pointer to the output parameters, which must contain the OH_HUKS_EXT_CRYPTO_TAG_EXTRA_DATA parameter.

Returns

Type	Description
struct OH_Huks_Result	Possible error codes (errorCode): OH_HUKS_SUCCESS 0: Operation successful. OH_HUKS_ERR_CODE_NOT_SUPPORTED_API 801: Unsupported API. OH_HUKS_ERR_CODE_COMMUNICATION_FAIL 12000005: IPC communication failed. OH_HUKS_ERR_CODE_CRYPTO_FAIL 12000006: Driver error. OH_HUKS_ERR_CODE_ITEM_NOT_EXIST 12000011: The specified handle in the cache is not found. OH_HUKS_ERR_CODE_INTERNAL_ERROR 12000012: An internal system error occurs. The processing function is not found. OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY 12000014: Insufficient memory. OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT 12000018: Invalid resourceId, propertyId, paramSet, or callback. OH_HUKS_ERR_CODE_EXTERNAL_ERROR 12000020: The provider or Ukey internal execution fails. OH_HUKS_ERR_CODE_PIN_LOCKED 12000021: The PIN is locked. OH_HUKS_ERR_CODE_PIN_NO_AUTH 12000023: PIN authentication fails. OH_HUKS_ERR_CODE_BUSY 12000024: The resources in the provider or Ukey are being used.

Type

Description

struct OH_Huks_Result

Possible error codes (errorCode):
OH_HUKS_SUCCESS 0: Operation successful.
OH_HUKS_ERR_CODE_NOT_SUPPORTED_API 801: Unsupported API.
OH_HUKS_ERR_CODE_COMMUNICATION_FAIL 12000005: IPC communication failed.
OH_HUKS_ERR_CODE_CRYPTO_FAIL 12000006: Driver error.
OH_HUKS_ERR_CODE_ITEM_NOT_EXIST 12000011: The specified handle in the cache is not found.
OH_HUKS_ERR_CODE_INTERNAL_ERROR 12000012: An internal system error occurs. The processing function is not found.
OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY 12000014: Insufficient memory.
OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT 12000018: Invalid resourceId, propertyId, paramSet, or callback.
OH_HUKS_ERR_CODE_EXTERNAL_ERROR 12000020: The provider or Ukey internal execution fails.
OH_HUKS_ERR_CODE_PIN_LOCKED 12000021: The PIN is locked.
OH_HUKS_ERR_CODE_PIN_NO_AUTH 12000023: PIN authentication fails.
OH_HUKS_ERR_CODE_BUSY 12000024: The resources in the provider or Ukey are being used.

OH_Huks_InitExternalCryptoParamSet()

struct OH_Huks_Result OH_Huks_InitExternalCryptoParamSet(OH_Huks_ExternalCryptoParamSet **paramSet)

Description

Initializes a parameter set.

Since: 22

Parameters

Name	Description
OH_Huks_ExternalCryptoParamSet **paramSet	Level-2 pointer to the parameter set to initialize.

Returns

Type	Description
struct OH_Huks_Result	Possible error codes (errorCode): OH_HUKS_SUCCESS 0: Operation successful. OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY 12000014: Insufficient memory. OH_HUKS_ERR_CODE_INVALID_ARGUMENT 12000018: params is NULL or paramSet is invalid.

OH_Huks_AddExternalCryptoParams()

struct OH_Huks_Result OH_Huks_AddExternalCryptoParams(OH_Huks_ExternalCryptoParamSet *paramSet, const OH_Huks_ExternalCryptoParam *params, uint32_t paramCnt)

Description

Adds parameters to a parameter set.

Since: 22

Parameters

Name	Description
OH_Huks_ExternalCryptoParamSet *paramSet	Pointer to the parameter set to which parameters are to be added.
const OH_Huks_ExternalCryptoParam *params	Pointer to the parameter array to be added.
uint32_t paramCnt	Number of parameters to be added.

Returns

Type	Description
struct OH_Huks_Result	Possible error codes (errorCode): OH_HUKS_SUCCESS 0: Operation successful. OH_HUKS_ERR_CODE_INVALID_ARGUMENT 12000018: params is NULL or paramSet is invalid.

OH_Huks_BuildExternalCryptoParamSet()

struct OH_Huks_Result OH_Huks_BuildExternalCryptoParamSet(OH_Huks_ExternalCryptoParamSet **paramSet)

Description

Builds a parameter set.

Since: 22

Parameters

Name	Description
OH_Huks_ExternalCryptoParamSet **paramSet	Level-2 pointer to the parameter set to build.

Returns

Type	Description
struct OH_Huks_Result	Possible error codes (errorCode): OH_HUKS_SUCCESS 0: Operation successful. OH_HUKS_ERR_CODE_INVALID_ARGUMENT 12000018 - Invalid paramSet. OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY 12000014: Insufficient memory.

OH_Huks_FreeExternalCryptoParamSet()

void OH_Huks_FreeExternalCryptoParamSet(OH_Huks_ExternalCryptoParamSet **paramSet)

Description

Destroys a parameter set and releases related memory.

Since: 22

Parameters

Name	Description
OH_Huks_ExternalCryptoParamSet **paramSet	Level-2 pointer to the parameter set to destroy.

OH_Huks_GetExternalCryptoParam()

struct OH_Huks_Result OH_Huks_GetExternalCryptoParam(OH_Huks_ExternalCryptoParamSet *paramSet, const uint32_t tag, OH_Huks_ExternalCryptoParam **param)

Description

Obtains a specified parameter from a parameter set.

Since: 22

Parameters

Name	Description
OH_Huks_ExternalCryptoParamSet *paramSet	Pointer to the target parameter set.
const uint32_t tag	Tag value of the parameter to obtain.
OH_Huks_ExternalCryptoParam **param	Level-2 pointer used to return the obtained parameter.

Returns

Type	Description
struct OH_Huks_Result	Possible error codes (errorCode): OH_HUKS_SUCCESS 0: Operation successful. OH_HUKS_ERR_CODE_INVALID_ARGUMENT 12000018 - paramSet or param is invalid, or the parameter does not exist in the set.