## 场景介绍

在完成数字盾密码设置后，用户可以在数字盾密码认证成功后，将系统已录入的人脸或指纹信息与账户绑定，即开通生物特征认证能力。此后，用户即可通过已绑定的生物特征（人脸或指纹）快速完成转账交易的身份验证。

## 约束与限制

本功能目前仅在手机设备支持。人脸认证功能仅支持具备**3D人脸识别能力**的设备，目前仅支持绑定一个指纹/人脸用于支付认证，且需应用服务器端同步接入配合端云协同认证。通过用户认证服务提供的接口[查询支持的认证能力](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/obtain-supported-authentication-capabilities)，可确认设备是否支持3D人脸。

## 业务流程

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/e8/v3/FFlMTAdjQlCdm0xXhLA_NA/zh-cn_image_0000002482788454.jpg?HW-CC-KV=V1&HW-CC-Date=20260414T043237Z&HW-CC-Expire=86400&HW-CC-Sign=9945719E8FCC4A9CA8085C39CCEBB7398E36AD95A787EBD2CCCF6C3171914BE0 "点击放大")

## 接口说明

接口及使用方法请参见[API参考](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/devicesecurity-trusted-auth-api)。

展开

| 接口名 | 描述 |
| --- | --- |
| [trustedAuthentication](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/devicesecurity-trusted-auth-api#section6763105845111)(challenge: Uint8Array, authID: bigint, label: TUILable): Promise<[AuthToken](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/devicesecurity-trusted-auth-api#section20919104010476)> | 数字盾密码认证 |
| [getBiometricAuthToken](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/devicesecurity-trusted-auth-api#section627215120542)(operType: [OperateType](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/devicesecurity-trusted-auth-api#section14617053498), tuiAuthToken: Uint8Array, bioAuthToken: Uint8Array): Promise<AuthToken> | 获取生物特征绑定完成后生成的authToken信息 |

## 开通生物特征认证能力界面介绍

如图表示开通人脸认证时对应的UI界面示例，当密码认证通过后，则会拉起系统人脸认证界面进行人脸信息绑定。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/21/v3/BEELx4CzTt6kWIIhajYj3w/zh-cn_image_0000002482908414.png?HW-CC-KV=V1&HW-CC-Date=20260414T043237Z&HW-CC-Expire=86400&HW-CC-Sign=8AE76ABCED9BB611E53B5651164A40B1E75D6B9134703188A6DD34D492935370 "点击放大") ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/34/v3/t8OWvEBrRRyfYJZVk16WyA/zh-cn_image_0000002515108415.png?HW-CC-KV=V1&HW-CC-Date=20260414T043237Z&HW-CC-Expire=86400&HW-CC-Sign=E32BC871BC4992CCCA9F2066E82A67488ED9CBFAD5C329485179BBF1618E8895 "点击放大")

## 开发步骤

1. 导入huks 、userAuth 、trustedAuthentication和相关依赖模块。

   收起

   自动换行

   深色代码主题

   复制

   ```
   1. import { resourceManager } from '@kit.LocalizationKit'
   2. import { huks } from '@kit.UniversalKeystoreKit';
   3. import { userAuth } from '@kit.UserAuthenticationKit';
   4. import { BusinessError } from '@kit.BasicServicesKit';
   5. import { trustedAuthentication } from '@kit.DeviceSecurityKit';
   6. import { cryptoFramework } from '@kit.CryptoArchitectureKit';
   7. import { hilog } from '@kit.PerformanceAnalysisKit';
   8. import { common } from '@kit.AbilityKit';
   ```
2. 通过用户认证服务提供的接口[查询设备是否已录入相关凭证](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-useriam-userauth#userauthgetenrolledstate12)。
3. 参考密钥管理服务提供的[签名/验签指导](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/huks-signing-signature-verification-arkts)，初始化签名会话。
4. 调用数字盾密码认证接口[trustedAuthentication](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/devicesecurity-trusted-auth-api#section6763105845111)发起生物特征认证前的密码认证申请。

   收起

   自动换行

   深色代码主题

   复制

   ```
   1. async function PwdVerify(challenge: Uint8Array, context: common.UIAbilityContext):Promise<trustedAuthentication.AuthToken> {
   2. try {
   3. const authID: bigint = 11842183505170721246n;//实际填充为从服务器获取到的账号对应的authID值
   4. const resourceMgr: resourceManager.ResourceManager = context.resourceManager;
   5. const fileData : Uint8Array = await resourceMgr.getRawFileContent('test_logo_rgba.png'); //实际使用时请替换为应用要在TUI界面展示的logo图片名称
   6. const buffer = fileData.buffer;
   7. const label:trustedAuthentication.TUILable = {
   8. image: buffer as ArrayBuffer,
   9. title: "数字盾密码认证",
   10. }
   11. const result = await trustedAuthentication.trustedAuthentication(challenge, authID, label);
   12. return result;
   13. } catch (err) {
   14. hilog.error(0x0000, 'testTag', `Failed to trustedAuthentication, code:${err.code}, message:${err.message}`);
   15. throw new Error('Password verify failed:' + (err as BusinessError).message);
   16. }
   17. }
   18. const rand = cryptoFramework.createRandom();
   19. const len: number = 32;
   20. const challenge: Uint8Array = rand?.generateRandomSync(len)?.data;//实际使用时请替换为通过UniversalKeystoreKit初始化会话获取的challenge
   21. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
   22. const authToken: trustedAuthentication.AuthToken = await PwdVerify(challenge, context);
   ```
5. 通过用户认证服务提供的接口，拉起生物特征认证控件并[发起认证](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/start-authentication)。
6. 当订阅的生物认证结果获取到后，将数字盾密码认证结果和生物特征认证结果统一整合，发起生物特征绑定请求。

   收起

   自动换行

   深色代码主题

   复制

   ```
   1. let tuiAuthToken = new Uint8Array(1024);//实际使用时请替换为步骤6密码认证获取的authToken
   2. let bioAuthToken = new Uint8Array(1024);//实际使用时请替换为步骤7生物特征认证获取的authToken
   3. let operType = trustedAuthentication.OperateType.OPERATE_TYPE_BIOMETRIC_AUTH;
   4. trustedAuthentication.getBiometricAuthToken(operType, tuiAuthToken, bioAuthToken).then((newBioAuthToken) => {
   5. let authToken = newBioAuthToken.authToken as Uint8Array;
   6. });
   ```
7. 参考密钥管理服务提供的[签名/验签指导](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/huks-signing-signature-verification-arkts), 对返回生物特征绑定对应的authToken数据进行签名，并结束会话。
8. 应用可将签名获取的生物特征进行验签校验，并将生物特征credential信息与账号信息在服务器端绑定。