通用密钥库系统

说明
开发前请熟悉鸿蒙开发指导文档：[gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md]
本模块首批接口从APIversion 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

向应用提供密钥库能力，包括密钥管理及密钥的密码学操作等功能。 HUKS所管理的密钥可以由应用导入或者由应用调用HUKS接口生成。

导入模块

import huks from '@ohos.security.huks'

HuksErrorCode

表示错误码的枚举。

系统能力：以下各项对应的系统能力均为SystemCapability.Security.Huks。

HuksKeyPurpose

表示密钥用途。

系统能力：以下各项对应的系统能力均为SystemCapability.Security.Huks。

HuksKeyDigest

表示摘要算法。

系统能力：以下各项对应的系统能力均为SystemCapability.Security.Huks。

HuksKeyPadding

表示补齐算法。

系统能力：以下各项对应的系统能力均为SystemCapability.Security.Huks。

HuksCipherMode

表示加密模式。

系统能力：以下各项对应的系统能力均为SystemCapability.Security.Huks。

HuksKeySize

表示密钥长度。

系统能力：以下各项对应的系统能力均为SystemCapability.Security.Huks。

HuksKeyAlg

表示密钥使用的算法。

系统能力：以下各项对应的系统能力均为SystemCapability.Security.Huks。

HuksKeyGenerateType

表示生成密钥的类型。

系统能力：以下各项对应的系统能力均为SystemCapability.Security.Huks。

HuksKeyFlag

表示密钥的产生方式。

系统能力：以下各项对应的系统能力均为SystemCapability.Security.Huks。

HuksKeyStorageType

表示密钥存储方式。

系统能力：以下各项对应的系统能力均为SystemCapability.Security.Huks。

HuksSendType

表示发送Tag的方式。

系统能力：以下各项对应的系统能力均为SystemCapability.Security.Huks。

HuksTagType

表示Tag的数据类型。

系统能力：以下各项对应的系统能力均为SystemCapability.Security.Huks。

HuksTag

表示调用参数的Tag。

系统能力：以下各项对应的系统能力均为SystemCapability.Security.Huks。

huks.generateKey

generateKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback) : void

生成密钥，使用Callback回调异步返回结果。

系统能力：以下各项对应的系统能力均为SystemCapability.Security.Huks。

参数：

示例：

/* 以生成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

generateKey(keyAlias: string, options: HuksOptions) : Promise

生成密钥，使用Promise方式异步返回结果。

系统能力：以下各项对应的系统能力均为SystemCapability.Security.Huks。

参数：

返回值：（可选，如不涉及可删除）

示例：

/* 以生成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

deleteKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback) : void

删除密钥，使用Callback回调异步返回结果。

系统能力：以下各项对应的系统能力均为SystemCapability.Security.Huks。

参数：

示例：

/* 此处options选择emptyOptions传空 */
var keyAlias = 'keyAlias';var emptyOptions = {
  properties: []
};
huks.deleteKey(keyAlias, emptyOptions, function (err, data) {});

huks.deleteKey

deleteKey(keyAlias: string, options: HuksOptions) : Promise

删除密钥，使用Promise方式异步返回结果。

系统能力：以下各项对应的系统能力均为SystemCapability.Security.Huks。

参数：

返回值：

示例：

/* 此处options选择emptyOptions传空 */
var keyAlias = 'keyAlias';var emptyOptions = {
  properties: []
};var result = huks.deleteKey(keyAlias, emptyOptions);

huks.getSdkVersion

getSdkVersion(options: HuksOptions) : string

获取当前系统sdk版本。

系统能力：以下各项对应的系统能力均为SystemCapability.Security.Huks。

参数：

返回值：

示例：

/* 此处options选择emptyOptions传空 */
var emptyOptions = {
  properties: []
};var result = huks.getSdkVersion(emptyOptions);

huks.importKey

importKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback) : void

导入密钥，使用Callback方式回调异步返回结果 。

系统能力：以下各项对应的系统能力均为SystemCapability.Security.Huks。

参数：

示例：

/* 以导入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

importKey(keyAlias: string, options: HuksOptions) : Promise

导入密钥，使用Promise方式异步返回结果。

系统能力：以下各项对应的系统能力均为SystemCapability.Security.Huks。

参数：

返回值：

示例：

/* 以导入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

exportKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback) : void

导出密钥，使用Callback方式回调异步返回的结果。

系统能力：以下各项对应的系统能力均为SystemCapability.Security.Huks。

参数：

示例：

/* 此处options选择emptyOptions来传空 */
var keyAlias = 'keyAlias';var emptyOptions = {
  properties: []
};
huks.exportKey(keyAlias, emptyOptions, function (err, data){});

huks.exportKey

exportKey(keyAlias: string, options: HuksOptions) : Promise

导出密钥，使用Promise方式回调异步返回的结果。

系统能力：以下各项对应的系统能力均为SystemCapability.Security.Huks。

参数：

返回值：

示例：

/* 此处options选择emptyOptions来传空 */
var keyAlias = 'keyAlias';var emptyOptions = {
  properties: []
};var result = huks.exportKey(keyAlias, emptyOptions);

huks.getKeyProperties

getKeyProperties(keyAlias: string, options: HuksOptions, callback: AsyncCallback) : void

获取密钥属性，使用Callback回调异步返回结果。

系统能力：以下各项对应的系统能力均为SystemCapability.Security.Huks。

参数：

示例：

/* 此处options选择emptyOptions来传空 */
var keyAlias = 'keyAlias';var emptyOptions = {
  properties: []
};
huks.getKeyProperties(keyAlias, emptyOptions, function (err, data){});

huks.getKeyProperties

getKeyProperties(keyAlias: string, options: HuksOptions) : Promise

获取密钥属性，使用Promise回调异步返回结果。

系统能力：以下各项对应的系统能力均为SystemCapability.Security.Huks。

参数：

返回值：

示例：

/* 此处options选择emptyOptions来传空 */
var keyAlias = 'keyAlias';var emptyOptions = {
  properties: []
};var result = huks.getKeyProperties(keyAlias, emptyOptions);

huks.isKeyExist

isKeyExist(keyAlias: string, options: HuksOptions, callback: AsyncCallback) : void

判断密钥是否存在，使用Callback回调异步返回结果 。

系统能力：以下各项对应的系统能力均为SystemCapability.Security.Huks。

参数：

示例：

/* 此处options选择emptyOptions来传空 */
var keyAlias = 'keyAlias';var emptyOptions = {
  properties: []
};
huks.isKeyExist(keyAlias, emptyOptions, function (err, data){});

huks.isKeyExist

isKeyExist(keyAlias: string, options: HuksOptions) : Promise

判断密钥是否存在，使用Promise回调异步返回结果 。

系统能力：以下各项对应的系统能力均为SystemCapability.Security.Huks。

参数：

返回值：

示例：

/* 此处options选择emptyOptions来传空 */
var keyAlias = 'keyAlias';var emptyOptions = {
  properties: []
};var result = huks.isKeyExist(keyAlias, emptyOptions);

huks.init

init(keyAlias: string, options: HuksOptions, callback: AsyncCallback) : void

init操作密钥接口，使用Callback回调异步返回结果 。

系统能力：以下各项对应的系统能力均为SystemCapability.Security.Huks。

参数：

huks.init

init(keyAlias: string, options: HuksOptions) : Promise

init操作密钥接口，使用Promise方式异步返回结果。

系统能力：以下各项对应的系统能力均为SystemCapability.Security.Huks。

参数：

huks.update

update(handle: number, token?: Uint8Array, options: HuksOptions, callback: AsyncCallback) : void

update操作密钥接口，使用Callback回调异步返回结果 。

系统能力：以下各项对应的系统能力均为SystemCapability.Security.Huks。

参数：

huks.update

update(handle: number, token?: Uint8Array, options: HuksOptions) : Promise

update操作密钥接口，使用Promise方式异步返回结果。

系统能力：以下各项对应的系统能力均为SystemCapability.Security.Huks。

参数：

huks.finish

finish(handle: number, options: HuksOptions, callback: AsyncCallback) : void

finish操作密钥接口，使用Callback回调异步返回结果 。

系统能力：以下各项对应的系统能力均为SystemCapability.Security.Huks。

参数：

huks.finish

finish(handle: number, options: HuksOptions) : Promise

finish操作密钥接口，使用Promise方式异步返回结果。

系统能力：以下各项对应的系统能力均为SystemCapability.Security.Huks。

参数：

huks.abort

abort(handle: number, options: HuksOptions, callback: AsyncCallback) : void

abort操作密钥接口，使用Callback回调异步返回结果 。

系统能力：以下各项对应的系统能力均为SystemCapability.Security.Huks。

参数：

示例：

/* huks.init, huks.update, huks.finish为三段式接口，需要一起使用，当huks.init和huks.update
 * 以及huks.finish操作中的任一阶段发生错误时，都需要调用huks.abort来终止密钥的使用。
 *
 * 以下以RSA1024密钥的callback操作使用为例
 */
import router from '@system.router';import huks from '@ohos.security.huks';async function routePage() {
let options = {
uri: 'pages/second'
  }
  try {
await router.push(options)
  } catch (err) {
console.error(`fail callback, code: ${err.code}, msg: ${err.msg}`)
  }
}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);
}@Entry
@Component
struct Index {
  build() {
Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Text('Hello World')
        .fontSize(50)
        .fontWeight(FontWeight.Bold)
Button() {
        Text('Tocallback')
          .fontSize(25)
          .fontWeight(FontWeight.Bold)
      }.type(ButtonType.Capsule)
      .margin({
top: 20
      })
      .width('50%')
      .height('10%')
      .backgroundColor('#0D9FFB')
      .onClick(() = > {
        routePage()
      })
Button() {
        Text('generateKey')
          .fontSize(25)
          .fontWeight(FontWeight.Bold)
      }.type(ButtonType.Capsule)
      .margin({
top: 20
      })
      .width('50%')
      .height('10%')
      .backgroundColor('#0D9FFB')
      .onClick(() = > {
        generateKey()
      })
Button() {
        Text('Init')
          .fontSize(25)
          .fontWeight(FontWeight.Bold)
      }.type(ButtonType.Capsule)
      .margin({
top: 20
      })
      .width('50%')
      .height('10%')
      .backgroundColor('#0D9FFB')
      .onClick(() = > {
        huksInit()
      })
Button() {
        Text('Update')
          .fontSize(25)
          .fontWeight(FontWeight.Bold)
      }.type(ButtonType.Capsule)
      .margin({
top: 20
      })
      .width('50%')
      .height('10%')
      .backgroundColor('#0D9FFB')
      .onClick(() = > {
        huksUpdate()
      })
Button() {
        Text('Finish')
          .fontSize(25)
          .fontWeight(FontWeight.Bold)
      }.type(ButtonType.Capsule)
      .margin({
top: 20
      })
      .width('50%')
      .height('10%')
      .backgroundColor('#0D9FFB')
      .onClick(() = > {
        huksFinish()
      })
Button() {
        Text('Abort')
          .fontSize(25)
          .fontWeight(FontWeight.Bold)
      }.type(ButtonType.Capsule)
      .margin({
top: 20
      })
      .width('50%')
      .height('10%')
      .backgroundColor('#0D9FFB')
      .onClick(() = > {
        huksAbort()
      })
    }
    .width('100%')
    .height('100%')
  }
}

huks.abort

abort(handle: number, options: HuksOptions) : Promise;

abort操作密钥接口，使用Promise方式异步返回结果。

系统能力：以下各项对应的系统能力均为SystemCapability.Security.Huks。

参数：

示例：

HuksParam

调用接口使用的options中的properties数组中的param。

系统能力：以下各项对应的系统能力均为SystemCapability.Security.Huks。

HuksOptions

调用接口使用的options。

系统能力：以下各项对应的系统能力均为SystemCapability.Security.Huks。

HuksHandle

huks Handle结构体。

系统能力：以下各项对应的系统能力均为SystemCapability.Security.Huks。

HuksResult

调用接口返回的result。

系统能力：以下各项对应的系统能力均为SystemCapability.Security.Huks。

审核编辑 黄宇