
HarmonyOSAPI:@ohos.security.huks (通用密钥库系统)
版本:v3.1 Beta
@ohos.security.huks (通用密钥库系统)
更新时间: 2023-03-10 16:42
向应用提供密钥库能力,包括密钥管理及密钥的密码学操作等功能。
HUKS所管理的密钥可以由应用导入或者由应用调用HUKS接口生成。
说明
本模块首批接口从API version 8开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
导入模块
HuksParam
调用接口使用的options中的properties数组中的param。
系统能力:SystemCapability.Security.Huks
名称 | 类型 | 必填 | 说明 |
tag | 是 | 标签。 | |
value | boolean|number|bigint|Uint8Array | 是 | 标签对应值。 |
HuksOptions
调用接口使用的options。
系统能力:SystemCapability.Security.Huks
名称 | 类型 | 必填 | 说明 |
properties | Array<HuksParam> | 否 | 属性,用于存HuksParam的数组。 |
inData | Uint8Array | 否 | 输入数据。 |
HuksSessionHandle9+
huks Handle结构体。
系统能力:SystemCapability.Security.Huks
名称 | 类型 | 必填 | 说明 |
handle | number | 是 | 表示handle值。 |
challenge | Uint8Array | 否 | 表示init操作之后获取到的challenge信息。 |
HuksReturnResult9+
调用接口返回的result。
系统能力:SystemCapability.Security.Huks
名称 | 类型 | 必填 | 说明 |
outData | Uint8Array | 否 | 表示输出数据。 |
properties | Array<HuksParam> | 否 | 表示属性信息。 |
certChains | Array<string> | 否 | 表示证书链数据。 |
huks.generateKeyItem9+
generateKeyItem(keyAlias: string, options: HuksOptions, callback: AsyncCallback<void>) : void
生成密钥,使用Callback回调异步返回结果。
系统能力:SystemCapability.Security.Huks
参数:
参数名 | 类型 | 必填 | 说明 |
keyAlias | string | 是 | 别名。 |
options | 是 | 用于存放生成key所需TAG。其中密钥使用的算法、密钥用途、密钥长度为必选参数。 | |
callback | AsyncCallback<void> | 是 | 回调函数。不返回err值时表示接口使用成功,其他时为错误。 |
示例:
huks.generateKeyItem9+
generateKeyItem(keyAlias: string, options: HuksOptions) : Promise<void>
生成密钥,使用Promise方式异步返回结果。
系统能力:SystemCapability.Security.Huks
参数:
参数名 | 类型 | 必填 | 说明 |
keyAlias | string | 是 | 密钥别名。 |
options | 是 | 用于存放生成key所需TAG。其中密钥使用的算法、密钥用途、密钥长度为必选参数。 |
示例:
huks.deleteKeyItem9+
deleteKeyItem(keyAlias: string, options: HuksOptions, callback: AsyncCallback<void>) : void
删除密钥,使用Callback回调异步返回结果。
系统能力:SystemCapability.Security.Huks
参数:
参数名 | 类型 | 必填 | 说明 |
keyAlias | string | 是 | 密钥别名,应为生成key时传入的别名。 |
options | 是 | 空对象(此处传空即可)。 | |
callback | AsyncCallback<void> | 是 | 回调函数。不返回err值时表示接口使用成功,其他时为错误。 |
示例:
huks.deleteKeyItem9+
deleteKeyItem(keyAlias: string, options: HuksOptions) : Promise<void>
删除密钥,使用Promise方式异步返回结果。
系统能力:SystemCapability.Security.Huks
参数:
参数名 | 类型 | 必填 | 说明 |
keyAlias | string | 是 | 密钥别名,应为生成key时传入的别名。 |
options | 是 | 空对象(此处传空即可)。 |
示例:
huks.getSdkVersion
getSdkVersion(options: HuksOptions) : string
获取当前系统sdk版本。
系统能力:SystemCapability.Security.Huks
参数:
参数名 | 类型 | 必填 | 说明 |
options | 是 | 空对象,用于存放sdk版本。 |
返回值:
类型 | 说明 |
string | 返回sdk版本。 |
示例:
huks.importKeyItem9+
importKeyItem(keyAlias: string, options: HuksOptions, callback: AsyncCallback<void>) : void
导入明文密钥,使用Callback方式回调异步返回结果 。
系统能力:SystemCapability.Security.Huks
参数:
参数名 | 类型 | 必填 | 说明 |
keyAlias | string | 是 | 密钥别名。 |
options | 是 | 用于导入时所需TAG和需要导入的密钥。其中密钥使用的算法、密钥用途、密钥长度为必选参数。 | |
callback | AsyncCallback<void> | 是 | 回调函数。不返回err值时表示接口使用成功,其他时为错误。 |
示例:
huks.importKeyItem9+
importKeyItem(keyAlias: string, options: HuksOptions) : Promise<void>
导入明文密钥,使用Promise方式异步返回结果。
系统能力:SystemCapability.Security.Huks
参数:
参数名 | 类型 | 必填 | 说明 |
keyAlias | string | 是 | 密钥别名。 |
options | 是 | 用于导入时所需TAG和需要导入的密钥。其中密钥使用的算法、密钥用途、密钥长度为必选参数。 |
示例:
huks.importWrappedKeyItem9+
importWrappedKeyItem(keyAlias: string, wrappingKeyAlias: string, options: HuksOptions, callback: AsyncCallback<void>) : void
导入加密密钥,使用Callback方式回调异步返回结果 。
系统能力:SystemCapability.Security.Huks
参数:
参数名 | 类型 | 必填 | 说明 |
keyAlias | string | 是 | 密钥别名,存放待导入密钥的别名。 |
wrappingKeyAlias | string | 是 | 密钥别名,对应密钥用于解密加密的密钥数据。 |
options | 是 | 用于导入时所需TAG和需要导入的加密的密钥数据。其中密钥使用的算法、密钥用途、密钥长度为必选参数。 | |
callback | AsyncCallback<void> | 是 | 回调函数。不返回err值时表示接口使用成功,其他时为错误。 |
示例:
huks.importWrappedKeyItem9+
importWrappedKeyItem(keyAlias: string, wrappingKeyAlias: string, options: HuksOptions) : Promise<void>
导入加密密钥,使用Promise方式异步返回结果。
系统能力:SystemCapability.Security.Huks
参数:
参数名 | 类型 | 必填 | 说明 |
keyAlias | string | 是 | 密钥别名,存放待导入密钥的别名。 |
wrappingKeyAlias | string | 是 | 密钥别名,对应密钥用于解密加密的密钥数据。 |
options | 是 | 用于导入时所需TAG和需要导入的加密的密钥数据。其中密钥使用的算法、密钥用途、密钥长度为必选参数。 |
示例:
huks.exportKeyItem9+
exportKeyItem(keyAlias: string, options: HuksOptions, callback: AsyncCallback<HuksReturnResult>) : void
导出密钥,使用Callback方式回调异步返回的结果。
系统能力:SystemCapability.Security.Huks
参数:
参数名 | 类型 | 必填 | 说明 |
keyAlias | string | 是 | 密钥别名,应与所用密钥生成时使用的别名相同。 |
options | 是 | 空对象(此处传空即可)。 | |
callback | AsyncCallback<HuksReturnResult> | 是 | 回调函数。返回HUKS_SUCCESS时表示接口使用成功,其他时为错误。outData:返回从密钥中导出的公钥。 |
示例:
huks.exportKeyItem9+
exportKeyItem(keyAlias: string, options: HuksOptions) : Promise<HuksReturnResult>
导出密钥,使用Promise方式回调异步返回的结果。
系统能力:SystemCapability.Security.Huks
参数:
参数名 | 类型 | 必填 | 说明 |
keyAlias | string | 是 | 密钥别名,应与所用密钥生成时使用的别名相同。 |
options | 是 | 空对象(此处传空即可)。 |
返回值:
类型 | 说明 |
Promise<HuksReturnResult> | Promise对象。不返回err值时表示接口使用成功,其他时为错误。outData:返回从密钥中导出的公钥。 |
示例:
huks.getKeyItemProperties9+
getKeyItemProperties(keyAlias: string, options: HuksOptions, callback: AsyncCallback<HuksReturnResult>) : void
获取密钥属性,使用Callback回调异步返回结果。
系统能力:SystemCapability.Security.Huks
参数:
参数名 | 类型 | 必填 | 说明 |
keyAlias | string | 是 | 密钥别名,应与所用密钥生成时使用的别名相同。 |
options | 是 | 空对象(此处传空即可)。 | |
callback | AsyncCallback<HuksReturnResult> | 是 | 回调函数。errorCode:返回HUKS_SUCCESS时表示接口使用成功,其他时为错误。 |
示例:
huks.getKeyItemProperties9+
getKeyItemProperties(keyAlias: string, options: HuksOptions) : Promise<HuksReturnResult>
获取密钥属性,使用Promise回调异步返回结果。
系统能力:SystemCapability.Security.Huks
参数:
参数名 | 类型 | 必填 | 说明 |
keyAlias | string | 是 | 密钥别名,应与所用密钥生成时使用的别名相同。 |
options | 是 | 空对象(此处传空即可)。 |
返回值:
类型 | 说明 |
Promise<HuksReturnResult> | Promise对象。不返回err值时表示接口使用成功,其他时为错误。properties:返回值为生成密钥时所需参数。 |
示例:
huks.isKeyItemExist9+
isKeyItemExist(keyAlias: string, options: HuksOptions, callback: AsyncCallback<boolean>) : void
判断密钥是否存在,使用Callback回调异步返回结果 。
系统能力:SystemCapability.Security.Huks
参数:
参数名 | 类型 | 必填 | 说明 |
keyAlias | string | 是 | 所需查找的密钥的别名。 |
options | 是 | 空对象(此处传空即可)。 | |
callback | AsyncCallback<boolean> | 是 | 回调函数。FALSE代表密钥不存在,TRUE代表密钥存在。 |
示例:
huks.isKeyItemExist9+
isKeyItemExist(keyAlias: string, options: HuksOptions) : Promise<boolean>
判断密钥是否存在,使用Promise回调异步返回结果 。
系统能力:SystemCapability.Security.Huks
参数:
参数名 | 类型 | 必填 | 说明 |
keyAlias | string | 是 | 所需查找的密钥的别名。 |
options | 是 | 空对象(此处传空即可)。 |
返回值:
类型 | 说明 |
Promise<boolean> | Promise对象。FALSE代表密钥不存在,TRUE代表密钥存在。 |
示例:
huks.initSession9+
initSession(keyAlias: string, options: HuksOptions, callback: AsyncCallback<HuksSessionHandle>) : void
initSession操作密钥接口,使用Callback回调异步返回结果。huks.initSession, huks.updateSession, huks.finishSession为三段式接口,需要一起使用。
系统能力:SystemCapability.Security.Huks
参数:
参数名 | 类型 | 必填 | 说明 |
keyAlias | string | 是 | Init操作密钥的别名。 |
options | 是 | Init操作的参数集合。 | |
callback | AsyncCallback<HuksSessionHandle> | 是 | 回调函数。将Init操作操作返回的handle添加到密钥管理系统的回调。 |
huks.initSession9+
initSession(keyAlias: string, options: HuksOptions) : Promise<HuksSessionHandle>
initSession操作密钥接口,使用Promise方式异步返回结果。huks.initSession, huks.updateSession, huks.finishSession为三段式接口,需要一起使用。
系统能力:SystemCapability.Security.Huks
参数:
参数名 | 类型 | 必填 | 说明 |
keyAlias | string | 是 | Init操作密钥的别名。 |
options | 是 | Init参数集合。 |
返回值:
类型 | 说明 |
Promise<HuksSessionHandle> | Promise对象。将Init操作返回的handle添加到密钥管理系统的回调。 |
huks.updateSession9+
updateSession(handle: number, options: HuksOptions, callback: AsyncCallback<HuksReturnResult>) : void
updateSession操作密钥接口,使用Callback回调异步返回结果。huks.initSession, huks.updateSession, huks.finishSession为三段式接口,需要一起使用。
系统能力:SystemCapability.Security.Huks
参数:
参数名 | 类型 | 必填 | 说明 |
handle | number | 是 | Update操作的handle。 |
options | 是 | Update的参数集合。 | |
callback | AsyncCallback<HuksReturnResult> | 是 | 回调函数。将Update操作的结果添加到密钥管理系统的回调。 |
huks.updateSession9+
updateSession(handle: number, options: HuksOptions, token: Uint8Array, callback: AsyncCallback<HuksReturnResult>) : void
updateSession操作密钥接口,使用Callback回调异步返回结果。huks.initSession, huks.updateSession, huks.finishSession为三段式接口,需要一起使用。
系统能力:SystemCapability.Security.Huks
参数:
参数名 | 类型 | 必填 | 说明 |
handle | number | 是 | Update操作的handle。 |
options | 是 | Update操作的参数集合。 | |
token | Uint8Array | 是 | Update操作的token。 |
callback | AsyncCallback<HuksReturnResult> | 是 | 回调函数。将Update操作的结果添加到密钥管理系统的回调。 |
huks.updateSession9+
updateSession(handle: number, options: HuksOptions, token?: Uint8Array) : Promise<HuksReturnResult>
uupdateSession操作密钥接口,使用Promise方式异步返回结果。huks.initSession, huks.updateSession, huks.finishSession为三段式接口,需要一起使用。
系统能力:SystemCapability.Security.Huks
参数:
参数名 | 类型 | 必填 | 说明 |
handle | number | 是 | Update操作的handle。 |
options | 是 | Update操作的参数集合。 | |
token | Uint8Array | 否 | Update操作的token。 |
返回值:
类型 | 说明 |
Promise<HuksReturnResult> | Promise对象。将Update操作的结果添加到密钥管理系统的回调。 |
huks.finishSession9+
finishSession(handle: number, options: HuksOptions, callback: AsyncCallback<HuksReturnResult>) : void
finishSession操作密钥接口,使用Callback回调异步返回结果。huks.initSession, huks.updateSession, huks.finishSession为三段式接口,需要一起使用。
系统能力:SystemCapability.Security.Huks
参数:
参数名 | 类型 | 必填 | 说明 |
handle | number | 是 | Finish操作的handle。 |
options | 是 | Finish的参数集合。 | |
token | Uint8Array | 是 | Finish操作的token。 |
callback | AsyncCallback<HuksReturnResult> | 是 | 回调函数。将Finish操作的结果添加到密钥管理系统的回调。 |
huks.finishSession9+
finishSession(handle: number, options: HuksOptions, token: Uint8Array, callback: AsyncCallback<HuksReturnResult>) : void
finishSession操作密钥接口,使用Callback回调异步返回结果。huks.initSession, huks.updateSession, huks.finishSession为三段式接口,需要一起使用。
系统能力:SystemCapability.Security.Huks
参数:
参数名 | 类型 | 必填 | 说明 |
handle | number | 是 | Finish操作的handle。 |
options | 是 | Finish的参数集合。 | |
token | Uint8Array | 是 | Finish操作的token。 |
callback | AsyncCallback<HuksReturnResult> | 是 | 回调函数。将Finish操作的结果添加到密钥管理系统的回调。 |
huks.finishSession9+
finishSession(handle: number, options: HuksOptions, token?: Uint8Array) : Promise<HuksReturnResult>
finishSession操作密钥接口,使用Promise方式异步返回结果。huks.initSession, huks.updateSession, huks.finishSession为三段式接口,需要一起使用。
系统能力:SystemCapability.Security.Huks
参数:
参数名 | 类型 | 必填 | 说明 |
handle | number | 是 | Finish操作的handle。 |
options | 是 | Finish操作的参数集合。 | |
token | Uint8Array | 否 | Finish操作的token。 |
返回值:
类型 | 说明 |
Promise<HuksReturnResult> | Promise对象,用于获取异步返回结果。 |
huks.abortSession9+
abortSession(handle: number, options: HuksOptions, callback: AsyncCallback<void>) : void
abort操作密钥接口,使用Callback回调异步返回结果 。
系统能力:SystemCapability.Security.Huks
参数:
参数名 | 类型 | 必填 | 说明 |
handle | number | 是 | Abort操作的handle。 |
options | 是 | Abort操作的参数集合。 | |
callback | AsyncCallback<void> | 是 | 回调函数。将Abort操作的结果添加到密钥管理系统的回调。 |
示例:
huks.abortSession9+
abortSession(handle: number, options: HuksOptions) : Promise<void>;
abort操作密钥接口,使用Promise方式异步返回结果。
系统能力:SystemCapability.Security.Huks
参数:
参数名 | 类型 | 必填 | 说明 |
handle | number | 是 | Abort操作的handle。 |
options | 是 | Abort操作的参数集合。 |
返回值:
类型 | 说明 |
Promise<void> | Promise对象。将Abort操作的结果添加到密钥管理系统的回调。 |
示例:
HuksExceptionErrCode9+
表示错误码的枚举以及对应的错误信息, 错误码表示错误类型,错误信息展示错误详情。
关于错误码的具体信息,可在错误码参考文档中查看。
系统能力:SystemCapability.Security.Huks
名称 | 值 | 说明 |
HUKS_ERR_CODE_PERMISSION_FAIL | 201 | 权限错误导致失败。 |
HUKS_ERR_CODE_ILLEGAL_ARGUMENT | 401 | 参数错误导致失败。 |
HUKS_ERR_CODE_NOT_SUPPORTED_API | 801 | 不支持的API。 |
HUKS_ERR_CODE_FEATURE_NOT_SUPPORTED | 12000001 | 不支持的功能/特性。 |
HUKS_ERR_CODE_MISSING_CRYPTO_ALG_ARGUMENT | 12000002 | 缺少密钥算法参数。 |
HUKS_ERR_CODE_INVALID_CRYPTO_ALG_ARGUMENT | 12000003 | 无效密钥算法参数。 |
HUKS_ERR_CODE_FILE_OPERATION_FAIL | 12000004 | 文件操作失败。 |
HUKS_ERR_CODE_COMMUNICATION_FAIL | 12000005 | 通信失败。 |
HUKS_ERR_CODE_CRYPTO_FAIL | 12000006 | 算法库操作失败。 |
HUKS_ERR_CODE_KEY_AUTH_PERMANENTLY_INVALIDATED | 12000007 | 密钥访问失败-密钥访问失效。 |
HUKS_ERR_CODE_KEY_AUTH_VERIFY_FAILED | 12000008 | 密钥访问失败-密钥认证失败。 |
HUKS_ERR_CODE_KEY_AUTH_TIME_OUT | 12000009 | 密钥访问失败-密钥访问超时。 |
HUKS_ERR_CODE_SESSION_LIMIT | 12000010 | 密钥操作会话数已达上限。 |
HUKS_ERR_CODE_ITEM_NOT_EXIST | 12000011 | 目标对象不存在。 |
HUKS_ERR_CODE_EXTERNAL_ERROR | 12000012 | 外部错误。 |
HUKS_ERR_CODE_CREDENTIAL_NOT_EXIST | 12000013 | 缺失所需凭据。 |
HUKS_ERR_CODE_INSUFFICIENT_MEMORY | 12000014 | 内存不足。 |
HUKS_ERR_CODE_CALL_SERVICE_FAILED | 12000015 | 调用其他系统服务失败。 |
HuksKeyPurpose
表示密钥用途。
系统能力:SystemCapability.Security.Huks
名称 | 值 | 说明 |
HUKS_KEY_PURPOSE_ENCRYPT | 1 | 表示密钥用于对明文进行加密操作。 |
HUKS_KEY_PURPOSE_DECRYPT | 2 | 表示密钥用于对密文进行解密操作。 |
HUKS_KEY_PURPOSE_SIGN | 4 | 表示密钥用于对数据进行签名。 |
HUKS_KEY_PURPOSE_VERIFY | 8 | 表示密钥用于验证签名后的数据。 |
HUKS_KEY_PURPOSE_DERIVE | 16 | 表示密钥用于派生密钥。 |
HUKS_KEY_PURPOSE_WRAP | 32 | 表示密钥用于加密导出。 |
HUKS_KEY_PURPOSE_UNWRAP | 64 | 表示密钥加密导入。 |
HUKS_KEY_PURPOSE_MAC | 128 | 表示密钥用于生成mac消息验证码。 |
HUKS_KEY_PURPOSE_AGREE | 256 | 表示密钥用于进行密钥协商。 |
HuksKeyDigest
表示摘要算法。
系统能力:SystemCapability.Security.Huks
名称 | 值 | 说明 |
HUKS_DIGEST_NONE | 0 | 表示无摘要算法。 |
HUKS_DIGEST_SM39+ | 2 | 表示SM3摘要算法。 |
HUKS_DIGEST_SHA256 | 12 | 表示SHA256摘要算法。 |
HUKS_DIGEST_SHA384 | 13 | 表示SHA384摘要算法。 |
HUKS_DIGEST_SHA512 | 14 | 表示SHA512摘要算法。 |
