# native_huks_external_crypto_api.h

#### 概述

定义面向外部密钥管理扩展的通用密钥库（HUKS）API。

**引用文件：** <huks/native\_huks\_external\_crypto\_api.h>

**库：** libhuks\_external\_crypto.z.so

**系统能力：** SystemCapability.Security.Huks.CryptoExtension

**起始版本：** 22

**相关模块：** HuksExternalCryptoApi

#### 汇总

#### 函数

| 名称 | 描述 |
| --- | --- |
| struct OH_Huks_Result OH_Huks_RegisterProvider(const struct OH_Huks_Blob *providerName, const OH_Huks_ExternalCryptoParamSet *paramSet) | 注册外部密钥管理能力扩展提供者。 |
| struct OH_Huks_Result OH_Huks_UnregisterProvider(const struct OH_Huks_Blob *providerName, const OH_Huks_ExternalCryptoParamSet *paramSet) | 注销外部密钥管理能力扩展提供者。 |
| struct OH_Huks_Result OH_Huks_OpenResource(const struct OH_Huks_Blob *resourceId, const OH_Huks_ExternalCryptoParamSet *paramSet) | 根据指定的资源ID打开资源。 注意：打开的资源必须通过OH_Huks_CloseResource关闭。 |
| struct OH_Huks_Result OH_Huks_CloseResource(const struct OH_Huks_Blob *resourceId, const OH_Huks_ExternalCryptoParamSet *paramSet) | 根据指定的资源ID关闭资源。 |
| struct OH_Huks_Result OH_Huks_GetUkeyPinAuthState(const struct OH_Huks_Blob *resourceId, const OH_Huks_ExternalCryptoParamSet *paramSet, OH_Huks_ExternalPinAuthState *authState) | 获取指定Ukey资源ID的PIN授权状态。 |
| 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) | 外部密钥管理能力扩展提供者获取属性信息。 |
| struct OH_Huks_Result OH_Huks_InitExternalCryptoParamSet(OH_Huks_ExternalCryptoParamSet **paramSet) | 初始化一个参数集合。 |
| struct OH_Huks_Result OH_Huks_AddExternalCryptoParams(OH_Huks_ExternalCryptoParamSet *paramSet, const OH_Huks_ExternalCryptoParam *params, uint32_t paramCnt) | 向参数集合中添加参数。 |
| struct OH_Huks_Result OH_Huks_BuildExternalCryptoParamSet(OH_Huks_ExternalCryptoParamSet **paramSet) | 构建一个参数集合。 |
| void OH_Huks_FreeExternalCryptoParamSet(OH_Huks_ExternalCryptoParamSet **paramSet) | 销毁一个参数集合并释放相关内存。 |
| struct OH_Huks_Result OH_Huks_GetExternalCryptoParam(OH_Huks_ExternalCryptoParamSet *paramSet, const uint32_t tag, OH_Huks_ExternalCryptoParam **param) | 从参数集合中获取指定参数。 |

#### 函数说明

#### OH\_Huks\_RegisterProvider()

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

**描述**

注册外部密钥管理能力扩展提供者。

**需要权限：** ohos.permission.CRYPTO\_EXTENSION\_REGISTER

**起始版本：** 22

**参数：**

| 参数项 | 描述 |
| --- | --- |
| const struct OH_Huks_Blob *providerName | 指定提供者名称。 |
| const OH_Huks_ExternalCryptoParamSet *paramSet | 指向注册参数的指针。 |

**返回：**

| 类型 | 说明 |
| --- | --- |
| struct OH_Huks_Result | 可能的返回码（errorCode）： OH_HUKS_SUCCESS 0 - 操作成功。 OH_HUKS_ERR_CODE_PERMISSION_FAIL 201 - 权限校验失败，请先申请所需权限。 OH_HUKS_ERR_CODE_NOT_SUPPORTED_API 801 - 不支持的API。 OH_HUKS_ERR_CODE_MISSING_CRYPTO_ALG_ARGUMENT 12000002 - 未能获取提供者参数。 OH_HUKS_ERR_CODE_COMMUNICATION_FAIL 12000005 - IPC通信失败。 OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY 12000014 - 内存不足。 OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT 12000018 - providerName或paramSet无效。 OH_HUKS_ERR_CODE_ITEM_NOT_EXIST 12000019 - 提供者已被注册。 OH_HUKS_ERR_CODE_EXTERNAL_ERROR 12000020 - 依赖模块发生错误。 OH_HUKS_ERR_CODE_EXCEED_LIMIT 12000025 - 提供者数量超过限制。 |

#### OH\_Huks\_UnregisterProvider()

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

**描述**

注销外部密钥管理能力扩展提供者。

**需要权限：** ohos.permission.CRYPTO\_EXTENSION\_REGISTER

**起始版本：** 22

**参数：**

| 参数项 | 描述 |
| --- | --- |
| const struct OH_Huks_Blob *providerName | 指定提供者名称。 |
| const OH_Huks_ExternalCryptoParamSet *paramSet | 指向注册参数的指针。 |

**返回：**

| 类型 | 说明 |
| --- | --- |
| struct OH_Huks_Result | 可能的返回码（errorCode）： OH_HUKS_SUCCESS 0 - 操作成功。 OH_HUKS_ERR_CODE_PERMISSION_FAIL 201 - 权限校验失败，请先申请所需权限。 OH_HUKS_ERR_CODE_NOT_SUPPORTED_API 801 - 不支持的API。 OH_HUKS_ERR_CODE_COMMUNICATION_FAIL 12000005 - IPC通信失败。 OH_HUKS_ERR_CODE_ITEM_NOT_EXIST 12000011 - 未找到指定的提供者。 OH_HUKS_ERR_CODE_INTERNAL_ERROR = 12000012 - 发生系统内部错误，密钥管理扩展模块没有加载。 OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY 12000014 - 内存不足。 OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT 12000018 - providerName无效。 |

#### OH\_Huks\_OpenResource()

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

**描述**

根据指定的资源ID打开资源。

注意：打开的资源必须通过OH\_Huks\_CloseResource关闭。

**起始版本：** 22

**参数：**

| 参数项 | 描述 |
| --- | --- |
| const struct OH_Huks_Blob *resourceId | 指定提供者的资源ID。 |
| const OH_Huks_ExternalCryptoParamSet *paramSet | 指向句柄操作参数的指针。 |

**返回：**

| 类型 | 说明 |
| --- | --- |
| struct OH_Huks_Result | 可能的返回码（errorCode）： OH_HUKS_SUCCESS 0 - 操作成功。 OH_HUKS_ERR_CODE_NOT_SUPPORTED_API 801 - 不支持的API。 OH_HUKS_ERR_CODE_COMMUNICATION_FAIL 12000005 - IPC通信失败。 OH_HUKS_ERR_CODE_CRYPTO_FAIL 12000006 - Ukey驱动报错。 OH_HUKS_ERR_CODE_ITEM_NOT_EXIST 12000011 - 未找到缓存的资源句柄，需要先根据资源ID打开资源。 OH_HUKS_ERR_CODE_INTERNAL_ERROR 12000012 - 发生系统内部错误，处理函数未找到。 OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY 12000014 - 内存不足。 OH_HUKS_ERR_CODE_KEY_ALREADY_EXIST 12000017 - 资源已打开。 OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT 12000018 - resourceId或paramSet无效。 OH_HUKS_ERR_CODE_EXTERNAL_ERROR 12000020 - 提供者执行失败。 OH_HUKS_ERR_CODE_BUSY 12000024 - 提供者或Ukey忙。 OH_HUKS_ERR_CODE_EXCEED_LIMIT 12000025 - 打开资源的数量超过限制。 |

#### OH\_Huks\_CloseResource()

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

**描述**

根据指定的资源ID关闭资源。

**起始版本：** 22

**参数：**

| 参数项 | 描述 |
| --- | --- |
| const struct OH_Huks_Blob *resourceId | 指定提供者的资源ID。 |
| const OH_Huks_ExternalCryptoParamSet *paramSet | 指向句柄操作参数的指针。 |

**返回：**

| 类型 | 说明 |
| --- | --- |
| struct OH_Huks_Result | 可能的返回码（errorCode）： OH_HUKS_SUCCESS 0 - 操作成功。 OH_HUKS_ERR_CODE_NOT_SUPPORTED_API 801 - 不支持的 API。 OH_HUKS_ERR_CODE_COMMUNICATION_FAIL 12000005 - IPC通信失败。 OH_HUKS_ERR_CODE_CRYPTO_FAIL 12000006 - Ukey驱动报错。 OH_HUKS_ERR_CODE_INTERNAL_ERROR 12000012 - 发生系统内部错误，处理函数未找到。 OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY 12000014 - 内存不足。 OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT 12000018 - resourceId或paramSet无效。 OH_HUKS_ERR_CODE_EXTERNAL_ERROR 12000020 - 提供者执行失败。 OH_HUKS_ERR_CODE_BUSY 12000024 - 提供者或Ukey忙。 |

#### 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)
```

**描述**

获取指定Ukey资源ID的PIN授权状态。

**起始版本：** 22

**参数：**

| 参数项 | 描述 |
| --- | --- |
| const struct OH_Huks_Blob *resourceId | 指定提供者的资源ID。 |
| const OH_Huks_ExternalCryptoParamSet *paramSet | 指向PIN授权参数的指针。 |
| bool *authState | 用于返回指定索引的授权状态。 |

**返回：**

| 类型 | 说明 |
| --- | --- |
| struct OH_Huks_Result | 可能的返回码（errorCode）： OH_HUKS_SUCCESS 0 - 操作成功。 OH_HUKS_ERR_CODE_NOT_SUPPORTED_API 801 - 不支持的API。 OH_HUKS_ERR_CODE_COMMUNICATION_FAIL 12000005 - IPC通信失败。 OH_HUKS_ERR_CODE_CRYPTO_FAIL 12000006 - Ukey驱动报错。 OH_HUKS_ERR_CODE_ITEM_NOT_EXIST 12000011 - 指定的资源ID无效。 OH_HUKS_ERR_CODE_INTERNAL_ERROR 12000012 - 发生系统内部错误，处理函数未找到。 OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY 12000014 - 内存不足。 OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT 12000018 - resourceId或paramSet无效。 OH_HUKS_ERR_CODE_EXTERNAL_ERROR 12000020 - 提供者执行失败。 OH_HUKS_ERR_CODE_BUSY 12000024 - 提供者或Ukey忙。 |

#### 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)
```

**描述**

外部密钥管理能力扩展提供者获取属性信息。

**起始版本：** 22

**参数：**

| 参数项 | 描述 |
| --- | --- |
| const struct OH_Huks_Blob *resourceId | 指定提供者的资源ID。 |
| const struct OH_Huks_Blob *propertyId | 指定按GMT 0016-2023定义的属性函数名称。 |
| const OH_Huks_ExternalCryptoParamSet *paramSetIn | 指向输入操作参数的指针。 |
| OH_Huks_ExternalCryptoParamSet **paramSetOut | 指向输出参数的指针，且必须包含参数OH_HUKS_EXT_CRYPTO_TAG_EXTRA_DATA。 |

**返回：**

| 类型 | 说明 |
| --- | --- |
| struct OH_Huks_Result | 可能的返回码（errorCode）： OH_HUKS_SUCCESS 0 - 操作成功。 OH_HUKS_ERR_CODE_NOT_SUPPORTED_API 801 - 不支持的API。 OH_HUKS_ERR_CODE_COMMUNICATION_FAIL 12000005 - IPC通信失败。 OH_HUKS_ERR_CODE_CRYPTO_FAIL 12000006 - 驱动错误。 OH_HUKS_ERR_CODE_ITEM_NOT_EXIST 12000011 - 未找到缓存的指定句柄。 OH_HUKS_ERR_CODE_INTERNAL_ERROR 12000012 - 发生系统内部错误，处理函数未找到。 OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY 12000014 - 内存不足。 OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT 12000018 - resourceId、propertyId、paramSet或回调无效。 OH_HUKS_ERR_CODE_EXTERNAL_ERROR 12000020 - 提供者或Ukey内部执行失败。 OH_HUKS_ERR_CODE_PIN_LOCKED 12000021 - PIN码被锁定。 OH_HUKS_ERR_CODE_PIN_NO_AUTH 12000023 - PIN码未通过认证。 OH_HUKS_ERR_CODE_BUSY 12000024 - 提供者或Ukey中的资源正在被使用。 |

#### OH\_Huks\_InitExternalCryptoParamSet()

```
struct OH_Huks_Result OH_Huks_InitExternalCryptoParamSet(OH_Huks_ExternalCryptoParamSet **paramSet)
```

**描述**

初始化一个参数集合。

**起始版本：** 22

**参数：**

| 参数项 | 描述 |
| --- | --- |
| OH_Huks_ExternalCryptoParamSet **paramSet | 指向要初始化的参数集合的二级指针。 |

**返回：**

| 类型 | 说明 |
| --- | --- |
| struct OH_Huks_Result | 可能的返回码（errorCode）： OH_HUKS_SUCCESS 0 - 操作成功。 OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY 12000014 - 内存不足。 OH_HUKS_ERR_CODE_INVALID_ARGUMENT 12000018 - params为NULL或paramSet无效。 |

#### OH\_Huks\_AddExternalCryptoParams()

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

**描述**

向参数集合中添加参数。

**起始版本：** 22

**参数：**

| 参数项 | 描述 |
| --- | --- |
| OH_Huks_ExternalCryptoParamSet *paramSet | 指向将要添加参数的参数集合。 |
| const OH_Huks_ExternalCryptoParam *params | 指向要添加的参数数组。 |
| uint32_t paramCnt | 要添加的参数数量。 |

**返回：**

| 类型 | 说明 |
| --- | --- |
| struct OH_Huks_Result | 可能的返回码（errorCode）： OH_HUKS_SUCCESS 0 - 操作成功。 OH_HUKS_ERR_CODE_INVALID_ARGUMENT 12000018 - params为NULL或paramSet无效。 |

#### OH\_Huks\_BuildExternalCryptoParamSet()

```
struct OH_Huks_Result OH_Huks_BuildExternalCryptoParamSet(OH_Huks_ExternalCryptoParamSet **paramSet)
```

**描述**

构建一个参数集合。

**起始版本：** 22

**参数：**

| 参数项 | 描述 |
| --- | --- |
| OH_Huks_ExternalCryptoParamSet **paramSet | 指向要构建的参数集合的二级指针。 |

**返回：**

| 类型 | 说明 |
| --- | --- |
| struct OH_Huks_Result | 可能的返回码（errorCode）： OH_HUKS_SUCCESS 0 - 操作成功。 OH_HUKS_ERR_CODE_INVALID_ARGUMENT 12000018 - paramSet无效。 OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY 12000014 - 内存不足。 |

#### OH\_Huks\_FreeExternalCryptoParamSet()

```
void OH_Huks_FreeExternalCryptoParamSet(OH_Huks_ExternalCryptoParamSet **paramSet)
```

**描述**

销毁一个参数集合并释放相关内存。

**起始版本：** 22

**参数：**

| 参数项 | 描述 |
| --- | --- |
| OH_Huks_ExternalCryptoParamSet **paramSet | 指向要销毁的参数集合的二级指针。 |

#### OH\_Huks\_GetExternalCryptoParam()

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

**描述**

从参数集合中获取指定参数。

**起始版本：** 22

**参数：**

| 参数项 | 描述 |
| --- | --- |
| OH_Huks_ExternalCryptoParamSet *paramSet | 指向目标参数集合的指针。 |
| const uint32_t tag | 指定要获取的参数标签值。 |
| OH_Huks_ExternalCryptoParam **param | 用于返回获取到的参数的二级指针。 |

**返回：**

| 类型 | 说明 |
| --- | --- |
| struct OH_Huks_Result | 可能的返回码（errorCode）： OH_HUKS_SUCCESS 0 - 操作成功。 OH_HUKS_ERR_CODE_INVALID_ARGUMENT 12000018 - paramSet或param无效，或参数在集合中不存在。 |