diff --git a/zh-cn/application-dev/reference/apis/js-apis-huks.md b/zh-cn/application-dev/reference/apis/js-apis-huks.md index 54640c9c8cab3189443c711107f90a5399aee282..5d48f88aa630de23060c93f215aa63c4a45e7ac0 100755 --- a/zh-cn/application-dev/reference/apis/js-apis-huks.md +++ b/zh-cn/application-dev/reference/apis/js-apis-huks.md @@ -35,18 +35,6 @@ import huks from '@ohos.security.huks' | properties | Array\<[HuksParam](#huksparam)> | 否 | 属性，用于存HuksParam的数组。 | | inData | Uint8Array | 否 | 输入数据。 | -## HuksHandle(deprecated) - -huks Handle结构体。 - -**系统能力**：SystemCapability.Security.Huks - -| 参数名 | 类型 | 必填 | 说明 | -| ---------- | ---------------- | ---- | -------- | -| errorCode | number | 是 | 表示错误码。 | -| handle | number | 是 | 表示handle值。 | -| token | Uint8Array | 否 | 表示[init](#huksinit)操作之后获取到的challenge信息。 | - ## HuksSessionHandle9+ huks Handle结构体。 @@ -58,21 +46,6 @@ huks Handle结构体。 | handle | number | 是 | 表示handle值。 | | challenge | Uint8Array | 否 | 表示[init](#huksinit)操作之后获取到的challenge信息。 | -## HuksResult(deprecated) - -调用接口返回的result。 - -**系统能力**：SystemCapability.Security.Huks - - - -| 参数名 | 类型 | 必填 | 说明 | -| ---------- | ------------------------------- | ---- | ---------------- | -| errorCode | number | 是 | 表示错误码。 | -| outData | Uint8Array | 否 | 表示输出数据。 | -| properties | Array\<[HuksParam](#huksparam)> | 否 | 表示属性信息。 | -| certChains | Array\ | 否 | 表示证书链数据。 | - ## HuksReturnResult9+ 调用接口返回的result。 @@ -87,110 +60,6 @@ huks Handle结构体。 | properties | Array\<[HuksParam](#huksparam)> | 否 | 表示属性信息。 | | certChains | Array\ | 否 | 表示证书链数据。 | -## huks.generateKey(deprecated) - -generateKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void - -生成密钥，使用Callback回调异步返回结果。 - -> **说明：** 从API Version 9开始废弃，建议使用[huks.generateKeyItem9+](#huksgeneratekeyitem9)替代。 - -**系统能力**：SystemCapability.Security.Huks - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | -| keyAlias | string | 是 | 别名。 | -| options | [HuksOptions](#huksoptions) | 是 | 用于存放生成key所需TAG。 | -| callback | AsyncCallback\<[HuksResult](#huksresult)> | 是 | 回调函数。返回HUKS_SUCCESS时表示接口使用成功，其余结果请参考HuksResult进行错误码查询。 | - -**示例：** - -```js -/* 以生成RSA512密钥为例 */ -var keyAlias = 'keyAlias'; -var properties = new Array(); -properties[0] = { - tag: huks.HuksTag.HUKS_TAG_ALGORITHM, - value: huks.HuksKeyAlg.HUKS_ALG_RSA -}; -properties[1] = { - tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, - value: huks.HuksKeySize.HUKS_RSA_KEY_SIZE_512 -}; -properties[2] = { - tag: huks.HuksTag.HUKS_TAG_PURPOSE, - value: -huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | -huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT -}; -properties[3] = { - tag: huks.HuksTag.HUKS_TAG_PADDING, - value: huks.HuksKeyPadding.HUKS_PADDING_OAEP -}; -properties[4] = { - tag: huks.HuksTag.HUKS_TAG_DIGEST, - value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256 -}; -var options = { - properties: properties -}; -huks.generateKey(keyAlias, options, function (err, data){}); -``` - -## huks.generateKey(deprecated) - -generateKey(keyAlias: string, options: HuksOptions) : Promise\ - -生成密钥，使用Promise方式异步返回结果。 - -> **说明：** 从API Version 9开始废弃，建议使用[huks.generateKeyItem9+](#huksgeneratekeyitem9-1)替代。 - -**系统能力**：SystemCapability.Security.Huks - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------------- | ---- | ------------------------ | -| keyAlias | string | 是 | 密钥别名。 | -| options | [HuksOptions](#huksoptions) | 是 | 用于存放生成key所需TAG。 | - -**返回值**： - -| 类型 | 说明 | -| ----------------------------------- | -------------------------------------------------- | -| Promise\<[HuksResult](#huksresult)> | Promise对象。返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。 | - -**示例：** - -```js -/* 以生成ECC256密钥为例 */ -var keyAlias = 'keyAlias'; -var properties = new Array(); -properties[0] = { - tag: huks.HuksTag.HUKS_TAG_ALGORITHM, - value: huks.HuksKeyAlg.HUKS_ALG_ECC -}; -properties[1] = { - tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, - value: huks.HuksKeySize.HUKS_ECC_KEY_SIZE_256 -}; -properties[2] = { - tag: huks.HuksTag.HUKS_TAG_PURPOSE, - value: -huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_SIGN | -huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_VERIFY -}; -properties[3] = { - tag: huks.HuksTag.HUKS_TAG_DIGEST, - value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256 -}; -var options = { - properties: properties -}; -var result = huks.generateKey(keyAlias, options); -``` ## huks.generateKeyItem9+ @@ -303,69 +172,6 @@ try { } ``` -## huks.deleteKey(deprecated) - -deleteKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void - -删除密钥，使用Callback回调异步返回结果。 - -> **说明：** 从API Version 9开始废弃，建议使用[huks.deleteKeyItem9+](#huksdeletekeyitem9)替代。 - -**系统能力**：SystemCapability.Security.Huks - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ----------------------------------------- | ---- | -------------------------------------------------- | -| keyAlias | string | 是 | 密钥别名，应为生成key时传入的别名。 | -| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | -| callback | AsyncCallback\<[HuksResult](#huksresult)> | 是 | 回调函数。返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。 | - -**示例：** - -```js -/* 此处options选择emptyOptions传空 */ -var keyAlias = 'keyAlias'; -var emptyOptions = { - properties: [] -}; -huks.deleteKey(keyAlias, emptyOptions, function (err, data) {}); -``` - -## huks.deleteKey(deprecated) - -deleteKey(keyAlias: string, options: HuksOptions) : Promise\ - -删除密钥，使用Promise方式异步返回结果。 - -> **说明：** 从API Version 9开始废弃，建议使用[huks.deleteKeyItem9+](#huksdeletekeyitem9-1)替代。 - -**系统能力**：SystemCapability.Security.Huks - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ----------- | ---- | ----------------------------------------------------- | -| keyAlias | string | 是 | 密钥别名，应为生成key时传入的别名。 | -| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | - -**返回值：** - -| 类型 | 说明 | -| ----------------------------------- | -------------------------------------------------- | -| Promise\<[HuksResult](#huksresult)> | Promise对象。返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。 | - -**示例：** - -```js -/* 此处options选择emptyOptions传空 */ -var keyAlias = 'keyAlias'; -var emptyOptions = { - properties: [] -}; -var result = huks.deleteKey(keyAlias, emptyOptions); -``` - ## huks.deleteKeyItem9+ deleteKeyItem(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void @@ -469,23 +275,21 @@ var emptyOptions = { var result = huks.getSdkVersion(emptyOptions); ``` -## huks.importKey(deprecated) +## huks.importKeyItem9+ -importKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void +importKeyItem(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void 导入明文密钥，使用Callback方式回调异步返回结果 。 -> **说明：** 从API Version 9开始废弃，建议使用[huks.importKeyItem9+](#huksimportkeyitem9)替代。 - **系统能力**：SystemCapability.Security.Huks **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------ | ---- | ------------------------------------------------- | -| keyAlias | string | 是 | 密钥别名。 | -| options | [HuksOptions](#huksoptions) | 是 | 用于导入时所需TAG和需要导入的密钥。 | -| callback | AsyncCallback\<[HuksResult](#huksresult)> | 是 | 回调函数。返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | --------------------------------------------- | +| keyAlias | string | 是 | 密钥别名。 | +| options | [HuksOptions](#huksoptions) | 是 | 用于导入时所需TAG和需要导入的密钥。 | +| callback | AsyncCallback\ | 是 | 回调函数。不返回err值时表示接口使用成功，其他时为错误。 | **示例：** @@ -502,171 +306,46 @@ function makeRandomArr(size) { var keyAlias = 'keyAlias'; var properties = new Array(); properties[0] = { - tag: huks.HuksTag.HUKS_TAG_ALGORITHM, - value: huks.HuksKeyAlg.HUKS_ALG_AES + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_AES }; properties[1] = { - tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, - value: huks.HuksKeySize.HUKS_AES_KEY_SIZE_256 + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_AES_KEY_SIZE_256 }; properties[2] = { - tag: huks.HuksTag.HUKS_TAG_PURPOSE, - value: -huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: + huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT }; properties[3] = { - tag: huks.HuksTag.HUKS_TAG_PADDING, - value:huks.HuksKeyPadding.HUKS_PADDING_PKCS7 + tag: huks.HuksTag.HUKS_TAG_PADDING, + value:huks.HuksKeyPadding.HUKS_PADDING_PKCS7 }; properties[4] = { - tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, - value: huks.HuksCipherMode.HUKS_MODE_ECB + tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, + value: huks.HuksCipherMode.HUKS_MODE_ECB }; var options = { - properties: properties, - inData: plainTextSize32 + properties: properties, + inData: plainTextSize32 }; -huks.importKey(keyAlias, options, function (err, data){}); +try { + huks.importKeyItem(keyAlias, options, function (error, data) { + if (error) { + console.error(`callback: importKeyItem failed, code: ${error.code}, msg: ${error.message}`); + } else { + console.info(`callback: importKeyItem success`); + } + }); +} catch (error) { + console.error(`callback: importKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); +} ``` -## huks.importKey(deprecated) +## huks.importKeyItem9+ -importKey(keyAlias: string, options: HuksOptions) : Promise\ - -导入明文密钥，使用Promise方式异步返回结果。 - -> **说明：** 从API Version 9开始废弃，建议使用[huks.importKeyItem9+](#huksimportkeyitem9-1)替代。 - -**系统能力**：SystemCapability.Security.Huks - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ----------- | ---- | ------------------------------------ | -| keyAlias | string | 是 | 密钥别名。 | -| options | [HuksOptions](#huksoptions) | 是 | 用于导入时所需TAG和需要导入的密钥。 | - -**返回值：** - -| 类型 | 说明 | -| ----------------------------------- | -------------------------------------------------- | -| Promise\<[HuksResult](#huksresult)> | Promise对象。返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。 | - -**示例：** - -```js -/* 以导入AES128为例 */ -var plainTextSize32 = makeRandomArr(32); - -function makeRandomArr(size) { - var arr = new Uint8Array(size); - for (var i = 0; i < size; i++) { - arr[i] = Math.floor(Math.random() * 10); - } - return arr; -}; - -/*第一步：生成密钥*/ -var keyAlias = 'keyAlias'; -var properties = new Array(); -properties[0] = { - tag: huks.HuksTag.HUKS_TAG_ALGORITHM, - value: huks.HuksKeyAlg.HUKS_ALG_AES -}; -properties[1] = { - tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, - value: huks.HuksKeySize.HUKS_AES_KEY_SIZE_128 -}; -properties[2] = { - tag: huks.HuksTag.HUKS_TAG_PURPOSE, - value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT -}; -properties[3] = { - tag: huks.HuksTag.HUKS_TAG_PADDING, - value:huks.HuksKeyPadding.HUKS_PADDING_PKCS7 -}; -properties[4] = { - tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, - value: huks.HuksCipherMode.HUKS_MODE_ECB -}; -var huksoptions = { - properties: properties, - inData: plainTextSize32 -}; -var result = huks.importKey(keyAlias, huksoptions); -``` - -## huks.importKeyItem9+ - -importKeyItem(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void - -导入明文密钥，使用Callback方式回调异步返回结果 。 - -**系统能力**：SystemCapability.Security.Huks - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------------- | ---- | --------------------------------------------- | -| keyAlias | string | 是 | 密钥别名。 | -| options | [HuksOptions](#huksoptions) | 是 | 用于导入时所需TAG和需要导入的密钥。 | -| callback | AsyncCallback\ | 是 | 回调函数。不返回err值时表示接口使用成功，其他时为错误。 | - -**示例：** - -```js -/* 以导入AES256密钥为例 */ -var plainTextSize32 = makeRandomArr(32); -function makeRandomArr(size) { - var arr = new Uint8Array(size); - for (var i = 0; i < size; i++) { - arr[i] = Math.floor(Math.random() * 10); - } - return arr; -}; -var keyAlias = 'keyAlias'; -var properties = new Array(); -properties[0] = { - tag: huks.HuksTag.HUKS_TAG_ALGORITHM, - value: huks.HuksKeyAlg.HUKS_ALG_AES -}; -properties[1] = { - tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, - value: huks.HuksKeySize.HUKS_AES_KEY_SIZE_256 -}; -properties[2] = { - tag: huks.HuksTag.HUKS_TAG_PURPOSE, - value: - huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT -}; -properties[3] = { - tag: huks.HuksTag.HUKS_TAG_PADDING, - value:huks.HuksKeyPadding.HUKS_PADDING_PKCS7 -}; -properties[4] = { - tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, - value: huks.HuksCipherMode.HUKS_MODE_ECB -}; -var options = { - properties: properties, - inData: plainTextSize32 -}; -try { - huks.importKeyItem(keyAlias, options, function (error, data) { - if (error) { - console.error(`callback: importKeyItem failed, code: ${error.code}, msg: ${error.message}`); - } else { - console.info(`callback: importKeyItem success`); - } - }); -} catch (error) { - console.error(`callback: importKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); -} -``` - -## huks.importKeyItem9+ - -importKeyItem(keyAlias: string, options: HuksOptions) : Promise\ +importKeyItem(keyAlias: string, options: HuksOptions) : Promise\ 导入明文密钥，使用Promise方式异步返回结果。 @@ -1233,69 +912,6 @@ async function TestImportWrappedFunc(alias, wrappingAlias, options) { } ``` -## huks.exportKey(deprecated) - -exportKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void - -导出密钥，使用Callback方式回调异步返回的结果。 - -> **说明：** 从API Version 9开始废弃，建议使用[huks.exportKeyItem9+](#huksexportkeyitem9)替代。 - -**系统能力**：SystemCapability.Security.Huks - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | -| keyAlias | string | 是 | 密钥别名，应与所用密钥生成时使用的别名相同。 | -| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | -| callback | AsyncCallback\<[HuksResult](#huksresult)> | 是 | 回调函数。返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。outData：返回从密钥中导出的公钥。 | - -**示例：** - -```js -/* 此处options选择emptyOptions来传空 */ -var keyAlias = 'keyAlias'; -var emptyOptions = { - properties: [] -}; -huks.exportKey(keyAlias, emptyOptions, function (err, data){}); -``` - -## huks.exportKey(deprecated) - -exportKey(keyAlias: string, options: HuksOptions) : Promise\ - -导出密钥，使用Promise方式回调异步返回的结果。 - -> **说明：** 从API Version 9开始废弃，建议使用[huks.exportKeyItem9+](#huksexportkeyitem9-1))替代。 - -**系统能力**：SystemCapability.Security.Huks - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ----------- | ---- | ------------------------------------------------------------ | -| keyAlias | string | 是 | 密钥别名，应与所用密钥生成时使用的别名相同。 | -| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | - -**返回值：** - -| 类型 | 说明 | -| ----------------------------------- | ------------------------------------------------------------ | -| Promise\<[HuksResult](#huksresult)> | Promise对象。返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。outData：返回从密钥中导出的公钥。 | - -**示例：** - -```js -/* 此处options选择emptyOptions来传空 */ -var keyAlias = 'keyAlias'; -var emptyOptions = { - properties: [] -}; -var result = huks.exportKey(keyAlias, emptyOptions); -``` - ## huks.exportKeyItem9+ exportKeyItem(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void @@ -1375,23 +991,21 @@ try { } ``` -## huks.getKeyProperties(deprecated) +## huks.getKeyItemProperties9+ -getKeyProperties(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void +getKeyItemProperties(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void 获取密钥属性，使用Callback回调异步返回结果。 -> **说明：** 从API Version 9开始废弃，建议使用[huks.getKeyItemProperties9+](#huksgetkeyitemproperties9)替代。 - **系统能力**：SystemCapability.Security.Huks **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | -| keyAlias | string | 是 | 密钥别名，应与所用密钥生成时使用的别名相同。 | -| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | -| callback | AsyncCallback\<[HuksResult](#huksresult)> | 是 | 回调函数。errorCode：返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------------------- | ---- | ------------------------------------------------------------ | +| keyAlias | string | 是 | 密钥别名，应与所用密钥生成时使用的别名相同。 | +| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | +| callback | AsyncCallback<[HuksReturnResult](#huksreturnresult)> | 是 | 回调函数。errorCode：返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。 | **示例：** @@ -1399,33 +1013,41 @@ getKeyProperties(keyAlias: string, options: HuksOptions, callback: AsyncCallback /* 此处options选择emptyOptions来传空 */ var keyAlias = 'keyAlias'; var emptyOptions = { - properties: [] + properties: [] }; -huks.getKeyProperties(keyAlias, emptyOptions, function (err, data){}); +try { + huks.getKeyItemProperties(keyAlias, emptyOptions, function (error, data) { + if (error) { + console.error(`callback: getKeyItemProperties failed, code: ${error.code}, msg: ${error.message}`); + } else { + console.info(`callback: getKeyItemProperties success, data = ${JSON.stringify(data)}`); + } + }); +} catch (error) { + console.error(`callback: getKeyItemProperties input arg invalid, code: ${error.code}, msg: ${error.message}`); +} ``` -## huks.getKeyProperties(deprecated) +## huks.getKeyItemProperties9+ -getKeyProperties(keyAlias: string, options: HuksOptions) : Promise\ +getKeyItemProperties(keyAlias: string, options: HuksOptions) : Promise\ 获取密钥属性，使用Promise回调异步返回结果。 -> **说明：** 从API Version 9开始废弃，建议使用[huks.getKeyItemProperties9+](#huksgetkeyitemproperties9-1)替代。 - **系统能力**：SystemCapability.Security.Huks **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ----------- | ---- | ------------------------------------------------------------ | -| keyAlias | string | 是 | 密钥别名，应与所用密钥生成时使用的别名相同。 | -| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | -------------------------------------------- | +| keyAlias | string | 是 | 密钥别名，应与所用密钥生成时使用的别名相同。 | +| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | **返回值：** -| 类型 | 说明 | -| ------------------ | ------------------------------------------------------------ | -| Promise\<[HuksResult](#huksoptions)> | Promise对象。errorCode：返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。properties：返回值为生成密钥时所需参数。 | +| 类型 | 说明 | +| ----------------------------------------------- | ------------------------------------------------------------ | +| Promise\<[HuksReturnResult](#huksreturnresult)> | Promise对象。不返回err值时表示接口使用成功，其他时为错误。properties：返回值为生成密钥时所需参数。 | **示例：** @@ -1433,76 +1055,7 @@ getKeyProperties(keyAlias: string, options: HuksOptions) : Promise\ /* 此处options选择emptyOptions来传空 */ var keyAlias = 'keyAlias'; var emptyOptions = { - properties: [] -}; -var result = huks.getKeyProperties(keyAlias, emptyOptions); -``` - -## huks.getKeyItemProperties9+ - -getKeyItemProperties(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void - -获取密钥属性，使用Callback回调异步返回结果。 - -**系统能力**：SystemCapability.Security.Huks - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------------------------------- | ---- | ------------------------------------------------------------ | -| keyAlias | string | 是 | 密钥别名，应与所用密钥生成时使用的别名相同。 | -| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | -| callback | AsyncCallback<[HuksReturnResult](#huksreturnresult)> | 是 | 回调函数。errorCode：返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。 | - -**示例：** - -```js -/* 此处options选择emptyOptions来传空 */ -var keyAlias = 'keyAlias'; -var emptyOptions = { - properties: [] -}; -try { - huks.getKeyItemProperties(keyAlias, emptyOptions, function (error, data) { - if (error) { - console.error(`callback: getKeyItemProperties failed, code: ${error.code}, msg: ${error.message}`); - } else { - console.info(`callback: getKeyItemProperties success, data = ${JSON.stringify(data)}`); - } - }); -} catch (error) { - console.error(`callback: getKeyItemProperties input arg invalid, code: ${error.code}, msg: ${error.message}`); -} -``` - -## huks.getKeyItemProperties9+ - -getKeyItemProperties(keyAlias: string, options: HuksOptions) : Promise\ - -获取密钥属性，使用Promise回调异步返回结果。 - -**系统能力**：SystemCapability.Security.Huks - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------------- | ---- | -------------------------------------------- | -| keyAlias | string | 是 | 密钥别名，应与所用密钥生成时使用的别名相同。 | -| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | - -**返回值：** - -| 类型 | 说明 | -| ----------------------------------------------- | ------------------------------------------------------------ | -| Promise\<[HuksReturnResult](#huksreturnresult)> | Promise对象。不返回err值时表示接口使用成功，其他时为错误。properties：返回值为生成密钥时所需参数。 | - -**示例：** - -```js -/* 此处options选择emptyOptions来传空 */ -var keyAlias = 'keyAlias'; -var emptyOptions = { - properties: [] + properties: [] }; try { huks.getKeyItemProperties(keyAlias, emptyOptions) @@ -1517,69 +1070,6 @@ try { } ``` -## huks.isKeyExist(deprecated) - -isKeyExist(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void - -判断密钥是否存在，使用Callback回调异步返回结果 。 - -> **说明：** 从API Version 9开始废弃，建议使用[huks.isKeyItemExist9+](#huksiskeyitemexist9)替代。 - -**系统能力**：SystemCapability.Security.Huks - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------- | ---- | ------------------------------------- | -| keyAlias | string | 是 | 所需查找的密钥的别名。 | -| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | -| callback | AsyncCallback\ | 是 | 回调函数。FALSE代表密钥不存在，TRUE代表密钥存在。 | - -**示例：** - -```js -/* 此处options选择emptyOptions来传空 */ -var keyAlias = 'keyAlias'; -var emptyOptions = { - properties: [] -}; -huks.isKeyExist(keyAlias, emptyOptions, function (err, data){}); -``` - -## huks.isKeyExist(deprecated) - -isKeyExist(keyAlias: string, options: HuksOptions) : Promise\ - -判断密钥是否存在，使用Promise回调异步返回结果 。 - -> **说明：** 从API Version 9开始废弃，建议使用[huks.isKeyItemExist9+](#huksiskeyitemexist9-1)替代。 - -**系统能力**：SystemCapability.Security.Huks - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ----------- | ---- | -------------------------------- | -| keyAlias | string | 是 | 所需查找的密钥的别名。 | -| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | - -**返回值：** - -| 类型 | 说明 | -| ----------------- | --------------------------------------- | -| Promise\ | Promise对象。FALSE代表密钥不存在，TRUE代表密钥存在。 | - -**示例：** - -```js -/* 此处options选择emptyOptions来传空 */ -var keyAlias = 'keyAlias'; -var emptyOptions = { - properties: [] -}; -var result = huks.isKeyExist(keyAlias, emptyOptions); -``` - ## huks.isKeyItemExist9+ isKeyItemExist(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void @@ -1659,48 +1149,6 @@ try { } ``` -## huks.init(deprecated) - -init(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void - -init操作密钥接口，使用Callback回调异步返回结果。huks.init, huks.update, huks.finish为三段式接口，需要一起使用。 - -> **说明：** 从API Version 9开始废弃，建议使用[huks.initSession9+](#huksinitsession9-1)替代。 - -**系统能力**：SystemCapability.Security.Huks - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------- | ---- | ------------------------------------- | -| keyAlias | string | 是 | Init操作密钥的别名。 | -| options | [HuksOptions](#huksoptions) | 是 | Init操作的参数集合。 | -| callback | AsyncCallback\<[HuksHandle](#hukshandle)> | 是 | 回调函数。将Init操作操作返回的handle添加到密钥管理系统的回调。 | - - -## huks.init(deprecated) - -init(keyAlias: string, options: HuksOptions) : Promise\ - -init操作密钥接口，使用Promise方式异步返回结果。huks.init, huks.update, huks.finish为三段式接口，需要一起使用。 - -> **说明：** 从API Version 9开始废弃，建议使用[huks.initSession9+](#huksinitsession9-1)替代。 - -**系统能力**：SystemCapability.Security.Huks - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------- | ---- | ------------------------------------- | -| keyAlias | string | 是 | Init操作密钥的别名。 | -| options | [HuksOptions](#huksoptions) | 是 | Init参数集合。 | - -**返回值**： - -| 类型 | 说明 | -| ----------------------------------- | -------------------------------------------------- | -| Promise\<[HuksHandle](#hukshandle)> | Promise对象。将Init操作返回的handle添加到密钥管理系统的回调。 | - ## huks.initSession9+ initSession(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void @@ -1739,67 +1187,6 @@ initSession操作密钥接口，使用Promise方式异步返回结果。huks.ini | ----------------------------------- | -------------------------------------------------- | | Promise\<[HuksSessionHandle](#hukssessionhandle)> | Promise对象。将Init操作返回的handle添加到密钥管理系统的回调。 | -## huks.update(deprecated) - -update(handle: number, options: HuksOptions, callback: AsyncCallback\) : void - -update操作密钥接口，使用Callback回调异步返回结果。huks.init, huks.update, huks.finish为三段式接口，需要一起使用。 - -> **说明：** 从API Version 9开始废弃，建议使用[huks.updateSession9+](#huksupdatesession9)替代。 - -**系统能力**：SystemCapability.Security.Huks - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ----------------------------------------- | ---- | -------------------------------------------- | -| handle | number | 是 | Update操作的handle。 | -| options | [HuksOptions](#huksoptions) | 是 | Update的参数集合。 | -| callback | AsyncCallback\<[HuksResult](#huksresult)> | 是 | 回调函数。将Update操作的结果添加到密钥管理系统的回调。 | - -## huks.update(deprecated) - -update(handle: number, options: HuksOptions, token: Uint8Array, callback: AsyncCallback\) : void - -update操作密钥接口，使用Callback回调异步返回结果。huks.init, huks.update, huks.finish为三段式接口，需要一起使用。 - -> **说明：** 从API Version 9开始废弃，建议使用[huks.updateSession9+](#huksupdatesession9-1)替代。 - -**系统能力**： SystemCapability.Security.Huks - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ----------------------------------------- | ---- | -------------------------------------------- | -| handle | number | 是 | Update操作的handle。 | -| token | Uint8Array | 否 | Update操作的token。 | -| options | [HuksOptions](#huksoptions) | 是 | Update操作的参数集合。 | -| callback | AsyncCallback\<[HuksResult](#huksresult)> | 是 | 回调函数。将Update操作的结果添加到密钥管理系统的回调。 | - -## huks.update(deprecated) - -update(handle: number, options: HuksOptions, token?: Uint8Array) : Promise\ - -update操作密钥接口，使用Promise方式异步返回结果。huks.init, huks.update, huks.finish为三段式接口，需要一起使用。 - -> **说明：** 从API Version 9开始废弃，建议使用[huks.updateSession9+](#huksupdatesession9-2)替代。 - -**系统能力**： SystemCapability.Security.Huks - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------- | ----------------------------------- | ---- | -------------------------------------------- | -| handle | number | 是 | Update操作的handle。 | -| token | Uint8Array | 否 | Update操作的token。 | -| options | [HuksOptions](#huksoptions) | 是 | Update操作的参数集合。 | - -**返回值**： - -| 类型 | 说明 | -| ----------------------------------- | -------------------------------------------------- | -| Promise\<[HuksResult](#huksresult)> | Promise对象。将Update操作的结果添加到密钥管理系统的回调。 | - ## huks.updateSession9+ updateSession(handle: number, options: HuksOptions, callback: AsyncCallback\) : void @@ -1856,70 +1243,28 @@ uupdateSession操作密钥接口，使用Promise方式异步返回结果。huks. | ----------------------------------- | -------------------------------------------------- | | Promise<[HuksReturnResult](#huksreturnresult)> | Promise对象。将Update操作的结果添加到密钥管理系统的回调。 | -## huks.finish(deprecated) - -finish(handle: number, options: HuksOptions, callback: AsyncCallback\) : void +## huks.finishSession9+ -finish操作密钥接口，使用Callback回调异步返回结果。huks.init, huks.update, huks.finish为三段式接口，需要一起使用。 +finishSession(handle: number, options: HuksOptions, callback: AsyncCallback\) : void -> **说明：** 从API Version 9开始废弃，建议使用[huks.finishSession9+](#huksfinishsession9)替代。 +finishSession操作密钥接口，使用Callback回调异步返回结果。huks.initSession, huks.updateSession, huks.finishSession为三段式接口，需要一起使用。 **系统能力**：SystemCapability.Security.Huks **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------- | ---- | ------------------------------------- | -| handle | number | 是 | Finish操作的handle。 | -| options | [HuksOptions](#huksoptions) | 是 | Finish的参数集合。 | -| callback | AsyncCallback\<[HuksResult](#huksresult)> | 是 | 回调函数。将Finish操作的结果添加到密钥管理系统的回调。 | - - -## huks.finish(deprecated) +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------------------- | ---- | -------------------------------------------- | +| handle | number | 是 | Finish操作的handle。 | +| options | [HuksOptions](#huksoptions) | 是 | Finish的参数集合。 | +| token | Uint8Array | 是 | Finish操作的token。 | +| callback | AsyncCallback<[HuksReturnResult](#huksreturnresult)> | 是 | 回调函数。将Finish操作的结果添加到密钥管理系统的回调。 | -finish(handle: number, options: HuksOptions) : Promise\ +## huks.finishSession9+ -finish操作密钥接口，使用Promise方式异步返回结果。huks.init, huks.update, huks.finish为三段式接口，需要一起使用。 +finishSession(handle: number, options: HuksOptions, token: Uint8Array, callback: AsyncCallback\) : void -> **说明：** 从API Version 9开始废弃，建议使用[huks.updateSession9+](#huksfinishsession9-1)替代。 - -**系统能力**：SystemCapability.Security.Huks - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------- | ---- | ------------------------------------- | -| handle | number | 是 | Finish操作的handle。 | -| options | [HuksOptions](#huksoptions) | 是 | Finish操作的参数集合。 | - -**返回值**： - -| 类型 | 说明 | -| ----------------------------------- | -------------------------------------------------- | -| Promise\<[HuksResult](#huksresult)> | Promise对象，用于获取异步返回结果。 | - -## huks.finishSession9+ - -finishSession(handle: number, options: HuksOptions, callback: AsyncCallback\) : void - -finishSession操作密钥接口，使用Callback回调异步返回结果。huks.initSession, huks.updateSession, huks.finishSession为三段式接口，需要一起使用。 - -**系统能力**：SystemCapability.Security.Huks - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------------------------------- | ---- | -------------------------------------------- | -| handle | number | 是 | Finish操作的handle。 | -| options | [HuksOptions](#huksoptions) | 是 | Finish的参数集合。 | -| token | Uint8Array | 是 | Finish操作的token。 | -| callback | AsyncCallback<[HuksReturnResult](#huksreturnresult)> | 是 | 回调函数。将Finish操作的结果添加到密钥管理系统的回调。 | - -## huks.finishSession9+ - -finishSession(handle: number, options: HuksOptions, token: Uint8Array, callback: AsyncCallback\) : void - -finishSession操作密钥接口，使用Callback回调异步返回结果。huks.initSession, huks.updateSession, huks.finishSession为三段式接口，需要一起使用。 +finishSession操作密钥接口，使用Callback回调异步返回结果。huks.initSession, huks.updateSession, huks.finishSession为三段式接口，需要一起使用。 **系统能力**：SystemCapability.Security.Huks @@ -1955,264 +1300,182 @@ finishSession操作密钥接口，使用Promise方式异步返回结果。huks.i | ----------------------------------- | -------------------------------------------------- | | Promise\<[HuksReturnResult](#huksreturnresult)> | Promise对象，用于获取异步返回结果。 | -## huks.abort(deprecated) -abort(handle: number, options: HuksOptions, callback: AsyncCallback\) : void +## huks.abortSession9+ -abort操作密钥接口，使用Callback回调异步返回结果。 +abortSession(handle: number, options: HuksOptions, callback: AsyncCallback\) : void -> **说明：** 从API Version 9开始废弃，建议使用[huks.abortSession9+](#huksabortsession9)替代。 +abort操作密钥接口，使用Callback回调异步返回结果 。 **系统能力**：SystemCapability.Security.Huks **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------- | ---- | ------------------------------------- | -| handle | number | 是 | Abort操作的handle。 | -| options | [HuksOptions](#huksoptions) | 是 | Abort操作的参数集合。 | -| callback | AsyncCallback\<[HuksResult](#huksresult)> | 是 | 回调函数。将Abort操作的结果添加到密钥管理系统的回调。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | ------------------------------------------- | +| handle | number | 是 | Abort操作的handle。 | +| options | [HuksOptions](#huksoptions) | 是 | Abort操作的参数集合。 | +| callback | AsyncCallback\ | 是 | 回调函数。将Abort操作的结果添加到密钥管理系统的回调。 | **示例：** ```js -/* huks.init, huks.update, huks.finish为三段式接口，需要一起使用，当huks.init和huks.update - * 以及huks.finish操作中的任一阶段发生错误时，都需要调用huks.abort来终止密钥的使用。 +/* huks.initSession, huks.updateSession, huks.finishSession为三段式接口，需要一起使用，当 + * huks.initSession和huks.updateSession + * 以及huks.finishSession操作中的任一阶段发生错误时， + * 都需要调用huks.abortSession来终止密钥的使用。 * - * 以下以RSA1024密钥的callback操作使用为例 + * 以下以RSA1024密钥的callback功能使用为例 */ -var keyalias = "HuksDemoRSA"; +function stringToUint8Array(str) { + var arr = []; + for (var i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + var tmpUint8Array = new Uint8Array(arr); + return tmpUint8Array; +} + +var keyAlias = "HuksDemoRSA"; var properties = new Array(); var options = { - properties: properties, - inData: new Uint8Array(0) + properties: properties, + inData: new Uint8Array(0) }; var handle; -var resultMessage = ""; async function generateKey() { - properties[0] = { - tag: huks.HuksTag.HUKS_TAG_ALGORITHM, - value: huks.HuksKeyAlg.HUKS_ALG_RSA - }; - properties[1] = { - tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, - value: huks.HuksKeySize.HUKS_RSA_KEY_SIZE_1024 - }; - properties[2] = { - tag: huks.HuksTag.HUKS_TAG_PURPOSE, - value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT - }; - properties[3] = { - tag: huks.HuksTag.HUKS_TAG_PADDING, - value: huks.HuksKeyPadding.HUKS_PADDING_OAEP - }; - properties[4] = { - tag: huks.HuksTag.HUKS_TAG_DIGEST, - value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256 - }; - huks.generateKey(keyalias, options); -} -function stringToUint8Array(str) { - var arr = []; - for (var i = 0, j = str.length; i < j; ++i) { - arr.push(str.charCodeAt(i)); - } - var tmpUint8Array = new Uint8Array(arr); - return tmpUint8Array; + properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_RSA + }; + properties[1] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_RSA_KEY_SIZE_1024 + }; + properties[2] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT + }; + properties[3] = { + tag: huks.HuksTag.HUKS_TAG_PADDING, + value: huks.HuksKeyPadding.HUKS_PADDING_PKCS1_V1_5 + }; + properties[4] = { + tag: huks.HuksTag.HUKS_TAG_DIGEST, + value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256 + }; + properties[5] = { + tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, + value: huks.HuksCipherMode.HUKS_MODE_ECB, + } + + try { + await huks.generateKeyItem(keyAlias, options, function (error, data) { + if (error) { + console.error(`callback: generateKeyItem failed, code: ${error.code}, msg: ${error.message}`); + } else { + console.info(`callback: generateKeyItem success`); + } + }); + } catch (error) { + console.error(`callback: generateKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); + } } + async function huksInit() { - await huks.init(keyalias, options).then((data) => { - console.log(`test init data: ${JSON.stringify(data)}`); - handle = data.handle; - }).catch((err) => { - console.log("test init err information: " + JSON.stringify(err)) - }) + console.log('enter huksInit'); + try { + huks.initSession(keyAlias, options, function (error, data) { + if (error) { + console.error(`callback: initSession failed, code: ${error.code}, msg: ${error.message}`); + } else { + console.info(`callback: initSession success, data = ${JSON.stringify(data)}`); + handle = data.handle; + } + }); + } catch (error) { + console.error(`callback: initSession input arg invalid, code: ${error.code}, msg: ${error.message}`); + } } + async function huksUpdate() { + console.log('enter huksUpdate'); options.inData = stringToUint8Array("huksHmacTest"); - await huks.update(handle, options).then((data) => { - if (data.errorCode === 0) { - resultMessage += "update success!"; - } else { - resultMessage += "update fail!"; - } - }); - console.log(resultMessage); + try { + huks.updateSession(handle, options, function (error, data) { + if (error) { + console.error(`callback: updateSession failed, code: ${error.code}, msg: ${error.message}`); + } else { + console.info(`callback: updateSession success, data = ${JSON.stringify(data)}`); + } + }); + } catch (error) { + console.error(`callback: updateSession input arg invalid, code: ${error.code}, msg: ${error.message}`); + } } -function huksFinish() { - options.inData = stringToUint8Array("HuksDemoHMAC"); - huks.finish(handle, options).then((data) => { - if (data.errorCode === 0) { - resultMessage = "finish success!"; - } else { - resultMessage = "finish fail errorCode: " + data.errorCode; + +async function huksFinish() { + console.log('enter huksFinish'); + options.inData = new Uint8Array(0); + try { + huks.finishSession(handle, options, function (error, data) { + if (error) { + console.error(`callback: finishSession failed, code: ${error.code}, msg: ${error.message}`); + } else { + console.info(`callback: finishSession success, data = ${JSON.stringify(data)}`); + } + }); + } catch (error) { + console.error(`callback: finishSession input arg invalid, code: ${error.code}, msg: ${error.message}`); } - }).catch((err) => { - resultMessage = "finish fail， catch errorMessage:" + JSON.stringify(err) - }); - console.log(resultMessage); } + async function huksAbort() { - huks.abort(handle, options).then((data) => { - if (data.errorCode === 0) { - resultMessage = "abort success!"; - } else { - resultMessage = "abort fail errorCode: " + data.errorCode; + console.log('enter huksAbort'); + try { + huks.abortSession(handle, options, function (error, data) { + if (error) { + console.error(`callback: abortSession failed, code: ${error.code}, msg: ${error.message}`); + } else { + console.info(`callback: abortSession success`); + } + }); + } catch (error) { + console.error(`callback: abortSession input arg invalid, code: ${error.code}, msg: ${error.message}`); } - }).catch((err) => { - resultMessage = "abort fail， catch errorMessage:" + JSON.stringify(err) - }); - console.log(resultMessage); } ``` -## huks.abort(deprecated) +## huks.abortSession9+ -abort(handle: number, options: HuksOptions) : Promise\; +abortSession(handle: number, options: HuksOptions) : Promise\; abort操作密钥接口，使用Promise方式异步返回结果。 -> **说明：** 从API Version 9开始废弃，建议使用[huks.abortSession9+](#huksabortsession9-1)替代。 - **系统能力**：SystemCapability.Security.Huks **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------- | ---- | ------------------------------------- | -| handle | number | 是 | Abort操作的handle。 | -| options | [HuksOptions](#huksoptions) | 是 | Abort操作的参数集合。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------- | --------------------------- | ---- | ------------------------------------------- | +| handle | number | 是 | Abort操作的handle。 | +| options | [HuksOptions](#huksoptions) | 是 | Abort操作的参数集合。 | **返回值**： | 类型 | 说明 | | ----------------------------------- | -------------------------------------------------- | -| Promise\<[HuksResult](#huksresult)> | Promise对象。将Abort操作的结果添加到密钥管理系统的回调。 | +| Promise\ | Promise对象。将Abort操作的结果添加到密钥管理系统的回调。 | **示例：** ```js -/* huks.init, huks.update, huks.finish为三段式接口，需要一起使用，当huks.init和huks.update - * 以及huks.finish操作中的任一阶段发生错误时，都需要调用huks.abort来终止密钥的使用。 +/* huks.initSession, huks.updateSession, huks.finishSession为三段式接口，需要一起使用，当 + * huks.initSession和huks.updateSession + * 以及huks.finishSession操作中的任一阶段发生错误时， + * 都需要调用huks.abortSession来终止密钥的使用。 * - * 以下以RSA1024密钥的promise操作使用为例 - */ -var keyalias = "HuksDemoRSA"; -var properties = new Array(); -var options = { - properties: properties, - inData: new Uint8Array(0) -}; -var handle; -var resultMessage = ""; -function stringToUint8Array(str) { - var arr = []; - for (var i = 0, j = str.length; i < j; ++i) { - arr.push(str.charCodeAt(i)); - } - var tmpUint8Array = new Uint8Array(arr); - return tmpUint8Array; -} - -async function generateKey() { - properties[0] = { - tag: huks.HuksTag.HUKS_TAG_ALGORITHM, - value: huks.HuksKeyAlg.HUKS_ALG_RSA - }; - properties[1] = { - tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, - value: huks.HuksKeySize.HUKS_RSA_KEY_SIZE_1024 - }; - properties[2] = { - tag: huks.HuksTag.HUKS_TAG_PURPOSE, - value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT - }; - properties[3] = { - tag: huks.HuksTag.HUKS_TAG_PADDING, - value: huks.HuksKeyPadding.HUKS_PADDING_OAEP - }; - properties[4] = { - tag: huks.HuksTag.HUKS_TAG_DIGEST, - value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256 - }; - huks.generateKey(keyalias, options, function (err, data) { }); -} -async function huksInit() { - return new Promise((resolve, reject) => { - huks.init(keyalias, options, async function (err, data) { - if (data.errorCode === 0) { - resultMessage = "init success!" - handle = data.handle; - } else { - resultMessage = "init fail errorCode: " + data.errorCode - } - }); - }); -} - -async function huksUpdate() { - options.inData = stringToUint8Array("huksHmacTest"); - new Promise((resolve, reject) => { - huks.update(handle, options, function (err, data) { - if (data.errorCode === 0) { - resultMessage += "update success!"; - } else { - resultMessage += "update fail!"; - } - }); - }); - console.log(resultMessage); - -} - -async function huksFinish() { - options.inData = stringToUint8Array("0"); - new Promise((resolve, reject) => { - huks.finish(handle, options, function (err, data) { - if (data.errorCode === 0) { - resultMessage = "finish success!"; - } else { - resultMessage = "finish fail errorCode: " + data.errorCode; - } - }); - }); -} - -function huksAbort() { - new Promise((resolve, reject) => { - huks.abort(handle, options, function (err, data) { - console.log(`Huks_Demo hmac huksAbort1 data ${JSON.stringify(data)}`); - console.log(`Huks_Demo hmac huksAbort1 err ${JSON.stringify(err)}`); - }); - }); -} -``` - -## huks.abortSession9+ - -abortSession(handle: number, options: HuksOptions, callback: AsyncCallback\) : void - -abort操作密钥接口，使用Callback回调异步返回结果 。 - -**系统能力**：SystemCapability.Security.Huks - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------------- | ---- | ------------------------------------------- | -| handle | number | 是 | Abort操作的handle。 | -| options | [HuksOptions](#huksoptions) | 是 | Abort操作的参数集合。 | -| callback | AsyncCallback\ | 是 | 回调函数。将Abort操作的结果添加到密钥管理系统的回调。 | - -**示例：** - -```js -/* huks.initSession, huks.updateSession, huks.finishSession为三段式接口，需要一起使用，当 - * huks.initSession和huks.updateSession - * 以及huks.finishSession操作中的任一阶段发生错误时， - * 都需要调用huks.abortSession来终止密钥的使用。 - * - * 以下以RSA1024密钥的callback功能使用为例 + * 以下以RSA1024密钥的callback功能使用为例 */ function stringToUint8Array(str) { var arr = []; @@ -2257,31 +1520,31 @@ async function generateKey() { } try { - await huks.generateKeyItem(keyAlias, options, function (error, data) { - if (error) { - console.error(`callback: generateKeyItem failed, code: ${error.code}, msg: ${error.message}`); - } else { - console.info(`callback: generateKeyItem success`); - } - }); + await huks.generateKeyItem(keyAlias, options) + .then((data) => { + console.info(`promise: generateKeyItem success`); + }) + .catch(error => { + console.error(`promise: generateKeyItem failed, code: ${error.code}, msg: ${error.message}`); + }); } catch (error) { - console.error(`callback: generateKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); + console.error(`promise: generateKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); } } async function huksInit() { console.log('enter huksInit'); try { - huks.initSession(keyAlias, options, function (error, data) { - if (error) { - console.error(`callback: initSession failed, code: ${error.code}, msg: ${error.message}`); - } else { - console.info(`callback: initSession success, data = ${JSON.stringify(data)}`); - handle = data.handle; - } - }); + await huks.initSession(keyAlias, options) + .then ((data) => { + console.info(`promise: initSession success, data = ${JSON.stringify(data)}`); + handle = data.handle; + }) + .catch(error => { + console.error(`promise: initSession key failed, code: ${error.code}, msg: ${error.message}`); + }); } catch (error) { - console.error(`callback: initSession input arg invalid, code: ${error.code}, msg: ${error.message}`); + console.error(`promise: initSession input arg invalid, code: ${error.code}, msg: ${error.message}`); } } @@ -2289,15 +1552,15 @@ async function huksUpdate() { console.log('enter huksUpdate'); options.inData = stringToUint8Array("huksHmacTest"); try { - huks.updateSession(handle, options, function (error, data) { - if (error) { - console.error(`callback: updateSession failed, code: ${error.code}, msg: ${error.message}`); - } else { - console.info(`callback: updateSession success, data = ${JSON.stringify(data)}`); - } - }); + await huks.updateSession(handle, options) + .then ((data) => { + console.info(`promise: updateSession success, data = ${JSON.stringify(data)}`); + }) + .catch(error => { + console.error(`promise: updateSession failed, code: ${error.code}, msg: ${error.message}`); + }); } catch (error) { - console.error(`callback: updateSession input arg invalid, code: ${error.code}, msg: ${error.message}`); + console.error(`promise: updateSession input arg invalid, code: ${error.code}, msg: ${error.message}`); } } @@ -2305,313 +1568,81 @@ async function huksFinish() { console.log('enter huksFinish'); options.inData = new Uint8Array(0); try { - huks.finishSession(handle, options, function (error, data) { - if (error) { - console.error(`callback: finishSession failed, code: ${error.code}, msg: ${error.message}`); - } else { - console.info(`callback: finishSession success, data = ${JSON.stringify(data)}`); - } - }); + await huks.finishSession(handle, options) + .then ((data) => { + console.info(`promise: finishSession success, data = ${JSON.stringify(data)}`); + }) + .catch(error => { + console.error(`promise: finishSession failed, code: ${error.code}, msg: ${error.message}`); + }); } catch (error) { - console.error(`callback: finishSession input arg invalid, code: ${error.code}, msg: ${error.message}`); + console.error(`promise: finishSession input arg invalid, code: ${error.code}, msg: ${error.message}`); } } async function huksAbort() { console.log('enter huksAbort'); try { - huks.abortSession(handle, options, function (error, data) { - if (error) { - console.error(`callback: abortSession failed, code: ${error.code}, msg: ${error.message}`); - } else { - console.info(`callback: abortSession success`); - } - }); + await huks.abortSession(keyAlias, options) + .then ((data) => { + console.info(`promise: abortSession success`); + }) + .catch(error => { + console.error(`promise: abortSession failed, code: ${error.code}, msg: ${error.message}`); + }); } catch (error) { - console.error(`callback: abortSession input arg invalid, code: ${error.code}, msg: ${error.message}`); + console.error(`promise: abortSession input arg invalid, code: ${error.code}, msg: ${error.message}`); } } ``` -## huks.abortSession9+ -abortSession(handle: number, options: HuksOptions) : Promise\; +## HuksExceptionErrCode9+ -abort操作密钥接口，使用Promise方式异步返回结果。 +表示错误码的枚举以及对应的错误信息， 错误码表示错误类型，错误信息展示错误详情。 + +关于错误码的具体信息，可在[错误码参考文档](../errorcodes/errorcode-huks.md)中查看。 **系统能力**：SystemCapability.Security.Huks -**参数：** +| 名称 | 说明 | 错误码 | +| ---------------------------------------------- | --------------------------- | -------- | +| HUKS_ERR_CODE_PERMISSION_FAIL | 权限错误导致失败。 | 201 | +| HUKS_ERR_CODE_ILLEGAL_ARGUMENT | 参数错误导致失败。 | 401 | +| HUKS_ERR_CODE_NOT_SUPPORTED_API | 不支持的API。 | 801 | +| 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 | -| 参数名 | 类型 | 必填 | 说明 | -| ------- | --------------------------- | ---- | ------------------------------------------- | -| handle | number | 是 | Abort操作的handle。 | -| options | [HuksOptions](#huksoptions) | 是 | Abort操作的参数集合。 | +## HuksKeyPurpose -**返回值**： +表示密钥用途。 -| 类型 | 说明 | -| ----------------------------------- | -------------------------------------------------- | -| Promise\ | Promise对象。将Abort操作的结果添加到密钥管理系统的回调。 | +**系统能力**：SystemCapability.Security.Huks -**示例：** - -```js -/* huks.initSession, huks.updateSession, huks.finishSession为三段式接口，需要一起使用，当 - * huks.initSession和huks.updateSession - * 以及huks.finishSession操作中的任一阶段发生错误时， - * 都需要调用huks.abortSession来终止密钥的使用。 - * - * 以下以RSA1024密钥的callback功能使用为例 - */ -function stringToUint8Array(str) { - var arr = []; - for (var i = 0, j = str.length; i < j; ++i) { - arr.push(str.charCodeAt(i)); - } - var tmpUint8Array = new Uint8Array(arr); - return tmpUint8Array; -} - -var keyAlias = "HuksDemoRSA"; -var properties = new Array(); -var options = { - properties: properties, - inData: new Uint8Array(0) -}; -var handle; -async function generateKey() { - properties[0] = { - tag: huks.HuksTag.HUKS_TAG_ALGORITHM, - value: huks.HuksKeyAlg.HUKS_ALG_RSA - }; - properties[1] = { - tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, - value: huks.HuksKeySize.HUKS_RSA_KEY_SIZE_1024 - }; - properties[2] = { - tag: huks.HuksTag.HUKS_TAG_PURPOSE, - value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT - }; - properties[3] = { - tag: huks.HuksTag.HUKS_TAG_PADDING, - value: huks.HuksKeyPadding.HUKS_PADDING_PKCS1_V1_5 - }; - properties[4] = { - tag: huks.HuksTag.HUKS_TAG_DIGEST, - value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256 - }; - properties[5] = { - tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, - value: huks.HuksCipherMode.HUKS_MODE_ECB, - } - - try { - await huks.generateKeyItem(keyAlias, options) - .then((data) => { - console.info(`promise: generateKeyItem success`); - }) - .catch(error => { - console.error(`promise: generateKeyItem failed, code: ${error.code}, msg: ${error.message}`); - }); - } catch (error) { - console.error(`promise: generateKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); - } -} - -async function huksInit() { - console.log('enter huksInit'); - try { - await huks.initSession(keyAlias, options) - .then ((data) => { - console.info(`promise: initSession success, data = ${JSON.stringify(data)}`); - handle = data.handle; - }) - .catch(error => { - console.error(`promise: initSession key failed, code: ${error.code}, msg: ${error.message}`); - }); - } catch (error) { - console.error(`promise: initSession input arg invalid, code: ${error.code}, msg: ${error.message}`); - } -} - -async function huksUpdate() { - console.log('enter huksUpdate'); - options.inData = stringToUint8Array("huksHmacTest"); - try { - await huks.updateSession(handle, options) - .then ((data) => { - console.info(`promise: updateSession success, data = ${JSON.stringify(data)}`); - }) - .catch(error => { - console.error(`promise: updateSession failed, code: ${error.code}, msg: ${error.message}`); - }); - } catch (error) { - console.error(`promise: updateSession input arg invalid, code: ${error.code}, msg: ${error.message}`); - } -} - -async function huksFinish() { - console.log('enter huksFinish'); - options.inData = new Uint8Array(0); - try { - await huks.finishSession(handle, options) - .then ((data) => { - console.info(`promise: finishSession success, data = ${JSON.stringify(data)}`); - }) - .catch(error => { - console.error(`promise: finishSession failed, code: ${error.code}, msg: ${error.message}`); - }); - } catch (error) { - console.error(`promise: finishSession input arg invalid, code: ${error.code}, msg: ${error.message}`); - } -} - -async function huksAbort() { - console.log('enter huksAbort'); - try { - await huks.abortSession(keyAlias, options) - .then ((data) => { - console.info(`promise: abortSession success`); - }) - .catch(error => { - console.error(`promise: abortSession failed, code: ${error.code}, msg: ${error.message}`); - }); - } catch (error) { - console.error(`promise: abortSession input arg invalid, code: ${error.code}, msg: ${error.message}`); - } -} -``` - -## HuksErrorCode(deprecated) - -表示错误码的枚举。 - -**系统能力**：SystemCapability.Security.Huks - -| 名称 | 值 | 说明 | -| -------------------------- | ----- | ---- | -| HUKS_SUCCESS | 0 |表示成功。| -| HUKS_FAILURE | -1 |表示失败。| -| HUKS_ERROR_BAD_STATE | -2 |表示错误的状态。| -| HUKS_ERROR_INVALID_ARGUMENT | -3 |表示无效的数据。| -| HUKS_ERROR_NOT_SUPPORTED | -4 |表示不支持。| -| HUKS_ERROR_NO_PERMISSION | -5 |表示没有许可。| -| HUKS_ERROR_INSUFFICIENT_DATA | -6 |表示数据不足。| -| HUKS_ERROR_BUFFER_TOO_SMALL | -7 |表示缓冲区太小。| -| HUKS_ERROR_INSUFFICIENT_MEMORY | -8 |表示内存不足。| -| HUKS_ERROR_COMMUNICATION_FAILURE | -9 |表示通讯失败。| -| HUKS_ERROR_STORAGE_FAILURE | -10 |表示存储故障。| -| HUKS_ERROR_HARDWARE_FAILURE | -11 |表示硬件故障。| -| HUKS_ERROR_ALREADY_EXISTS | -12 |表示已经存在。| -| HUKS_ERROR_NOT_EXIST | -13 |表示不存在。| -| HUKS_ERROR_NULL_POINTER | -14 |表示空指针。| -| HUKS_ERROR_FILE_SIZE_FAIL | -15 |表示文件大小失败。| -| HUKS_ERROR_READ_FILE_FAIL | -16 |表示读取文件失败。| -| HUKS_ERROR_INVALID_PUBLIC_KEY | -17 |表示无效的公钥。| -| HUKS_ERROR_INVALID_PRIVATE_KEY | -18 |表示无效的私钥。| -| HUKS_ERROR_INVALID_KEY_INFO | -19 |表示无效的密钥信息。| -| HUKS_ERROR_HASH_NOT_EQUAL | -20 |表示哈希不相等。| -| HUKS_ERROR_MALLOC_FAIL | -21 |表示MALLOC 失败。| -| HUKS_ERROR_WRITE_FILE_FAIL | -22 |表示写文件失败。| -| HUKS_ERROR_REMOVE_FILE_FAIL | -23 |表示删除文件失败。| -| HUKS_ERROR_OPEN_FILE_FAIL | -24 |表示打开文件失败。| -| HUKS_ERROR_CLOSE_FILE_FAIL | -25 |表示关闭文件失败。| -| HUKS_ERROR_MAKE_DIR_FAIL | -26 |表示创建目录失败。| -| HUKS_ERROR_INVALID_KEY_FILE | -27 |表示无效的密钥文件。| -| HUKS_ERROR_IPC_MSG_FAIL | -28 |表示IPC 信息失败。| -| HUKS_ERROR_REQUEST_OVERFLOWS | -29 |表示请求溢出。| -| HUKS_ERROR_PARAM_NOT_EXIST | -30 |表示参数不存在。| -| HUKS_ERROR_CRYPTO_ENGINE_ERROR | -31 |表示CRYPTO ENGINE错误。| -| HUKS_ERROR_COMMUNICATION_TIMEOUT | -32 |表示通讯超时。| -| HUKS_ERROR_IPC_INIT_FAIL | -33 |表示IPC 初始化失败。| -| HUKS_ERROR_IPC_DLOPEN_FAIL | -34 |表示IPC DLOPEN 失败。| -| HUKS_ERROR_EFUSE_READ_FAIL | -35 |表示EFUSE 读取失败。| -| HUKS_ERROR_NEW_ROOT_KEY_MATERIAL_EXIST | -36 |表示存在新的根密钥材料。| -| HUKS_ERROR_UPDATE_ROOT_KEY_MATERIAL_FAIL | -37 |表示更新根密钥材料失败。| -| HUKS_ERROR_VERIFICATION_FAILED | -38 |表示验证证书链失败。| -| HUKS_ERROR_GET_USERIAM_SECINFO_FAILED9+ | -40 |表示获取当前用户安全属性信息失败。| -| HUKS_ERROR_GET_USERIAM_AUTHINFO_FAILED9+ | -41 |表示获取当前用户认证信息失败。| -| HUKS_ERROR_USER_AUTH_TYPE_NOT_SUPPORT9+ | -42 |表示不支持当前用户认证类型的访问控制。| -| HUKS_ERROR_KEY_AUTH_FAILED9+ | -43 |表示安全访问控制认证失败。| -| HUKS_ERROR_DEVICE_NO_CREDENTIAL9+ | -44 |表示设备当前未录入凭据。| -| HUKS_ERROR_CHECK_GET_ALG_FAIL | -100 |表示检查获取 ALG 失败。| -| HUKS_ERROR_CHECK_GET_KEY_SIZE_FAIL | -101 |表示检查获取密钥大小失败。| -| HUKS_ERROR_CHECK_GET_PADDING_FAIL | -102 |表示检查获取填充失败。| -| HUKS_ERROR_CHECK_GET_PURPOSE_FAIL | -103 |表示检查获取目的失败。| -| HUKS_ERROR_CHECK_GET_DIGEST_FAIL | -104 |表示检查获取摘要失败。| -| HUKS_ERROR_CHECK_GET_MODE_FAIL | -105 |表示检查获取模式失败。| -| HUKS_ERROR_CHECK_GET_NONCE_FAIL | -106 |表示检查获取随机数失败。| -| HUKS_ERROR_CHECK_GET_AAD_FAIL | -107 |表示检查获取 AAD 失败。| -| HUKS_ERROR_CHECK_GET_IV_FAIL | -108 |表示检查 GET IV 失败。| -| HUKS_ERROR_CHECK_GET_AE_TAG_FAIL | -109 |表示检查获取 AE 标记失败。| -| HUKS_ERROR_CHECK_GET_SALT_FAIL | -110 |表示检查获取SALT失败。| -| HUKS_ERROR_CHECK_GET_ITERATION_FAIL | -111 |表示检查获取迭代失败。| -| HUKS_ERROR_INVALID_ALGORITHM | -112 |表示无效的算法。| -| HUKS_ERROR_INVALID_KEY_SIZE | -113 |表示无效的密钥大小。| -| HUKS_ERROR_INVALID_PADDING | -114 |表示无效的填充。| -| HUKS_ERROR_INVALID_PURPOSE | -115 |表示无效的目的。| -| HUKS_ERROR_INVALID_MODE | -116 |表示无效模式。| -| HUKS_ERROR_INVALID_DIGEST | -117 |表示无效的摘要。| -| HUKS_ERROR_INVALID_SIGNATURE_SIZE | -118 |表示签名大小无效。| -| HUKS_ERROR_INVALID_IV | -119 |表示无效的 IV。| -| HUKS_ERROR_INVALID_AAD | -120 |表示无效的 AAD。| -| HUKS_ERROR_INVALID_NONCE | -121 |表示无效的随机数。| -| HUKS_ERROR_INVALID_AE_TAG | -122 |表示无效的 AE 标签。| -| HUKS_ERROR_INVALID_SALT | -123 |表示无效SALT。| -| HUKS_ERROR_INVALID_ITERATION | -124 |表示无效的迭代。| -| HUKS_ERROR_INVALID_OPERATION | -125 |表示无效操作。| -| HUKS_ERROR_INVALID_WRAPPED_FORMAT9+ | -126 |表示导入加密密钥时，密钥格式错误。| -| HUKS_ERROR_INVALID_USAGE_OF_KEY9+ | -127 |表示导入加密密钥时，密钥用途错误。| -| HUKS_ERROR_INTERNAL_ERROR | -999 |表示内部错误。| -| HUKS_ERROR_UNKNOWN_ERROR | -1000 |表示未知错误。| - -## HuksExceptionErrCode9+ - -表示错误码的枚举以及对应的错误信息， 错误码表示错误类型，错误信息展示错误详情。 - -关于错误码的具体信息，可在[错误码参考文档](../errorcodes/errorcode-huks.md)中查看。 - -**系统能力**：SystemCapability.Security.Huks - -| 名称 | 说明 | 错误码 | -| ---------------------------------------------- | --------------------------- | -------- | -| HUKS_ERR_CODE_PERMISSION_FAIL | 权限错误导致失败。 | 201 | -| HUKS_ERR_CODE_ILLEGAL_ARGUMENT | 参数错误导致失败。 | 401 | -| HUKS_ERR_CODE_NOT_SUPPORTED_API | 不支持的API。 | 801 | -| 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 | 表示密钥用于进行密钥协商。 | +| 名称 | 值 | 说明 | +| ------------------------ | ---- | -------------------------------- | +| 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 @@ -2945,3 +1976,986 @@ async function huksAbort() { | HUKS_TAG_SYMMETRIC_KEY_DATA | HuksTagType.HUKS_TAG_TYPE_BYTES \| 20001 | 预留。 | | HUKS_TAG_ASYMMETRIC_PUBLIC_KEY_DATA | HuksTagType.HUKS_TAG_TYPE_BYTES \| 20002 | 预留。 | | HUKS_TAG_ASYMMETRIC_PRIVATE_KEY_DATA | HuksTagType.HUKS_TAG_TYPE_BYTES \| 20003 | 预留。 | + +## huks.generateKey(deprecated) + +generateKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void + +生成密钥，使用Callback回调异步返回结果。 + +> **说明：** 从API Version 9开始废弃，建议使用[huks.generateKeyItem9+](#huksgeneratekeyitem9)替代。 + +**系统能力**：SystemCapability.Security.Huks + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | +| keyAlias | string | 是 | 别名。 | +| options | [HuksOptions](#huksoptions) | 是 | 用于存放生成key所需TAG。 | +| callback | AsyncCallback\<[HuksResult](#huksresult)> | 是 | 回调函数。返回HUKS_SUCCESS时表示接口使用成功，其余结果请参考HuksResult进行错误码查询。 | + +**示例：** + +```js +/* 以生成RSA512密钥为例 */ +var keyAlias = 'keyAlias'; +var properties = new Array(); +properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_RSA +}; +properties[1] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_RSA_KEY_SIZE_512 +}; +properties[2] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: +huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | +huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT +}; +properties[3] = { + tag: huks.HuksTag.HUKS_TAG_PADDING, + value: huks.HuksKeyPadding.HUKS_PADDING_OAEP +}; +properties[4] = { + tag: huks.HuksTag.HUKS_TAG_DIGEST, + value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256 +}; +var options = { + properties: properties +}; +huks.generateKey(keyAlias, options, function (err, data){}); +``` + +## huks.generateKey(deprecated) + +generateKey(keyAlias: string, options: HuksOptions) : Promise\ + +生成密钥，使用Promise方式异步返回结果。 + +> **说明：** 从API Version 9开始废弃，建议使用[huks.generateKeyItem9+](#huksgeneratekeyitem9-1)替代。 + +**系统能力**：SystemCapability.Security.Huks + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | ------------------------ | +| keyAlias | string | 是 | 密钥别名。 | +| options | [HuksOptions](#huksoptions) | 是 | 用于存放生成key所需TAG。 | + +**返回值**： + +| 类型 | 说明 | +| ----------------------------------- | -------------------------------------------------- | +| Promise\<[HuksResult](#huksresult)> | Promise对象。返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。 | + +**示例：** + +```js +/* 以生成ECC256密钥为例 */ +var keyAlias = 'keyAlias'; +var properties = new Array(); +properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_ECC +}; +properties[1] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_ECC_KEY_SIZE_256 +}; +properties[2] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: +huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_SIGN | +huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_VERIFY +}; +properties[3] = { + tag: huks.HuksTag.HUKS_TAG_DIGEST, + value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256 +}; +var options = { + properties: properties +}; +var result = huks.generateKey(keyAlias, options); +``` + + +## huks.deleteKey(deprecated) + +deleteKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void + +删除密钥，使用Callback回调异步返回结果。 + +> **说明：** 从API Version 9开始废弃，建议使用[huks.deleteKeyItem9+](#huksdeletekeyitem9)替代。 + +**系统能力**：SystemCapability.Security.Huks + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------------------------- | ---- | -------------------------------------------------- | +| keyAlias | string | 是 | 密钥别名，应为生成key时传入的别名。 | +| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | +| callback | AsyncCallback\<[HuksResult](#huksresult)> | 是 | 回调函数。返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。 | + +**示例：** + +```js +/* 此处options选择emptyOptions传空 */ +var keyAlias = 'keyAlias'; +var emptyOptions = { + properties: [] +}; +huks.deleteKey(keyAlias, emptyOptions, function (err, data) {}); +``` + +## huks.deleteKey(deprecated) + +deleteKey(keyAlias: string, options: HuksOptions) : Promise\ + +删除密钥，使用Promise方式异步返回结果。 + +> **说明：** 从API Version 9开始废弃，建议使用[huks.deleteKeyItem9+](#huksdeletekeyitem9-1)替代。 + +**系统能力**：SystemCapability.Security.Huks + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------- | ---- | ----------------------------------------------------- | +| keyAlias | string | 是 | 密钥别名，应为生成key时传入的别名。 | +| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | + +**返回值：** + +| 类型 | 说明 | +| ----------------------------------- | -------------------------------------------------- | +| Promise\<[HuksResult](#huksresult)> | Promise对象。返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。 | + +**示例：** + +```js +/* 此处options选择emptyOptions传空 */ +var keyAlias = 'keyAlias'; +var emptyOptions = { + properties: [] +}; +var result = huks.deleteKey(keyAlias, emptyOptions); +``` + + +## huks.importKey(deprecated) + +importKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void + +导入明文密钥，使用Callback方式回调异步返回结果 。 + +> **说明：** 从API Version 9开始废弃，建议使用[huks.importKeyItem9+](#huksimportkeyitem9)替代。 + +**系统能力**：SystemCapability.Security.Huks + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------ | ---- | ------------------------------------------------- | +| keyAlias | string | 是 | 密钥别名。 | +| options | [HuksOptions](#huksoptions) | 是 | 用于导入时所需TAG和需要导入的密钥。 | +| callback | AsyncCallback\<[HuksResult](#huksresult)> | 是 | 回调函数。返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。 | + +**示例：** + +```js +/* 以导入AES256密钥为例 */ +var plainTextSize32 = makeRandomArr(32); +function makeRandomArr(size) { + var arr = new Uint8Array(size); + for (var i = 0; i < size; i++) { + arr[i] = Math.floor(Math.random() * 10); + } + return arr; +}; +var keyAlias = 'keyAlias'; +var properties = new Array(); +properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_AES +}; +properties[1] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_AES_KEY_SIZE_256 +}; +properties[2] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: +huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT +}; +properties[3] = { + tag: huks.HuksTag.HUKS_TAG_PADDING, + value:huks.HuksKeyPadding.HUKS_PADDING_PKCS7 +}; +properties[4] = { + tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, + value: huks.HuksCipherMode.HUKS_MODE_ECB +}; +var options = { + properties: properties, + inData: plainTextSize32 +}; +huks.importKey(keyAlias, options, function (err, data){}); +``` + +## huks.importKey(deprecated) + +importKey(keyAlias: string, options: HuksOptions) : Promise\ + +导入明文密钥，使用Promise方式异步返回结果。 + +> **说明：** 从API Version 9开始废弃，建议使用[huks.importKeyItem9+](#huksimportkeyitem9-1)替代。 + +**系统能力**：SystemCapability.Security.Huks + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------- | ---- | ------------------------------------ | +| keyAlias | string | 是 | 密钥别名。 | +| options | [HuksOptions](#huksoptions) | 是 | 用于导入时所需TAG和需要导入的密钥。 | + +**返回值：** + +| 类型 | 说明 | +| ----------------------------------- | -------------------------------------------------- | +| Promise\<[HuksResult](#huksresult)> | Promise对象。返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。 | + +**示例：** + +```js +/* 以导入AES128为例 */ +var plainTextSize32 = makeRandomArr(32); + +function makeRandomArr(size) { + var arr = new Uint8Array(size); + for (var i = 0; i < size; i++) { + arr[i] = Math.floor(Math.random() * 10); + } + return arr; +}; + +/*第一步：生成密钥*/ +var keyAlias = 'keyAlias'; +var properties = new Array(); +properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_AES +}; +properties[1] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_AES_KEY_SIZE_128 +}; +properties[2] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT +}; +properties[3] = { + tag: huks.HuksTag.HUKS_TAG_PADDING, + value:huks.HuksKeyPadding.HUKS_PADDING_PKCS7 +}; +properties[4] = { + tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, + value: huks.HuksCipherMode.HUKS_MODE_ECB +}; +var huksoptions = { + properties: properties, + inData: plainTextSize32 +}; +var result = huks.importKey(keyAlias, huksoptions); +``` + + +## huks.exportKey(deprecated) + +exportKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void + +导出密钥，使用Callback方式回调异步返回的结果。 + +> **说明：** 从API Version 9开始废弃，建议使用[huks.exportKeyItem9+](#huksexportkeyitem9)替代。 + +**系统能力**：SystemCapability.Security.Huks + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | +| keyAlias | string | 是 | 密钥别名，应与所用密钥生成时使用的别名相同。 | +| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | +| callback | AsyncCallback\<[HuksResult](#huksresult)> | 是 | 回调函数。返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。outData：返回从密钥中导出的公钥。 | + +**示例：** + +```js +/* 此处options选择emptyOptions来传空 */ +var keyAlias = 'keyAlias'; +var emptyOptions = { + properties: [] +}; +huks.exportKey(keyAlias, emptyOptions, function (err, data){}); +``` + +## huks.exportKey(deprecated) + +exportKey(keyAlias: string, options: HuksOptions) : Promise\ + +导出密钥，使用Promise方式回调异步返回的结果。 + +> **说明：** 从API Version 9开始废弃，建议使用[huks.exportKeyItem9+](#huksexportkeyitem9-1))替代。 + +**系统能力**：SystemCapability.Security.Huks + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------- | ---- | ------------------------------------------------------------ | +| keyAlias | string | 是 | 密钥别名，应与所用密钥生成时使用的别名相同。 | +| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | + +**返回值：** + +| 类型 | 说明 | +| ----------------------------------- | ------------------------------------------------------------ | +| Promise\<[HuksResult](#huksresult)> | Promise对象。返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。outData：返回从密钥中导出的公钥。 | + +**示例：** + +```js +/* 此处options选择emptyOptions来传空 */ +var keyAlias = 'keyAlias'; +var emptyOptions = { + properties: [] +}; +var result = huks.exportKey(keyAlias, emptyOptions); +``` + + +## huks.getKeyProperties(deprecated) + +getKeyProperties(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void + +获取密钥属性，使用Callback回调异步返回结果。 + +> **说明：** 从API Version 9开始废弃，建议使用[huks.getKeyItemProperties9+](#huksgetkeyitemproperties9)替代。 + +**系统能力**：SystemCapability.Security.Huks + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | +| keyAlias | string | 是 | 密钥别名，应与所用密钥生成时使用的别名相同。 | +| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | +| callback | AsyncCallback\<[HuksResult](#huksresult)> | 是 | 回调函数。errorCode：返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。 | + +**示例：** + +```js +/* 此处options选择emptyOptions来传空 */ +var keyAlias = 'keyAlias'; +var emptyOptions = { + properties: [] +}; +huks.getKeyProperties(keyAlias, emptyOptions, function (err, data){}); +``` + +## huks.getKeyProperties(deprecated) + +getKeyProperties(keyAlias: string, options: HuksOptions) : Promise\ + +获取密钥属性，使用Promise回调异步返回结果。 + +> **说明：** 从API Version 9开始废弃，建议使用[huks.getKeyItemProperties9+](#huksgetkeyitemproperties9-1)替代。 + +**系统能力**：SystemCapability.Security.Huks + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------- | ---- | ------------------------------------------------------------ | +| keyAlias | string | 是 | 密钥别名，应与所用密钥生成时使用的别名相同。 | +| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------ | ------------------------------------------------------------ | +| Promise\<[HuksResult](#huksoptions)> | Promise对象。errorCode：返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。properties：返回值为生成密钥时所需参数。 | + +**示例：** + +```js +/* 此处options选择emptyOptions来传空 */ +var keyAlias = 'keyAlias'; +var emptyOptions = { + properties: [] +}; +var result = huks.getKeyProperties(keyAlias, emptyOptions); +``` + + +## huks.isKeyExist(deprecated) + +isKeyExist(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void + +判断密钥是否存在，使用Callback回调异步返回结果 。 + +> **说明：** 从API Version 9开始废弃，建议使用[huks.isKeyItemExist9+](#huksiskeyitemexist9)替代。 + +**系统能力**：SystemCapability.Security.Huks + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------- | ---- | ------------------------------------- | +| keyAlias | string | 是 | 所需查找的密钥的别名。 | +| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | +| callback | AsyncCallback\ | 是 | 回调函数。FALSE代表密钥不存在，TRUE代表密钥存在。 | + +**示例：** + +```js +/* 此处options选择emptyOptions来传空 */ +var keyAlias = 'keyAlias'; +var emptyOptions = { + properties: [] +}; +huks.isKeyExist(keyAlias, emptyOptions, function (err, data){}); +``` + +## huks.isKeyExist(deprecated) + +isKeyExist(keyAlias: string, options: HuksOptions) : Promise\ + +判断密钥是否存在，使用Promise回调异步返回结果 。 + +> **说明：** 从API Version 9开始废弃，建议使用[huks.isKeyItemExist9+](#huksiskeyitemexist9-1)替代。 + +**系统能力**：SystemCapability.Security.Huks + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------- | ---- | -------------------------------- | +| keyAlias | string | 是 | 所需查找的密钥的别名。 | +| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | + +**返回值：** + +| 类型 | 说明 | +| ----------------- | --------------------------------------- | +| Promise\ | Promise对象。FALSE代表密钥不存在，TRUE代表密钥存在。 | + +**示例：** + +```js +/* 此处options选择emptyOptions来传空 */ +var keyAlias = 'keyAlias'; +var emptyOptions = { + properties: [] +}; +var result = huks.isKeyExist(keyAlias, emptyOptions); +``` + +## huks.init(deprecated) + +init(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void + +init操作密钥接口，使用Callback回调异步返回结果。huks.init, huks.update, huks.finish为三段式接口，需要一起使用。 + +> **说明：** 从API Version 9开始废弃，建议使用[huks.initSession9+](#huksinitsession9-1)替代。 + +**系统能力**：SystemCapability.Security.Huks + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------- | ---- | ------------------------------------- | +| keyAlias | string | 是 | Init操作密钥的别名。 | +| options | [HuksOptions](#huksoptions) | 是 | Init操作的参数集合。 | +| callback | AsyncCallback\<[HuksHandle](#hukshandle)> | 是 | 回调函数。将Init操作操作返回的handle添加到密钥管理系统的回调。 | + + +## huks.init(deprecated) + +init(keyAlias: string, options: HuksOptions) : Promise\ + +init操作密钥接口，使用Promise方式异步返回结果。huks.init, huks.update, huks.finish为三段式接口，需要一起使用。 + +> **说明：** 从API Version 9开始废弃，建议使用[huks.initSession9+](#huksinitsession9-1)替代。 + +**系统能力**：SystemCapability.Security.Huks + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------- | ---- | ------------------------------------- | +| keyAlias | string | 是 | Init操作密钥的别名。 | +| options | [HuksOptions](#huksoptions) | 是 | Init参数集合。 | + +**返回值**： + +| 类型 | 说明 | +| ----------------------------------- | -------------------------------------------------- | +| Promise\<[HuksHandle](#hukshandle)> | Promise对象。将Init操作返回的handle添加到密钥管理系统的回调。 | + + +## huks.update(deprecated) + +update(handle: number, options: HuksOptions, callback: AsyncCallback\) : void + +update操作密钥接口，使用Callback回调异步返回结果。huks.init, huks.update, huks.finish为三段式接口，需要一起使用。 + +> **说明：** 从API Version 9开始废弃，建议使用[huks.updateSession9+](#huksupdatesession9)替代。 + +**系统能力**：SystemCapability.Security.Huks + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------------------------- | ---- | -------------------------------------------- | +| handle | number | 是 | Update操作的handle。 | +| options | [HuksOptions](#huksoptions) | 是 | Update的参数集合。 | +| callback | AsyncCallback\<[HuksResult](#huksresult)> | 是 | 回调函数。将Update操作的结果添加到密钥管理系统的回调。 | + +## huks.update(deprecated) + +update(handle: number, options: HuksOptions, token: Uint8Array, callback: AsyncCallback\) : void + +update操作密钥接口，使用Callback回调异步返回结果。huks.init, huks.update, huks.finish为三段式接口，需要一起使用。 + +> **说明：** 从API Version 9开始废弃，建议使用[huks.updateSession9+](#huksupdatesession9-1)替代。 + +**系统能力**： SystemCapability.Security.Huks + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------------------------- | ---- | -------------------------------------------- | +| handle | number | 是 | Update操作的handle。 | +| token | Uint8Array | 否 | Update操作的token。 | +| options | [HuksOptions](#huksoptions) | 是 | Update操作的参数集合。 | +| callback | AsyncCallback\<[HuksResult](#huksresult)> | 是 | 回调函数。将Update操作的结果添加到密钥管理系统的回调。 | + +## huks.update(deprecated) + +update(handle: number, options: HuksOptions, token?: Uint8Array) : Promise\ + +update操作密钥接口，使用Promise方式异步返回结果。huks.init, huks.update, huks.finish为三段式接口，需要一起使用。 + +> **说明：** 从API Version 9开始废弃，建议使用[huks.updateSession9+](#huksupdatesession9-2)替代。 + +**系统能力**： SystemCapability.Security.Huks + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ----------------------------------- | ---- | -------------------------------------------- | +| handle | number | 是 | Update操作的handle。 | +| token | Uint8Array | 否 | Update操作的token。 | +| options | [HuksOptions](#huksoptions) | 是 | Update操作的参数集合。 | + +**返回值**： + +| 类型 | 说明 | +| ----------------------------------- | -------------------------------------------------- | +| Promise\<[HuksResult](#huksresult)> | Promise对象。将Update操作的结果添加到密钥管理系统的回调。 | + + +## huks.finish(deprecated) + +finish(handle: number, options: HuksOptions, callback: AsyncCallback\) : void + +finish操作密钥接口，使用Callback回调异步返回结果。huks.init, huks.update, huks.finish为三段式接口，需要一起使用。 + +> **说明：** 从API Version 9开始废弃，建议使用[huks.finishSession9+](#huksfinishsession9)替代。 + +**系统能力**：SystemCapability.Security.Huks + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------- | ---- | ------------------------------------- | +| handle | number | 是 | Finish操作的handle。 | +| options | [HuksOptions](#huksoptions) | 是 | Finish的参数集合。 | +| callback | AsyncCallback\<[HuksResult](#huksresult)> | 是 | 回调函数。将Finish操作的结果添加到密钥管理系统的回调。 | + + +## huks.finish(deprecated) + +finish(handle: number, options: HuksOptions) : Promise\ + +finish操作密钥接口，使用Promise方式异步返回结果。huks.init, huks.update, huks.finish为三段式接口，需要一起使用。 + +> **说明：** 从API Version 9开始废弃，建议使用[huks.updateSession9+](#huksfinishsession9-1)替代。 + +**系统能力**：SystemCapability.Security.Huks + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------- | ---- | ------------------------------------- | +| handle | number | 是 | Finish操作的handle。 | +| options | [HuksOptions](#huksoptions) | 是 | Finish操作的参数集合。 | + +**返回值**： + +| 类型 | 说明 | +| ----------------------------------- | -------------------------------------------------- | +| Promise\<[HuksResult](#huksresult)> | Promise对象，用于获取异步返回结果。 | + + +## huks.abort(deprecated) + +abort(handle: number, options: HuksOptions, callback: AsyncCallback\) : void + +abort操作密钥接口，使用Callback回调异步返回结果。 + +> **说明：** 从API Version 9开始废弃，建议使用[huks.abortSession9+](#huksabortsession9)替代。 + +**系统能力**：SystemCapability.Security.Huks + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------- | ---- | ------------------------------------- | +| handle | number | 是 | Abort操作的handle。 | +| options | [HuksOptions](#huksoptions) | 是 | Abort操作的参数集合。 | +| callback | AsyncCallback\<[HuksResult](#huksresult)> | 是 | 回调函数。将Abort操作的结果添加到密钥管理系统的回调。 | + +**示例：** + +```js +/* huks.init, huks.update, huks.finish为三段式接口，需要一起使用，当huks.init和huks.update + * 以及huks.finish操作中的任一阶段发生错误时，都需要调用huks.abort来终止密钥的使用。 + * + * 以下以RSA1024密钥的callback操作使用为例 + */ +var keyalias = "HuksDemoRSA"; +var properties = new Array(); +var options = { + properties: properties, + inData: new Uint8Array(0) +}; +var handle; +var resultMessage = ""; +async function generateKey() { + properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_RSA + }; + properties[1] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_RSA_KEY_SIZE_1024 + }; + properties[2] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT + }; + properties[3] = { + tag: huks.HuksTag.HUKS_TAG_PADDING, + value: huks.HuksKeyPadding.HUKS_PADDING_OAEP + }; + properties[4] = { + tag: huks.HuksTag.HUKS_TAG_DIGEST, + value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256 + }; + huks.generateKey(keyalias, options); +} +function stringToUint8Array(str) { + var arr = []; + for (var i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + var tmpUint8Array = new Uint8Array(arr); + return tmpUint8Array; +} +async function huksInit() { + await huks.init(keyalias, options).then((data) => { + console.log(`test init data: ${JSON.stringify(data)}`); + handle = data.handle; + }).catch((err) => { + console.log("test init err information: " + JSON.stringify(err)) + }) +} +async function huksUpdate() { + options.inData = stringToUint8Array("huksHmacTest"); + await huks.update(handle, options).then((data) => { + if (data.errorCode === 0) { + resultMessage += "update success!"; + } else { + resultMessage += "update fail!"; + } + }); + console.log(resultMessage); +} +function huksFinish() { + options.inData = stringToUint8Array("HuksDemoHMAC"); + huks.finish(handle, options).then((data) => { + if (data.errorCode === 0) { + resultMessage = "finish success!"; + } else { + resultMessage = "finish fail errorCode: " + data.errorCode; + } + }).catch((err) => { + resultMessage = "finish fail， catch errorMessage:" + JSON.stringify(err) + }); + console.log(resultMessage); +} +async function huksAbort() { + huks.abort(handle, options).then((data) => { + if (data.errorCode === 0) { + resultMessage = "abort success!"; + } else { + resultMessage = "abort fail errorCode: " + data.errorCode; + } + }).catch((err) => { + resultMessage = "abort fail， catch errorMessage:" + JSON.stringify(err) + }); + console.log(resultMessage); +} +``` + +## huks.abort(deprecated) + +abort(handle: number, options: HuksOptions) : Promise\; + +abort操作密钥接口，使用Promise方式异步返回结果。 + +> **说明：** 从API Version 9开始废弃，建议使用[huks.abortSession9+](#huksabortsession9-1)替代。 + +**系统能力**：SystemCapability.Security.Huks + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------- | ---- | ------------------------------------- | +| handle | number | 是 | Abort操作的handle。 | +| options | [HuksOptions](#huksoptions) | 是 | Abort操作的参数集合。 | + +**返回值**： + +| 类型 | 说明 | +| ----------------------------------- | -------------------------------------------------- | +| Promise\<[HuksResult](#huksresult)> | Promise对象。将Abort操作的结果添加到密钥管理系统的回调。 | + +**示例：** + +```js +/* huks.init, huks.update, huks.finish为三段式接口，需要一起使用，当huks.init和huks.update + * 以及huks.finish操作中的任一阶段发生错误时，都需要调用huks.abort来终止密钥的使用。 + * + * 以下以RSA1024密钥的promise操作使用为例 + */ +var keyalias = "HuksDemoRSA"; +var properties = new Array(); +var options = { + properties: properties, + inData: new Uint8Array(0) +}; +var handle; +var resultMessage = ""; +function stringToUint8Array(str) { + var arr = []; + for (var i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + var tmpUint8Array = new Uint8Array(arr); + return tmpUint8Array; +} + +async function generateKey() { + properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_RSA + }; + properties[1] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_RSA_KEY_SIZE_1024 + }; + properties[2] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT + }; + properties[3] = { + tag: huks.HuksTag.HUKS_TAG_PADDING, + value: huks.HuksKeyPadding.HUKS_PADDING_OAEP + }; + properties[4] = { + tag: huks.HuksTag.HUKS_TAG_DIGEST, + value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256 + }; + huks.generateKey(keyalias, options, function (err, data) { }); +} +async function huksInit() { + return new Promise((resolve, reject) => { + huks.init(keyalias, options, async function (err, data) { + if (data.errorCode === 0) { + resultMessage = "init success!" + handle = data.handle; + } else { + resultMessage = "init fail errorCode: " + data.errorCode + } + }); + }); +} + +async function huksUpdate() { + options.inData = stringToUint8Array("huksHmacTest"); + new Promise((resolve, reject) => { + huks.update(handle, options, function (err, data) { + if (data.errorCode === 0) { + resultMessage += "update success!"; + } else { + resultMessage += "update fail!"; + } + }); + }); + console.log(resultMessage); + +} + +async function huksFinish() { + options.inData = stringToUint8Array("0"); + new Promise((resolve, reject) => { + huks.finish(handle, options, function (err, data) { + if (data.errorCode === 0) { + resultMessage = "finish success!"; + } else { + resultMessage = "finish fail errorCode: " + data.errorCode; + } + }); + }); +} + +function huksAbort() { + new Promise((resolve, reject) => { + huks.abort(handle, options, function (err, data) { + console.log(`Huks_Demo hmac huksAbort1 data ${JSON.stringify(data)}`); + console.log(`Huks_Demo hmac huksAbort1 err ${JSON.stringify(err)}`); + }); + }); +} +``` + + +## HuksHandle(deprecated) + +huks Handle结构体。 + +**系统能力**：SystemCapability.Security.Huks + +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | ---------------- | ---- | -------- | +| errorCode | number | 是 | 表示错误码。 | +| handle | number | 是 | 表示handle值。 | +| token | Uint8Array | 否 | 表示[init](#huksinit)操作之后获取到的challenge信息。 | + + +## HuksResult(deprecated) + +调用接口返回的result。 + +**系统能力**：SystemCapability.Security.Huks + + + +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | ------------------------------- | ---- | ---------------- | +| errorCode | number | 是 | 表示错误码。 | +| outData | Uint8Array | 否 | 表示输出数据。 | +| properties | Array\<[HuksParam](#huksparam)> | 否 | 表示属性信息。 | +| certChains | Array\ | 否 | 表示证书链数据。 | + + +## HuksErrorCode(deprecated) + +表示错误码的枚举。 + +**系统能力**：SystemCapability.Security.Huks + +| 名称 | 值 | 说明 | +| -------------------------- | ----- | ---- | +| HUKS_SUCCESS | 0 |表示成功。| +| HUKS_FAILURE | -1 |表示失败。| +| HUKS_ERROR_BAD_STATE | -2 |表示错误的状态。| +| HUKS_ERROR_INVALID_ARGUMENT | -3 |表示无效的数据。| +| HUKS_ERROR_NOT_SUPPORTED | -4 |表示不支持。| +| HUKS_ERROR_NO_PERMISSION | -5 |表示没有许可。| +| HUKS_ERROR_INSUFFICIENT_DATA | -6 |表示数据不足。| +| HUKS_ERROR_BUFFER_TOO_SMALL | -7 |表示缓冲区太小。| +| HUKS_ERROR_INSUFFICIENT_MEMORY | -8 |表示内存不足。| +| HUKS_ERROR_COMMUNICATION_FAILURE | -9 |表示通讯失败。| +| HUKS_ERROR_STORAGE_FAILURE | -10 |表示存储故障。| +| HUKS_ERROR_HARDWARE_FAILURE | -11 |表示硬件故障。| +| HUKS_ERROR_ALREADY_EXISTS | -12 |表示已经存在。| +| HUKS_ERROR_NOT_EXIST | -13 |表示不存在。| +| HUKS_ERROR_NULL_POINTER | -14 |表示空指针。| +| HUKS_ERROR_FILE_SIZE_FAIL | -15 |表示文件大小失败。| +| HUKS_ERROR_READ_FILE_FAIL | -16 |表示读取文件失败。| +| HUKS_ERROR_INVALID_PUBLIC_KEY | -17 |表示无效的公钥。| +| HUKS_ERROR_INVALID_PRIVATE_KEY | -18 |表示无效的私钥。| +| HUKS_ERROR_INVALID_KEY_INFO | -19 |表示无效的密钥信息。| +| HUKS_ERROR_HASH_NOT_EQUAL | -20 |表示哈希不相等。| +| HUKS_ERROR_MALLOC_FAIL | -21 |表示MALLOC 失败。| +| HUKS_ERROR_WRITE_FILE_FAIL | -22 |表示写文件失败。| +| HUKS_ERROR_REMOVE_FILE_FAIL | -23 |表示删除文件失败。| +| HUKS_ERROR_OPEN_FILE_FAIL | -24 |表示打开文件失败。| +| HUKS_ERROR_CLOSE_FILE_FAIL | -25 |表示关闭文件失败。| +| HUKS_ERROR_MAKE_DIR_FAIL | -26 |表示创建目录失败。| +| HUKS_ERROR_INVALID_KEY_FILE | -27 |表示无效的密钥文件。| +| HUKS_ERROR_IPC_MSG_FAIL | -28 |表示IPC 信息失败。| +| HUKS_ERROR_REQUEST_OVERFLOWS | -29 |表示请求溢出。| +| HUKS_ERROR_PARAM_NOT_EXIST | -30 |表示参数不存在。| +| HUKS_ERROR_CRYPTO_ENGINE_ERROR | -31 |表示CRYPTO ENGINE错误。| +| HUKS_ERROR_COMMUNICATION_TIMEOUT | -32 |表示通讯超时。| +| HUKS_ERROR_IPC_INIT_FAIL | -33 |表示IPC 初始化失败。| +| HUKS_ERROR_IPC_DLOPEN_FAIL | -34 |表示IPC DLOPEN 失败。| +| HUKS_ERROR_EFUSE_READ_FAIL | -35 |表示EFUSE 读取失败。| +| HUKS_ERROR_NEW_ROOT_KEY_MATERIAL_EXIST | -36 |表示存在新的根密钥材料。| +| HUKS_ERROR_UPDATE_ROOT_KEY_MATERIAL_FAIL | -37 |表示更新根密钥材料失败。| +| HUKS_ERROR_VERIFICATION_FAILED | -38 |表示验证证书链失败。| +| HUKS_ERROR_GET_USERIAM_SECINFO_FAILED9+ | -40 |表示获取当前用户安全属性信息失败。| +| HUKS_ERROR_GET_USERIAM_AUTHINFO_FAILED9+ | -41 |表示获取当前用户认证信息失败。| +| HUKS_ERROR_USER_AUTH_TYPE_NOT_SUPPORT9+ | -42 |表示不支持当前用户认证类型的访问控制。| +| HUKS_ERROR_KEY_AUTH_FAILED9+ | -43 |表示安全访问控制认证失败。| +| HUKS_ERROR_DEVICE_NO_CREDENTIAL9+ | -44 |表示设备当前未录入凭据。| +| HUKS_ERROR_CHECK_GET_ALG_FAIL | -100 |表示检查获取 ALG 失败。| +| HUKS_ERROR_CHECK_GET_KEY_SIZE_FAIL | -101 |表示检查获取密钥大小失败。| +| HUKS_ERROR_CHECK_GET_PADDING_FAIL | -102 |表示检查获取填充失败。| +| HUKS_ERROR_CHECK_GET_PURPOSE_FAIL | -103 |表示检查获取目的失败。| +| HUKS_ERROR_CHECK_GET_DIGEST_FAIL | -104 |表示检查获取摘要失败。| +| HUKS_ERROR_CHECK_GET_MODE_FAIL | -105 |表示检查获取模式失败。| +| HUKS_ERROR_CHECK_GET_NONCE_FAIL | -106 |表示检查获取随机数失败。| +| HUKS_ERROR_CHECK_GET_AAD_FAIL | -107 |表示检查获取 AAD 失败。| +| HUKS_ERROR_CHECK_GET_IV_FAIL | -108 |表示检查 GET IV 失败。| +| HUKS_ERROR_CHECK_GET_AE_TAG_FAIL | -109 |表示检查获取 AE 标记失败。| +| HUKS_ERROR_CHECK_GET_SALT_FAIL | -110 |表示检查获取SALT失败。| +| HUKS_ERROR_CHECK_GET_ITERATION_FAIL | -111 |表示检查获取迭代失败。| +| HUKS_ERROR_INVALID_ALGORITHM | -112 |表示无效的算法。| +| HUKS_ERROR_INVALID_KEY_SIZE | -113 |表示无效的密钥大小。| +| HUKS_ERROR_INVALID_PADDING | -114 |表示无效的填充。| +| HUKS_ERROR_INVALID_PURPOSE | -115 |表示无效的目的。| +| HUKS_ERROR_INVALID_MODE | -116 |表示无效模式。| +| HUKS_ERROR_INVALID_DIGEST | -117 |表示无效的摘要。| +| HUKS_ERROR_INVALID_SIGNATURE_SIZE | -118 |表示签名大小无效。| +| HUKS_ERROR_INVALID_IV | -119 |表示无效的 IV。| +| HUKS_ERROR_INVALID_AAD | -120 |表示无效的 AAD。| +| HUKS_ERROR_INVALID_NONCE | -121 |表示无效的随机数。| +| HUKS_ERROR_INVALID_AE_TAG | -122 |表示无效的 AE 标签。| +| HUKS_ERROR_INVALID_SALT | -123 |表示无效SALT。| +| HUKS_ERROR_INVALID_ITERATION | -124 |表示无效的迭代。| +| HUKS_ERROR_INVALID_OPERATION | -125 |表示无效操作。| +| HUKS_ERROR_INVALID_WRAPPED_FORMAT9+ | -126 |表示导入加密密钥时，密钥格式错误。| +| HUKS_ERROR_INVALID_USAGE_OF_KEY9+ | -127 |表示导入加密密钥时，密钥用途错误。| +| HUKS_ERROR_INTERNAL_ERROR | -999 |表示内部错误。| +| HUKS_ERROR_UNKNOWN_ERROR | -1000 |表示未知错误。| \ No newline at end of file