目录

Digital Shield Signature Key Backup and Restoration

Use Cases

Before activating the digital shield, an enterprise app needs to submit a key generation request to Universal Keystore Kit and specify the technical parameters (such as the algorithm and length) of the required key. The successfully generated key will be stored in Universal Keystore Kit. The app can request to use the key to sign or verify the signature of service data related to the digital shield. If the app is uninstalled, Universal Keystore Kit will automatically delete the corresponding key data. As a result, the digital shield function cannot be used after the app is reinstalled.

To restore the digital shield function using historical data after the app is reinstalled on the same device, perform the following operations after activating the digital shield:

  1. Send a request to Universal Keystore Kit to export the key ciphertext.

  2. Send a key backup request to the digital shield service and securely store the key ciphertext in the digital shield service.

After the app is uninstalled and reinstalled, if you want to continue to use the key data generated by Universal Keystore Kit before the app uninstallation to directly restore the historical digital shield function without reactivating the digital shield password, perform the following operations:

  1. Send a key restoration request to the digital shield service. After the digital shield password is successfully authenticated, export the key data backed up before the app uninstallation to the app.

  2. Send the key data to Universal Keystore Kit to complete key restoration.

  • Once the digital shield service is disabled, the digital shield service will automatically clear the corresponding password and key data. When the digital shield is enabled again, key data needs to be backed up again.

  • Repeated key imports to the digital shield service are not supported between key import and digital shield password disabling.

Constraints

In versions earlier than 6.1.1(24), this function is supported only on mobile phones. In 6.1.1(24) and later versions, this function is supported on PCs/2-in-1 devices and tablets with the TUI capability. You can call the checkConfirmUITextFormat API to check whether a device has the TUI capability. When an unsupported device calls the service APIs of the Digital Shield service, error code 1019100016 is returned.

Service Process

API Description

For details about the APIs and their usage, see API Reference.

API Description
importData(data: ArrayBuffer, authID: bigint): Promise<void> Import data (the encryption key information used during HUKS signing and signature verification).
exportData(authID: bigint, label: TUILable): Promise<ArrayBuffer> Export data (the encryption key information used during HUKS signing and signature verification).

Development Procedure

  1. Import the huks module, trustedAuthentication module, and dependent modules.

     import { resourceManager } from '@kit.LocalizationKit'
 import { huks } from '@kit.UniversalKeystoreKit';
 import { BusinessError } from '@kit.BasicServicesKit';
 import { trustedAuthentication } from '@kit.DeviceSecurityKit';
 import { hilog } from '@kit.PerformanceAnalysisKit';
 import { common } from '@kit.AbilityKit';

  2. Export the key by referring to the wrapKeyItem method provided by Universal Keystore Kit.

    private async exportKeyFromHuks(): Promise<Uint8Array> {
  let wrapKeyProperties: Array<huks.HuksParam> = [
    {
      tag: huks.HuksTag.HUKS_TAG_KEY_WRAP_TYPE,
      value: huks.HuksKeyWrapType.HUKS_KEY_WRAP_TYPE_HUK_BASED
    }
  ];

  let wrapKeyOptions: huks.HuksOptions = {
    properties: wrapKeyProperties
  };

  try {
    // Export the ciphertext of the generated key from Universal Keystore Kit.
    let data = await huks.wrapKeyItem(KEY_ALIAS, wrapKeyOptions);
    let wrappedKey: Uint8Array = data.outData as Uint8Array;
    hilog.info(0x0000, 'testTag', 'exportKeyFromHuks success, size=' + wrappedKey.length);
    return wrappedKey;
  } catch (error) {
    hilog.error(0x0000, 'testTag', 'exportKeyFromHuks failed', JSON.stringify(error));
    throw new Error('Export key from HUKS failed:' + (error as BusinessError).message);
  }
}

  3. Retrieve the authID value obtained during digital shield password setup from the server for the current account, and send a data import request to the digital shield service using authID as the index.

    private async importDataToDigitalShield(wrappedKey: Uint8Array, authID: bigint): Promise<void> {
  try {
    let buffer: ArrayBuffer = wrappedKey.buffer.slice(
      wrappedKey.byteOffset, wrappedKey.byteOffset + wrappedKey.byteLength
    );
    await trustedAuthentication.importData(buffer, authID);
    hilog.info(DOMAIN, 'testTag', 'importDataToDigitalShield success');
  } catch (error) {
    hilog.error(DOMAIN, 'testTag', 'importDataToDigitalShield failed', JSON.stringify(error));
    throw new Error('Import data to Digital Shield failed:' + (error as BusinessError).message);
  }
}

  4. After the app is uninstalled and reinstalled, send a key restoration request from the app to the digital shield server.

    private async exportDataFromDigitalShield(authID: bigint): Promise<ArrayBuffer> {
  try {
    const context = AppStorage.get('context') as Context;
    const buffer: ArrayBuffer = await CryptoUtils.ImportImage(); // Obtain the app logo image to be displayed on the TUI.
    const label: trustedAuthentication.TUILable = {
      image: buffer,
      title: context.resourceManager.getStringSync($r('app.string.ExportKeyInfoLabel').id)
    };
    let data: ArrayBuffer = await trustedAuthentication.exportData(authID, label);
    hilog.info(0x0000, 'testTag', 'exportDataFromDigitalShield success, size=' + data.byteLength);
    return data;
  } catch (error) {
    hilog.error(0x0000, 'testTag', 'exportDataFromDigitalShield failed', JSON.stringify(error));
    throw new Error('Export data from Digital Shield failed:' + (error as BusinessError).message);
  }
}

  5. Send the key data obtained from the digital shield service to Universal Keystore Kit for key import and restoration.

    private async importKeyToHuks(wrappedKey: Uint8Array): Promise<void> {
  let wrapKeyProperties: Array<huks.HuksParam> = [
    {
      tag: huks.HuksTag.HUKS_TAG_KEY_WRAP_TYPE,
      value: huks.HuksKeyWrapType.HUKS_KEY_WRAP_TYPE_HUK_BASED
    }
  ];

  let wrapKeyOptions: huks.HuksOptions = {
    properties: wrapKeyProperties
  };

  try {
    await huks.unwrapKeyItem(KEY_ALIAS, wrapKeyOptions, wrappedKey);
    hilog.info(DOMAIN, 'testTag', 'importKeyToHuks success');
  } catch (error) {
    hilog.error(DOMAIN, 'testTag', 'importKeyToHuks failed', JSON.stringify(error));
    throw new Error('Import key to HUKS failed:' + (error as BusinessError).message);
  }
}