HUKS

NOTE

The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Openharmony Universal KeyStore (HUKS) provides KeyStore (KS) capabilities for applications, including key management and key cryptography operations. HUKS also provides APIs for applications to import or generate keys.

Modules to Import

import huks from '@ohos.security.huks'

HuksErrorCode

Enumerates the error codes.

System capability: SystemCapability.Security.Huks

HuksKeyPurpose

Enumerates the key purposes.

System capability: SystemCapability.Security.Huks

HuksKeyDigest

Enumerates the digest algorithms.

System capability: SystemCapability.Security.Huks

HuksKeyPadding

Enumerates the padding algorithms.

System capability: SystemCapability.Security.Huks

HuksCipherMode

Enumerates the cipher modes.

System capability: SystemCapability.Security.Huks

HuksKeySize

Enumerates the key sizes.

System capability: SystemCapability.Security.Huks

HuksKeyAlg

Enumerates the key algorithms.

System capability: SystemCapability.Security.Huks

HuksKeyGenerateType

Enumerates the key generation types.

System capability: SystemCapability.Security.Huks

HuksKeyFlag

Enumerates the key generation modes.

System capability: SystemCapability.Security.Huks

HuksKeyStorageType

Enumerates the key storage modes.

System capability: SystemCapability.Security.Huks

HuksSendType

Enumerates the tag transfer modes.

System capability: SystemCapability.Security.Huks

HuksTagType

Enumerates the tag data types.

System capability: SystemCapability.Security.Huks

HuksTag

Enumerates the tags used to invoke parameters.

System capability: SystemCapability.Security.Huks

huks.generateKey

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

Generates a key. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Security.Huks

Parameters

Example

/* Generate an RSA key of 512 bits. */
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<HuksResult>

Generates a key. This API uses a promise to return the result.

System capability: SystemCapability.Security.Huks

Parameters

Return value

Example

/* Generate an ECC key of 256 bits. */
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<HuksResult>) : void

Deletes a key. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Security.Huks

Parameters

Example

/* Set options to emptyOptions. */
var keyAlias = 'keyAlias';
var emptyOptions = {
  properties: []
};
huks.deleteKey(keyAlias, emptyOptions, function (err, data) {});

huks.deleteKey

deleteKey(keyAlias: string, options: HuksOptions) : Promise<HuksResult>

Deletes a key. This API uses a promise to return the result.

System capability: SystemCapability.Security.Huks

Parameters

Return value

Example

/* Set options to emptyOptions. */
var keyAlias = 'keyAlias';
var emptyOptions = {
  properties: []
};
var result = huks.deleteKey(keyAlias, emptyOptions);

huks.getSdkVersion

getSdkVersion(options: HuksOptions) : string

Obtains the SDK version of the current system.

System capability: SystemCapability.Security.Huks

Parameters

Return value

Example

/* Set options to emptyOptions. */
var emptyOptions = {
  properties: []
};
var result = huks.getSdkVersion(emptyOptions);

huks.importKey

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

Imports a key. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Security.Huks

Parameters

Example

/* Import an AES key of 256 bits. */
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<HuksResult>

Imports a key. This API uses a promise to return the result.

System capability: SystemCapability.Security.Huks

Parameters

Return value

Example

/* Import an AES key of 128 bits. */
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;
};

/* Step 1 Generate a key. */
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<HuksResult>) : void

Exports a key. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Security.Huks

Parameters

Example

/* Set options to emptyOptions. */
var keyAlias = 'keyAlias';
var emptyOptions = {
  properties: []
};
huks.exportKey(keyAlias, emptyOptions, function (err, data){});

huks.exportKey

exportKey(keyAlias: string, options: HuksOptions) : Promise<HuksResult>

Exports a key. This API uses a promise to return the result.

System capability: SystemCapability.Security.Huks

Parameters

Return value

Example

/* Set options to emptyOptions. */
var keyAlias = 'keyAlias';
var emptyOptions = {
  properties: []
};
var result = huks.exportKey(keyAlias, emptyOptions);

huks.getKeyProperties

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

Obtains key properties. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Security.Huks

Parameters

Example

/* Set options to emptyOptions. */
var keyAlias = 'keyAlias';
var emptyOptions = {
  properties: []
};
huks.getKeyProperties(keyAlias, emptyOptions, function (err, data){});

huks.getKeyProperties

getKeyProperties(keyAlias: string, options: HuksOptions) : Promise<HuksResult>

Obtains key properties. This API uses a promise to return the result.

System capability: SystemCapability.Security.Huks

Parameters

Return value

Example

/* Set options to emptyOptions. */
var keyAlias = 'keyAlias';
var emptyOptions = {
  properties: []
};
var result = huks.getKeyProperties(keyAlias, emptyOptions);

huks.isKeyExist

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

Checks whether a key exists. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Security.Huks

Parameters

Example

/* Set options to emptyOptions. */
var keyAlias = 'keyAlias';
var emptyOptions = {
  properties: []
};
huks.isKeyExist(keyAlias, emptyOptions, function (err, data){});

huks.isKeyExist

isKeyExist(keyAlias: string, options: HuksOptions) : Promise<boolean>

Checks whether a key exists. This API uses a promise to return the result.

System capability: SystemCapability.Security.Huks

Parameters

Return value

Example

/* Set options to emptyOptions. */
var keyAlias = 'keyAlias';
var emptyOptions = {
  properties: []
};
var result = huks.isKeyExist(keyAlias, emptyOptions);

huks.init

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

Initializes a key. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Security.Huks

Parameters

huks.init

init(keyAlias: string, options: HuksOptions) : Promise<HuksHandle>

Initializes a key. This API uses a promise to return the result.

System capability: SystemCapability.Security.Huks

Parameters

huks.update

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

Updates a key. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Security.Huks

Parameters

huks.update

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

Updates a key. This API uses a promise to return the result.

System capability: SystemCapability.Security.Huks

Parameters

huks.finish

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

Completes the key operation and releases resources. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Security.Huks

Parameters

huks.finish

finish(handle: number, options: HuksOptions) : Promise<HuksResult>

Completes the key operation and releases resources. This API uses a promise to return the result.

System capability: SystemCapability.Security.Huks

Parameters

huks.abort

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

Aborts the use of the key. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Security.Huks

Parameters

Example

/* huks.init, huks.update, and huks.finish must be used together.
 * If an error occurs in any of them, huks.abort must be called to terminate the use of the key.
 *
 * The following uses the callback of an RSA 1024-bit key as an example.
 */
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 = "Failed to complete the key operation. 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 = "Failed to abort the use of the key. 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<HuksResult>;

Aborts the use of the key. This API uses a promise to return the result.

System capability: SystemCapability.Security.Huks

Parameters

Example

/* huks.init, huks.update, and huks.finish must be used together.
 * If an error occurs in any of them, huks.abort must be called to terminate the use of the key.
 *
 * The following uses the promise of an RSA 1024-bit key as an example.
 */
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 = "";
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 = "Initialization successful!"
        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)}`);
    });
  });
}
@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('to Promise')
          .fontSize(20)
          .fontWeight(FontWeight.Bold)
      }.type(ButtonType.Capsule)
      .margin({
        top: 20
      })
      .width('50%')
      .height('10%')
      .backgroundColor('#0D9FFB')
      .onClick(() => {
        router.back()
      })
      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%')
  }
}

HuksParam

Defines the param in the properties array of options used in the APIs.

System capability: SystemCapability.Security.Huks

HuksOptions

Defines the options used in the APIs.

System capability: SystemCapability.Security.Huks

HuksHandle

Defines the HUKS handle structure.

System capability: SystemCapability.Security.Huks

HuksResult

Defines the HuksResult structure.

System capability: SystemCapability.Security.Huks