Enabling Biometric Authentication

Use Cases

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.
The facial authentication function requires the device to have the 3D facial recognition capability. You can call the obtaining supported authentication capabilities API to check whether a device supports 3D facial recognition. Currently, only one fingerprint or face can be bound for payment authentication.
This function requires the app server of an enterprise developer to complete API access to support the device-cloud collaborative authentication process.

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 mobile phones, some PCs/2-in-1 devices, and some tablets. The facial authentication function is supported only on devices that support 3D facial recognition. Currently, only one fingerprint or face can be bound for payment authentication, and the app server of an enterprise developer must be used for device-cloud collaborative authentication. You can call the obtaining supported authentication capabilities API to check whether a device supports 3D facial recognition.

Service Process

API Description

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

API	Description
trustedAuthentication(challenge: Uint8Array, authID: bigint, label: TUILable): Promise<AuthToken>	Authenticates the digital shield password.
getBiometricAuthToken(operType: OperateType, tuiAuthToken: Uint8Array, bioAuthToken: Uint8Array): Promise<AuthToken>	Obtains the authToken generated from biometric binding.

Development Procedure

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

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

Use the API provided by User Authentication Kit to check whether the device has enrolled related credential information.
Initialize the signature session. For details, please refer to Signing and Signature Verification of Universal Keystore Kit.

Call the password authentication API trustedAuthentication of the digital shield service to initiate a password authentication request before biometric authentication.

async PwdVerify(challenge: Uint8Array, assetName: string): Promise<trustedAuthentication.AuthToken> {
  try {
    let resArray: Uint8Array = await AssetUtils.QueryDataFromAssetStore(assetName);
    let credentialID: bigint = CryptoUtils.uint8ArrayToBigInt(resArray);
    const context = AppStorage.get('context') as Context;
    const buffer: ArrayBuffer = await CryptoUtils.ImportImage();
    const label: trustedAuthentication.TUILable = {
      image: buffer,
      title: context.resourceManager.getStringSync($r('app.string.ShieldPwVerification').id)
    }
    const result = await trustedAuthentication.trustedAuthentication(challenge, credentialID, label);
    hilog.info(DOMAIN, 'testTag', 'DigitalShield password verification success: ', result.authToken.length,
      result.authToken);
    return result;
  } catch (error) {
    hilog.error(DOMAIN, 'testTag', 'DigitalShield password verification failed: ', error);
    throw new Error('DigitalShield password verification failed: ' + (error as BusinessError).message);
  }
}

Call the API provided by User Authentication Kit to start the BioAuthn control and initiate authentication.

After the subscribed biometric authentication result is obtained, integrate the digital shield password authentication result and biometric authentication result, and initiate a biometric binding request.

try {
  let session = await TrustedAuth.SignInit();
  hilog.info(DOMAIN, 'testTag', 'Finish Signature Initialization');
  const tuiAuthToken: Uint8Array =
    await TrustedAuth.GetTUIAuthTokenBeforeBioVerify('placeholder', session, TUI_BIND_FACE, 'pin_label1'); // authToken obtained in step 6
  let bioAuthToken: Uint8Array =
    await TrustedAuth.UserAuthBeforeSign(session, TUI_BIND_FACE); // authToken obtained in step 7
  let operType = trustedAuthentication.OperateType.OPERATE_TYPE_BIOMETRIC_AUTH;
  let resignAuthToken =
    await trustedAuthentication.getBiometricAuthToken(operType, tuiAuthToken, bioAuthToken);
  let inputdata = 'placeholder';
  await TrustedAuth.bindFaceID(session.handle, resignAuthToken.authToken, inputdata)
  // ...
} catch (error) {
  hilog.error(DOMAIN, 'testTag', 'Bind Face Fail:', error);
  // ...
}