目录

TrustedAuthentication (Digital Shield)

This module provides APIs for creating, changing, and deleting digital shield passwords, API for executing transaction authentication, API for enabling biometric (3D face/fingerprint) transaction authentication, API for executing biometric transaction authentication, and APIs importing and exporting key information. Finance apps can use these APIs to support digital shield service development.

Since: 6.0.0(20)

Modules to Import

import { trustedAuthentication } from '@kit.DeviceSecurityKit';

trustedAuthentication.enableTrustedAuthentication

enableTrustedAuthentication(challenge: Uint8Array, pwdInfo: PasswordInfo, label: TUILable): Promise<AuthInfo>

Starts the trusted user interface (TUI) and instructs the user to create a digital shield password. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 26.0.0.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.TrustedAuthentication

Device behavior differences: For version earlier than 6.1.1(24), this API is supported on phones and tablets. On other device types, it returns service error code 1019100016. For 6.1.1(24) and later versions, this API is supported on phones, tablets that support the TUI capability, and PCs/2-in-1 devices. On tablets that do not support the TUI capability, PCs/2-in-1 devices, and other device types, this API returns service error code 1019100016. You can use the checkConfirmUITextFormat API to check whether the capability is supported.

Since: 6.0.0(20)

Parameters:

Name Type Mandatory Description
challenge Uint8Array Yes Challenge value obtained in session initialization in Universal Keystore Kit before the request is sent. The value must be a 32-byte random number.
pwdInfo PasswordInfo Yes Custom password information. For details, please refer to PasswordInfo.
label TUILable Yes Custom information for TUI display. For details, please refer to TUILable.

Returns:

Type Description
Promise<AuthInfo> Promise used to return the authID and authToken parameters corresponding to digital shield password enabling.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
801

Failed to call the API due to limited device capabilities.

Applicable versions: 26.0.0+
1019100001 The interface invoker does not have the corresponding permission.
1019100002

Parameter error.

Possible causes:

1. Mandatory parameters are left unspecified.

2. Incorrect parameter types.

3. Parameter verification failed.
1019100007 Unsupported custom image.
1019100008 The user canceled the operation.
1019100011 The title text cannot be displayed.
1019100013 Failed to set the password.
1019100023

Secure element fault.

Applicable versions: 26.0.0+
1019100025

The TUI is occupied by another app.

Applicable versions: 6.1.1(24)+

Example:

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

const TAG = 'TrustedAuthenticationJsTest';
try {
  const rand = cryptoFramework.createRandom();
  const len: number = 32;
  const challenge: Uint8Array = rand?.generateRandomSync(len)?.data;
  const passwordInfo: trustedAuthentication.PasswordInfo = {
    pwdType: trustedAuthentication.PasswordType.PASSWORD_TYPE_MIXED,
    pwdMaxLength: 10,
    pwdMinLength: 6,
    maxAuthFailCount: 6
  };
  let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
  const resourceMgr: resourceManager.ResourceManager = context.resourceManager;
  const fileData : Uint8Array = await resourceMgr.getRawFileContent('test_logo_rgba.png');
  const buffer = fileData.buffer;
  const label:trustedAuthentication.TUILable = {
    image: buffer as ArrayBuffer,
    title: "Enable Digital Shield",
  }
  const authToken = await trustedAuthentication.enableTrustedAuthentication(challenge, passwordInfo, label);
} catch (err) {
  let e: BusinessError = err as BusinessError;
  hilog.error(0x0000, TAG, 'enableTrustedAuthentication failed: %{public}d %{public}s', e.code, e.message);
}

trustedAuthentication.modifyTrustedAuthenticationPwd

modifyTrustedAuthenticationPwd(challenge: Uint8Array, pwdInfo: PasswordInfo, authID: bigint, label: TUILable): Promise<AuthToken>

Starts the TUI and instructs the user to change the digital shield password. The password will be authenticated based on authID before the change. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 26.0.0.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.TrustedAuthentication

Device behavior differences: For version earlier than 6.1.1(24), this API is supported on phones and tablets. On other device types, it returns service error code 1019100016. For 6.1.1(24) and later versions, this API is supported on phones, tablets that support the TUI capability, and PCs/2-in-1 devices. On tablets that do not support the TUI capability, PCs/2-in-1 devices, and other device types, this API returns service error code 1019100016. You can use the checkConfirmUITextFormat API to check whether the capability is supported.

Since: 6.0.0(20)

Parameters:

Name Type Mandatory Description
challenge Uint8Array Yes Challenge value obtained in session initialization in Universal Keystore Kit before the request is sent. The value must be a 32-byte random number.
pwdInfo PasswordInfo Yes Custom password information.
authID bigint Yes authID obtained during password creation.
label TUILable Yes Custom information for TUI display.

Returns:

Type Description
Promise<AuthToken> Promise used to return the authToken corresponding to digital shield password change.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
1019100001 The interface invoker does not have the corresponding permission.
1019100002

Parameter error.

Possible causes:

1. Mandatory parameters are left unspecified.

2. Incorrect parameter types.

3. Parameter verification failed.
1019100003 The maximum number of password authentication attempts has been reached.
1019100005 Face/Fingerprint/Password authentication failed.
1019100007 Unsupported custom image.
1019100008 The user canceled the operation.
1019100011 The title text cannot be displayed.
1019100012 Invalid authentication ID.
1019100014 Failed to change the password.
1019100023

Secure element fault.

Applicable versions: 26.0.0+
1019100025

The TUI is occupied by another app.

Applicable versions: 6.1.1(24)+

Example:

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

const TAG = 'TrustedAuthenticationJsTest';

try {
 const rand = cryptoFramework.createRandom();
 const len: number = 32;
 const challenge: Uint8Array = rand?.generateRandomSync(len)?.data;
 const passwordInfo: trustedAuthentication.PasswordInfo = {
   pwdType: trustedAuthentication.PasswordType.PASSWORD_TYPE_DIGITAL,
   pwdMaxLength: 10,
   pwdMinLength: 6,
   maxAuthFailCount: 6,
 };
 const authID: bigint = 1687413472599354502n;
 let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
 const resourceMgr: resourceManager.ResourceManager = context.resourceManager;
 const fileData : Uint8Array = await resourceMgr.getRawFileContent('test_logo_rgba.png');
 const buffer = fileData.buffer;
 const label:trustedAuthentication.TUILable = {
   image: buffer as ArrayBuffer,
   title: "Change Password",
 }
 const authToken = await trustedAuthentication.modifyTrustedAuthenticationPwd(challenge, passwordInfo, authID, label);
} catch (err) {
  let e: BusinessError = err as BusinessError;
  hilog.error(0x0000, TAG, 'modifyTrustedAuthenticationPwd failed: %{public}d %{public}s', e.code, e.message);
}

trustedAuthentication.disableTrustedAuthentication

disableTrustedAuthentication(challenge: Uint8Array, needAuth: boolean, authID: bigint, label: TUILable): Promise<AuthToken>

Disables the digital shield service. You can use the needAuth parameter to specify whether password authentication is required for digital shield disabling. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 26.0.0.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.TrustedAuthentication

Device behavior differences: For version earlier than 6.1.1(24), this API is supported on phones and tablets. On other device types, it returns service error code 1019100016. For 6.1.1(24) and later versions, this API is supported on phones, tablets that support the TUI capability, and PCs/2-in-1 devices. On tablets that do not support the TUI capability, PCs/2-in-1 devices, and other device types, this API returns service error code 1019100016. You can use the checkConfirmUITextFormat API to check whether the capability is supported.

Since: 6.0.0(20)

Parameters:

Name Type Mandatory Description
challenge Uint8Array Yes

When the value of needAuth is true, the challenge value is the value obtained in session initialization in Universal Keystore Kit before the request is sent. The value must be a 32-byte random number.

When the value of needAuth is false, the challenge value can be any 32-byte number and does not need to be obtained from Universal Keystore Kit.
needAuth boolean Yes

Indicates whether password authentication is required for disabling the digital shield service.

When the value is false, password authentication is not required.

When the value is true, password authentication is required. The digital shield service can be disabled only after password authentication succeeds.
authID bigint Yes authID obtained during password creation.
label TUILable Yes Custom information for TUI display.

Returns:

Type Description
Promise<AuthToken> Promise used to return the authToken corresponding to digital shield password deletion. When needAuth is set to false, the returned authToken is an invalid value with all zeros.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
1019100001 The interface invoker does not have the corresponding permission.
1019100002

Parameter error.

Possible causes:

1. Mandatory parameters are left unspecified.

2. Incorrect parameter types.

3. Parameter verification failed.
1019100003 The maximum number of password authentication attempts has been reached.
1019100004 Failed to delete the password.
1019100005 Face/Fingerprint/Password authentication failed.
1019100007 Unsupported custom image.
1019100008 The user canceled the operation.
1019100011 The title text cannot be displayed.
1019100012 Invalid authentication ID.
1019100023

Secure element fault.

Applicable versions: 26.0.0+
1019100025

The TUI is occupied by another app.

Applicable versions: 6.1.1(24)+

Example:

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

const TAG = 'TrustedAuthenticationJsTest';

try {
 const rand = cryptoFramework.createRandom();
 const len: number = 32;
 const challenge: Uint8Array = rand?.generateRandomSync(len)?.data;
 const authID: bigint = 1687413472599354502n;
 let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
 const resourceMgr: resourceManager.ResourceManager = context.resourceManager;
 const fileData : Uint8Array = await resourceMgr.getRawFileContent('test_logo_rgba.png');
 const buffer = fileData.buffer;
 const label:trustedAuthentication.TUILable = {
   image: buffer as ArrayBuffer,
   title: "Disable Digital Shield",
 }
 const authToken = await trustedAuthentication.disableTrustedAuthentication(challenge, true, authID, label);
} catch (err) {
  let e: BusinessError = err as BusinessError;
  hilog.error(0x0000, TAG, 'disableTrustedAuthentication failed: %{public}d %{public}s', e.code, e.message);
}

trustedAuthentication.trustedAuthentication

trustedAuthentication(challenge: Uint8Array, authID: bigint, label: TUILable): Promise<AuthToken>

Provides the digital shield password authentication capability. You can call this API to complete password authentication before binding biometric information for payment authentication. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 26.0.0.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.TrustedAuthentication

Device behavior differences: For version earlier than 6.1.1(24), this API is supported on phones and tablets. On other device types, it returns service error code 1019100016. For 6.1.1(24) and later versions, this API is supported on phones, tablets that support the TUI capability, and PCs/2-in-1 devices. On tablets that do not support the TUI capability, PCs/2-in-1 devices, and other device types, this API returns service error code 1019100016. You can use the checkConfirmUITextFormat API to check whether the capability is supported.

Since: 6.0.0(20)

Parameters:

Name Type Mandatory Description
challenge Uint8Array Yes Challenge value obtained in session initialization in Universal Keystore Kit before the request is sent. The value must be a 32-byte random number.
authID bigint Yes authID obtained during password creation.
label TUILable Yes Custom information for TUI display.

Returns:

Type Description
Promise<AuthToken> Promise used to return the authToken corresponding to digital shield password authentication.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
1019100001 The interface invoker does not have the corresponding permission.
1019100002

Parameter error.

Possible causes:

1. Mandatory parameters are left unspecified.

2. Incorrect parameter types.

3. Parameter verification failed.
1019100003 The maximum number of password authentication attempts has been reached.
1019100005 Face/Fingerprint/Password authentication failed.
1019100007 Unsupported custom image.
1019100008 The user canceled the operation.
1019100012 Invalid authentication ID.
1019100023

Secure element fault.

Applicable versions: 26.0.0+
1019100025

The TUI is occupied by another app.

Applicable versions: 6.1.1(24)+

Example:

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

const TAG = 'TrustedAuthenticationJsTest';

try {
 const rand = cryptoFramework.createRandom();
 const len: number = 32;
 const challenge: Uint8Array = rand?.generateRandomSync(len)?.data;
 const authID: bigint = 1687413472599354502n;
 let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
 const resourceMgr: resourceManager.ResourceManager = context.resourceManager;
 const fileData : Uint8Array = await resourceMgr.getRawFileContent('test_logo_rgba.png');
 const buffer = fileData.buffer;
 const label:trustedAuthentication.TUILable = {
   image: buffer as ArrayBuffer,
   title: "Password Authentication",
 }
 const authToken = await trustedAuthentication.trustedAuthentication(challenge, authID, label);
} catch (err) {
  let e: BusinessError = err as BusinessError;
  hilog.error(0x0000, TAG, 'trustedAuthentication failed: %{public}d %{public}s', e.code, e.message);
}

trustedAuthentication.procContentAuthentication

procContentAuthentication(challenge: Uint8Array, authID: bigint, authMsg: AuthReqParams, label: TUILable): Promise<AuthToken>

Authenticates a transaction. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 26.0.0.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.TrustedAuthentication

Device behavior differences: For version earlier than 6.1.1(24), this API is supported on phones and tablets. On other device types, it returns service error code 1019100016. For 6.1.1(24) and later versions, this API is supported on phones, tablets that support the TUI capability, and PCs/2-in-1 devices. On tablets that do not support the TUI capability, PCs/2-in-1 devices, and other device types, this API returns service error code 1019100016. You can use the checkConfirmUITextFormat API to check whether the capability is supported.

Since: 6.0.0(20)

Parameters:

Name Type Mandatory Description
challenge Uint8Array Yes Challenge value obtained in session initialization in Universal Keystore Kit before the request is sent. The value must be a 32-byte random number.
authID bigint Yes authID obtained during password creation.
authMsg AuthReqParams Yes Transaction authentication request parameters.
label TUILable Yes Custom information for TUI display.

Returns:

Type Description
Promise<AuthToken>

Promise used to return the result.

When password authentication is used, the returned result includes the authToken of the transaction data.

During biometric authentication, the returned result is a temporary authToken. After biometric authentication is successful, getBiometricAuthToken must be called to obtain the officially issued authToken containing transaction information.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
1019100001 The interface invoker does not have the corresponding permission.
1019100002

Parameter error.

Possible causes:

1. Mandatory parameters are left unspecified.

2. Incorrect parameter types.

3. Parameter verification failed.
1019100005 Face/Fingerprint/Password authentication failed.
1019100008 The user canceled the operation.
1019100011 The text content cannot be displayed.
1019100012 Invalid authentication ID.
1019100021 The corresponding biometric data has not been bound.
1019100023

Secure element fault.

Applicable versions: 26.0.0+
1019100024

The bound biometric ID is invalid.

Applicable versions: 26.0.0+
1019100025

The TUI is occupied by another app.

Applicable versions: 6.1.1(24)+

Example:

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

const TAG = 'TrustedAuthenticationJsTest';

try {
 const rand = cryptoFramework.createRandom();
 const len: number = 32;
 const challenge: Uint8Array = rand?.generateRandomSync(len)?.data;
 const authID: bigint = 1687413472599354502n;
 let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
 const resourceMgr: resourceManager.ResourceManager = context.resourceManager;
 const fileData : Uint8Array = await resourceMgr.getRawFileContent('test_logo_rgba.png');
 const reqParams:trustedAuthentication.AuthReqParams = {
  reqType: trustedAuthentication.AuthType.AUTH_TYPE_TUI_PIN,
  authContent: ["User: John xx", "Account: 95588180804408xxxx", "Transaction amount: 1000000000"];
 }
 const buffer = fileData.buffer;
 const label:trustedAuthentication.TUILable = {
  image: buffer as ArrayBuffer,
  title: "Password-based Transaction Authentication",
 }
 const result = await trustedAuthentication.procContentAuthentication(challenge, authID, reqParams, label);
} catch (err) {
  let e: BusinessError = err as BusinessError;
  hilog.error(0x0000, TAG, 'procContentAuthentication failed: %{public}d %{public}s', e.code, e.message);
}

trustedAuthentication.getBiometricAuthToken

getBiometricAuthToken(operType: OperateType, tuiAuthToken: Uint8Array, bioAuthToken: Uint8Array): Promise<AuthToken>

Obtains the authToken corresponding to biometric binding or biometric transaction authentication. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 26.0.0.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.TrustedAuthentication

Device behavior differences: For version earlier than 6.1.1(24), this API is supported on phones and tablets. On other device types, it returns service error code 1019100016. For 6.1.1(24) and later versions, this API is supported on phones, tablets that support the TUI capability, and PCs/2-in-1 devices. On tablets that do not support the TUI capability, PCs/2-in-1 devices, and other device types, this API returns service error code 1019100016. You can use the checkConfirmUITextFormat API to check whether the capability is supported.

Since: 6.0.0(20)

Parameters:

Name Type Mandatory Description
operType OperateType Yes Operation type for obtaining the authToken. For details, please refer to OperateType.
tuiAuthToken Uint8Array Yes

When the operation type is OPERATE_TYPE_BIOMETRIC_AUTH, tuiAuthToken indicates the authToken information obtained through password authentication (trustedAuthentication).

When the operation type is OPERATE_TYPE_CONTENT_AUTH, tuiAuthToken indicates the authToken information obtained through temporary transaction information confirmation (procContentAuthentication).
bioAuthToken Uint8Array Yes authToken obtained through biometric authentication. The tuiAuthToken and bioAuthToken must be obtained using the same challenge, that is, the two authTokens must be obtained in the same session.

Returns:

Type Description
Promise<AuthToken>

Promise used to return the result.

In the biometric binding process, the obtained authToken contains the biometric feature ID and is issued after being authenticated by the digital shield service.

In the biometric transaction authentication process, the obtained authToken contains the transaction information and biometric feature ID, but has not been authenticated by the digital shield service.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
1019100001 The interface invoker does not have the corresponding permission.
1019100002

Parameter error.

Possible causes:

1. Mandatory parameters are left unspecified.

2. Incorrect parameter types.

3. Parameter verification failed.
1019100005 Face/Fingerprint/Password authentication failed.
1019100015 Failed to get the biometric authToken.
1019100019 The biometric data for authentication does not match the bound biometric feature.
1019100020 The biometric data has already been bound.
1019100023

Secure element fault.

Applicable versions: 26.0.0+

Example:

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

const TAG = 'TrustedAuthenticationJsTest';
async function PwdVerify(challenge: Uint8Array,
  resourceMgr:resourceManager.ResourceManager):Promise<trustedAuthentication.AuthToken> {
  try {
    const authID: bigint = 11842183505170721246n; // In actual use, replace the value with the **credentialID** of the account obtained from the server.
    const fileData : Uint8Array = await resourceMgr.getRawFileContent('test_logo_rgba.png'); // In actual use, replace the value with the name of the app logo image to be displayed on the TUI.
    const buffer = fileData.buffer;
    const label:trustedAuthentication.TUILable = {
      image: buffer as ArrayBuffer,
      title: "Digital Shield Password Authentication",
    }
    const result = await trustedAuthentication.trustedAuthentication(challenge, authID, label);
    return result;
  } catch (err) {
    hilog.error(0x0000, 'testTag', `Failed to trustedAuthentication, code:${err.code}, message:${err.message}`);
    throw new Error('Password verify failed:' + (err as BusinessError).message);
  }
}
const rand = cryptoFramework.createRandom();
const len: number = 32;
let challengeID: Uint8Array = rand?.generateRandomSync(len)?.data;
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
const resourceMgr: resourceManager.ResourceManager = context.resourceManager;
const TuiAuthToken: trustedAuthentication.AuthToken = await PwdVerify(challengeID, resourceMgr);
let authTypeList :number[] = new Array();
authTypeList[0] = userAuth.UserAuthType.FINGERPRINT;
authTypeList[1] = userAuth.UserAuthType.FACE;

const authParam : userAuth.AuthParam = {
  challenge: challengeID,
  authType: authTypeList,
  authTrustLevel: userAuth.AuthTrustLevel.ATL4
};
const widgetParam: userAuth.WidgetParam = {
  title: 'Enter Digital Shield Password',
  navigationButtonText: 'Enter Digital Shield Password',
};

try {
  const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam);
  userAuthInstance.on('result', {
    onResult(result) {
      let authTokenData = result.token;
      let operType = trustedAuthentication.OperateType.OPERATE_TYPE_BIOMETRIC_AUTH;
      trustedAuthentication.getBiometricAuthToken(operType, TuiAuthToken.authToken, authTokenData).then((newAuthToken) => {
        let authToken = newAuthToken.authToken as Uint8Array;
        hilog.info(0x0000, TAG, `authToken content: ${authToken}`);
      });
    }
  })
  userAuthInstance.start();
} catch (err) {
  let e: BusinessError = err as BusinessError;
  hilog.error(0x0000, TAG, 'getUserAuthInstance failed: %{public}d %{public}s', e.code, e.message);
}

trustedAuthentication.importData

importData(data: ArrayBuffer, authID: bigint): Promise<void>

Imports backup data (the encryption key information used during HUKS signing and signature verification). This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 26.0.0.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.TrustedAuthentication

Device behavior differences: For version earlier than 6.1.1(24), this API is supported on phones and tablets. On other device types, it returns service error code 1019100016. For 6.1.1(24) and later versions, this API is supported on phones, tablets that support the TUI capability, and PCs/2-in-1 devices. On tablets that do not support the TUI capability, PCs/2-in-1 devices, and other device types, this API returns service error code 1019100016. You can use the checkConfirmUITextFormat API to check whether the capability is supported.

Since: 6.0.0(20)

Parameters:

Name Type Mandatory Description
data ArrayBuffer Yes Generally, this parameter is set to the wrapkey data obtained from Universal Keystore Kit. The imported data cannot exceed 2048 bytes. The data cannot be imported repeatedly.
authID bigint Yes authID obtained during password creation.

Returns:

Type Description
Promise<void> Promise that returns no value.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
1019100001 The interface invoker does not have the corresponding permission.
1019100002

Parameter error.

Possible causes:

1. Mandatory parameters are left unspecified.

2. Incorrect parameter types.

3. Parameter verification failed.
1019100010 Failed to import data.
1019100012 Invalid authentication ID.
1019100023

Secure element fault.

Applicable versions: 26.0.0+

Example:

import { trustedAuthentication} from '@kit.DeviceSecurityKit';
import { BusinessError} from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG = 'TrustedAuthenticationJsTest';

try {
 const authID: bigint = 1687413472599354502n;
 const buffer = new ArrayBuffer(8);
 const bufferArray = new Uint8Array(buffer);
 bufferArray.set([1, 2, 3, 4, 5, 6, 7, 8]);
 const result = await trustedAuthentication.importData(buffer, authID);
} catch (err) {
  let e: BusinessError = err as BusinessError;
  hilog.error(0x0000, TAG, 'importData failed: %{public}d %{public}s', e.code, e.message);
}

trustedAuthentication.exportData

exportData(authID: bigint, label: TUILable): Promise<ArrayBuffer>

Exports backup data (the encryption key information used during HUKS signing and signature verification). The backup data can be exported only after the password authentication is successful. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 26.0.0.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.TrustedAuthentication

Device behavior differences: For version earlier than 6.1.1(24), this API is supported on phones and tablets. On other device types, it returns service error code 1019100016. For 6.1.1(24) and later versions, this API is supported on phones, tablets that support the TUI capability, and PCs/2-in-1 devices. On tablets that do not support the TUI capability, PCs/2-in-1 devices, and other device types, this API returns service error code 1019100016. You can use the checkConfirmUITextFormat API to check whether the capability is supported.

Since: 6.0.0(20)

Parameters:

Name Type Mandatory Description
authID bigint Yes authID obtained during password creation.
label TUILable Yes Custom information for TUI display. For details, please refer to TUILable.

Returns:

Type Description
Promise<ArrayBuffer> Promise used to return the backup data.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
1019100001 The interface invoker does not have the corresponding permission.
1019100002

Parameter error.

Possible causes:

1. Mandatory parameters are left unspecified.

2. Incorrect parameter types.

3. Parameter verification failed.
1019100009 Failed to export data.
1019100012 Invalid authentication ID.
1019100023

Secure element fault.

Applicable versions: 26.0.0+
1019100025

The TUI is occupied by another app.

Applicable versions: 6.1.1(24)+

Example:

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

const TAG = 'TrustedAuthenticationJsTest';

try {
 const credentialID: bigint = 1687413472599354502n;
 let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
 const resourceMgr: resourceManager.ResourceManager = context.resourceManager;
 const fileData : Uint8Array = await resourceMgr.getRawFileContent('test_logo_rgba.png');
 const buffer = fileData.buffer;
 const label:trustedAuthentication.TUILable = {
  image: buffer as ArrayBuffer,
  title: "Export Backup Data",
 }
 const result = await trustedAuthentication.exportData(credentialID, label);
} catch (err) {
  let e: BusinessError = err as BusinessError;
  hilog.error(0x0000, TAG, 'exportData failed: %{public}d %{public}s', e.code, e.message);
}

trustedAuthentication.checkConfirmUITextFormat

checkConfirmUITextFormat(text: string): Promise<TextCheckResult>

Checks whether the content to be displayed on the TUI can be completely displayed in a single line on the screen. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 26.0.0.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.TrustedAuthentication

Device behavior differences: For version earlier than 6.1.1(24), this API is supported on phones and tablets. On other device types, it returns service error code 1019100016. For 6.1.1(24) and later versions, this API is supported on phones, tablets that support the TUI capability, and PCs/2-in-1 devices. On tablets that do not support the TUI capability, PCs/2-in-1 devices, and other device types, this API returns service error code 1019100016.

Since: 6.0.0(20)

Parameters:

Name Type Mandatory Description
text string Yes Authentication information to be displayed on the TUI. Before transaction authentication, you can use this API to check whether the transaction information can be completely displayed in a single line on the screen. The length of the transaction information ranges from 1 to 200 bytes.

Returns:

Type Description
Promise<TextCheckResult> Promise used to return the check result about the display check result of the specified text on the TUI.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
1019100001 The interface invoker does not have the corresponding permission.
1019100002

Parameter error.

Possible causes:

1. Mandatory parameters are left unspecified.

2. Incorrect parameter types.

3. Parameter verification failed.
1019100006 Check input confirm text failed.
1019100025

The TUI is occupied by another app.

Applicable versions: 6.1.1(24)+

Example:

import { trustedAuthentication} from '@kit.DeviceSecurityKit';
import { BusinessError} from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG = 'TrustedAuthenticationJsTest';

try {
 const text: string = "Check whether the text to be displayed on the TUI can be properly displayed.";
 const result = await trustedAuthentication.checkConfirmUITextFormat(text);
} catch (err) {
  let e: BusinessError = err as BusinessError;
  hilog.error(0x0000, TAG, 'checkConfirmUITextFormat failed: %{public}d %{public}s', e.code, e.message);
}

You can use this API to indirectly determine whether a device has the TUI capability.

Example:

import { trustedAuthentication} from '@kit.DeviceSecurityKit';
import { BusinessError} from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
const TAG = 'TrustedAuthenticationJsTest';

async function isSupportTUI():Promise<boolean> {
  if (canIUse('SystemCapability.Security.TrustedAuthentication')) {
    let text = 'a'; // Any short string.
    try {
      const result = await trustedAuthentication.checkConfirmUITextFormat(text);
      if (result.result == 0) {
        return true;
      }
    } catch (error) {
      hilog.error(0x0000, TAG, 'The trusted authentication feature is not enabled.');
      return false;
    }
  }
  return false;
}
let supportFlag:boolean = await isSupportTUI();

trustedAuthentication.getRemainAuthTimes

getRemainAuthTimes(authID: bigint): Promise<number>

Obtains the number of remaining authentication times of the digital shield. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 26.0.0.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.TrustedAuthentication

Device behavior differences: For version earlier than 6.1.1(24), this API is supported on phones and tablets. On other device types, it returns service error code 1019100016. For 6.1.1(24) and later versions, this API is supported on phones, tablets that support the TUI capability, and PCs/2-in-1 devices. On tablets that do not support the TUI capability, PCs/2-in-1 devices, and other device types, this API returns service error code 1019100016. You can use the checkConfirmUITextFormat API to check whether the capability is supported.

Since: 6.0.0(20)

Parameters:

Name Type Mandatory Description
authID bigint Yes authID obtained during password creation.

Returns:

Type Description
Promise<number> Promise used to return the number of remaining authentication times of the digital shield.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
1019100001 The interface invoker does not have the corresponding permission.
1019100002

Parameter error.

Possible causes:

1. Mandatory parameters are left unspecified.

2. Incorrect parameter types.

3. Parameter verification failed.
1019100012 Invalid authentication ID.
1019100017 Failed to get the remaining number of authentication attempts.
1019100023

Secure element fault.

Applicable versions: 26.0.0+

Example:

import { trustedAuthentication} from '@kit.DeviceSecurityKit';
import { BusinessError} from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG = 'TrustedAuthenticationJsTest';

try {
 const authID: bigint = 1687413472599354502n;
 const remainTimes = await trustedAuthentication.getRemainAuthTimes(authID);
} catch (err) {
  let e: BusinessError = err as BusinessError;
  hilog.error(0x0000, TAG, 'getRemainAuthTimesfailed: %{public}d %{public}s', e.code, e.message);
}

trustedAuthentication.disableTrustedBioAuthentication

disableTrustedBioAuthentication(authID: bigint, authType: AuthType): Promise<void>

Disables the authentication capability of a specified biometric feature. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 26.0.0.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.TrustedAuthentication

Device behavior differences: For version earlier than 6.1.1(24), this API is supported on phones and tablets. On other device types, it returns service error code 1019100016. For 6.1.1(24) and later versions, this API is supported on phones, tablets that support the TUI capability, and PCs/2-in-1 devices. On tablets that do not support the TUI capability, PCs/2-in-1 devices, and other device types, this API returns service error code 1019100016. You can use the checkConfirmUITextFormat API to check whether the capability is supported.

Since: 6.0.0(20)

Parameters:

Name Type Mandatory Description
authID bigint Yes authID obtained during password creation.
authType AuthType Yes The value can only be AUTH_TYPE_FACE or AUTH_TYPE_FINGERPRINT.

Returns:

Type Description
Promise<void> Promise that returns no value.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
1019100001 The interface invoker does not have the corresponding permission.
1019100002

Parameter error.

Possible causes:

1. Mandatory parameters are left unspecified.

2. Incorrect parameter types.

3. Parameter verification failed.
1019100012 Invalid authentication ID.
1019100018 Failed to unbind the corresponding biometric data.
1019100021 The corresponding biometric data has not been bound.

Example:

import { trustedAuthentication} from '@kit.DeviceSecurityKit';
import { BusinessError} from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG = 'TrustedAuthenticationJsTest';

try {
 const authID: bigint = 1687413472599354502n;
 const remainTimes = await trustedAuthentication.disableTrustedBioAuthentication(authID, trustedAuthentication.AuthType.AUTH_TYPE_FACE);
} catch (err) {
  let e: BusinessError = err as BusinessError;
  hilog.error(0x0000, TAG, 'disableTrustedBioAuthentication: %{public}d %{public}s', e.code, e.message);
}

trustedAuthentication.getSecurityLevel

getSecurityLevel(authID?: bigint): Promise<SecurityLevel>

Obtains the highest security level supported by the system for enabling the digital shield or the security level corresponding to a specified digital shield. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 26.0.0.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.TrustedAuthentication

Device behavior differences: For version earlier than API 24, this API is supported on phones and tablets. On other device types, it returns service error code 1019100016. For API 24 and later versions, this API is supported on phones, tablets that support the TUI capability, and PCs/2-in-1 devices. On tablets that do not support the TUI capability, PCs/2-in-1 devices, and other device types, this API returns service error code 1019100016. You can use the checkConfirmUITextFormat API to check whether the capability is supported.

Since: 26.0.0

Parameters:

Name Type Mandatory Description
authID bigint No authID corresponding to the digital shield. If this parameter is not set, it indicates querying the highest security level supported by the system for enabling the digital shield.

Returns:

Type Description
Promise<SecurityLevel> Promise used to return the security level of the system or digital shield.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
1019100001 The interface invoker does not have the corresponding permission.
1019100012 Invalid authentication ID.
1019100016 The trusted authentication feature is not enabled.

Example:

import { trustedAuthentication} from '@kit.DeviceSecurityKit';
import { BusinessError} from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG = "TrustedAuthenticationJsTest";

try {
  const securityLevel = await trustedAuthentication.getSecurityLevel();
  hilog.info(0x0000, TAG, `The current system supports enabling the highest security level for the digital shield is: ${securityLevel}`);
} catch (err) {
  let e: BusinessError = err as BusinessError;
  hilog.error(0x0000, TAG, 'get system securityLevel failed: %{public}d %{public}s', e.code, e.message);
}

try {
 const authID: bigint = 1687413472599354502n;
 const securityLevel = await trustedAuthentication.getSecurityLevel(authID);
  hilog.info(0x0000, TAG, `The digital shield security level is: ${securityLevel}`);
} catch (err) {
  let e: BusinessError = err as BusinessError;
  hilog.error(0x0000, TAG, 'getSecurityLevel failed: %{public}d %{public}s', e.code, e.message);
}

PasswordInfo

Specifies the requirements on the password parameters during password setup.

Atomic service API: This API can be used in atomic services since API version 26.0.0.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.TrustedAuthentication

Since: 6.0.0(20)

Name Type Read-Only Optional Description
pwdType PasswordType No No Password type. For details about the value range, please refer to PasswordType.
pwdMaxLength number No No Maximum password length. The value ranges from 6 to 18.
pwdMinLength number No No Minimum password length. The value ranges from 6 to 18 and must be less than or equal to the value of pwdMaxLength.
maxAuthFailCount number No No Maximum number of consecutive password authentication failures. The value ranges from 1 to 10.
securityLevel SecurityLevel No Yes

Security level of the digital shield to be enabled. If this parameter is not passed, SECURITY_LEVEL_TEE is used by default. This parameter is valid when** enableTrustedAuthentication** is called. When modifyTrustedAuthenticationPwd is called, this parameter does not take effect and the security level of the current digital shield is used.

Since: 26.0.0

TUILable

Custom information on the TUI, including the logo and page title.

Atomic service API: This API can be used in atomic services since API version 26.0.0.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.TrustedAuthentication

Since: 6.0.0(20)

Name Type Read-Only Optional Description
image ArrayBuffer No No Custom logo information. The image must be in PNG RGBA format, and the maximum width and height must be 216 px.
title string No No Custom TUI page title. The maximum length is 31 bytes.

AuthInfo

Parameters for enabling the digital shield service.

Atomic service API: This API can be used in atomic services since API version 26.0.0.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.TrustedAuthentication

Since: 6.0.0(20)

Name Type Read-Only Optional Description
authToken Uint8Array No No authToken information, including the password authID.
authID bigint No No authID of the digital shield password, which is an index for password authentication, deletion, and change.

AuthToken

authToken obtained after a specified digital shield operation. The encrypted information contained in the authToken varies depending on the operation process. For details, please refer to the parameter description of each API.

Atomic service API: This API can be used in atomic services since API version 26.0.0.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.TrustedAuthentication

Since: 6.0.0(20)

Name Type Read-Only Optional Description
authToken Uint8Array No No authToken in an operation process.

AuthType

Enumerates the transaction authentication types.

Atomic service API: This API can be used in atomic services since API version 26.0.0.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.TrustedAuthentication

Since: 6.0.0(20)

Name Value Description
AUTH_TYPE_FACE 2 Facial authentication
AUTH_TYPE_FINGERPRINT 4 Fingerprint authentication.
AUTH_TYPE_TUI_PIN 32 TUI password authentication.

SecurityLevel

Enumerates the security levels of the digital shield.

Atomic service API: This API can be used in atomic services since API version 26.0.0.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.TrustedAuthentication

Since: 26.0.0

Name Value Description
SECURITY_LEVEL_TEE 0 TEE security level.
SECURITY_LEVEL_SE 1 SE security level.

PasswordType

Enumerates the password types. The secure keyboard displayed on the TUI varies depending on the password type.

Atomic service API: This API can be used in atomic services since API version 26.0.0.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.TrustedAuthentication

Since: 6.0.0(20)

Name Value Description
PASSWORD_TYPE_DIGITAL 0 Numeric password containing only digits.
PASSWORD_TYPE_MIXED 1 Alphanumeric password containing digits and other characters.

OperateType

Enumerates the operation types.

Atomic service API: This API can be used in atomic services since API version 26.0.0.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.TrustedAuthentication

Since: 6.0.0(20)

Name Value Description
OPERATE_TYPE_BIOMETRIC_AUTH 1 Binds biometric features to password authentication.
OPERATE_TYPE_CONTENT_AUTH 2 Uses biometric features for transaction authentication.

AuthReqParams

Transaction authentication request parameters.

Atomic service API: This API can be used in atomic services since API version 26.0.0.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.TrustedAuthentication

Since: 6.0.0(20)

Name Type Read-Only Optional Description
reqType AuthType No No Authentication type. For details about the value range, please refer to AuthType.
authContent Array<string> No No Authentication data, that is, transaction data in the transaction scenario. The size of a single data record cannot exceed 1024 bytes. Line breaks must be represented by \n, and \r\n is not supported.

TextCheckResult

Defines the check result of whether text information can be displayed in a single line on the TUI.

Atomic service API: This API can be used in atomic services since API version 26.0.0.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.TrustedAuthentication

Since: 6.0.0(20)

Name Type Read-Only Optional Description
result number No No Check result for the specified input text. If the text can be displayed properly, 0 is returned. Otherwise, 1019100011 Invalid TUI Authentication Information is returned.
lastIndex number No No Index of the last character that can be properly displayed in the input string.

TrustedAuthErrorCode

Enumerates the error codes indicating the execution failure of a digital shield open API.

Atomic service API: This API can be used in atomic services since API version 26.0.0.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.TrustedAuthentication

Since: 6.0.0(20)

Name Value Description
TRUSTED_AUTH_ERROR_NO_PERMISSION 1019100001 Permission verification failed.
TRUSTED_AUTH_ERROR_ILLEGAL_ARGUMENT 1019100002 Parameter check failed.
TRUSTED_AUTH_ERROR_PWD_LIMIT_REACHED 1019100003 The number of consecutive password authentication failures reaches the upper limit defined by the app.
TRUSTED_AUTH_ERROR_PWD_DELETE_FAILED 1019100004 Failed to delete the password.
TRUSTED_AUTH_ERROR_VERIFY_FAILED 1019100005 Password authentication failed.
TRUSTED_AUTH_ERROR_CHECK_CONFIRM_TEXT_FAILED 1019100006 Input text check failed.
TRUSTED_AUTH_ERROR_NOT_SUPPORT_IMAGE 1019100007 Unsupported image format.
TRUSTED_AUTH_ERROR_USER_REQ_CANCEL 1019100008 The user canceled the operation.
TRUSTED_AUTH_ERROR_EXPORT_DATA_FAILED 1019100009 Failed to export the backup data.
TRUSTED_AUTH_ERROR_IMPORT_DATA_FAILED 1019100010 Failed to import the backup data.
TRUSTED_AUTH_ERROR_INVALID_CONTENT 1019100011 Invalid TUI authentication information.
TRUSTED_AUTH_ERROR_INVALID_AUTH_ID 1019100012 Invalid authID.
TRUSTED_AUTH_ERROR_SET_PWD_FAILED 1019100013 Failed to create the password.
TRUSTED_AUTH_ERROR_MODIFY_PWD_FAILED 1019100014 Failed to change the password.
TRUSTED_AUTH_ERROR_BIO_RESIGN_FAILED 1019100015 Failed to issue the authToken for biometric authentication.
TRUSTED_AUTH_FEATURE_INITIALIZATION_FAILED 1019100016 The digital shield service is not enabled.
TRUSTED_AUTH_ERROR_GET_REMAIN_TIME 1019100017 Failed to obtain the number of remaining authentication times of the digital shield.
TRUSTED_AUTH_ERROR_DISABLE_BIO_AUTH 1019100018 Failed to disable the authentication capability of a specified biometric feature.
TRUSTED_AUTH_ERROR_BIO_MISMATCH 1019100019 The authenticated biometric feature does not match the bound biometric feature.
TRUSTED_AUTH_ERROR_BIO_REPEATED_BIND 1019100020 The biometric feature has been bound.
TRUSTED_AUTH_ERROR_NOT_BIND_BIO 1019100021 The biometric feature is not bound.
TRUSTED_AUTH_ERROR_SE_FAULT 1019100023

The security element is faulty.

Applicable versions: 26.0.0+
TRUSTED_AUTH_ERROR_BIO_ID_INVALID 1019100024

The bound biometric ID is invalid.

Applicable versions: 26.0.0+
TRUSTED_AUTH_ERROR_TUI_OCCUPIED 1019100025

The TUI is occupied by another app.

Applicable versions: 6.1.1(24)+