1# @ohos.userIAM.userAuth (用户认证) 2 3<!--Kit: User Authentication Kit--> 4<!--Subsystem: UserIAM--> 5<!--Owner: @WALL_EYE--> 6<!--Designer: @lichangting518--> 7<!--Tester: @jane_lz--> 8<!--Adviser: @zengyawen--> 9 10提供用户认证能力，应用于设备解锁、支付、应用登录等场景。 11 12> **说明：** 13> 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 14 15 16## 导入模块 17 18```ts 19import { userAuth } from '@kit.UserAuthenticationKit'; 20``` 21 22## 常量 23 24| 名称 | 值 | 说明 | 25| ----------- | ---- | ---------- | 26| MAX_ALLOWABLE_REUSE_DURATION<sup>12+</sup> | 300000 | 复用解锁认证结果最大有效时长，值为300000毫秒。<br/> **系统能力：** SystemCapability.UserIAM.UserAuth.Core <br/> **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 27 28## UserAuthTipCode<sup>20+</sup> 29 30表示身份认证中间状态。 31 32**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 33 34**系统能力**：SystemCapability.UserIAM.UserAuth.Core 35 36| 名称 | 值 | 说明 | 37| ----------- | ---- | ---------- | 38| COMPARE_FAILURE | 1 | 认证失败。 | 39| TIMEOUT | 2 | 认证超时。 | 40| TEMPORARILY_LOCKED | 3 | 临时冻结。 | 41| PERMANENTLY_LOCKED | 4 | 永久冻结。 | 42| WIDGET_LOADED | 5 | 身份认证界面加载完毕。 | 43| WIDGET_RELEASED | 6 | 当前的身份认证界面退出，切换其他认证界面或身份认证控件关闭。 | 44| COMPARE_FAILURE_WITH_FROZEN | 7 | 认证失败并触发了认证冻结。 | 45 46## EnrolledState<sup>12+</sup> 47 48用户注册凭据的状态。 49 50**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 51 52**系统能力**：SystemCapability.UserIAM.UserAuth.Core 53 54| 名称 | 类型 | 只读 | 可选 | 说明 | 55| ------------ | ---------- | ---- | ---- | -------------------- | 56| credentialDigest | number | 否 | 否 | 注册的凭据摘要，在凭据增加时随机生成。| 57| credentialCount | number | 否 | 否 | 注册的凭据数量。 | 58 59## ReuseMode<sup>12+</sup> 60 61复用解锁认证结果的模式。 62 63**系统能力**：SystemCapability.UserIAM.UserAuth.Core 64 65| 名称 | 值 | 说明 | 66| ----------- | ---- | ---------- | 67| AUTH_TYPE_RELEVANT | 1 | 与认证类型相关，只有当设备解锁认证结果在有效时间内，并且设备解锁的认证类型匹配上本次认证指定认证类型之一时，可以复用该结果。<br/> **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 68| AUTH_TYPE_IRRELEVANT | 2 | 与认证类型无关，设备解锁认证结果在有效时间内，可以重复使用。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 69| CALLER_IRRELEVANT_AUTH_TYPE_RELEVANT<sup>14+</sup> | 3 | 与认证类型相关，任意身份认证（包括设备解锁）结果在有效时间内，并且身份认证的认证类型匹配上本次认证指定认证类型之一时，可以复用该结果。<br/>**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 70| CALLER_IRRELEVANT_AUTH_TYPE_IRRELEVANT<sup>14+</sup> | 4 | 与认证类型无关，任意身份认证（包括设备解锁）结果在有效时间内，可以重复使用。<br/>**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 71 72## ReuseUnlockResult<sup>12+</sup> 73 74复用解锁认证结果。 75> **说明**： 76> 77> 如果身份认证解锁（包括设备解锁）后，在有效时间内凭据发生了变化，身份认证的结果依然可以复用，认证结果中返回当前实际的EnrolledState。若复用认证结果时，之前认证时所使用的身份认证凭据已经被删除，如果删除的是人脸、指纹，则认证结果依然可以复用，只是返回的EnrolledState中credentialCount和credentialDigest均为0；如果删除的是锁屏口令，则此次复用会失败。 78 79**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 80 81**系统能力**：SystemCapability.UserIAM.UserAuth.Core 82 83| 名称 | 类型 | 必填 | 说明 | 84| ------------ | ---------- | ---- | -------------------- | 85| reuseMode | [ReuseMode](#reusemode12) | 是 | 复用解锁认证结果的模式。 | 86| reuseDuration | number | 是 | 允许复用解锁认证结果的有效时长，有效时长的值应大于0，最大值为[MAX_ALLOWABLE_REUSE_DURATION](#常量)。 | 87 88## userAuth.getEnrolledState<sup>12+</sup> 89 90getEnrolledState(authType : UserAuthType): EnrolledState 91 92查询凭据注册的状态，以检测用户注册凭据的变更。 93 94**需要权限**：ohos.permission.ACCESS_BIOMETRIC 95 96**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 97 98**系统能力**：SystemCapability.UserIAM.UserAuth.Core 99 100**参数：** 101 102| 参数名 | 类型 | 必填 | 说明 | 103| -------------- | ---------------------------------- | ---- | -------------------------- | 104| authType | [UserAuthType](#userauthtype8) | 是 | 认证类型。| 105 106**返回值：** 107 108| 类型 | 说明 | 109| --------------------- | ------------------------------------------------------------ | 110| [EnrolledState](#enrolledstate12) | 当查询成功时，返回值为用户注册凭据的状态。| 111 112**错误码：** 113 114以下错误码的详细介绍请参见[用户认证错误码](errorcode-useriam.md)。 115 116| 错误码ID | 错误信息 | 117| -------- | ------- | 118| 201 | Permission denied. | 119| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. | 120| 12500002 | General operation error. | 121| 12500005 | The authentication type is not supported. | 122| 12500010 | The type of credential has not been enrolled. | 123 124**示例：** 125 126```ts 127import { userAuth } from '@kit.UserAuthenticationKit'; 128import { BusinessError } from '@kit.BasicServicesKit'; 129 130try { 131 let enrolledState = userAuth.getEnrolledState(userAuth.UserAuthType.FACE); 132 console.info(`get current enrolled state success, enrolledState = ${JSON.stringify(enrolledState)}`); 133} catch (error) { 134 const err: BusinessError = error as BusinessError; 135 console.error(`get current enrolled state failed, Code is ${err?.code}, message is ${err?.message}`); 136} 137``` 138 139## AuthParam<sup>10+</sup> 140 141用户认证相关参数。 142 143**系统能力**：SystemCapability.UserIAM.UserAuth.Core 144 145| 名称 | 类型 | 必填 | 说明 | 146| -------------- | ---------------------------------- | ---- | ------------------------------------------------------------ | 147| challenge | Uint8Array | 是 | 随机挑战值，可用于防重放攻击。最大长度为32字节，可传Uint8Array([])。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 148| authType | [UserAuthType](#userauthtype8)[] | 是 | 认证类型列表，用来指定用户认证界面提供的认证方法。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 149| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | 是 | 期望达到的认证可信等级。典型操作需要的身份认证可写等级，以及身份认证可信等级的划分请参见[认证可信等级划分原则](../../security/UserAuthenticationKit/user-authentication-overview.md#生物认证可信等级划分原则)。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 150| reuseUnlockResult<sup>12+</sup> | [ReuseUnlockResult](#reuseunlockresult12) | 否 |表示可以复用解锁认证的结果。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 151| skipLockedBiometricAuth<sup>20+</sup> | boolean | 否 | 是否跳过已禁用的认证方式自动切换至其它方式的认证，true表示已跳过，false表示未跳过，若无可切换的认证方式则关闭控件，返回认证冻结错误码。<br>**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。| 152 153## WidgetParam<sup>10+</sup> 154 155用户认证界面配置相关参数。 156 157**系统能力**：SystemCapability.UserIAM.UserAuth.Core 158 159| 名称 | 类型 | 必填 | 说明 | 160| -------------------- | ----------------------------------- | ---- | ------------------------------------------------------------ | 161| title | string | 是 | 用户认证界面的标题，建议传入认证目的，例如用于支付、登录应用等，不支持传空字串，最大长度为500字符。 <br> **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 162| navigationButtonText | string | 否 | 导航按键的说明文本，最大长度为60字符。在单指纹、单人脸场景下支持，从API 18开始，增加支持人脸+指纹场景。 <br> **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 163| uiContext<sup>18+</sup> | Context | 否 | 以模应用方式显示身份认证对话框，仅支持在2in1设备上使用，如果没有此参数或其他类型的设备，身份认证对话框将以模系统方式显示。 <br> **原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。| 164 165## UserAuthResult<sup>10+</sup> 166 167用户认证结果。认证成功时，返回认证类型和认证成功的令牌信息。 168 169**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 170 171**系统能力**：SystemCapability.UserIAM.UserAuth.Core 172 173| 名称 | 类型 | 必填 | 说明 | 174| -------- | ------------------------------ | ---- | ------------------------------------------------------------ | 175| result | number | 是 | 用户认证结果。若成功返回SUCCESS，若失败返回相应错误码，参见[UserAuthResultCode](#userauthresultcode9)。 | 176| token | Uint8Array | 否 | 认证成功时，返回认证成功的令牌信息。最大长度为1024字节。 | 177| authType | [UserAuthType](#userauthtype8) | 否 | 认证成功时，返回认证类型。 | 178| enrolledState<sup>12+</sup> | [EnrolledState](#enrolledstate12) | 否 | 认证成功时，返回注册凭据的状态。| 179 180## IAuthCallback<sup>10+</sup> 181 182返回认证结果的回调对象。 183 184### onResult<sup>10+</sup> 185 186onResult(result: UserAuthResult): void 187 188回调函数，返回认证结果。认证成功时，可以通过UserAuthResult获取到认证成功的令牌信息。 189 190**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 191 192**系统能力**：SystemCapability.UserIAM.UserAuth.Core 193 194**参数：** 195 196| 参数名 | 类型 | 必填 | 说明 | 197| ------ | ----------------------------------- | ---- | ---------- | 198| result | [UserAuthResult](#userauthresult10) | 是 | 认证结果。 | 199 200**示例1：** 201 202发起用户认证，采用认证可信等级≥ATL3的锁屏口令认证，获取认证结果： 203 204```ts 205import { BusinessError } from '@kit.BasicServicesKit'; 206import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 207import { userAuth } from '@kit.UserAuthenticationKit'; 208 209try { 210 const rand = cryptoFramework.createRandom(); 211 const len: number = 16; 212 let randData: Uint8Array | null = null; 213 let retryCount = 0; 214 while(retryCount < 3){ 215 randData = rand?.generateRandomSync(len)?.data; 216 if(randData){ 217 break; 218 } 219 retryCount++; 220 } 221 if(!randData){ 222 return; 223 } 224 const authParam: userAuth.AuthParam = { 225 challenge: randData, 226 authType: [userAuth.UserAuthType.PIN], 227 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 228 }; 229 const widgetParam: userAuth.WidgetParam = { 230 title: '请输入密码', 231 }; 232 233 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 234 console.info('get userAuth instance success'); 235 // 需要调用UserAuthInstance的start()接口，启动认证后，才能通过onResult获取到认证结果。 236 userAuthInstance.on('result', { 237 onResult (result) { 238 console.info(`userAuthInstance callback result = ${JSON.stringify(result)}`); 239 } 240 }); 241 console.info('auth on success'); 242 userAuthInstance.start(); 243 console.info('auth start success'); 244} catch (error) { 245 const err: BusinessError = error as BusinessError; 246 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 247} 248``` 249 250**示例2：** 251 252发起用户认证，采用认证可信等级≥ATL3的锁屏口令+认证类型相关+复用设备解锁最大有效时长认证，获取认证结果。 253 254```ts 255import { BusinessError } from '@kit.BasicServicesKit'; 256import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 257import { userAuth } from '@kit.UserAuthenticationKit'; 258 259let reuseUnlockResult: userAuth.ReuseUnlockResult = { 260 reuseMode: userAuth.ReuseMode.AUTH_TYPE_RELEVANT, 261 reuseDuration: userAuth.MAX_ALLOWABLE_REUSE_DURATION, 262} 263try { 264 const rand = cryptoFramework.createRandom(); 265 const len: number = 16; 266 let randData: Uint8Array | null = null; 267 let retryCount = 0; 268 while(retryCount < 3){ 269 randData = rand?.generateRandomSync(len)?.data; 270 if(randData){ 271 break; 272 } 273 retryCount++; 274 } 275 if(!randData){ 276 return; 277 } 278 const authParam: userAuth.AuthParam = { 279 challenge: randData, 280 authType: [userAuth.UserAuthType.PIN], 281 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 282 reuseUnlockResult: reuseUnlockResult, 283 }; 284 const widgetParam: userAuth.WidgetParam = { 285 title: '请输入密码', 286 }; 287 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 288 console.info('get userAuth instance success'); 289 // 需要调用UserAuthInstance的start()接口，启动认证后，才能通过onResult获取到认证结果。 290 userAuthInstance.on('result', { 291 onResult (result) { 292 console.info(`userAuthInstance callback result = ${JSON.stringify(result)}`); 293 } 294 }); 295 console.info('auth on success'); 296 userAuthInstance.start(); 297 console.info('auth start success'); 298} catch (error) { 299 const err: BusinessError = error as BusinessError; 300 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 301} 302``` 303 304**示例3：** 305 306发起用户认证，采用认证可信等级≥ATL3的锁屏口令+任意应用认证类型相关+复用任意应用最大有效时长认证，获取认证结果。 307 308```ts 309import { BusinessError } from '@kit.BasicServicesKit'; 310import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 311import { userAuth } from '@kit.UserAuthenticationKit'; 312 313let reuseUnlockResult: userAuth.ReuseUnlockResult = { 314 reuseMode: userAuth.ReuseMode.CALLER_IRRELEVANT_AUTH_TYPE_RELEVANT, 315 reuseDuration: userAuth.MAX_ALLOWABLE_REUSE_DURATION, 316} 317try { 318 const rand = cryptoFramework.createRandom(); 319 const len: number = 16; 320 let randData: Uint8Array | null = null; 321 let retryCount = 0; 322 while(retryCount < 3){ 323 randData = rand?.generateRandomSync(len)?.data; 324 if(randData){ 325 break; 326 } 327 retryCount++; 328 } 329 if(!randData){ 330 return; 331 } 332 const authParam: userAuth.AuthParam = { 333 challenge: randData, 334 authType: [userAuth.UserAuthType.PIN], 335 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 336 reuseUnlockResult: reuseUnlockResult, 337 }; 338 const widgetParam: userAuth.WidgetParam = { 339 title: '请输入密码', 340 }; 341 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 342 console.info('get userAuth instance success'); 343 // 需要调用UserAuthInstance的start()接口，启动认证后，才能通过onResult获取到认证结果。 344 userAuthInstance.on('result', { 345 onResult (result) { 346 console.info(`userAuthInstance callback result = ${JSON.stringify(result)}`); 347 } 348 }); 349 console.info('auth on success'); 350 userAuthInstance.start(); 351 console.info('auth start success'); 352} catch (error) { 353 const err: BusinessError = error as BusinessError; 354 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 355} 356``` 357 358## AuthTipInfo<sup>20+</sup> 359 360用户认证中间状态。 361 362**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 363 364**系统能力**：SystemCapability.UserIAM.UserAuth.Core 365 366| 名称 | 类型 | 只读 | 可选 | 说明 | 367| -------- | ------------------------------------ | ---- | ---- | ------------------------------------ | 368| tipType | [UserAuthType](#userauthtype8) | 否 | 否 | 中间状态对应的认证类型。 | 369| tipCode | [UserAuthTipCode](#userauthtipcode20) | 否 | 否 | 中间状态值。| 370 371## AuthTipCallback<sup>20+</sup> 372 373type AuthTipCallback = (authTipInfo: AuthTipInfo) => void 374 375回调函数，返回认证中间状态。 376 377**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 378 379**系统能力**：SystemCapability.UserIAM.UserAuth.Core 380 381**参数：** 382 383| 参数名 | 类型 | 必填 | 说明 | 384| ------ | -----------------------------------| ---- | ---------- | 385| authTipInfo | [AuthTipInfo](#authtipinfo20) | 是 | 认证中间状态。 | 386 387**示例：** 388 389```ts 390import { BusinessError } from '@kit.BasicServicesKit'; 391import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 392import { userAuth } from '@kit.UserAuthenticationKit'; 393 394try { 395 const rand = cryptoFramework.createRandom(); 396 const len: number = 16; 397 let randData: Uint8Array | null = null; 398 let retryCount = 0; 399 while(retryCount < 3){ 400 randData = rand?.generateRandomSync(len)?.data; 401 if(randData){ 402 break; 403 } 404 retryCount++; 405 } 406 if(!randData){ 407 return; 408 } 409 const authParam: userAuth.AuthParam = { 410 challenge: randData, 411 authType: [userAuth.UserAuthType.PIN], 412 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 413 }; 414 const widgetParam: userAuth.WidgetParam = { 415 title: '请输入密码', 416 }; 417 418 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 419 console.info('get userAuth instance success'); 420 // 需要调用UserAuthInstance的start()接口，启动认证后，才能通过onAuthTip获取到认证中间状态。 421 userAuthInstance.on('authTip', (authTipInfo: userAuth.AuthTipInfo) => { 422 console.info(`userAuthInstance callback authTipInfo = ${JSON.stringify(authTipInfo)}`); 423 }); 424 console.info('auth on success'); 425 userAuthInstance.start(); 426 console.info('auth start success'); 427} catch (error) { 428 const err: BusinessError = error as BusinessError; 429 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 430} 431``` 432 433## UserAuthInstance<sup>10+</sup> 434 435用于执行用户身份认证，并支持使用统一用户身份认证控件。 436使用以下接口前，需先通过[getUserAuthInstance](#userauthgetuserauthinstance10)方法获取UserAuthInstance对象。 437 438### on<sup>10+</sup> 439 440on(type: 'result', callback: IAuthCallback): void 441 442订阅用户身份认证的结果。 443 444**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 445 446**系统能力**：SystemCapability.UserIAM.UserAuth.Core 447 448**参数：** 449 450| 参数名 | 类型 | 必填 | 说明 | 451| -------- | --------------------------------- | ---- | ------------------------------------------ | 452| type | 'result' | 是 | 订阅事件类型，表明该事件用来返回认证结果。 | 453| callback | [IAuthCallback](#iauthcallback10) | 是 | 认证接口的回调函数，用于返回认证结果。 | 454 455**错误码：** 456 457以下错误码的详细介绍请参见[用户认证错误码](errorcode-useriam.md)。 458 459| 错误码ID | 错误信息 | 460| -------- | ------------------------ | 461| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 462| 12500002 | General operation error. | 463 464**示例1：** 465 466以模系统方式进行用户身份认证。 467 468```ts 469import { BusinessError } from '@kit.BasicServicesKit'; 470import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 471import { userAuth } from '@kit.UserAuthenticationKit'; 472 473try { 474 const rand = cryptoFramework.createRandom(); 475 const len: number = 16; 476 let randData: Uint8Array | null = null; 477 let retryCount = 0; 478 while(retryCount < 3){ 479 randData = rand?.generateRandomSync(len)?.data; 480 if(randData){ 481 break; 482 } 483 retryCount++; 484 } 485 if(!randData){ 486 return; 487 } 488 const authParam: userAuth.AuthParam = { 489 challenge: randData, 490 authType: [userAuth.UserAuthType.PIN], 491 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 492 }; 493 const widgetParam: userAuth.WidgetParam = { 494 title: '请输入密码', 495 }; 496 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 497 console.info('get userAuth instance success'); 498 // 需要调用UserAuthInstance的start()接口，启动认证后，才能通过onResult获取到认证结果。 499 userAuthInstance.on('result', { 500 onResult (result) { 501 console.info(`userAuthInstance callback result = ${JSON.stringify(result)}`); 502 } 503 }); 504 console.info('auth on success'); 505 userAuthInstance.start(); 506 console.info('auth start success'); 507} catch (error) { 508 const err: BusinessError = error as BusinessError; 509 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 510} 511``` 512 513**示例2：** 514 515以模应用方式进行用户身份认证。 516 517```ts 518import { BusinessError } from '@kit.BasicServicesKit'; 519import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 520import { userAuth } from '@kit.UserAuthenticationKit'; 521 522@Entry 523@Component 524struct Index { 525 modelApplicationAuth(): void { 526 try { 527 const rand = cryptoFramework.createRandom(); 528 const len: number = 16; 529 let randData: Uint8Array | null = null; 530 let retryCount = 0; 531 while(retryCount < 3){ 532 randData = rand?.generateRandomSync(len)?.data; 533 if(randData){ 534 break; 535 } 536 retryCount++; 537 } 538 if(!randData){ 539 return; 540 } 541 const authParam: userAuth.AuthParam = { 542 challenge: randData, 543 authType: [userAuth.UserAuthType.PIN], 544 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 545 }; 546 const uiContext: UIContext = this.getUIContext(); 547 const context: Context | undefined = uiContext.getHostContext(); 548 const widgetParam: userAuth.WidgetParam = { 549 title: '请输入密码', 550 uiContext: context, 551 }; 552 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 553 console.info('get userAuth instance success'); 554 // 需要调用UserAuthInstance的start()接口，启动认证后，才能通过onResult获取到认证结果。 555 userAuthInstance.on('result', { 556 onResult (result) { 557 console.info(`userAuthInstance callback result = ${JSON.stringify(result)}`); 558 } 559 }); 560 console.info('auth on success'); 561 userAuthInstance.start(); 562 console.info('auth start success'); 563 } catch (error) { 564 const err: BusinessError = error as BusinessError; 565 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 566 } 567 } 568 569 build() { 570 Column() { 571 Button('start auth') 572 .onClick(() => { 573 this.modelApplicationAuth(); 574 }) 575 } 576 } 577} 578``` 579 580### off<sup>10+</sup> 581 582off(type: 'result', callback?: IAuthCallback): void 583 584取消订阅用户身份认证的结果。 585 586> **说明**： 587> 588> 需要使用已经成功订阅事件的[UserAuthInstance](#userauthinstance10)对象调用该接口进行取消订阅。 589 590**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 591 592**系统能力**：SystemCapability.UserIAM.UserAuth.Core 593 594**参数：** 595 596| 参数名 | 类型 | 必填 | 说明 | 597| -------- | --------------------------------- | ---- | ------------------------------------------ | 598| type | 'result' | 是 | 订阅事件类型，表明该事件用来返回认证结果。 | 599| callback | [IAuthCallback](#iauthcallback10) | 否 | 认证接口的回调函数，用于返回认证结果。 | 600 601**错误码：** 602 603以下错误码的详细介绍请参见[用户认证错误码](errorcode-useriam.md)。 604 605| 错误码ID | 错误信息 | 606| -------- | ------------------------ | 607| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 608| 12500002 | General operation error. | 609 610**示例：** 611 612```ts 613import { BusinessError } from '@kit.BasicServicesKit'; 614import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 615import { userAuth } from '@kit.UserAuthenticationKit'; 616 617try { 618 const rand = cryptoFramework.createRandom(); 619 const len: number = 16; 620 let randData: Uint8Array | null = null; 621 let retryCount = 0; 622 while(retryCount < 3){ 623 randData = rand?.generateRandomSync(len)?.data; 624 if(randData){ 625 break; 626 } 627 retryCount++; 628 } 629 if(!randData){ 630 return; 631 } 632 const authParam: userAuth.AuthParam = { 633 challenge: randData, 634 authType: [userAuth.UserAuthType.PIN], 635 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 636 }; 637 const widgetParam: userAuth.WidgetParam = { 638 title: '请输入密码', 639 }; 640 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 641 console.info('get userAuth instance success'); 642 userAuthInstance.off('result', { 643 onResult (result) { 644 console.info(`auth off result = ${JSON.stringify(result)}`); 645 } 646 }); 647 console.info('auth off success'); 648} catch (error) { 649 const err: BusinessError = error as BusinessError; 650 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 651} 652``` 653 654### start<sup>10+</sup> 655 656start(): void 657 658开始认证。 659 660> **说明：** 661> 每个UserAuthInstance只能进行一次认证，需要再次认证时，必须重新获取UserAuthInstance。 662 663**需要权限**：ohos.permission.ACCESS_BIOMETRIC 或 ohos.permission.USER_AUTH_FROM_BACKGROUND（仅向系统应用开放） 664 665从API 20开始，仅系统应用可以通过申请ohos.permission.USER_AUTH_FROM_BACKGROUND，在后台发起认证。 666 667**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 668 669**系统能力**：SystemCapability.UserIAM.UserAuth.Core 670 671**错误码：** 672 673以下错误码的详细介绍请参见[用户认证错误码](errorcode-useriam.md)。 674 675| 错误码ID | 错误信息 | 676| -------- | ------------------------------------------------ | 677| 201 | Permission denied. Possible causes:1.No permission to access biometric. 2.No permission to start authentication from background.| 678| 401 | Parameter error. Possible causes: 1.Incorrect parameter types. | 679| 12500002 | General operation error. | 680| 12500003 | Authentication canceled. | 681| 12500005 | The authentication type is not supported. | 682| 12500006 | The authentication trust level is not supported. | 683| 12500009 | Authentication is locked out. | 684| 12500010 | The type of credential has not been enrolled. | 685| 12500011 | Switched to the customized authentication process. | 686| 12500013 | Operation failed because of PIN expired. | 687 688**示例：** 689 690```ts 691import { BusinessError } from '@kit.BasicServicesKit'; 692import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 693import { userAuth } from '@kit.UserAuthenticationKit'; 694 695try { 696 const rand = cryptoFramework.createRandom(); 697 const len: number = 16; 698 let randData: Uint8Array | null = null; 699 let retryCount = 0; 700 while(retryCount < 3){ 701 randData = rand?.generateRandomSync(len)?.data; 702 if(randData){ 703 break; 704 } 705 retryCount++; 706 } 707 if(!randData){ 708 return; 709 } 710 const authParam: userAuth.AuthParam = { 711 challenge: randData, 712 authType: [userAuth.UserAuthType.PIN], 713 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 714 }; 715 const widgetParam: userAuth.WidgetParam = { 716 title: '请输入密码', 717 }; 718 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 719 console.info('get userAuth instance success'); 720 userAuthInstance.start(); 721 console.info('auth start success'); 722} catch (error) { 723 const err: BusinessError = error as BusinessError; 724 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 725} 726``` 727 728### cancel<sup>10+</sup> 729 730cancel(): void 731 732取消认证。 733 734> **说明**： 735> 736> 此时UserAuthInstance必须是正在进行认证的对象。 737 738**需要权限**：ohos.permission.ACCESS_BIOMETRIC 739 740**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 741 742**系统能力**：SystemCapability.UserIAM.UserAuth.Core 743 744**错误码：** 745 746| 错误码ID | 错误信息 | 747| -------- | ------------------------------- | 748| 201 | Permission denied. | 749| 401 | Parameter error. Possible causes: 1.Incorrect parameter types. | 750| 12500002 | General operation error. | 751 752**示例：** 753 754```ts 755import { BusinessError } from '@kit.BasicServicesKit'; 756import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 757import { userAuth } from '@kit.UserAuthenticationKit'; 758 759try { 760 const rand = cryptoFramework.createRandom(); 761 const len: number = 16; 762 let randData: Uint8Array | null = null; 763 let retryCount = 0; 764 while(retryCount < 3){ 765 randData = rand?.generateRandomSync(len)?.data; 766 if(randData){ 767 break; 768 } 769 retryCount++; 770 } 771 if(!randData){ 772 return; 773 } 774 const authParam : userAuth.AuthParam = { 775 challenge: randData, 776 authType: [userAuth.UserAuthType.PIN], 777 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 778 }; 779 const widgetParam: userAuth.WidgetParam = { 780 title: '请输入密码', 781 }; 782 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 783 console.info('get userAuth instance success'); 784 // 需要调用UserAuthInstance的start()接口，启动认证后，才能调用cancel()接口。 785 userAuthInstance.start(); 786 console.info('auth start success'); 787 userAuthInstance.cancel(); 788 console.info('auth cancel success'); 789} catch (error) { 790 const err: BusinessError = error as BusinessError; 791 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 792} 793``` 794 795### on<sup>20+</sup> 796 797on(type: 'authTip', callback: AuthTipCallback): void 798 799订阅身份认证中间状态。 800 801**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 802 803**系统能力**：SystemCapability.UserIAM.UserAuth.Core 804 805**参数：** 806 807| 参数名 | 类型 | 必填 | 说明 | 808| -------- | ------------- | ---- | ------------------------------------------ | 809| type | string | 是 | 订阅事件类型，支持的事件为'authTip'，当[start()](#start10)调用完成，发起身份认证，触发该事件。 | 810| callback | [AuthTipCallback](#authtipcallback20) | 是 | 认证接口的回调函数，用于返回认证中间状态。 | 811 812**错误码：** 813 814以下错误码的详细介绍请参见[用户认证错误码](errorcode-useriam.md)。 815 816| 错误码ID | 错误信息 | 817| -------- | ------------------------ | 818| 12500002 | General operation error. | 819 820**示例：** 821 822```ts 823import { BusinessError } from '@kit.BasicServicesKit'; 824import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 825import { userAuth } from '@kit.UserAuthenticationKit'; 826 827try { 828 const rand = cryptoFramework.createRandom(); 829 const len: number = 16; 830 let randData: Uint8Array | null = null; 831 let retryCount = 0; 832 while(retryCount < 3){ 833 randData = rand?.generateRandomSync(len)?.data; 834 if(randData){ 835 break; 836 } 837 retryCount++; 838 } 839 if(!randData){ 840 return; 841 } 842 const authParam: userAuth.AuthParam = { 843 challenge: randData, 844 authType: [userAuth.UserAuthType.PIN], 845 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 846 }; 847 const widgetParam: userAuth.WidgetParam = { 848 title: '请输入密码', 849 }; 850 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 851 console.info('get userAuth instance success'); 852 // 需要调用UserAuthInstance的start()接口，启动认证后，才能通过onAuthTip获取到认证中间状态。 853 userAuthInstance.on('authTip', (authTipInfo: userAuth.AuthTipInfo) => { 854 console.info(`userAuthInstance callback authTipInfo = ${JSON.stringify(authTipInfo)}`); 855 }); 856 console.info('auth on success'); 857 userAuthInstance.start(); 858 console.info('auth start success'); 859} catch (error) { 860 const err: BusinessError = error as BusinessError; 861 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 862} 863``` 864 865### off<sup>20+</sup> 866 867off(type: 'authTip', callback?: AuthTipCallback): void 868 869取消订阅用户身份认证中间状态。 870 871> **说明**： 872> 873> 需要使用已经成功订阅事件的[UserAuthInstance](#userauthinstance10)对象调用该接口进行取消订阅。 874 875**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 876 877**系统能力**：SystemCapability.UserIAM.UserAuth.Core 878 879**参数：** 880 881| 参数名 | 类型 | 必填 | 说明 | 882| -------- | ------------- | ---- | ------------------------------------------ | 883| type | string | 是 | 取消订阅的事件类型，支持的事件为'authTip'，当[start()](#start10)调用完成，发起身份认证并调用[on()](#on20)订阅该事件后，调用该方法可取消订阅，不会再触发该事件。 | 884| callback | [AuthTipCallback](#authtipcallback20) | 否 | 认证接口的回调函数，用于返回认证中间状态。 当不传该参数时默认值为调用[on()](#on20)接口时传递的参数值。 | 885 886**错误码：** 887 888以下错误码的详细介绍请参见[用户认证错误码](errorcode-useriam.md)。 889 890| 错误码ID | 错误信息 | 891| -------- | ------------------------ | 892| 12500002 | General operation error. | 893 894**示例：** 895 896```ts 897import { BusinessError } from '@kit.BasicServicesKit'; 898import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 899import { userAuth } from '@kit.UserAuthenticationKit'; 900 901try { 902 const rand = cryptoFramework.createRandom(); 903 const len: number = 16; 904 let randData: Uint8Array | null = null; 905 let retryCount = 0; 906 while(retryCount < 3){ 907 randData = rand?.generateRandomSync(len)?.data; 908 if(randData){ 909 break; 910 } 911 retryCount++; 912 } 913 if(!randData){ 914 return; 915 } 916 const authParam: userAuth.AuthParam = { 917 challenge: randData, 918 authType: [userAuth.UserAuthType.PIN], 919 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 920 }; 921 const widgetParam: userAuth.WidgetParam = { 922 title: '请输入密码', 923 }; 924 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 925 console.info('get userAuth instance success'); 926 userAuthInstance.off('authTip', (authTipInfo: userAuth.AuthTipInfo) => { 927 console.info(`userAuthInstance callback authTipInfo = ${JSON.stringify(authTipInfo)}`); 928 }); 929 console.info('auth off success'); 930} catch (error) { 931 const err: BusinessError = error as BusinessError; 932 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 933} 934``` 935 936## userAuth.getUserAuthInstance<sup>10+</sup> 937 938getUserAuthInstance(authParam: AuthParam, widgetParam: WidgetParam): UserAuthInstance 939 940获取[UserAuthInstance](#userauthinstance10)对象，执行用户身份认证，并支持使用统一用户身份认证控件。 941 942> **说明：** 943> 每个UserAuthInstance只能进行一次认证，需要再次认证时，必须重新获取UserAuthInstance。 944 945**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 946 947**系统能力**：SystemCapability.UserIAM.UserAuth.Core 948 949**参数：** 950 951| 参数名 | 类型 | 必填 | 说明 | 952| ----------- | ----------------------------- | ---- | -------------------------- | 953| authParam | [AuthParam](#authparam10) | 是 | 用户认证相关参数。 | 954| widgetParam | [WidgetParam](#widgetparam10) | 是 | 用户认证界面配置相关参数。 | 955 956**返回值：** 957 958| 类型 | 说明 | 959| --------------------------------------- | -------------------------- | 960| [UserAuthInstance](#userauthinstance10) | 支持用户界面的认证器对象。 | 961 962**错误码：** 963 964以下错误码的详细介绍请参见[用户认证错误码](errorcode-useriam.md)。 965 966| 错误码ID | 错误信息 | 967| -------- | ------------------------------------------------ | 968| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 969| 12500002 | General operation error. | 970| 12500005 | The authentication type is not supported. | 971| 12500006 | The authentication trust level is not supported. | 972 973**示例：** 974 975```ts 976import { BusinessError } from '@kit.BasicServicesKit'; 977import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 978import { userAuth } from '@kit.UserAuthenticationKit'; 979 980try { 981 const rand = cryptoFramework.createRandom(); 982 const len: number = 16; 983 let randData: Uint8Array | null = null; 984 let retryCount = 0; 985 while(retryCount < 3){ 986 randData = rand?.generateRandomSync(len)?.data; 987 if(randData){ 988 break; 989 } 990 retryCount++; 991 } 992 if(!randData){ 993 return; 994 } 995 const authParam: userAuth.AuthParam = { 996 challenge: randData, 997 authType: [userAuth.UserAuthType.PIN], 998 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 999 }; 1000 const widgetParam: userAuth.WidgetParam = { 1001 title: '请输入密码', 1002 }; 1003 let userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 1004 console.info('get userAuth instance success'); 1005} catch (error) { 1006 const err: BusinessError = error as BusinessError; 1007 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 1008} 1009``` 1010 1011## AuthResultInfo<sup>(deprecated)</sup> 1012 1013表示认证结果信息，用于描述认证结果。 1014 1015> **说明：** 1016> 从 API version 9 开始支持，从 API version 11 开始废弃。 1017 1018**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1019 1020| 名称 | 类型 | 必填 | 说明 | 1021| ------------ | ---------- | ---- | -------------------- | 1022| result | number | 是 | 认证结果。 | 1023| token | Uint8Array | 否 | 用户身份认证通过的凭证。 | 1024| remainAttempts | number | 否 | 剩余的认证尝试次数。 | 1025| lockoutDuration | number | 否 | 认证操作的锁定时长，时间单位为毫秒ms。 | 1026 1027## TipInfo<sup>(deprecated)</sup> 1028 1029表示认证过程中的提示信息，用于提供认证过程的反馈。 1030 1031> **说明：** 1032> 从 API version 9 开始支持，从 API version 11 开始废弃。 1033 1034**系统能力**：SystemCapability.UserIAM.UserAuth.Core。 1035 1036| 名称 | 类型 | 必填 | 说明 | 1037| ------------ | ---------- | ---- | -------------------- | 1038| module | number | 是 | 发送提示信息的模块标识。 | 1039| tip | number | 是 | 认证过程提示信息。 | 1040 1041## EventInfo<sup>(deprecated)</sup> 1042 1043type EventInfo = AuthResultInfo | TipInfo 1044 1045表示认证过程中事件信息的类型。 1046 1047该类型为下表类型取值中的联合类型。 1048 1049> **说明：** 1050> 从 API version 9 开始支持，从 API version 11 开始废弃，请使用[UserAuthResult](#userauthresult10)替代。 1051 1052**系统能力**：SystemCapability.UserIAM.UserAuth.Core。 1053 1054| 类型 | 说明 | 1055| --------- | ----------------------- | 1056| [AuthResultInfo](#authresultinfodeprecated) | 获取到的认证结果信息。 | 1057| [TipInfo](#tipinfodeprecated) | 认证过程中的提示信息。 | 1058 1059## AuthEventKey<sup>(deprecated)</sup> 1060 1061type AuthEventKey = 'result' | 'tip' 1062 1063表示认证事件类型的关键字，作为[on](#ondeprecated)接口的参数。 1064 1065该类型为下表类型取值中的联合类型。 1066 1067> **说明：** 1068> 从 API version 9 开始支持，从 API version 11 开始废弃。 1069 1070**系统能力**：SystemCapability.UserIAM.UserAuth.Core。 1071 1072| 类型 | 说明 | 1073| ---------- | ----------------------- | 1074| 'result' | [on](#ondeprecated)接口第一个参数为"result"时，[callback](#callbackdeprecated)回调返回认证的结果信息。 | 1075| 'tip' | [on](#ondeprecated)接口第一个参数为"tip"时，[callback](#callbackdeprecated)回调返回认证操作中的提示信息。 | 1076 1077## AuthEvent<sup>(deprecated)</sup> 1078 1079认证接口的异步回调对象。 1080 1081> **说明：** 1082> 从 API version 9 开始支持，从 API version 11 开始废弃，请使用[IAuthCallback](#iauthcallback10)替代。 1083 1084### callback<sup>(deprecated)</sup> 1085 1086callback(result : EventInfo) : void 1087 1088通过该回调获取认证结果信息或认证过程中的提示信息。 1089 1090> **说明：** 1091> 从 API version 9 开始支持，从 API version 11 开始废弃，请使用[onResult](#onresult10)替代。 1092 1093**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1094 1095**参数：** 1096 1097| 参数名 | 类型 | 必填 | 说明 | 1098| --------- | -------------------------- | ---- | ------------------------------ | 1099| result | [EventInfo](#eventinfodeprecated) | 是 | 返回的认证结果信息或提示信息。 | 1100 1101**示例：** 1102 1103```ts 1104import { userAuth } from '@kit.UserAuthenticationKit'; 1105 1106let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 1107let authType = userAuth.UserAuthType.FACE; 1108let authTrustLevel = userAuth.AuthTrustLevel.ATL1; 1109// 通过callback获取认证结果。 1110try { 1111 let auth = userAuth.getAuthInstance(challenge, authType, authTrustLevel); 1112 auth.on('result', { 1113 callback: (result: userAuth.AuthResultInfo) => { 1114 console.info(`authV9 result ${result.result}`); 1115 console.info(`authV9 token ${result.token}`); 1116 console.info(`authV9 remainAttempts ${result.remainAttempts}`); 1117 console.info(`authV9 lockoutDuration ${result.lockoutDuration}`); 1118 } 1119 } as userAuth.AuthEvent); 1120 auth.start(); 1121 console.info('authV9 start success'); 1122} catch (error) { 1123 console.error(`authV9 error = ${error}`); 1124 // do error. 1125} 1126// 通过callback获取认证过程中的提示信息。 1127try { 1128 let auth = userAuth.getAuthInstance(challenge, authType, authTrustLevel); 1129 auth.on('tip', { 1130 callback : (result : userAuth.TipInfo) => { 1131 switch (result.tip) { 1132 case userAuth.FaceTips.FACE_AUTH_TIP_TOO_BRIGHT: 1133 // do something; 1134 break; 1135 case userAuth.FaceTips.FACE_AUTH_TIP_TOO_DARK: 1136 // do something; 1137 break; 1138 default: 1139 // do others. 1140 } 1141 } 1142 } as userAuth.AuthEvent); 1143 auth.start(); 1144 console.info('authV9 start success'); 1145} catch (error) { 1146 console.error(`authV9 error = ${error}`); 1147 // do error. 1148} 1149``` 1150 1151## AuthInstance<sup>(deprecated)</sup> 1152 1153执行用户认证的对象。 1154 1155> **说明：** 1156> 从 API version 9 开始支持，从 API version 10 开始废弃，请使用[UserAuthInstance](#userauthinstance10)替代。 1157 1158### on<sup>(deprecated)</sup> 1159 1160on : (name : AuthEventKey, callback : AuthEvent) => void 1161 1162订阅指定类型的用户认证事件。 1163 1164> **说明：** 1165> - 从 API version 9 开始支持，从 API version 10 开始废弃。 1166> - 使用获取到的[AuthInstance](#authinstancedeprecated)对象调用该接口进行订阅。 1167 1168**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1169 1170**参数：** 1171 1172| 参数名 | 类型 | 必填 | 说明 | 1173| --------- | -------------------------- | ---- | ------------------------- | 1174| name | [AuthEventKey](#autheventkeydeprecated) | 是 | 表示认证事件类型，取值为"result"时，回调函数返回认证结果；取值为"tip"时，回调函数返回认证过程中的提示信息。 | 1175| callback | [AuthEvent](#autheventdeprecated) | 是 | 认证接口的回调函数，用于返回认证结果或认证过程中的提示信息。 | 1176 1177**错误码：** 1178 1179以下错误码的详细介绍请参见[用户认证错误码](errorcode-useriam.md)。 1180 1181| 错误码ID | 错误信息 | 1182| -------- | ------- | 1183| 401 | Parameter error. | 1184| 12500002 | General operation error. | 1185 1186**示例：** 1187 1188```ts 1189import { userAuth } from '@kit.UserAuthenticationKit'; 1190 1191let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 1192let authType = userAuth.UserAuthType.FACE; 1193let authTrustLevel = userAuth.AuthTrustLevel.ATL1; 1194try { 1195 let auth = userAuth.getAuthInstance(challenge, authType, authTrustLevel); 1196 // 订阅认证结果。 1197 auth.on('result', { 1198 callback: (result: userAuth.AuthResultInfo) => { 1199 console.info(`authV9 result ${result.result}`); 1200 console.info(`authV9 token ${result.token}`); 1201 console.info(`authV9 remainAttempts ${result.remainAttempts}`); 1202 console.info(`authV9 lockoutDuration ${result.lockoutDuration}`); 1203 } 1204 }); 1205 // 订阅认证过程中的提示信息。 1206 auth.on('tip', { 1207 callback : (result : userAuth.TipInfo) => { 1208 switch (result.tip) { 1209 case userAuth.FaceTips.FACE_AUTH_TIP_TOO_BRIGHT: 1210 // do something; 1211 break; 1212 case userAuth.FaceTips.FACE_AUTH_TIP_TOO_DARK: 1213 // do something; 1214 break; 1215 default: 1216 // do others. 1217 } 1218 } 1219 } as userAuth.AuthEvent); 1220 auth.start(); 1221 console.info('authV9 start success'); 1222} catch (error) { 1223 console.error(`authV9 error = ${error}`); 1224 // do error. 1225} 1226``` 1227 1228### off<sup>(deprecated)</sup> 1229 1230off : (name : AuthEventKey) => void 1231 1232取消订阅特定类型的认证事件。 1233 1234> **说明：** 1235> - 从 API version 9 开始支持，从 API version 10 开始废弃。 1236> - 需要使用已经成功订阅事件的[AuthInstance](#authinstancedeprecated)对象调用该接口进行取消订阅。 1237 1238**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1239 1240| 名称 | 类型 | 必填 | 说明 | 1241| --------- | -------------------------- | ---- | ------------------------- | 1242| name | [AuthEventKey](#autheventkeydeprecated) | 是 | 表示认证事件类型，取值为"result"时，取消订阅认证结果；取值为"tip"时，取消订阅认证过程中的提示信息。 | 1243 1244**错误码：** 1245 1246以下错误码的详细介绍请参见[用户认证错误码](errorcode-useriam.md)。 1247 1248| 错误码ID | 错误信息 | 1249| -------- | ------- | 1250| 401 | Parameter error. | 1251| 12500002 | General operation error. | 1252 1253**示例：** 1254 1255```ts 1256import { userAuth } from '@kit.UserAuthenticationKit'; 1257 1258let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 1259let authType = userAuth.UserAuthType.FACE; 1260let authTrustLevel = userAuth.AuthTrustLevel.ATL1; 1261try { 1262 let auth = userAuth.getAuthInstance(challenge, authType, authTrustLevel); 1263 // 订阅认证结果。 1264 auth.on('result', { 1265 callback: (result: userAuth.AuthResultInfo) => { 1266 console.info(`authV9 result ${result.result}`); 1267 console.info(`authV9 token ${result.token}`); 1268 console.info(`authV9 remainAttempts ${result.remainAttempts}`); 1269 console.info(`authV9 lockoutDuration ${result.lockoutDuration}`); 1270 } 1271 }); 1272 // 取消订阅结果。 1273 auth.off('result'); 1274 console.info('cancel subscribe authentication event success'); 1275} catch (error) { 1276 console.error(`cancel subscribe authentication event failed, error = ${error}`); 1277 // do error. 1278} 1279``` 1280 1281### start<sup>(deprecated)</sup> 1282 1283start : () => void 1284 1285开始认证。 1286 1287> **说明：** 1288> - 从 API version 9 开始支持，从 API version 10 开始废弃。 1289> - 使用获取到的[AuthInstance](#authinstancedeprecated)对象调用该接口进行认证。 1290 1291**需要权限**：ohos.permission.ACCESS_BIOMETRIC 1292 1293**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1294 1295**错误码：** 1296 1297以下错误码的详细介绍请参见[用户认证错误码](errorcode-useriam.md)。 1298 1299| 错误码ID | 错误信息 | 1300| -------- | ------- | 1301| 201 | Permission denied. | 1302| 401 | Parameter error. | 1303| 12500001 | Authentication failed. | 1304| 12500002 | General operation error. | 1305| 12500003 | The operation is canceled. | 1306| 12500004 | The operation is time-out. | 1307| 12500005 | The authentication type is not supported. | 1308| 12500006 | The authentication trust level is not supported. | 1309| 12500007 | The authentication task is busy. | 1310| 12500009 | The authenticator is locked. | 1311| 12500010 | The type of credential has not been enrolled. | 1312 1313**示例：** 1314 1315```ts 1316import { userAuth } from '@kit.UserAuthenticationKit'; 1317 1318let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 1319let authType = userAuth.UserAuthType.FACE; 1320let authTrustLevel = userAuth.AuthTrustLevel.ATL1; 1321 1322try { 1323 let auth = userAuth.getAuthInstance(challenge, authType, authTrustLevel); 1324 auth.start(); 1325 console.info('authV9 start auth success'); 1326} catch (error) { 1327 console.error(`authV9 start auth failed, error = ${error}`); 1328} 1329``` 1330 1331### cancel<sup>(deprecated)</sup> 1332 1333cancel : () => void 1334 1335取消认证。 1336 1337> **说明：** 1338> 1339> - 从 API version 9 开始支持，从 API version 10 开始废弃。 1340> - 使用获取到的[AuthInstance](#authinstancedeprecated)对象调用该接口进行取消认证，此[AuthInstance](#authinstancedeprecated)需要是正在进行认证的对象。 1341 1342**需要权限**：ohos.permission.ACCESS_BIOMETRIC 1343 1344**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1345 1346**错误码：** 1347 1348以下错误码的详细介绍请参见[用户认证错误码](errorcode-useriam.md)。 1349 1350| 错误码ID | 错误信息 | 1351| -------- | ------- | 1352| 201 | Permission denied. | 1353| 401 | Parameter error. | 1354| 12500002 | General operation error. | 1355 1356**示例：** 1357 1358```ts 1359import { userAuth } from '@kit.UserAuthenticationKit'; 1360 1361let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 1362let authType = userAuth.UserAuthType.FACE; 1363let authTrustLevel = userAuth.AuthTrustLevel.ATL1; 1364 1365try { 1366 let auth = userAuth.getAuthInstance(challenge, authType, authTrustLevel); 1367 auth.cancel(); 1368 console.info('cancel auth success'); 1369} catch (error) { 1370 console.error(`cancel auth failed, error = ${error}`); 1371} 1372``` 1373 1374## userAuth.getAuthInstance<sup>(deprecated)</sup> 1375 1376getAuthInstance(challenge : Uint8Array, authType : UserAuthType, authTrustLevel : AuthTrustLevel): AuthInstance 1377 1378获取AuthInstance对象，用于执行用户身份认证。 1379 1380> **说明：** 1381> 1382> - 从 API version 9 开始支持，从 API version 10 开始废弃，请使用[getUserAuthInstance](#userauthgetuserauthinstance10)替代。 1383> - 每个AuthInstance只能进行一次认证，若需要再次进行认证则需重新获取AuthInstance。 1384 1385 1386**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1387 1388**参数：** 1389 1390| 参数名 | 类型 | 必填 | 说明 | 1391| -------------- | ---------------------------------------- | ---- | ------------------------ | 1392| challenge | Uint8Array | 是 | 挑战值，最大长度为32字节，可以传Uint8Array([])。 | 1393| authType | [UserAuthType](#userauthtype8) | 是 | 认证类型，当前支持FACE和FINGERPRINT。 | 1394| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | 是 | 认证信任等级。 | 1395 1396**返回值：** 1397 1398| 类型 | 说明 | 1399| --------------------------------------- | ------------ | 1400| [AuthInstance](#authinstancedeprecated) | 认证器对象。 | 1401 1402**错误码：** 1403 1404以下错误码的详细介绍请参见[用户认证错误码](errorcode-useriam.md)。 1405 1406| 错误码ID | 错误信息 | 1407| -------- | ------- | 1408| 401 | Parameter error. | 1409| 12500002 | General operation error. | 1410| 12500005 | The authentication type is not supported. | 1411| 12500006 | The authentication trust level is not supported. | 1412 1413**示例：** 1414 1415```ts 1416import { userAuth } from '@kit.UserAuthenticationKit'; 1417 1418let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 1419let authType = userAuth.UserAuthType.FACE; 1420let authTrustLevel = userAuth.AuthTrustLevel.ATL1; 1421 1422try { 1423 let auth = userAuth.getAuthInstance(challenge, authType, authTrustLevel); 1424 console.info('let auth instance success'); 1425} catch (error) { 1426 console.error(`get auth instance success failed, error = ${error}`); 1427} 1428``` 1429 1430## userAuth.getAvailableStatus<sup>9+</sup> 1431 1432getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel): void 1433 1434查询指定类型和等级的认证能力是否支持。 1435 1436**需要权限**：ohos.permission.ACCESS_BIOMETRIC 1437 1438**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1439 1440**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1441 1442**参数：** 1443 1444| 参数名 | 类型 | 必填 | 说明 | 1445| -------------- | ---------------------------------- | ---- | -------------------------- | 1446| authType | [UserAuthType](#userauthtype8) | 是 | 认证类型。从 API version 11 开始支持PIN查询。| 1447| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | 是 | 认证信任等级。 | 1448 1449> **错误码返回顺序说明：** 1450> 1451> - 如果未注册对应执行器，系统不支持该认证能力，需返回12500005。 1452> - 如果已注册对应执行器，功能未禁用，但认证安全等级低于业务指定时，需返回12500006。 1453> - 如果已注册对应执行器，功能未禁用，但用户未注册凭据时，需返回12500010。 1454> - 如果已注册对应执行器，功能未禁用，但密码过期时，需返回12500013。 1455 1456> **注意：** 1457> - 若用户注册的锁屏口令是4位PIN时，其认证可信等级为ATL3，调用该接口查询是否支持ATL4级别的密码认证时，需返回12500010。 1458 1459**错误码：** 1460 1461以下错误码的详细介绍请参见[用户认证错误码](errorcode-useriam.md)。 1462 1463| 错误码ID | 错误信息 | 1464| -------- | ------- | 1465| 201 | Permission denied. | 1466| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. | 1467| 12500002 | General operation error. | 1468| 12500005 | The authentication type is not supported. | 1469| 12500006 | The authentication trust level is not supported. | 1470| 12500010 | The type of credential has not been enrolled. | 1471| 12500013 | Operation failed because of PIN expired. | 1472 1473**示例：** 1474 1475```ts 1476import { userAuth } from '@kit.UserAuthenticationKit'; 1477 1478try { 1479 userAuth.getAvailableStatus(userAuth.UserAuthType.FACE, userAuth.AuthTrustLevel.ATL3); 1480 console.info('current auth trust level is supported'); 1481} catch (error) { 1482 console.error(`current auth trust level is not supported, error = ${error}`); 1483} 1484``` 1485 1486## UserAuthResultCode<sup>9+</sup> 1487 1488表示返回码的枚举。 1489 1490**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1491 1492| 名称 | 值 | 说明 | 1493| ----------------------- | ------ | -------------------- | 1494| SUCCESS | 12500000 | 执行成功。<br/> **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1495| FAIL | 12500001 | 认证失败。<br/> **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1496| GENERAL_ERROR | 12500002 | 操作通用错误。<br/> **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1497| CANCELED | 12500003 | 认证取消。<br/> **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1498| TIMEOUT | 12500004 | 认证超时。<br/> **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1499| TYPE_NOT_SUPPORT | 12500005 | 认证类型不支持。<br/> **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 1500| TRUST_LEVEL_NOT_SUPPORT | 12500006 | 认证等级不支持。<br/> **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 1501| BUSY | 12500007 | 系统繁忙。<br/> **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1502| INVALID_PARAMETERS<sup>20+</sup> | 12500008 | 参数校验失败。<br/> **原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 | 1503| LOCKED | 12500009 | 认证器已锁定。<br/> **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1504| NOT_ENROLLED | 12500010 | 用户未录入指定的系统身份认证凭据。<br/> **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1505| CANCELED_FROM_WIDGET<sup>10+</sup> | 12500011 | 用户取消了系统认证方式，选择应用自定义认证。需调用者拉起自定义认证界面。<br/> **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1506| PIN_EXPIRED<sup>12+</sup> | 12500013 | 当前的认证操作执行失败。返回这个错误码，表示系统锁屏口令过期。<br/> **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1507 1508## UserAuth<sup>(deprecated)</sup> 1509 1510认证器对象。 1511 1512### constructor<sup>(deprecated)</sup> 1513 1514constructor() 1515 1516创建认证器对象。 1517 1518> **说明：** 1519> 从 API version 8 开始支持，从 API version 9 开始废弃，请使用[getAuthInstance](#userauthgetauthinstancedeprecated)替代。 1520 1521**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1522 1523**示例：** 1524 1525```ts 1526import { userAuth } from '@kit.UserAuthenticationKit'; 1527 1528let auth = new userAuth.UserAuth(); 1529``` 1530 1531### getVersion<sup>(deprecated)</sup> 1532 1533getVersion() : number 1534 1535获取认证器的版本信息。 1536 1537> **说明：** 1538> 从 API version 8 开始支持，从 API version 9 开始废弃。 1539 1540**需要权限**：ohos.permission.ACCESS_BIOMETRIC 1541 1542**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1543 1544**返回值：** 1545 1546| 类型 | 说明 | 1547| ------ | ---------------------- | 1548| number | 认证器版本信息。 | 1549 1550**示例：** 1551 1552```ts 1553import { userAuth } from '@kit.UserAuthenticationKit'; 1554 1555let auth = new userAuth.UserAuth(); 1556let version = auth.getVersion(); 1557console.info(`auth version = ${version}`); 1558``` 1559 1560### getAvailableStatus<sup>(deprecated)</sup> 1561 1562getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel) : number 1563 1564查询指定类型和等级的认证能力是否支持。 1565 1566> **说明：** 1567> 从 API version 8 开始支持，从 API version 9 开始废弃，请使用[getAvailableStatus](#userauthgetavailablestatus9)替代。 1568 1569**需要权限**：ohos.permission.ACCESS_BIOMETRIC 1570 1571**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1572 1573**参数：** 1574 1575| 参数名 | 类型 | 必填 | 说明 | 1576| -------------- | ---------------------------------- | ---- | -------------------------- | 1577| authType | [UserAuthType](#userauthtype8) | 是 | 认证类型，当前支持FACE和FINGERPRINT。 | 1578| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | 是 | 认证信任等级。 | 1579 1580**返回值：** 1581 1582| 类型 | 说明 | 1583| ------ | ------------------------------------------------------------ | 1584| number | 查询结果，结果为SUCCESS时表示支持，其他返回值参见[ResultCode](#resultcodedeprecated)。 | 1585 1586**示例：** 1587 1588```ts 1589import { userAuth } from '@kit.UserAuthenticationKit'; 1590 1591let auth = new userAuth.UserAuth(); 1592let checkCode = auth.getAvailableStatus(userAuth.UserAuthType.FACE, userAuth.AuthTrustLevel.ATL1); 1593if (checkCode == userAuth.ResultCode.SUCCESS) { 1594 console.info('check auth support success'); 1595} else { 1596 console.error(`check auth support fail, code = ${checkCode}`); 1597} 1598``` 1599 1600### auth<sup>(deprecated)</sup> 1601 1602auth(challenge: Uint8Array, authType: UserAuthType, authTrustLevel: AuthTrustLevel, callback: IUserAuthCallback): Uint8Array 1603 1604执行用户认证，使用回调函数返回结果。 1605 1606> **说明：** 1607> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[start](#startdeprecated)代替。 1608 1609**需要权限**：ohos.permission.ACCESS_BIOMETRIC 1610 1611**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1612 1613**参数：** 1614 1615| 参数名 | 类型 | 必填 | 说明 | 1616| -------------- | ---------------------------------------- | ---- | ------------------------ | 1617| challenge | Uint8Array | 是 | 挑战值，可以传Uint8Array([])。 | 1618| authType | [UserAuthType](#userauthtype8) | 是 | 认证类型，当前支持FACE和FINGERPRINT。 | 1619| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | 是 | 认证信任等级。 | 1620| callback | [IUserAuthCallback](#iuserauthcallbackdeprecated) | 是 | 回调函数。 | 1621 1622**返回值：** 1623 1624| 类型 | 说明 | 1625| ---------- | ------------------------------------------------------------ | 1626| Uint8Array | ContextId，作为取消认证[cancelAuth](#cancelauthdeprecated)接口的入参。 | 1627 1628**示例：** 1629 1630```ts 1631import { userAuth } from '@kit.UserAuthenticationKit'; 1632 1633let auth = new userAuth.UserAuth(); 1634let challenge = new Uint8Array([]); 1635auth.auth(challenge, userAuth.UserAuthType.FACE, userAuth.AuthTrustLevel.ATL1, { 1636 onResult: (result, extraInfo) => { 1637 try { 1638 console.info(`auth onResult result = ${result}`); 1639 console.info(`auth onResult extraInfo = ${JSON.stringify(extraInfo)}`); 1640 if (result == userAuth.ResultCode.SUCCESS) { 1641 // 此处添加认证成功逻辑。 1642 } else { 1643 // 此处添加认证失败逻辑。 1644 } 1645 } catch (error) { 1646 console.error(`auth onResult error = ${error}`); 1647 } 1648 } 1649}); 1650``` 1651 1652### cancelAuth<sup>(deprecated)</sup> 1653 1654cancelAuth(contextID : Uint8Array) : number 1655 1656表示通过contextID取消本次认证。 1657 1658> **说明：** 1659> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[cancel](#canceldeprecated)代替。 1660 1661**需要权限**：ohos.permission.ACCESS_BIOMETRIC 1662 1663**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1664 1665**参数：** 1666 1667| 参数名 | 类型 | 必填 | 说明 | 1668| --------- | ---------- | ---- | ------------------------------------------ | 1669| contextID | Uint8Array | 是 | 上下文的标识，通过[auth](#authdeprecated)接口获取。 | 1670 1671**返回值：** 1672 1673| 类型 | 说明 | 1674| ------ | ------------------------ | 1675| number | 取消认证的结果，结果为SUCCESS时表示取消成功，其他返回值参见[ResultCode](#resultcodedeprecated)。 | 1676 1677**示例：** 1678 1679```ts 1680import { userAuth } from '@kit.UserAuthenticationKit'; 1681 1682// contextId可通过auth接口获取，此处直接定义。 1683let contextId = new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7]); 1684let auth = new userAuth.UserAuth(); 1685let cancelCode = auth.cancelAuth(contextId); 1686if (cancelCode == userAuth.ResultCode.SUCCESS) { 1687 console.info('cancel auth success'); 1688} else { 1689 console.error('cancel auth fail'); 1690} 1691``` 1692 1693## IUserAuthCallback<sup>(deprecated)</sup> 1694 1695返回认证结果的回调对象。 1696 1697> **说明：** 1698> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[AuthEvent](#autheventdeprecated)代替。 1699 1700### onResult<sup>(deprecated)</sup> 1701 1702onResult: (result : number, extraInfo : AuthResult) => void 1703 1704回调函数，返回认证结果。 1705 1706> **说明：** 1707> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[callback](#callbackdeprecated)代替。 1708 1709**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1710 1711**参数：** 1712 1713| 参数名 | 类型 | 必填 | 说明 | 1714| --------- | -------------------------- | ---- | ------------------------------------------------ | 1715| result | number | 是 | 认证结果，参见[ResultCode](#resultcodedeprecated)。 | 1716| extraInfo | [AuthResult](#authresultdeprecated) | 是 | 扩展信息，不同情况下的具体信息，<br/>如果身份验证通过，则在extraInfo中返回用户认证令牌，<br/>如果身份验证失败，则在extraInfo中返回剩余的用户认证次数，<br/>如果身份验证执行器被锁定，则在extraInfo中返回冻结时间。 | 1717 1718**示例：** 1719 1720```ts 1721import { userAuth } from '@kit.UserAuthenticationKit'; 1722 1723let auth = new userAuth.UserAuth(); 1724let challenge = new Uint8Array([]); 1725auth.auth(challenge, userAuth.UserAuthType.FACE, userAuth.AuthTrustLevel.ATL1, { 1726 onResult: (result, extraInfo) => { 1727 try { 1728 console.info(`auth onResult result = ${result}`); 1729 console.info(`auth onResult extraInfo = ${JSON.stringify(extraInfo)}`); 1730 if (result == userAuth.ResultCode.SUCCESS) { 1731 // 此处添加认证成功逻辑。 1732 } else { 1733 // 此处添加认证失败逻辑。 1734 } 1735 } catch (error) { 1736 console.error(`auth onResult error = ${error}`); 1737 } 1738 } 1739}); 1740``` 1741 1742### onAcquireInfo<sup>(deprecated)</sup> 1743 1744onAcquireInfo ?: (module : number, acquire : number, extraInfo : any) => void 1745 1746回调函数，返回认证过程中的提示信息，非必须实现。 1747 1748> **说明：** 1749> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[callback](#callbackdeprecated)代替。 1750 1751**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1752 1753**参数：** 1754 1755| 参数名 | 类型 | 必填 | 说明 | 1756| --------- | ------ | ---- | ------------------------------ | 1757| module | number | 是 | 发送提示信息的模块标识。 | 1758| acquire | number | 是 | 认证执过程中的提示信息。 | 1759| extraInfo | any | 是 | 预留字段。 | 1760 1761**示例：** 1762 1763```ts 1764import { userAuth } from '@kit.UserAuthenticationKit'; 1765 1766let auth = new userAuth.UserAuth(); 1767let challenge = new Uint8Array([]); 1768auth.auth(challenge, userAuth.UserAuthType.FACE, userAuth.AuthTrustLevel.ATL1, { 1769 onResult: (result, extraInfo) => { 1770 try { 1771 console.info(`auth onResult result = ${result}`); 1772 console.info(`auth onResult extraInfo = ${JSON.stringify(extraInfo)}`); 1773 if (result == userAuth.ResultCode.SUCCESS) { 1774 // 此处添加认证成功逻辑。 1775 } else { 1776 // 此处添加认证失败逻辑。 1777 } 1778 } catch (error) { 1779 console.error(`auth onResult error = ${error}`); 1780 } 1781 }, 1782 onAcquireInfo: (module, acquire, extraInfo : userAuth.AuthResult) => { 1783 try { 1784 console.info(`auth onAcquireInfo module = ${module}`); 1785 console.info(`auth onAcquireInfo acquire = ${acquire}`); 1786 console.info(`auth onAcquireInfo extraInfo = ${JSON.stringify(extraInfo)}`); 1787 } catch (error) { 1788 console.error(`auth onAcquireInfo error = ${error}`); 1789 } 1790 } 1791}); 1792``` 1793 1794## AuthResult<sup>(deprecated)</sup> 1795 1796表示认证结果的对象。 1797 1798> **说明：** 1799> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[AuthResultInfo](#authresultinfodeprecated)代替。 1800 1801**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1802 1803| 名称 | 类型 | 必填 | 说明 | 1804| ------------ | ---------- | ---- | -------------------| 1805| token | Uint8Array | 否 | 认证成功的令牌信息。 | 1806| remainTimes | number | 否 | 剩余的认证操作次数。 | 1807| freezingTime | number | 否 | 认证操作的冻结时间。 | 1808 1809## ResultCode<sup>(deprecated)</sup> 1810 1811表示返回码的枚举。 1812 1813> **说明：** 1814> 从 API version 9 开始废弃，建议使用[UserAuthResultCode](#userauthresultcode9)代替。 1815 1816**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1817 1818| 名称 | 值 | 说明 | 1819| ----------------------- | ------ | -------------------- | 1820| SUCCESS | 0 | 执行成功。 | 1821| FAIL | 1 | 认证失败。 | 1822| GENERAL_ERROR | 2 | 操作通用错误。 | 1823| CANCELED | 3 | 操作取消。 | 1824| TIMEOUT | 4 | 操作超时。 | 1825| TYPE_NOT_SUPPORT | 5 | 不支持的认证类型。 | 1826| TRUST_LEVEL_NOT_SUPPORT | 6 | 不支持的认证等级。 | 1827| BUSY | 7 | 忙碌状态。 | 1828| INVALID_PARAMETERS | 8 | 无效参数。 | 1829| LOCKED | 9 | 认证器已锁定。 | 1830| NOT_ENROLLED | 10 | 用户未录入认证信息。 | 1831 1832## FaceTips<sup>(deprecated)</sup> 1833 1834表示人脸认证过程中提示码的枚举。 1835 1836> **说明：** 1837> 从 API version 8 开始支持，从 API version 11 开始废弃。 1838 1839**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1840 1841| 名称 | 值 | 说明 | 1842| ----------------------------- | ------ | ------------------------------------ | 1843| FACE_AUTH_TIP_TOO_BRIGHT | 1 | 光线太强，获取的图像太亮。 | 1844| FACE_AUTH_TIP_TOO_DARK | 2 | 光线太暗，获取的图像太暗。 | 1845| FACE_AUTH_TIP_TOO_CLOSE | 3 | 人脸距离设备过近。 | 1846| FACE_AUTH_TIP_TOO_FAR | 4 | 人脸距离设备过远。 | 1847| FACE_AUTH_TIP_TOO_HIGH | 5 | 设备太高，仅获取到人脸上部。 | 1848| FACE_AUTH_TIP_TOO_LOW | 6 | 设备太低，仅获取到人脸下部。 | 1849| FACE_AUTH_TIP_TOO_RIGHT | 7 | 设备太靠右，仅获取到人脸右部。 | 1850| FACE_AUTH_TIP_TOO_LEFT | 8 | 设备太靠左，仅获取到人脸左部。 | 1851| FACE_AUTH_TIP_TOO_MUCH_MOTION | 9 | 在图像采集过程中，用户人脸移动太快。 | 1852| FACE_AUTH_TIP_POOR_GAZE | 10 | 没有正视摄像头。 | 1853| FACE_AUTH_TIP_NOT_DETECTED | 11 | 没有检测到人脸信息。 | 1854 1855 1856## FingerprintTips<sup>(deprecated)</sup> 1857 1858表示指纹认证过程中提示码的枚举。 1859 1860> **说明：** 1861> 从 API version 8 开始支持，从 API version 11 开始废弃。 1862 1863**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1864 1865| 名称 | 值 | 说明 | 1866| --------------------------------- | ------ | -------------------------------------------------- | 1867| FINGERPRINT_AUTH_TIP_GOOD | 0 | 获取的指纹图像良好。 | 1868| FINGERPRINT_AUTH_TIP_DIRTY | 1 | 由于传感器上可疑或检测到的污垢，指纹图像噪音过大。 | 1869| FINGERPRINT_AUTH_TIP_INSUFFICIENT | 2 | 由于检测到的情况，指纹图像噪声太大，无法处理。 | 1870| FINGERPRINT_AUTH_TIP_PARTIAL | 3 | 仅检测到部分指纹图像。 | 1871| FINGERPRINT_AUTH_TIP_TOO_FAST | 4 | 快速移动，指纹图像不完整。 | 1872| FINGERPRINT_AUTH_TIP_TOO_SLOW | 5 | 缺少运动，指纹图像无法读取。 | 1873 1874 1875## UserAuthType<sup>8+</sup> 1876 1877表示身份认证的凭据类型枚举。 1878 1879**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1880 1881**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1882 1883| 名称 | 值 | 说明 | 1884| ----------- | ---- | ---------- | 1885| PIN<sup>10+</sup> | 1 | 口令认证。 | 1886| FACE | 2 | 人脸认证。 | 1887| FINGERPRINT | 4 | 指纹认证。 | 1888 1889## AuthTrustLevel<sup>8+</sup> 1890 1891表示认证结果的信任等级枚举。 1892 1893典型场景及举例可参考[认证可信等级划分原则](../../security/UserAuthenticationKit/user-authentication-overview.md#生物认证可信等级划分原则)。 1894 1895**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1896 1897**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1898 1899| 名称 | 值 | 说明 | 1900| ---- | ----- | ------------------------------------------------------------ | 1901| ATL1 | 10000 | 认证结果的信任等级级别1，表示该认证方案能够识别用户个体，具备一定的活体检测能力。适用于业务风控、一般个人数据查询等场景。 | 1902| ATL2 | 20000 | 认证结果的信任等级级别2，表示该认证方案能够精确识别用户个体，具备一定的活体检测能力。适用于维持设备解锁状态、应用登录等场景。| 1903| ATL3 | 30000 | 认证结果的信任等级级别3，表示该认证方案能够精确识别用户个体，具备较强的活体检测能力。适用于设备解锁等场景。| 1904| ATL4 | 40000 | 认证结果的信任等级级别4，表示该认证方案能够高精度的识别用户个体，具备很强的活体检测能力。适用于小额支付等场景。| 1905 1906## SecureLevel<sup>(deprecated)</sup> 1907 1908type SecureLevel = string 1909 1910表示认证的安全级别。 1911 1912**原子化服务API：** 从 API version 6 开始支持，从 API version 8 开始废弃。 1913 1914**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1915 1916| 类型 | 说明 | 1917| ---- | ------------------------------------------------------------ | 1918| string | 表示类型为字符，认证的安全级别包括：`'S1'` \| `'S2'`\|`'S3'`\|`'S4'`。 <br/>\- `'S1'`：认证结果的信任等级级别1，代表该认证方案能够识别用户个体，有一定的活体检测能力。常用的业务场景有业务风控、一般个人数据查询等。 <br/>\- `'S2'`：认证结果的信任等级级别2，代表该认证方案能够精确识别用户个体，有一定的活体检测能力。常用的业务场景有维持设备解锁状态，应用登录等。 <br/>\- `'S3'`：认证结果的信任等级级别3，代表该认证方案能够精确识别用户个体，有较强的活体检测能力。常用的业务场景有设备解锁等。 <br/>\- `'S4'`：认证结果的信任等级级别4，代表该认证方案能够高精度的识别用户个体，有很强的活体检测能力。常用的业务场景有小额支付等。 | 1919 1920## AuthType<sup>(deprecated)</sup> 1921 1922type AuthType = string 1923 1924表示认证类型。 1925 1926**原子化服务API：** 从 API version 6 开始支持，从 API version 8 开始废弃。 1927 1928**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1929 1930| 类型 | 说明 | 1931| ---- | ------------------------------------------------------------ | 1932| string | 表示认证类型为字符，认证类型包括：`'ALL'`\|`'FACE_ONLY'`。<br/>\- `'ALL'`：预留参数，当前版本暂不支持ALL类型的认证。<br/>\- `'FACE_ONLY'`：人脸认证。 | 1933 1934## userAuth.getAuthenticator<sup>(deprecated)</sup> 1935 1936getAuthenticator(): Authenticator 1937 1938获取Authenticator对象，用于执行用户身份认证。 1939 1940> **说明：** 1941> 从 API version 8 开始废弃，建议使用[constructor](#constructordeprecated)替代。 1942 1943**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1944 1945**返回值：** 1946 1947| 类型 | 说明 | 1948| ----------------------------------------- | ------------ | 1949| [Authenticator](#authenticatordeprecated) | 认证器对象。 | 1950 1951**示例：** 1952 ```ts 1953 import { userAuth } from '@kit.UserAuthenticationKit'; 1954 1955 let authenticator = userAuth.getAuthenticator(); 1956 ``` 1957 1958## Authenticator<sup>(deprecated)</sup> 1959 1960认证器对象。 1961 1962> **说明：** 1963> 从 API version 8 开始废弃，建议使用[UserAuth](#userauthdeprecated)替代。 1964 1965### execute<sup>(deprecated)</sup> 1966 1967execute(type: AuthType, level: SecureLevel, callback: AsyncCallback<number>): void 1968 1969执行用户认证，使用callback方式作为异步方法。 1970 1971> **说明：** 1972> 从 API version 8 开始废弃，建议使用[auth](#authdeprecated)替代。 1973 1974**需要权限**：ohos.permission.ACCESS_BIOMETRIC 1975 1976**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1977 1978**参数：** 1979 1980| 参数名 | 类型 | 必填 | 说明 | 1981| -------- | --------------------------- | ---- |-----------------------------------------------------------------------------------------------------------------------| 1982| type | AuthType | 是 | 认证类型，当前只支持"FACE_ONLY"。<br/>ALL为预留参数。当前版本暂不支持ALL类型的认证。 | 1983| level | SecureLevel | 是 | 安全级别，对应认证的安全级别，有效值为"S1"（最低）、"S2"、"S3"、"S4"（最高）。<br/>具备3D人脸识别能力的设备支持"S3"及以下安全级别的认证。<br/>具备2D人脸识别能力的设备支持"S2"及以下安全级别的认证。 | 1984| callback | AsyncCallback<number> | 是 | 回调函数。number表示认证结果，参见[AuthenticationResult](#authenticationresultdeprecated)。 | 1985 1986**示例：** 1987 1988```ts 1989import { userAuth } from '@kit.UserAuthenticationKit'; 1990 1991let authenticator = userAuth.getAuthenticator(); 1992authenticator.execute('FACE_ONLY', 'S2', (error, code)=>{ 1993 if (code === userAuth.ResultCode.SUCCESS) { 1994 console.info('auth success'); 1995 return; 1996 } 1997 console.error(`auth fail, code = ${code}`); 1998}); 1999``` 2000 2001 2002### execute<sup>(deprecated)</sup> 2003 2004execute(type : AuthType, level : SecureLevel): Promise<number> 2005 2006执行用户认证，使用promise方式作为异步方法。 2007 2008> **说明：** 2009> 从 API version 8 开始废弃，建议使用[auth](#authdeprecated)替代。 2010 2011**需要权限**：ohos.permission.ACCESS_BIOMETRIC 2012 2013**系统能力**：SystemCapability.UserIAM.UserAuth.Core 2014 2015**参数：** 2016 2017| 参数名 | 类型 | 必填 | 说明 | 2018| ------ | ------ | ---- |-----------------------------------------------------------------------------------------------------------------------| 2019| type | AuthType | 是 | 认证类型，当前只支持"FACE_ONLY"。<br/>ALL为预留参数。当前版本暂不支持ALL类型的认证。 | 2020| level | SecureLevel | 是 | 安全级别，对应认证的安全级别，有效值为"S1"（最低）、"S2"、"S3"、"S4"（最高）。<br/>具备3D人脸识别能力的设备支持"S3"及以下安全级别的认证。<br/>具备2D人脸识别能力的设备支持"S2"及以下安全级别的认证。 | 2021 2022**返回值：** 2023 2024| 类型 | 说明 | 2025| --------------------- | ------------------------------------------------------------ | 2026| Promise<number> | 返回携带一个number的Promise。number 为认证结果，参见[AuthenticationResult](#authenticationresultdeprecated)。 | 2027 2028**示例：** 2029 2030```ts 2031import { userAuth } from '@kit.UserAuthenticationKit'; 2032 2033try { 2034 let authenticator = userAuth.getAuthenticator(); 2035 authenticator.execute('FACE_ONLY', 'S2').then((code)=>{ 2036 console.info('auth success'); 2037 }) 2038} catch (error) { 2039 console.error(`auth fail, code = ${error}`); 2040} 2041``` 2042 2043## AuthenticationResult<sup>(deprecated)</sup> 2044 2045表示认证结果的枚举。 2046 2047> **说明：** 2048> 从 API version 8 开始废弃，建议使用[ResultCode](#resultcodedeprecated)替代。 2049 2050**系统能力**：SystemCapability.UserIAM.UserAuth.Core 2051 2052| 名称 | 值 | 说明 | 2053| ------------------ | ------ | -------------------------- | 2054| NO_SUPPORT | -1 | 设备不支持当前的认证方式。 | 2055| SUCCESS | 0 | 认证成功。 | 2056| COMPARE_FAILURE | 1 | 比对失败。 | 2057| CANCELED | 2 | 用户取消认证。 | 2058| TIMEOUT | 3 | 认证超时。 | 2059| CAMERA_FAIL | 4 | 开启相机失败。 | 2060| BUSY | 5 | 认证服务忙，请稍后重试。 | 2061| INVALID_PARAMETERS | 6 | 认证参数无效。 | 2062| LOCKED | 7 | 认证失败次数过多，已锁定。 | 2063| NOT_ENROLLED | 8 | 未录入认证凭据。 | 2064| GENERAL_ERROR | 100 | 其他错误。 | 2065 2066