关闭数字盾服务
=======

#### 场景介绍

当用户不再使用数字盾时，可以通过密码认证主动发起关闭数字盾的操作；若用户忘记密码或连续密码认证失败次数达到最大限制导致数字盾密码锁定，当企业开发者应用将在重新激活数字盾时，无需进行密码认证直接关闭最初激活的数字盾，并通过[设置数字盾密码](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/devicesecurity-trustedauth-setpwd)重新创建新的数字盾密码。

#### 约束与限制

本功能在API 24之前版本仅支持Phone；API24及之后版本，新增支持具备TUI能力的PC/2in1、具备TUI能力的Tablet。可通过接口[checkConfirmUITextFormat](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/devicesecurity-trusted-auth-api#checkconfirmuitextformat)查询设备是否具备TUI能力。不支持的设备在调用数字盾服务相关业务接口时，返回错误码1019100016。

#### 业务流程

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/87/v3/1d4BQOgZTG2uE_jbBXzSyw/zh-cn_image_0000002594828550.jpg?HW-CC-KV=V1&HW-CC-Date=20260612T073411Z&HW-CC-Expire=86400&HW-CC-Sign=88B09C022B32D1A18F6FD7E913FB5569213627D5788B27C3A45310BF5F802FFD)

当不需要密码认证进行关闭数字盾申请时，则无需和Universal Keystore Kit交互，使用随机生成的challenge完成关闭数字盾操作。

#### 接口说明

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

| 接口名 | 描述 |
| :-- | :-- |
| [disableTrustedAuthentication](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/devicesecurity-trusted-auth-api#disabletrustedauthentication)(challenge: Uint8Array, needAuth: boolean, authID: bigint, label: TUILable): Promise<AuthToken> | 关闭数字盾服务 |

#### 关闭数字盾服务界面介绍

如图为需要进行密码认证的方式关闭数字盾服务时对应的TUI界面示例。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/8a/v3/Mc64Bp4nRGiKp-Wtsop3SQ/zh-cn_image_0000002625187997.png?HW-CC-KV=V1&HW-CC-Date=20260612T073411Z&HW-CC-Expire=86400&HW-CC-Sign=F422D36F8F777A91724E4F78ED0E7D68652603C4CB5EEB1F0CAD3DD7B6DFD966)

#### 开发步骤

#### \[h2\]密码认证方式关闭数字盾服务

1.  导入huks 、trustedAuthentication 和相关依赖模块。
    
    import { resourceManager } from '@kit.LocalizationKit'
    import { huks } from '@kit.UniversalKeystoreKit';
    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';
    
2.  关闭数字盾前，需从服务器获取当前账号在[设置数字盾密码](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/devicesecurity-trustedauth-setpwd)时获取的authID。
    
3.  参考密钥管理服务提供的[签名/验签指导](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/huks-signing-signature-verification-arkts)，初始化签名会话。
    
4.  调用关闭数字盾服务接口，发起数字盾服务关闭申请。
    
    // 关闭数字盾服务
    async function DisablePwd(challenge: Uint8Array, context: common.UIAbilityContext):Promise<trustedAuthentication.AuthToken> {
     try {
       const authID: bigint = 1687413472599354502n; // 实际填充为从服务器获取到的账号对应的authID值
       const resourceMgr: resourceManager.ResourceManager = context.resourceManager;
       const fileData : Uint8Array = await resourceMgr.getRawFileContent('test\_logo\_rgba.png'); // 实际使用时请替换为企业开发者应用要在TUI界面展示的logo图片名称
       const buffer = fileData.buffer;
       const label:trustedAuthentication.TUILable = {
         image: buffer as ArrayBuffer,
         title: "关闭数字盾",
       }
       const authToken = await trustedAuthentication.disableTrustedAuthentication(challenge, true, authID, label);
       return authToken;
     } catch (err) {
       hilog.error(0x0000, 'testTag', \`Failed to disableTrustedAuthentication, code:${err.code}, message:${err.message}\`);
       throw new Error('Close trusted authentication failed:' + (err as BusinessError).message);
     }
    }
    const rand = cryptoFramework.createRandom();
    const len: number = 32;
    const challenge: Uint8Array = rand?.generateRandomSync(len)?.data; // 实际使用时请替换为通过UniversalKeystoreKit初始化会话获取的challenge
    let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
    const authToken: trustedAuthentication.AuthToken = await DisablePwd(challenge, context);
    
5.  参考密钥管理服务提供的[签名/验签指导](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/huks-signing-signature-verification-arkts), 对通过关闭数字盾获取到的authToken数据进行签名，并结束会话。
    

#### \[h2\]无需密码认证方式关闭数字盾服务

使用cryptoFramework生成的32字节随机数作为challenge，直接调用关闭数字盾服务接口即可，生成的authToken信息未经过密码认证，不可进行签名校验。

// 关闭数字盾服务
async function DisablePwd(challenge: Uint8Array):Promise<trustedAuthentication.AuthToken> {
 try {
   const authID: bigint = 1687413472599354502n; // 实际填充为从服务器获取到的账号对应的authID值
   let emptyBuffer = new ArrayBuffer(0);
   const label:trustedAuthentication.TUILable = {
     image: emptyBuffer,
     title: "",
   }
   const authToken = await trustedAuthentication.disableTrustedAuthentication(challenge, false, authID, label);
   return authToken;
 } catch (err) {
   hilog.error(0x0000, 'testTag', \`Failed to disableTrustedAuthentication, code:${err.code}, message:${err.message}\`);
   throw new Error('Close trusted authentication failed:' + (err as BusinessError).message);
 }
}
const rand = cryptoFramework.createRandom();
const len: number = 32;
const challenge: Uint8Array = rand?.generateRandomSync(len)?.data; // 此处使用的challenge为通过cryptoFramework生成的32字节随机数即可
const authToken: trustedAuthentication.AuthToken = await DisablePwd(challenge);