!5016 huks import wrapped key API

Merge pull request !5016 from HaixiangW/master

zh-cn/application-dev/reference/apis/js-apis-huks.md

@@ -85,6 +85,8 @@ import huks from '@ohos.security.huks'
 | HUKS_ERROR_INVALID_SALT | -123  |表示无效SALT。|
 | HUKS_ERROR_INVALID_ITERATION | -124  |表示无效的迭代。|
 | HUKS_ERROR_INVALID_OPERATION | -125  |表示无效操作。|
+| HUKS_ERROR_INVALID_WRAPPED_FORMAT<sup>9+</sup> | -126 |表示导入加密密钥时，密钥格式错误。|
+| HUKS_ERROR_INVALID_USAGE_OF_KEY<sup>9+</sup> | -127 |表示导入加密密钥时，密钥用途错误。|
 | HUKS_ERROR_INTERNAL_ERROR | -999  |表示内部错误。|
 | HUKS_ERROR_UNKNOWN_ERROR | -1000 |表示未知错误。|
 
@@ -117,6 +119,7 @@ import huks from '@ohos.security.huks'
 | ---------------------- | ---- | ---------------------------------------- |
 | HUKS_DIGEST_NONE       | 0   | 表示无摘要算法。 |
 | HUKS_DIGEST_MD5        | 1    | 表示MD5摘要算法。 |
+| HUKS_DIGEST_SM3<sup>9+</sup> | 2 | 表示SM3摘要算法。 |
 | HUKS_DIGEST_SHA1       | 10   | 表示SHA1摘要算法。 |
 | HUKS_DIGEST_SHA224 | 11   | 表示SHA224摘要算法。 |
 | HUKS_DIGEST_SHA256 | 12  | 表示SHA256摘要算法。 |
@@ -160,7 +163,7 @@ import huks from '@ohos.security.huks'
 **系统能力**：以下各项对应的系统能力均为SystemCapability.Security.Huks。
 
 | 名称                               | 值   | 说明                                       |
-| ---------------------------- | ---- | ------------------------------------------ |
+| ---------------------------------- | ---- | ------------------------------------------ |
 | HUKS_RSA_KEY_SIZE_512              | 512  | 表示使用RSA算法的密钥长度为512bit。        |
 | HUKS_RSA_KEY_SIZE_768              | 768  | 表示使用RSA算法的密钥长度为768bit。        |
 | HUKS_RSA_KEY_SIZE_1024             | 1024 | 表示使用RSA算法的密钥长度为1024bit。       |
@@ -179,6 +182,8 @@ import huks from '@ohos.security.huks'
 | HUKS_DH_KEY_SIZE_2048              | 2048 | 表示使用DH算法的密钥长度为2048bit。        |
 | HUKS_DH_KEY_SIZE_3072              | 3072 | 表示使用DH算法的密钥长度为3072bit。        |
 | HUKS_DH_KEY_SIZE_4096              | 4096 | 表示使用DH算法的密钥长度为4096bit。        |
+| HUKS_SM2_KEY_SIZE_256<sup>9+</sup> | 256  | 表示SM2算法的密钥长度为256bit。            |
+| HUKS_SM4_KEY_SIZE_128<sup>9+</sup> | 128  | 表示SM4算法的密钥长度为128bit。            |
 
 ## HuksKeyAlg
 
@@ -187,7 +192,7 @@ import huks from '@ohos.security.huks'
 **系统能力**：以下各项对应的系统能力均为SystemCapability.Security.Huks。
 
 | 名称                      | 值   | 说明                  |
-| ---------------- | ---- | --------------------- |
+| ------------------------- | ---- | --------------------- |
 | HUKS_ALG_RSA              | 1    | 表示使用RSA算法。     |
 | HUKS_ALG_ECC              | 2    | 表示使用ECC算法。     |
 | HUKS_ALG_DSA              | 3    | 表示使用DSA算法。     |
@@ -199,6 +204,9 @@ import huks from '@ohos.security.huks'
 | HUKS_ALG_X25519           | 101  | 表示使用X25519算法。  |
 | HUKS_ALG_ED25519          | 102  | 表示使用ED25519算法。 |
 | HUKS_ALG_DH               | 103  | 表示使用DH算法。      |
+| HUKS_ALG_SM2<sup>9+</sup> | 150  | 表示使用SM2算法。     |
+| HUKS_ALG_SM3<sup>9+</sup> | 151  | 表示使用SM3算法。     |
+| HUKS_ALG_SM4<sup>9+</sup> | 152  | 表示使用SM4算法。     |
 
 ## HuksKeyGenerateType
 
@@ -247,6 +255,29 @@ import huks from '@ohos.security.huks'
 | HUKS_SEND_TYPE_ASYNC | 0    | 表示异步发送TAG。 |
 | HUKS_SEND_TYPE_SYNC  | 1    | 表示同步发送TAG。 |
 
+## HuksUnwrapSuite<sup>9+</sup>
+
+表示导入加密密钥的算法套件。
+
+**系统能力**：以下各项对应的系统能力均为SystemCapability.Security.Huks。
+
+| 名称                                           | 值   | 说明                                                  |
+| ---------------------------------------------- | ---- | ----------------------------------------------------- |
+| HUKS_UNWRAP_SUITE_X25519_AES_256_GCM_NOPADDING | 1    | 导入加密密钥时，X25519密钥协商后使用AES-256 GCM加密。 |
+| HUKS_UNWRAP_SUITE_ECDH_AES_256_GCM_NOPADDING   | 2    | 导入加密密钥时，ECDH密钥协商后使用AES-256 GCM加密。   |
+
+##  HuksImportKeyType<sup>9+</sup>
+
+表示导入密钥的密钥类型，默认为导入公钥，导入对称密钥时不需要该字段。
+
+**系统能力**：以下各项对应的系统能力均为SystemCapability.Security.Huks。
+
+| 名称                      | 值   | 说明                           |
+| ------------------------- | ---- | ------------------------------ |
+| HUKS_KEY_TYPE_PUBLIC_KEY  | 0    | 表示导入的密钥类型为公钥。     |
+| HUKS_KEY_TYPE_PRIVATE_KEY | 1    | 表示导入的密钥类型为私钥。     |
+| HUKS_KEY_TYPE_KEY_PAIR    | 2    | 表示导入的密钥类型为公私钥对。 |
+
 ## HuksTagType
 
 表示Tag的数据类型。
@@ -270,7 +301,7 @@ import huks from '@ohos.security.huks'
 **系统能力**：以下各项对应的系统能力均为SystemCapability.Security.Huks。
 
 | 名称                                         | 值                                       | 说明                                   |
-| -------------------------------------- | ---------------------------------------- | -------------------------------------- |
+| -------------------------------------------- | ---------------------------------------- | -------------------------------------- |
 | HUKS_TAG_INVALID                             | HuksTagType.HUKS_TAG_TYPE_INVALID \| 0   | 表示非法的Tag。                        |
 | HUKS_TAG_ALGORITHM                           | HUKS_TAG_TYPE_UINT \| 1                  | 表示算法的Tag。                        |
 | HUKS_TAG_PURPOSE                             | HuksTagType.HUKS_TAG_TYPE_UINT \| 2      | 表示密钥用途的Tag。                    |
@@ -296,6 +327,8 @@ import huks from '@ohos.security.huks'
 | HUKS_TAG_AGREE_PUBLIC_KEY                    | HuksTagType.HUKS_TAG_TYPE_BYTES \| 22    | 表示密钥协商时的公钥。                 |
 | HUKS_TAG_KEY_ALIAS                           | HuksTagType.HUKS_TAG_TYPE_BYTES \| 23    | 表示密钥别名。                         |
 | HUKS_TAG_DERIVE_KEY_SIZE                     | HuksTagType.HUKS_TAG_TYPE_UINT \| 24     | 表示派生密钥的大小。                   |
+| HUKS_TAG_IMPORT_KEY_TYPE<sup>9+</sup>        | HuksTagType.HUKS_TAG_TYPE_UINT \| 25     | 表示导入的密钥类型                     |
+| HUKS_TAG_UNWRAP_ALGORITHM_SUITE<sup>9+</sup> | HuksTagType.HUKS_TAG_TYPE_UINT \| 26     | 表示导入加密密钥的套件                 |
 | HUKS_TAG_ACTIVE_DATETIME                     | HuksTagType.HUKS_TAG_TYPE_ULONG \| 201   | 预留。                                 |
 | HUKS_TAG_ORIGINATION_EXPIRE_DATETIME         | HuksTagType.HUKS_TAG_TYPE_ULONG \| 202   | 预留。                                 |
 | HUKS_TAG_USAGE_EXPIRE_DATETIME               | HuksTagType.HUKS_TAG_TYPE_ULONG \| 203   | 预留。                                 |
@@ -542,7 +575,7 @@ var result = huks.getSdkVersion(emptyOptions);
 
 importKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback\<HuksResult>) : void
 
-导入密钥，使用Callback方式回调异步返回结果 。
+导入明文密钥，使用Callback方式回调异步返回结果 。
 
 **系统能力**：以下各项对应的系统能力均为SystemCapability.Security.Huks。
 
@@ -600,7 +633,7 @@ huks.importKey(keyAlias, options, function (err, data){});
 
 importKey(keyAlias: string, options: HuksOptions) : Promise\<HuksResult>
 
-导入密钥，使用Promise方式异步返回结果。
+导入明文密钥，使用Promise方式异步返回结果。
 
 **系统能力**：以下各项对应的系统能力均为SystemCapability.Security.Huks。
 
@@ -661,6 +694,230 @@ var huksoptions = {
 var result = huks.importKey(keyAlias, huksoptions);
 ```
 
+## huks.importWrappedKey<sup>9+</sup>
+
+importWrappedKey(keyAlias: string, wrappingKeyAlias: string, options: HuksOptions, callback: AsyncCallback\<HuksResult>) : void
+
+导入加密密钥，使用Callback方式回调异步返回结果 。
+
+**系统能力**：以下各项对应的系统能力均为SystemCapability.Security.Huks。
+
+**参数：**
+
+| 参数名           | 类型                                      | 必填 | 说明                                               |
+| ---------------- | ----------------------------------------- | ---- | -------------------------------------------------- |
+| keyAlias         | string                                    | 是   | 密钥别名，存放待导入密钥的别名。                   |
+| wrappingKeyAlias | string                                    | 是   | 密钥别名，对应密钥用于解密加密的密钥数据。         |
+| options          | [HuksOptions](#huksoptions)               | 是   | 用于导入时所需TAG和需要导入的加密的密钥数据。      |
+| callback         | AsyncCallback\<[HuksResult](#huksresult)> | 是   | 返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。 |
+
+**示例：**
+
+```js
+var exportWrappingKey;
+var alias1 = "importAlias";
+var alias2 = "wrappingKeyAlias";
+
+async function TestGenFunc(alias, options) {
+  await genKey(alias, options)
+    .then((data) => {
+      console.log(`test genKey data: ${JSON.stringify(data)}`);
+    })
+    .catch((err) => {
+      console.log('test genKey err information: ' + JSON.stringify(err));
+    });
+}
+
+function genKey(alias, options) {
+  return new Promise((resolve, reject) => {
+    huks.generateKey(alias, options, function (err, data) {
+      console.log(`test genKey data: ${JSON.stringify(data)}`);
+      if (err.code !== 0) {
+        console.log('test genKey err information: ' + JSON.stringify(err));
+        reject(err);
+      } else {
+        resolve(data);
+      }
+    });
+  });
+}
+
+async function TestExportFunc(alias, options) {
+  await exportKey(alias, options)
+    .then((data) => {
+      console.log(`test exportKey data: ${JSON.stringify(data)}`);
+    })
+    .catch((err) => {
+      console.log('test exportKey err information: ' + JSON.stringify(err));
+    });
+}
+
+function exportKey(alias, options) {
+  return new Promise((resolve, reject) => {
+    huks.exportKey(alias, options, function (err, data) {
+      console.log(`test exportKey data: ${JSON.stringify(data)}`);
+      if (err.code !== 0) {
+        console.log('test exportKey err information: ' + JSON.stringify(err));
+        reject(err);
+      } else {
+        exportWrappingKey = data.outData;
+        resolve(data);
+      }
+    });
+  });
+}
+
+async function TestImportWrappedFunc(alias, wrappingAlias, options) {
+  await importWrappedKey(alias, wrappingAlias, options)
+    .then((data) => {
+      console.log(`TestImportWrappedFunc data: ${JSON.stringify(data)}`);
+    })
+    .catch((err) => {
+      console.log('test importWrappedKey err information: ' + JSON.stringify(err));
+    });
+}
+
+function importWrappedKey(alias, wrappingAlias, options) {
+  return new Promise((resolve, reject) => {
+    huks.importWrappedKey(alias, wrappingAlias, options, function (err, data) {
+      console.log(`importWrappedKey data: ${JSON.stringify(data)}`);
+      if (err.code !== 0) {
+        console.log('importWrappedKey err information: ' + JSON.stringify(err));
+        reject(err);
+      } else {
+        resolve(data);
+      }
+    });
+  });
+}
+
+async function TestImportWrappedKeyFunc(
+  alias,
+  wrappingAlias,
+  genOptions,
+  importOptions
+) {
+    await TestGenFunc(wrappingAlias, genOptions);
+    await TestExportFunc(wrappingAlias, genOptions);
+
+    /* 以下操作不需要调用HUKS接口，此处不给出具体实现。
+     * 假设待导入的密钥为keyA
+     * 1.生成ECC公私钥keyB，公钥为keyB_pub, 私钥为keyB_pri
+     * 2.使用keyB_pri和wrappingAlias密钥中获取的公钥进行密钥协商，协商出共享密钥share_key
+     * 3.随机生成密钥kek，用于加密keyA，采用AES-GCM加密，加密过程中需要记录：nonce1/aad1/加密后的密文keyA_enc/加密后的tag1。
+     * 4.使用share_key加密kek，采用AES-GCM加密，加密过程中需要记录：nonce2/aad2/加密后的密文kek_enc/加密后的tag2。
+     * 5.拼接importOptions.inData字段，满足以下格式:
+     * keyB_pub的长度（4字节） + keyB_pub的数据 + aad2的长度（4字节） + aad2的数据 +
+     * nonce2的长度（4字节）   + nonce2的数据   + tag2的长度（4字节） + tag2的数据 +
+     * kek_enc的长度（4字节）  + kek_enc的数据  + aad1的长度（4字节） + aad1的数据 +
+     * nonce1的长度（4字节）   + nonce1的数据   + tag1的长度（4字节） + tag1的数据 +
+     * keyA长度占用的内存长度（4字节）  + keyA的长度     + keyA_enc的长度（4字节） + keyA_enc的数据
+     */
+    var inputKey = new Uint8Array([0x02, 0x00, 0x00, 0x00]);
+    importOptions.inData = inputKey;
+    await TestImportWrappedFunc(alias, wrappingAlias, importOptions);
+}
+
+function makeGenerateOptions() {
+  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_UNWRAP
+  };
+  properties[3] = {
+    tag: huks.HuksTag.HUKS_TAG_DIGEST,
+    value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256
+  };
+  var options = {
+    properties: properties
+  };
+  return options;
+};
+
+function makeImportOptions() {
+  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_BLOCK_MODE,
+    value: huks.HuksCipherMode.HUKS_MODE_CBC
+  };
+  properties[4] = {
+    tag: huks.HuksTag.HUKS_TAG_UNWRAP_ALGORITHM_SUITE,
+    value: huks.HuksUnwrapSuite.HUKS_UNWRAP_SUITE_ECDH_AES_256_GCM_NOPADDING
+  };
+  var options = {
+    properties: properties
+  };
+  return options;
+};
+
+function huksImportWrappedKey() {
+  var genOptions = makeGenerateOptions();
+  var importOptions = makeImportOptions();
+  TestImportWrappedKeyFunc(
+    alias1,
+    alias2,
+    genOptions,
+    importOptions
+  );
+}
+```
+
+## huks.importWrappedKey<sup>9+</sup>
+
+importWrappedKey(keyAlias: string, wrappingKeyAlias: string, options: HuksOptions) : Promise\<HuksResult>
+
+导入加密密钥，使用Promise方式异步返回结果。
+
+**系统能力**：以下各项对应的系统能力均为SystemCapability.Security.Huks。
+
+**参数：**
+
+| 参数名           | 类型                        | 必填 | 说明                                          |
+| ---------------- | --------------------------- | ---- | --------------------------------------------- |
+| keyAlias         | string                      | 是   | 密钥别名，存放待导入密钥的别名。              |
+| wrappingKeyAlias | string                      | 是   | 密钥别名，对应密钥用于解密加密的密钥数据。    |
+| options          | [HuksOptions](#huksoptions) | 是   | 用于导入时所需TAG和需要导入的加密的密钥数据。 |
+
+**返回值：**
+
+| 类型                                | 说明                                               |
+| ----------------------------------- | -------------------------------------------------- |
+| Promise\<[HuksResult](#huksresult)> | 返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。 |
+
+**示例：**
+
+```js
+/* 处理流程与callback类似，主要差异点为如下函数： */
+async function TestImportWrappedFunc(alias, wrappingAlias, options) {
+  var result = await huks.importWrappedKey(alias, wrappingAlias, options);
+  if (result.errorCode === 0) {
+    console.log('test importWrappedKey success');
+  } else {
+    console.log('test importWrappedKey fail');
+  }
+}
+```
+
 ## huks.exportKey
 
 exportKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback\<HuksResult>) : void