1# @ohos.userIAM.userAuth (用户认证) 2 3提供用户认证能力，可应用于设备解锁、支付、应用登录等身份认证场景。 4 5> **说明：** 6> 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 7 8 9## 导入模块 10 11```ts 12import { userAuth } from '@kit.UserAuthenticationKit'; 13``` 14 15## 常量 16 17表示复用设备解锁结果最大有效时长。 18 19**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 20 21**系统能力**：SystemCapability.UserIAM.UserAuth.Core 22 23| 名称 | 值 | 说明 | 24| ----------- | ---- | ---------- | 25| MAX_ALLOWABLE_REUSE_DURATION<sup>12+</sup> | 300000 | 复用设备解锁结果最大有效时长，值为300000毫秒。 | 26 27## EnrolledState<sup>12+</sup> 28 29表示用户注册凭据的状态。 30 31**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 32 33**系统能力**：SystemCapability.UserIAM.UserAuth.Core 34 35| 名称 | 类型 | 可读 | 可写 | 说明 | 36| ------------ | ---------- | ---- | ---- | -------------------- | 37| credentialDigest | number | 是 | 否 | 注册的凭据摘要，在凭据增加时随机生成。| 38| credentialCount | number | 是 | 否 | 注册的凭据数量。 | 39 40## ReuseMode<sup>12+</sup> 41 42表示复用设备解锁结果的模式。 43 44**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 45 46**系统能力**：SystemCapability.UserIAM.UserAuth.Core 47 48| 名称 | 值 | 说明 | 49| ----------- | ---- | ---------- | 50| AUTH_TYPE_RELEVANT | 1 | 与认证类型相关，只有当设备解锁结果在有效时间内，并且设备解锁的认证类型匹配上本次认证指定认证类型之一时，可以复用该结果。 | 51| AUTH_TYPE_IRRELEVANT | 2 | 与认证类型无关，只要解锁认证结果在有效时间内，就可以重复使用。 | 52 53## ReuseUnlockResult<sup>12+</sup> 54 55表示复用设备解锁结果。 56> **说明**： 57> 58> 如果锁屏解锁后，在有效时间内凭据发生了变化，锁屏认证结果依然可以复用，认证结果中返回当前实际的EnrolledState。若复用锁屏认证结果 59> 时，凭据已经被完全删除，则返回的EnrolledState中credentialCount和credentialDigest均为0。 60 61**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 62 63**系统能力**：SystemCapability.UserIAM.UserAuth.Core 64 65| 名称 | 类型 | 必填 | 说明 | 66| ------------ | ---------- | ---- | -------------------- | 67| reuseMode | [ReuseMode](#reusemode12) | 是 | 复用设备解锁结果的模式。 | 68| reuseDuration | number | 是 | 允许复用设备解锁结果的有效时长，有效时长的值应大于0，最大值为[MAX_ALLOWABLE_REUSE_DURATION](#常量)。 | 69 70## userAuth.getEnrolledState<sup>12+</sup> 71 72getEnrolledState(authType : UserAuthType): EnrolledState 73 74查询凭据注册的状态，用于感知用户注册凭据变化。 75 76**需要权限**：ohos.permission.ACCESS_BIOMETRIC 77 78**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 79 80**系统能力**：SystemCapability.UserIAM.UserAuth.Core 81 82**参数：** 83 84| 参数名 | 类型 | 必填 | 说明 | 85| -------------- | ---------------------------------- | ---- | -------------------------- | 86| authType | [UserAuthType](#userauthtype8) | 是 | 认证类型。| 87 88**返回值：** 89 90| 类型 | 说明 | 91| --------------------- | ------------------------------------------------------------ | 92| [EnrolledState](#enrolledstate12) | 当查询成功时，返回用户注册凭据的状态。 | 93 94**错误码：** 95 96以下错误码的详细介绍请参见[用户认证错误码](errorcode-useriam.md)。 97 98| 错误码ID | 错误信息 | 99| -------- | ------- | 100| 201 | Permission verification failed. | 101| 401 | Incorrect parameters. Possible causes: 1.Mandatory parameters are left unspecified. | 102| 12500002 | General operation error. | 103| 12500005 | The authentication type is not supported. | 104| 12500010 | The type of credential has not been enrolled. | 105 106**示例：** 107 108```ts 109import { userAuth } from '@kit.UserAuthenticationKit'; 110 111try { 112 let enrolledState = userAuth.getEnrolledState(userAuth.UserAuthType.FACE); 113 console.info('get current enrolled state success, enrolledState = ' + JSON.stringify(enrolledState)); 114} catch (error) { 115 console.error('get current enrolled state failed, error = ' + JSON.stringify(error)); 116} 117``` 118 119## AuthParam<sup>10+</sup> 120 121用户认证相关参数。 122 123**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 124 125**系统能力**：SystemCapability.UserIAM.UserAuth.Core 126 127| 名称 | 类型 | 必填 | 说明 | 128| -------------- | ---------------------------------- | ---- | ------------------------------------------------------------ | 129| challenge | Uint8Array | 是 | 随机挑战值，用来防重放攻击。最大长度为32字节，可传Uint8Array([])。 | 130| authType | [UserAuthType](#userauthtype8)[] | 是 | 认证类型列表，用来指定用户认证界面提供的认证方法。 | 131| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | 是 | 认证信任等级。 | 132| reuseUnlockResult<sup>12+</sup> | [ReuseUnlockResult](#reuseunlockresult12) | 否 |表示可以复用设备解锁结果。| 133 134## WidgetParam<sup>10+</sup> 135 136用户认证界面配置相关参数。 137 138**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 139 140**系统能力**：SystemCapability.UserIAM.UserAuth.Core 141 142| 名称 | 类型 | 必填 | 说明 | 143| -------------------- | ----------------------------------- | ---- | ------------------------------------------------------------ | 144| title | string | 是 | 用户认证界面的标题，最大长度为500字符。 | 145| navigationButtonText | string | 否 | 导航按键的说明文本，最大长度为60字符。仅在单指纹、单人脸场景下支持。 | 146 147## UserAuthResult<sup>10+</sup> 148 149用户认证结果。当认证结果为成功时，返回认证类型和认证通过的令牌信息。 150 151**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 152 153**系统能力**：SystemCapability.UserIAM.UserAuth.Core 154 155| 名称 | 类型 | 必填 | 说明 | 156| -------- | ------------------------------ | ---- | ------------------------------------------------------------ | 157| result | number | 是 | 用户认证结果。若成功返回SUCCESS，若失败返回相应错误码，参见[UserAuthResultCode](#userauthresultcode9)。 | 158| token | Uint8Array | 否 | 当认证结果为成功时，返回认证通过的令牌信息。 | 159| authType | [UserAuthType](#userauthtype8) | 否 | 当认证结果为成功时，返回认证类型。 | 160| enrolledState<sup>12+</sup> | [EnrolledState](#enrolledstate12) | 否 | 当认证结果为成功时，返回注册凭据的状态。 | 161 162## IAuthCallback<sup>10+</sup> 163 164返回认证结果的回调对象。 165 166### onResult<sup>10+</sup> 167 168onResult(result: UserAuthResult): void 169 170回调函数，返回认证结果。如果认证成功，可以通过UserAuthResult获取到认证通过的令牌信息。 171 172**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 173 174**系统能力**：SystemCapability.UserIAM.UserAuth.Core 175 176**参数：** 177 178| 参数名 | 类型 | 必填 | 说明 | 179| ------ | ----------------------------------- | ---- | ---------- | 180| result | [UserAuthResult](#userauthresult10) | 是 | 认证结果。 | 181 182**示例1：** 183 184```ts 185import { BusinessError } from '@kit.BasicServicesKit'; 186import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 187import { userAuth } from '@kit.UserAuthenticationKit'; 188 189try { 190 const rand = cryptoFramework.createRandom(); 191 const len: number = 16; 192 const randData: Uint8Array = rand?.generateRandomSync(len)?.data; 193 const authParam: userAuth.AuthParam = { 194 challenge: randData, 195 authType: [userAuth.UserAuthType.PIN], 196 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 197 }; 198 const widgetParam: userAuth.WidgetParam = { 199 title: '请输入密码', 200 }; 201 202 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 203 console.log('get userAuth instance success'); 204 // 需要调用UserAuthInstance的start()接口，启动认证后，才能通过onResult获取到认证结果。 205 userAuthInstance.on('result', { 206 onResult (result) { 207 console.log(`userAuthInstance callback result = ${JSON.stringify(result)}`); 208 } 209 }); 210 console.log('auth on success'); 211} catch (error) { 212 const err: BusinessError = error as BusinessError; 213 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 214} 215``` 216 217**示例2：** 218 219```ts 220import { BusinessError } from '@kit.BasicServicesKit'; 221import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 222import { userAuth } from '@kit.UserAuthenticationKit'; 223 224let reuseUnlockResult: userAuth.ReuseUnlockResult = { 225 reuseMode: userAuth.ReuseMode.AUTH_TYPE_RELEVANT, 226 reuseDuration: userAuth.MAX_ALLOWABLE_REUSE_DURATION, 227} 228try { 229 const rand = cryptoFramework.createRandom(); 230 const len: number = 16; 231 const randData: Uint8Array = rand?.generateRandomSync(len)?.data; 232 const authParam: userAuth.AuthParam = { 233 challenge: randData, 234 authType: [userAuth.UserAuthType.PIN], 235 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 236 reuseUnlockResult: reuseUnlockResult, 237 }; 238 const widgetParam: userAuth.WidgetParam = { 239 title: '请输入密码', 240 }; 241 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 242 console.log('get userAuth instance success'); 243 // 需要调用UserAuthInstance的start()接口，启动认证后，才能通过onResult获取到认证结果。 244 userAuthInstance.on('result', { 245 onResult (result) { 246 console.log(`userAuthInstance callback result = ${JSON.stringify(result)}`); 247 } 248 }); 249 console.log('auth on success'); 250} catch (error) { 251 const err: BusinessError = error as BusinessError; 252 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 253} 254``` 255 256## UserAuthInstance<sup>10+</sup> 257 258用于执行用户身份认证，并支持使用统一用户身份认证控件。 259使用以下接口前，都需要先通过[getUserAuthInstance](#userauthgetuserauthinstance10)方法获取UserAuthInstance对象。 260 261### on<sup>10+</sup> 262 263on(type: 'result', callback: IAuthCallback): void 264 265订阅用户身份认证结果。 266 267**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 268 269**系统能力**：SystemCapability.UserIAM.UserAuth.Core 270 271**参数：** 272 273| 参数名 | 类型 | 必填 | 说明 | 274| -------- | --------------------------------- | ---- | ------------------------------------------ | 275| type | 'result' | 是 | 订阅事件类型，表明该事件用来返回认证结果。 | 276| callback | [IAuthCallback](#iauthcallback10) | 是 | 认证接口的回调函数，用于返回认证结果。 | 277 278**错误码：** 279 280以下错误码的详细介绍请参见[用户认证错误码](errorcode-useriam.md)。 281 282| 错误码ID | 错误信息 | 283| -------- | ------------------------ | 284| 401 | Incorrect parameters. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 285| 12500002 | General operation error. | 286 287**示例：** 288 289```ts 290import { BusinessError } from '@kit.BasicServicesKit'; 291import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 292import { userAuth } from '@kit.UserAuthenticationKit'; 293 294try { 295 const rand = cryptoFramework.createRandom(); 296 const len: number = 16; 297 const randData: Uint8Array = rand?.generateRandomSync(len)?.data; 298 const authParam: userAuth.AuthParam = { 299 challenge: randData, 300 authType: [userAuth.UserAuthType.PIN], 301 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 302 }; 303 const widgetParam: userAuth.WidgetParam = { 304 title: '请输入密码', 305 }; 306 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 307 console.log('get userAuth instance success'); 308 // 需要调用UserAuthInstance的start()接口，启动认证后，才能通过onResult获取到认证结果。 309 userAuthInstance.on('result', { 310 onResult (result) { 311 console.log(`userAuthInstance callback result = ${JSON.stringify(result)}`); 312 } 313 }); 314 console.log('auth on success'); 315} catch (error) { 316 const err: BusinessError = error as BusinessError; 317 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 318} 319``` 320 321### off<sup>10+</sup> 322 323off(type: 'result', callback?: IAuthCallback): void 324 325取消订阅用户身份认证结果。 326 327> **说明**： 328> 329> 需要使用已经成功订阅事件的[UserAuthInstance](#userauthinstance10)对象调用该接口进行取消订阅。 330 331**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 332 333**系统能力**：SystemCapability.UserIAM.UserAuth.Core 334 335**参数：** 336 337| 参数名 | 类型 | 必填 | 说明 | 338| -------- | --------------------------------- | ---- | ------------------------------------------ | 339| type | 'result' | 是 | 订阅事件类型，表明该事件用来返回认证结果。 | 340| callback | [IAuthCallback](#iauthcallback10) | 否 | 认证接口的回调函数，用于返回认证结果。 | 341 342**错误码：** 343 344以下错误码的详细介绍请参见[用户认证错误码](errorcode-useriam.md)。 345 346| 错误码ID | 错误信息 | 347| -------- | ------------------------ | 348| 401 | Incorrect parameters. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 349| 12500002 | General operation error. | 350 351**示例：** 352 353```ts 354import { BusinessError } from '@kit.BasicServicesKit'; 355import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 356import { userAuth } from '@kit.UserAuthenticationKit'; 357 358try { 359 const rand = cryptoFramework.createRandom(); 360 const len: number = 16; 361 const randData: Uint8Array = rand?.generateRandomSync(len)?.data; 362 const authParam: userAuth.AuthParam = { 363 challenge: randData, 364 authType: [userAuth.UserAuthType.PIN], 365 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 366 }; 367 const widgetParam: userAuth.WidgetParam = { 368 title: '请输入密码', 369 }; 370 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 371 console.log('get userAuth instance success'); 372 userAuthInstance.off('result', { 373 onResult (result) { 374 console.log(`auth off result = ${JSON.stringify(result)}`); 375 } 376 }); 377 console.log('auth off success'); 378} catch (error) { 379 const err: BusinessError = error as BusinessError; 380 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 381} 382``` 383 384### start<sup>10+</sup> 385 386start(): void 387 388开始认证。 389 390> **说明：** 391> 每个UserAuthInstance只能进行一次认证，若需要再次进行认证则需重新获取UserAuthInstance。 392 393**需要权限**：ohos.permission.ACCESS_BIOMETRIC 394 395**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 396 397**系统能力**：SystemCapability.UserIAM.UserAuth.Core 398 399**错误码：** 400 401以下错误码的详细介绍请参见[用户认证错误码](errorcode-useriam.md)。 402 403| 错误码ID | 错误信息 | 404| -------- | ------------------------------------------------ | 405| 201 | Permission verification failed. | 406| 401 | Incorrect parameters. Possible causes: 1.Incorrect parameter types. | 407| 12500001 | Authentication failed. | 408| 12500002 | General operation error. | 409| 12500003 | Authentication canceled. | 410| 12500004 | Authentication timeout. | 411| 12500005 | The authentication type is not supported. | 412| 12500006 | The authentication trust level is not supported. | 413| 12500007 | Authentication service is busy. | 414| 12500009 | Authentication is locked out. | 415| 12500010 | The type of credential has not been enrolled. | 416| 12500011 | Switched to the custom authentication process. | 417| 12500013 | Operation failed because of PIN expired. | 418 419**示例：** 420 421```ts 422import { BusinessError } from '@kit.BasicServicesKit'; 423import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 424import { userAuth } from '@kit.UserAuthenticationKit'; 425 426try { 427 const rand = cryptoFramework.createRandom(); 428 const len: number = 16; 429 const randData: Uint8Array = rand?.generateRandomSync(len)?.data; 430 const authParam: userAuth.AuthParam = { 431 challenge: randData, 432 authType: [userAuth.UserAuthType.PIN], 433 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 434 }; 435 const widgetParam: userAuth.WidgetParam = { 436 title: '请输入密码', 437 }; 438 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 439 console.log('get userAuth instance success'); 440 userAuthInstance.start(); 441 console.log('auth start success'); 442} catch (error) { 443 const err: BusinessError = error as BusinessError; 444 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 445} 446``` 447 448### cancel<sup>10+</sup> 449 450cancel(): void 451 452取消认证。 453 454> **说明**： 455> 456> 此时UserAuthInstance需要是正在进行认证的对象。 457 458**需要权限**：ohos.permission.ACCESS_BIOMETRIC 459 460**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 461 462**系统能力**：SystemCapability.UserIAM.UserAuth.Core 463 464**错误码：** 465 466| 错误码ID | 错误信息 | 467| -------- | ------------------------------- | 468| 201 | Permission verification failed. | 469| 401 | Incorrect parameters. Possible causes: 1.Incorrect parameter types. | 470| 12500002 | General operation error. | 471 472**示例：** 473 474```ts 475import { BusinessError } from '@kit.BasicServicesKit'; 476import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 477import { userAuth } from '@kit.UserAuthenticationKit'; 478 479try { 480 const rand = cryptoFramework.createRandom(); 481 const len: number = 16; 482 const randData: Uint8Array = rand?.generateRandomSync(len)?.data; 483 const authParam : userAuth.AuthParam = { 484 challenge: randData, 485 authType: [userAuth.UserAuthType.PIN], 486 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 487 }; 488 const widgetParam: userAuth.WidgetParam = { 489 title: '请输入密码', 490 }; 491 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 492 console.log('get userAuth instance success'); 493 // 需要调用UserAuthInstance的start()接口，启动认证后，才能调用cancel()接口。 494 userAuthInstance.cancel(); 495 console.log('auth cancel success'); 496} catch (error) { 497 const err: BusinessError = error as BusinessError; 498 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 499} 500``` 501 502## userAuth.getUserAuthInstance<sup>10+</sup> 503 504getUserAuthInstance(authParam: AuthParam, widgetParam: WidgetParam): UserAuthInstance 505 506获取[UserAuthInstance](#userauthinstance10)对象，用于执行用户身份认证，并支持使用统一用户身份认证控件。 507 508> **说明：** 509> 每个UserAuthInstance只能进行一次认证，若需要再次进行认证则需重新获取UserAuthInstance。 510 511**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 512 513**系统能力**：SystemCapability.UserIAM.UserAuth.Core 514 515**参数：** 516 517| 参数名 | 类型 | 必填 | 说明 | 518| ----------- | ----------------------------- | ---- | -------------------------- | 519| authParam | [AuthParam](#authparam10) | 是 | 用户认证相关参数。 | 520| widgetParam | [WidgetParam](#widgetparam10) | 是 | 用户认证界面配置相关参数。 | 521 522**返回值：** 523 524| 类型 | 说明 | 525| --------------------------------------- | -------------------------- | 526| [UserAuthInstance](#userauthinstance10) | 支持用户界面的认证器对象。 | 527 528**错误码：** 529 530以下错误码的详细介绍请参见[用户认证错误码](errorcode-useriam.md)。 531 532| 错误码ID | 错误信息 | 533| -------- | ------------------------------------------------ | 534| 401 | Incorrect parameters. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 535| 12500002 | General operation error. | 536| 12500005 | The authentication type is not supported. | 537| 12500006 | The authentication trust level is not supported. | 538 539**示例：** 540 541```ts 542import { BusinessError } from '@kit.BasicServicesKit'; 543import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 544import { userAuth } from '@kit.UserAuthenticationKit'; 545 546try { 547 const rand = cryptoFramework.createRandom(); 548 const len: number = 16; 549 const randData: Uint8Array = rand?.generateRandomSync(len)?.data; 550 const authParam: userAuth.AuthParam = { 551 challenge: randData, 552 authType: [userAuth.UserAuthType.PIN], 553 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 554 }; 555 const widgetParam: userAuth.WidgetParam = { 556 title: '请输入密码', 557 }; 558 let userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 559 console.log('get userAuth instance success'); 560} catch (error) { 561 const err: BusinessError = error as BusinessError; 562 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 563} 564``` 565 566## AuthResultInfo<sup>(deprecated)</sup> 567 568表示认证结果信息。 569 570> **说明：** 571> 从 API version 9 开始支持，从 API version 11 开始废弃。 572 573**系统能力**：SystemCapability.UserIAM.UserAuth.Core 574 575| 名称 | 类型 | 必填 | 说明 | 576| ------------ | ---------- | ---- | -------------------- | 577| result | number | 是 | 认证结果。 | 578| token | Uint8Array | 否 | 用户身份认证通过的凭证。 | 579| remainAttempts | number | 否 | 剩余的认证尝试次数。 | 580| lockoutDuration | number | 否 | 认证操作的锁定时长，时间单位为毫秒ms。 | 581 582## TipInfo<sup>(deprecated)</sup> 583 584表示认证过程中的提示信息。 585 586> **说明：** 587> 从 API version 9 开始支持，从 API version 11 开始废弃。 588 589**系统能力**：SystemCapability.UserIAM.UserAuth.Core。 590 591| 名称 | 类型 | 必填 | 说明 | 592| ------------ | ---------- | ---- | -------------------- | 593| module | number | 是 | 发送提示信息的模块标识。 | 594| tip | number | 是 | 认证过程提示信息。 | 595 596## EventInfo<sup>(deprecated)</sup> 597 598type EventInfo = AuthResultInfo | TipInfo 599 600表示认证过程中事件信息的类型。 601 602该类型为下表类型中的联合类型。 603 604> **说明：** 605> 从 API version 9 开始支持，从 API version 11 开始废弃，请使用[UserAuthResult](#userauthresult10)替代。 606 607**系统能力**：SystemCapability.UserIAM.UserAuth.Core。 608 609| 类型 | 说明 | 610| --------- | ----------------------- | 611| [AuthResultInfo](#authresultinfodeprecated) | 获取到的认证结果信息。 | 612| [TipInfo](#tipinfodeprecated) | 认证过程中的提示信息。 | 613 614## AuthEventKey<sup>(deprecated)</sup> 615 616type AuthEventKey = 'result' | 'tip' 617 618表示认证事件类型的关键字，作为[on](#ondeprecated)接口的的参数。 619 620该类型为下表类型取值中的联合类型。 621 622> **说明：** 623> 从 API version 9 开始支持，从 API version 11 开始废弃。 624 625**系统能力**：SystemCapability.UserIAM.UserAuth.Core。 626 627| 类型 | 说明 | 628| ---------- | ----------------------- | 629| 'result' | [on](#ondeprecated)接口第一个参数为"result"时，[callback](#callbackdeprecated)回调返回认证的结果信息。 | 630| 'tip' | [on](#ondeprecated)接口第一个参数为"tip"时，[callback](#callbackdeprecated)回调返回认证操作中的提示信息。 | 631 632## AuthEvent<sup>(deprecated)</sup> 633 634认证接口的异步回调对象。 635 636> **说明：** 637> 从 API version 9 开始支持，从 API version 11 开始废弃，请使用[IAuthCallback](#iauthcallback10)替代。 638 639### callback<sup>(deprecated)</sup> 640 641callback(result : EventInfo) : void 642 643通过该回调获取认证结果信息或认证过程中的提示信息。 644 645> **说明：** 646> 从 API version 9 开始支持，从 API version 11 开始废弃，请使用[onResult](#onresult10)替代。 647 648**系统能力**：SystemCapability.UserIAM.UserAuth.Core 649 650**参数：** 651 652| 参数名 | 类型 | 必填 | 说明 | 653| --------- | -------------------------- | ---- | ------------------------------ | 654| result | [EventInfo](#eventinfodeprecated) | 是 | 返回的认证结果信息或提示信息。 | 655 656**示例：** 657 658```ts 659import { userAuth } from '@kit.UserAuthenticationKit'; 660 661let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 662let authType = userAuth.UserAuthType.FACE; 663let authTrustLevel = userAuth.AuthTrustLevel.ATL1; 664// 通过callback获取认证结果 665try { 666 let auth = userAuth.getAuthInstance(challenge, authType, authTrustLevel); 667 auth.on('result', { 668 callback: (result: userAuth.AuthResultInfo) => { 669 console.log('authV9 result ' + result.result); 670 console.log('authV9 token ' + result.token); 671 console.log('authV9 remainAttempts ' + result.remainAttempts); 672 console.log('authV9 lockoutDuration ' + result.lockoutDuration); 673 } 674 } as userAuth.AuthEvent); 675 auth.start(); 676 console.log('authV9 start success'); 677} catch (error) { 678 console.error('authV9 error = ' + error); 679 // do error 680} 681// 通过callback获取认证过程中的提示信息 682try { 683 let auth = userAuth.getAuthInstance(challenge, authType, authTrustLevel); 684 auth.on('tip', { 685 callback : (result : userAuth.TipInfo) => { 686 switch (result.tip) { 687 case userAuth.FaceTips.FACE_AUTH_TIP_TOO_BRIGHT: 688 // do something; 689 case userAuth.FaceTips.FACE_AUTH_TIP_TOO_DARK: 690 // do something; 691 default: 692 // do others 693 } 694 } 695 } as userAuth.AuthEvent); 696 auth.start(); 697 console.log('authV9 start success'); 698} catch (error) { 699 console.error('authV9 error = ' + error); 700 // do error 701} 702``` 703 704## AuthInstance<sup>(deprecated)</sup> 705 706执行用户认证的对象。 707 708> **说明：** 709> 从 API version 9 开始支持，从 API version 10 开始废弃，请使用[UserAuthInstance](#userauthinstance10)替代。 710 711### on<sup>(deprecated)</sup> 712 713on : (name : AuthEventKey, callback : AuthEvent) => void 714 715订阅指定类型的用户认证事件。 716 717> **说明：** 718> - 从 API version 9 开始支持，从 API version 10 开始废弃。 719> - 使用获取到的[AuthInstance](#authinstancedeprecated)对象调用该接口进行订阅。 720 721**系统能力**：SystemCapability.UserIAM.UserAuth.Core 722 723**参数：** 724 725| 参数名 | 类型 | 必填 | 说明 | 726| --------- | -------------------------- | ---- | ------------------------- | 727| name | [AuthEventKey](#autheventkeydeprecated) | 是 | 表示认证事件类型，取值为"result"时，回调函数返回认证结果；取值为"tip"时，回调函数返回认证过程中的提示信息。 | 728| callback | [AuthEvent](#autheventdeprecated) | 是 | 认证接口的回调函数，用于返回认证结果或认证过程中的提示信息。 | 729 730**错误码：** 731 732以下错误码的详细介绍请参见[用户认证错误码](errorcode-useriam.md)。 733 734| 错误码ID | 错误信息 | 735| -------- | ------- | 736| 401 | Incorrect parameters. | 737| 12500002 | General operation error. | 738 739**示例：** 740 741```ts 742import { userAuth } from '@kit.UserAuthenticationKit'; 743 744let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 745let authType = userAuth.UserAuthType.FACE; 746let authTrustLevel = userAuth.AuthTrustLevel.ATL1; 747try { 748 let auth = userAuth.getAuthInstance(challenge, authType, authTrustLevel); 749 // 订阅认证结果 750 auth.on('result', { 751 callback: (result: userAuth.AuthResultInfo) => { 752 console.log('authV9 result ' + result.result); 753 console.log('authV9 token ' + result.token); 754 console.log('authV9 remainAttempts ' + result.remainAttempts); 755 console.log('authV9 lockoutDuration ' + result.lockoutDuration); 756 } 757 }); 758 // 订阅认证过程中的提示信息 759 auth.on('tip', { 760 callback : (result : userAuth.TipInfo) => { 761 switch (result.tip) { 762 case userAuth.FaceTips.FACE_AUTH_TIP_TOO_BRIGHT: 763 // do something; 764 case userAuth.FaceTips.FACE_AUTH_TIP_TOO_DARK: 765 // do something; 766 default: 767 // do others 768 } 769 } 770 } as userAuth.AuthEvent); 771 auth.start(); 772 console.log('authV9 start success'); 773} catch (error) { 774 console.error('authV9 error = ' + error); 775 // do error 776} 777``` 778 779### off<sup>(deprecated)</sup> 780 781off : (name : AuthEventKey) => void 782 783取消订阅特定类型的认证事件。 784 785> **说明：** 786> - 从 API version 9 开始支持，从 API version 10 开始废弃。 787> - 需要使用已经成功订阅事件的[AuthInstance](#authinstancedeprecated)对象调用该接口进行取消订阅。 788 789**系统能力**：SystemCapability.UserIAM.UserAuth.Core 790 791| 名称 | 类型 | 必填 | 说明 | 792| --------- | -------------------------- | ---- | ------------------------- | 793| name | [AuthEventKey](#autheventkeydeprecated) | 是 | 表示认证事件类型，取值为"result"时，取消订阅认证结果；取值为"tip"时，取消订阅认证过程中的提示信息。 | 794 795**错误码：** 796 797以下错误码的详细介绍请参见[用户认证错误码](errorcode-useriam.md)。 798 799| 错误码ID | 错误信息 | 800| -------- | ------- | 801| 401 | Incorrect parameters. | 802| 12500002 | General operation error. | 803 804**示例：** 805 806```ts 807import { userAuth } from '@kit.UserAuthenticationKit'; 808 809let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 810let authType = userAuth.UserAuthType.FACE; 811let authTrustLevel = userAuth.AuthTrustLevel.ATL1; 812try { 813 let auth = userAuth.getAuthInstance(challenge, authType, authTrustLevel); 814 // 订阅认证结果 815 auth.on('result', { 816 callback: (result: userAuth.AuthResultInfo) => { 817 console.log('authV9 result ' + result.result); 818 console.log('authV9 token ' + result.token); 819 console.log('authV9 remainAttempts ' + result.remainAttempts); 820 console.log('authV9 lockoutDuration ' + result.lockoutDuration); 821 } 822 }); 823 // 取消订阅结果 824 auth.off('result'); 825 console.info('cancel subscribe authentication event success'); 826} catch (error) { 827 console.error('cancel subscribe authentication event failed, error =' + error); 828 // do error 829} 830``` 831 832### start<sup>(deprecated)</sup> 833 834start : () => void 835 836开始认证。 837 838> **说明：** 839> - 从 API version 9 开始支持，从 API version 10 开始废弃。 840> - 使用获取到的[AuthInstance](#authinstancedeprecated)对象调用该接口进行认证。 841 842**需要权限**：ohos.permission.ACCESS_BIOMETRIC 843 844**系统能力**：SystemCapability.UserIAM.UserAuth.Core 845 846**错误码：** 847 848以下错误码的详细介绍请参见[用户认证错误码](errorcode-useriam.md)。 849 850| 错误码ID | 错误信息 | 851| -------- | ------- | 852| 201 | Permission verification failed. | 853| 401 | Incorrect parameters. | 854| 12500001 | Authentication failed. | 855| 12500002 | General operation error. | 856| 12500003 | The operation is canceled. | 857| 12500004 | The operation is time-out. | 858| 12500005 | The authentication type is not supported. | 859| 12500006 | The authentication trust level is not supported. | 860| 12500007 | The authentication task is busy. | 861| 12500009 | The authenticator is locked. | 862| 12500010 | The type of credential has not been enrolled. | 863 864**示例：** 865 866```ts 867import { userAuth } from '@kit.UserAuthenticationKit'; 868 869let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 870let authType = userAuth.UserAuthType.FACE; 871let authTrustLevel = userAuth.AuthTrustLevel.ATL1; 872 873try { 874 let auth = userAuth.getAuthInstance(challenge, authType, authTrustLevel); 875 auth.start(); 876 console.info('authV9 start auth success'); 877} catch (error) { 878 console.error('authV9 start auth failed, error = ' + error); 879} 880``` 881 882### cancel<sup>(deprecated)</sup> 883 884cancel : () => void 885 886取消认证。 887 888> **说明：** 889> 890> - 从 API version 9 开始支持，从 API version 10 开始废弃。 891> - 使用获取到的[AuthInstance](#authinstancedeprecated)对象调用该接口进行取消认证，此[AuthInstance](#authinstancedeprecated)需要是正在进行认证的对象。 892 893**需要权限**：ohos.permission.ACCESS_BIOMETRIC 894 895**系统能力**：SystemCapability.UserIAM.UserAuth.Core 896 897**错误码：** 898 899以下错误码的详细介绍请参见[用户认证错误码](errorcode-useriam.md)。 900 901| 错误码ID | 错误信息 | 902| -------- | ------- | 903| 201 | Permission verification failed. | 904| 401 | Incorrect parameters. | 905| 12500002 | General operation error. | 906 907**示例：** 908 909```ts 910import { userAuth } from '@kit.UserAuthenticationKit'; 911 912let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 913let authType = userAuth.UserAuthType.FACE; 914let authTrustLevel = userAuth.AuthTrustLevel.ATL1; 915 916try { 917 let auth = userAuth.getAuthInstance(challenge, authType, authTrustLevel); 918 auth.cancel(); 919 console.info('cancel auth success'); 920} catch (error) { 921 console.error('cancel auth failed, error = ' + error); 922} 923``` 924 925## userAuth.getAuthInstance<sup>(deprecated)</sup> 926 927getAuthInstance(challenge : Uint8Array, authType : UserAuthType, authTrustLevel : AuthTrustLevel): AuthInstance 928 929获取AuthInstance对象，用于执行用户身份认证。 930 931> **说明：** 932> 933> - 从 API version 9 开始支持，从 API version 10 开始废弃，请使用[getUserAuthInstance](#userauthgetuserauthinstance10)替代。 934> - 每个AuthInstance只能进行一次认证，若需要再次进行认证则需重新获取AuthInstance。 935 936 937**系统能力**：SystemCapability.UserIAM.UserAuth.Core 938 939**参数：** 940 941| 参数名 | 类型 | 必填 | 说明 | 942| -------------- | ---------------------------------------- | ---- | ------------------------ | 943| challenge | Uint8Array | 是 | 挑战值，最大长度为32字节，可以传Uint8Array([])。 | 944| authType | [UserAuthType](#userauthtype8) | 是 | 认证类型，当前支持FACE和FINGERPRINT。 | 945| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | 是 | 认证信任等级。 | 946 947**返回值：** 948 949| 类型 | 说明 | 950| --------------------------------------- | ------------ | 951| [AuthInstance](#authinstancedeprecated) | 认证器对象。 | 952 953**错误码：** 954 955以下错误码的详细介绍请参见[用户认证错误码](errorcode-useriam.md)。 956 957| 错误码ID | 错误信息 | 958| -------- | ------- | 959| 401 | Incorrect parameters. | 960| 12500002 | General operation error. | 961| 12500005 | The authentication type is not supported. | 962| 12500006 | The authentication trust level is not supported. | 963 964**示例：** 965 966```ts 967import { userAuth } from '@kit.UserAuthenticationKit'; 968 969let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 970let authType = userAuth.UserAuthType.FACE; 971let authTrustLevel = userAuth.AuthTrustLevel.ATL1; 972 973try { 974 let auth = userAuth.getAuthInstance(challenge, authType, authTrustLevel); 975 console.info('let auth instance success'); 976} catch (error) { 977 console.error('get auth instance success failed, error = ' + error); 978} 979``` 980 981## userAuth.getAvailableStatus<sup>9+</sup> 982 983getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel): void 984 985查询指定类型和等级的认证能力是否支持。 986 987**需要权限**：ohos.permission.ACCESS_BIOMETRIC 988 989**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 990 991**系统能力**：SystemCapability.UserIAM.UserAuth.Core 992 993**参数：** 994 995| 参数名 | 类型 | 必填 | 说明 | 996| -------------- | ---------------------------------- | ---- | -------------------------- | 997| authType | [UserAuthType](#userauthtype8) | 是 | 认证类型。从 API version 11 开始支持PIN查询。| 998| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | 是 | 认证信任等级。 | 999 1000> **错误码返回顺序说明：** 1001> 1002> - 无对应执行器注册时，判断系统不支持该认证能力，需返回12500005。 1003> - 有对应执行器注册时，功能未禁用，但认证安全等级低于业务指定时，需返回12500006。 1004> - 有对应执行器注册时，功能未禁用，但用户没有注册凭据时，需返回12500010。 1005> - 有对应执行器注册时，功能未禁用，但密码过期时，需返回12500013。 1006 1007**错误码：** 1008 1009以下错误码的详细介绍请参见[用户认证错误码](errorcode-useriam.md)。 1010 1011| 错误码ID | 错误信息 | 1012| -------- | ------- | 1013| 201 | Permission verification failed. | 1014| 401 | Incorrect parameters. Possible causes: 1.Mandatory parameters are left unspecified. | 1015| 12500002 | General operation error. | 1016| 12500005 | The authentication type is not supported. | 1017| 12500006 | The authentication trust level is not supported. | 1018| 12500010 | The type of credential has not been enrolled. | 1019| 12500013 | Operation failed because of PIN expired. | 1020 1021**示例：** 1022 1023```ts 1024import { userAuth } from '@kit.UserAuthenticationKit'; 1025 1026try { 1027 userAuth.getAvailableStatus(userAuth.UserAuthType.FACE, userAuth.AuthTrustLevel.ATL1); 1028 console.info('current auth trust level is supported'); 1029} catch (error) { 1030 console.error('current auth trust level is not supported, error = ' + error); 1031} 1032``` 1033 1034## UserAuthResultCode<sup>9+</sup> 1035 1036表示返回码的枚举。 1037 1038**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1039 1040**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1041 1042| 名称 | 值 | 说明 | 1043| ----------------------- | ------ | -------------------- | 1044| SUCCESS | 12500000 | 执行成功。 | 1045| FAIL | 12500001 | 认证失败。 | 1046| GENERAL_ERROR | 12500002 | 操作通用错误。 | 1047| CANCELED | 12500003 | 操作取消。 | 1048| TIMEOUT | 12500004 | 操作超时。 | 1049| TYPE_NOT_SUPPORT | 12500005 | 不支持的认证类型。 | 1050| TRUST_LEVEL_NOT_SUPPORT | 12500006 | 不支持的认证等级。 | 1051| BUSY | 12500007 | 忙碌状态。 | 1052| LOCKED | 12500009 | 认证器已锁定。 | 1053| NOT_ENROLLED | 12500010 | 用户未录入认证信息。 | 1054| CANCELED_FROM_WIDGET<sup>10+</sup> | 12500011 | 当前的认证操作被用户从组件取消。返回这个错误码，表示使用应用自定义认证。 | 1055| PIN_EXPIRED<sup>12+</sup> | 12500013 | 当前的认证操作执行失败。返回这个错误码，表示系统锁屏密码过期。 | 1056 1057## UserAuth<sup>(deprecated)</sup> 1058 1059认证器对象。 1060 1061### constructor<sup>(deprecated)</sup> 1062 1063constructor() 1064 1065创建认证器对象。 1066 1067> **说明：** 1068> 从 API version 8 开始支持，从 API version 9 开始废弃，请使用[getAuthInstance](#userauthgetauthinstancedeprecated)替代。 1069 1070**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1071 1072**示例：** 1073 1074```ts 1075import { userAuth } from '@kit.UserAuthenticationKit'; 1076 1077let auth = new userAuth.UserAuth(); 1078``` 1079 1080### getVersion<sup>(deprecated)</sup> 1081 1082getVersion() : number 1083 1084获取认证器的版本信息。 1085 1086> **说明：** 1087> 从 API version 8 开始支持，从 API version 9 开始废弃。 1088 1089**需要权限**：ohos.permission.ACCESS_BIOMETRIC 1090 1091**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1092 1093**返回值：** 1094 1095| 类型 | 说明 | 1096| ------ | ---------------------- | 1097| number | 认证器版本信息。 | 1098 1099**示例：** 1100 1101```ts 1102import { userAuth } from '@kit.UserAuthenticationKit'; 1103 1104let auth = new userAuth.UserAuth(); 1105let version = auth.getVersion(); 1106console.info('auth version = ' + version); 1107``` 1108 1109### getAvailableStatus<sup>(deprecated)</sup> 1110 1111getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel) : number 1112 1113查询指定类型和等级的认证能力是否支持。 1114 1115> **说明：** 1116> 从 API version 8 开始支持，从 API version 9 开始废弃，请使用[getAvailableStatus](#userauthgetavailablestatus9)替代。 1117 1118**需要权限**：ohos.permission.ACCESS_BIOMETRIC 1119 1120**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1121 1122**参数：** 1123 1124| 参数名 | 类型 | 必填 | 说明 | 1125| -------------- | ---------------------------------- | ---- | -------------------------- | 1126| authType | [UserAuthType](#userauthtype8) | 是 | 认证类型，当前支持FACE和FINGERPRINT。 | 1127| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | 是 | 认证信任等级。 | 1128 1129**返回值：** 1130 1131| 类型 | 说明 | 1132| ------ | ------------------------------------------------------------ | 1133| number | 查询结果，结果为SUCCESS时表示支持，其他返回值参见[ResultCode](#resultcodedeprecated)。 | 1134 1135**示例：** 1136 1137```ts 1138import { userAuth } from '@kit.UserAuthenticationKit'; 1139 1140let auth = new userAuth.UserAuth(); 1141let checkCode = auth.getAvailableStatus(userAuth.UserAuthType.FACE, userAuth.AuthTrustLevel.ATL1); 1142if (checkCode == userAuth.ResultCode.SUCCESS) { 1143 console.info('check auth support success'); 1144} else { 1145 console.error('check auth support fail, code = ' + checkCode); 1146} 1147``` 1148 1149### auth<sup>(deprecated)</sup> 1150 1151auth(challenge: Uint8Array, authType: UserAuthType, authTrustLevel: AuthTrustLevel, callback: IUserAuthCallback): Uint8Array 1152 1153执行用户认证，使用回调函数返回结果。 1154 1155> **说明：** 1156> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[start](#startdeprecated)代替。 1157 1158**需要权限**：ohos.permission.ACCESS_BIOMETRIC 1159 1160**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1161 1162**参数：** 1163 1164| 参数名 | 类型 | 必填 | 说明 | 1165| -------------- | ---------------------------------------- | ---- | ------------------------ | 1166| challenge | Uint8Array | 是 | 挑战值，可以传Uint8Array([])。 | 1167| authType | [UserAuthType](#userauthtype8) | 是 | 认证类型，当前支持FACE和FINGERPRINT。 | 1168| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | 是 | 认证信任等级。 | 1169| callback | [IUserAuthCallback](#iuserauthcallbackdeprecated) | 是 | 回调函数。 | 1170 1171**返回值：** 1172 1173| 类型 | 说明 | 1174| ---------- | ------------------------------------------------------------ | 1175| Uint8Array | ContextId，作为取消认证[cancelAuth](#cancelauthdeprecated)接口的入参。 | 1176 1177**示例：** 1178 1179```ts 1180import { userAuth } from '@kit.UserAuthenticationKit'; 1181 1182let auth = new userAuth.UserAuth(); 1183let challenge = new Uint8Array([]); 1184auth.auth(challenge, userAuth.UserAuthType.FACE, userAuth.AuthTrustLevel.ATL1, { 1185 onResult: (result, extraInfo) => { 1186 try { 1187 console.info('auth onResult result = ' + result); 1188 console.info('auth onResult extraInfo = ' + JSON.stringify(extraInfo)); 1189 if (result == userAuth.ResultCode.SUCCESS) { 1190 // 此处添加认证成功逻辑 1191 } else { 1192 // 此处添加认证失败逻辑 1193 } 1194 } catch (error) { 1195 console.error('auth onResult error = ' + error); 1196 } 1197 } 1198}); 1199``` 1200 1201### cancelAuth<sup>(deprecated)</sup> 1202 1203cancelAuth(contextID : Uint8Array) : number 1204 1205表示通过contextID取消本次认证操作。 1206 1207> **说明：** 1208> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[cancel](#canceldeprecated)代替。 1209 1210**需要权限**：ohos.permission.ACCESS_BIOMETRIC 1211 1212**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1213 1214**参数：** 1215 1216| 参数名 | 类型 | 必填 | 说明 | 1217| --------- | ---------- | ---- | ------------------------------------------ | 1218| contextID | Uint8Array | 是 | 上下文的标识，通过[auth](#authdeprecated)接口获取。 | 1219 1220**返回值：** 1221 1222| 类型 | 说明 | 1223| ------ | ------------------------ | 1224| number | 取消认证的结果，结果为SUCCESS时表示取消成功，其他返回值参见[ResultCode](#resultcodedeprecated)。 | 1225 1226**示例：** 1227 1228```ts 1229import { userAuth } from '@kit.UserAuthenticationKit'; 1230 1231// contextId可通过auth接口获取，此处直接定义 1232let contextId = new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7]); 1233let auth = new userAuth.UserAuth(); 1234let cancelCode = auth.cancelAuth(contextId); 1235if (cancelCode == userAuth.ResultCode.SUCCESS) { 1236 console.info('cancel auth success'); 1237} else { 1238 console.error('cancel auth fail'); 1239} 1240``` 1241 1242## IUserAuthCallback<sup>(deprecated)</sup> 1243 1244返回认证结果的回调对象。 1245 1246> **说明：** 1247> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[AuthEvent](#autheventdeprecated)代替。 1248 1249### onResult<sup>(deprecated)</sup> 1250 1251onResult: (result : number, extraInfo : AuthResult) => void 1252 1253回调函数，返回认证结果。 1254 1255> **说明：** 1256> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[callback](#callbackdeprecated)代替。 1257 1258**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1259 1260**参数：** 1261 1262| 参数名 | 类型 | 必填 | 说明 | 1263| --------- | -------------------------- | ---- | ------------------------------------------------ | 1264| result | number | 是 | 认证结果，参见[ResultCode](#resultcodedeprecated)。 | 1265| extraInfo | [AuthResult](#authresultdeprecated) | 是 | 扩展信息，不同情况下的具体信息，<br/>如果身份验证通过，则在extraInfo中返回用户认证令牌，<br/>如果身份验证失败，则在extraInfo中返回剩余的用户认证次数，<br/>如果身份验证执行器被锁定，则在extraInfo中返回冻结时间。 | 1266 1267**示例：** 1268 1269```ts 1270import { userAuth } from '@kit.UserAuthenticationKit'; 1271 1272let auth = new userAuth.UserAuth(); 1273let challenge = new Uint8Array([]); 1274auth.auth(challenge, userAuth.UserAuthType.FACE, userAuth.AuthTrustLevel.ATL1, { 1275 onResult: (result, extraInfo) => { 1276 try { 1277 console.info('auth onResult result = ' + result); 1278 console.info('auth onResult extraInfo = ' + JSON.stringify(extraInfo)); 1279 if (result == userAuth.ResultCode.SUCCESS) { 1280 // 此处添加认证成功逻辑 1281 } else { 1282 // 此处添加认证失败逻辑 1283 } 1284 } catch (error) { 1285 console.error('auth onResult error = ' + error); 1286 } 1287 } 1288}); 1289``` 1290 1291### onAcquireInfo<sup>(deprecated)</sup> 1292 1293onAcquireInfo ?: (module : number, acquire : number, extraInfo : any) => void 1294 1295回调函数，返回认证过程中的提示信息，非必须实现。 1296 1297> **说明：** 1298> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[callback](#callbackdeprecated)代替。 1299 1300**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1301 1302**参数：** 1303 1304| 参数名 | 类型 | 必填 | 说明 | 1305| --------- | ------ | ---- | ------------------------------ | 1306| module | number | 是 | 发送提示信息的模块标识。 | 1307| acquire | number | 是 | 认证执过程中的提示信息。 | 1308| extraInfo | any | 是 | 预留字段。 | 1309 1310**示例：** 1311 1312```ts 1313import { userAuth } from '@kit.UserAuthenticationKit'; 1314 1315let auth = new userAuth.UserAuth(); 1316let challenge = new Uint8Array([]); 1317auth.auth(challenge, userAuth.UserAuthType.FACE, userAuth.AuthTrustLevel.ATL1, { 1318 onResult: (result, extraInfo) => { 1319 try { 1320 console.info('auth onResult result = ' + result); 1321 console.info('auth onResult extraInfo = ' + JSON.stringify(extraInfo)); 1322 if (result == userAuth.ResultCode.SUCCESS) { 1323 // 此处添加认证成功逻辑 1324 } else { 1325 // 此处添加认证失败逻辑 1326 } 1327 } catch (error) { 1328 console.error('auth onResult error = ' + error); 1329 } 1330 }, 1331 onAcquireInfo: (module, acquire, extraInfo : userAuth.AuthResult) => { 1332 try { 1333 console.info('auth onAcquireInfo module = ' + module); 1334 console.info('auth onAcquireInfo acquire = ' + acquire); 1335 console.info('auth onAcquireInfo extraInfo = ' + JSON.stringify(extraInfo)); 1336 } catch (error) { 1337 console.error('auth onAcquireInfo error = ' + error); 1338 } 1339 } 1340}); 1341``` 1342 1343## AuthResult<sup>(deprecated)</sup> 1344 1345表示认证结果的对象。 1346 1347> **说明：** 1348> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[AuthResultInfo](#authresultinfodeprecated)代替。 1349 1350**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1351 1352| 名称 | 类型 | 必填 | 说明 | 1353| ------------ | ---------- | ---- | -------------------| 1354| token | Uint8Array | 否 | 认证通过的令牌信息。 | 1355| remainTimes | number | 否 | 剩余的认证操作次数。 | 1356| freezingTime | number | 否 | 认证操作的冻结时间。 | 1357 1358## ResultCode<sup>(deprecated)</sup> 1359 1360表示返回码的枚举。 1361 1362> **说明：** 1363> 从 API version 9 开始废弃，建议使用[UserAuthResultCode](#userauthresultcode9)代替。 1364 1365**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1366 1367| 名称 | 值 | 说明 | 1368| ----------------------- | ------ | -------------------- | 1369| SUCCESS | 0 | 执行成功。 | 1370| FAIL | 1 | 认证失败。 | 1371| GENERAL_ERROR | 2 | 操作通用错误。 | 1372| CANCELED | 3 | 操作取消。 | 1373| TIMEOUT | 4 | 操作超时。 | 1374| TYPE_NOT_SUPPORT | 5 | 不支持的认证类型。 | 1375| TRUST_LEVEL_NOT_SUPPORT | 6 | 不支持的认证等级。 | 1376| BUSY | 7 | 忙碌状态。 | 1377| INVALID_PARAMETERS | 8 | 无效参数。 | 1378| LOCKED | 9 | 认证器已锁定。 | 1379| NOT_ENROLLED | 10 | 用户未录入认证信息。 | 1380 1381## FaceTips<sup>(deprecated)</sup> 1382 1383表示人脸认证过程中提示码的枚举。 1384 1385> **说明：** 1386> 从 API version 8 开始支持，从 API version 11 开始废弃。 1387 1388**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1389 1390| 名称 | 值 | 说明 | 1391| ----------------------------- | ------ | ------------------------------------ | 1392| FACE_AUTH_TIP_TOO_BRIGHT | 1 | 光线太强，获取的图像太亮。 | 1393| FACE_AUTH_TIP_TOO_DARK | 2 | 光线太暗，获取的图像太暗。 | 1394| FACE_AUTH_TIP_TOO_CLOSE | 3 | 人脸距离设备过近。 | 1395| FACE_AUTH_TIP_TOO_FAR | 4 | 人脸距离设备过远。 | 1396| FACE_AUTH_TIP_TOO_HIGH | 5 | 设备太高，仅获取到人脸上部。 | 1397| FACE_AUTH_TIP_TOO_LOW | 6 | 设备太低，仅获取到人脸下部。 | 1398| FACE_AUTH_TIP_TOO_RIGHT | 7 | 设备太靠右，仅获取到人脸右部。 | 1399| FACE_AUTH_TIP_TOO_LEFT | 8 | 设备太靠左，仅获取到人脸左部。 | 1400| FACE_AUTH_TIP_TOO_MUCH_MOTION | 9 | 在图像采集过程中，用户人脸移动太快。 | 1401| FACE_AUTH_TIP_POOR_GAZE | 10 | 没有正视摄像头。 | 1402| FACE_AUTH_TIP_NOT_DETECTED | 11 | 没有检测到人脸信息。 | 1403 1404 1405## FingerprintTips<sup>(deprecated)</sup> 1406 1407表示指纹认证过程中提示码的枚举。 1408 1409> **说明：** 1410> 从 API version 8 开始支持，从 API version 11 开始废弃。 1411 1412**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1413 1414| 名称 | 值 | 说明 | 1415| --------------------------------- | ------ | -------------------------------------------------- | 1416| FINGERPRINT_AUTH_TIP_GOOD | 0 | 获取的指纹图像良好。 | 1417| FINGERPRINT_AUTH_TIP_DIRTY | 1 | 由于传感器上可疑或检测到的污垢，指纹图像噪音过大。 | 1418| FINGERPRINT_AUTH_TIP_INSUFFICIENT | 2 | 由于检测到的情况，指纹图像噪声太大，无法处理。 | 1419| FINGERPRINT_AUTH_TIP_PARTIAL | 3 | 仅检测到部分指纹图像。 | 1420| FINGERPRINT_AUTH_TIP_TOO_FAST | 4 | 快速移动，指纹图像不完整。 | 1421| FINGERPRINT_AUTH_TIP_TOO_SLOW | 5 | 缺少运动，指纹图像无法读取。 | 1422 1423 1424## UserAuthType<sup>8+</sup> 1425 1426表示身份认证的凭据类型枚举。 1427 1428**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1429 1430**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1431 1432| 名称 | 值 | 说明 | 1433| ----------- | ---- | ---------- | 1434| PIN<sup>10+</sup> | 1 | 口令认证。 | 1435| FACE | 2 | 人脸认证。 | 1436| FINGERPRINT | 4 | 指纹认证。 | 1437 1438## AuthTrustLevel<sup>8+</sup> 1439 1440表示认证结果的信任等级枚举。 1441 1442**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1443 1444**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1445 1446| 名称 | 值 | 说明 | 1447| ---- | ----- | ------------------------------------------------------------ | 1448| ATL1 | 10000 | 认证结果的信任等级级别1，代表该认证方案能够识别用户个体，有一定的活体检测能力。常用的业务场景有业务风控、一般个人数据查询等。 | 1449| ATL2 | 20000 | 认证结果的信任等级级别2，代表该认证方案能够精确识别用户个体，有一定的活体检测能力。常用的业务场景有维持设备解锁状态，应用登录等。 | 1450| ATL3 | 30000 | 认证结果的信任等级级别3，代表该认证方案能够精确识别用户个体，有较强的活体检测能力。常用的业务场景有设备解锁等。 | 1451| ATL4 | 40000 | 认证结果的信任等级级别4，代表该认证方案能够高精度的识别用户个体，有很强的活体检测能力。常用的业务场景有小额支付等。 | 1452 1453## userAuth.getAuthenticator<sup>(deprecated)</sup> 1454 1455getAuthenticator(): Authenticator 1456 1457获取Authenticator对象，用于执行用户身份认证。 1458 1459> **说明：** 1460> 从 API version 8 开始废弃，建议使用[constructor](#constructordeprecated)替代。 1461 1462**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1463 1464**返回值：** 1465 1466| 类型 | 说明 | 1467| ----------------------------------------- | ------------ | 1468| [Authenticator](#authenticatordeprecated) | 认证器对象。 | 1469 1470**示例：** 1471 ```ts 1472 import { userAuth } from '@kit.UserAuthenticationKit'; 1473 1474 let authenticator = userAuth.getAuthenticator(); 1475 ``` 1476 1477## Authenticator<sup>(deprecated)</sup> 1478 1479认证器对象。 1480 1481> **说明：** 1482> 从 API version 8 开始废弃，建议使用[UserAuth](#userauthdeprecated)替代。 1483 1484### execute<sup>(deprecated)</sup> 1485 1486execute(type: AuthType, level: SecureLevel, callback: AsyncCallback<number>): void 1487 1488执行用户认证，使用callback方式作为异步方法。 1489 1490> **说明：** 1491> 从 API version 8 开始废弃，建议使用[auth](#authdeprecated)替代。 1492 1493**需要权限**：ohos.permission.ACCESS_BIOMETRIC 1494 1495**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1496 1497**参数：** 1498 1499| 参数名 | 类型 | 必填 | 说明 | 1500| -------- | --------------------------- | ---- |-----------------------------------------------------------------------------------------------------------------------| 1501| type | AuthType | 是 | 认证类型，当前只支持"FACE_ONLY"。<br/>ALL为预留参数。当前版本暂不支持ALL类型的认证。 | 1502| level | SecureLevel | 是 | 安全级别，对应认证的安全级别，有效值为"S1"（最低）、"S2"、"S3"、"S4"（最高）。<br/>具备3D人脸识别能力的设备支持"S3"及以下安全级别的认证。<br/>具备2D人脸识别能力的设备支持"S2"及以下安全级别的认证。 | 1503| callback | AsyncCallback<number> | 是 | 回调函数。number表示认证结果，参见[AuthenticationResult](#authenticationresultdeprecated)。 | 1504 1505**示例：** 1506 1507```ts 1508import { userAuth } from '@kit.UserAuthenticationKit'; 1509 1510let authenticator = userAuth.getAuthenticator(); 1511authenticator.execute('FACE_ONLY', 'S2', (error, code)=>{ 1512 if (code === userAuth.ResultCode.SUCCESS) { 1513 console.info('auth success'); 1514 return; 1515 } 1516 console.error('auth fail, code = ' + code); 1517}); 1518``` 1519 1520 1521### execute<sup>(deprecated)</sup> 1522 1523execute(type : AuthType, level : SecureLevel): Promise<number> 1524 1525执行用户认证，使用promise方式作为异步方法。 1526 1527> **说明：** 1528> 从 API version 8 开始废弃，建议使用[auth](#authdeprecated)替代。 1529 1530**需要权限**：ohos.permission.ACCESS_BIOMETRIC 1531 1532**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1533 1534**参数：** 1535 1536| 参数名 | 类型 | 必填 | 说明 | 1537| ------ | ------ | ---- |-----------------------------------------------------------------------------------------------------------------------| 1538| type | AuthType | 是 | 认证类型，当前只支持"FACE_ONLY"。<br/>ALL为预留参数。当前版本暂不支持ALL类型的认证。 | 1539| level | SecureLevel | 是 | 安全级别，对应认证的安全级别，有效值为"S1"（最低）、"S2"、"S3"、"S4"（最高）。<br/>具备3D人脸识别能力的设备支持"S3"及以下安全级别的认证。<br/>具备2D人脸识别能力的设备支持"S2"及以下安全级别的认证。 | 1540 1541**返回值：** 1542 1543| 类型 | 说明 | 1544| --------------------- | ------------------------------------------------------------ | 1545| Promise<number> | 返回携带一个number的Promise。number 为认证结果，参见[AuthenticationResult](#authenticationresultdeprecated)。 | 1546 1547**示例：** 1548 1549```ts 1550import { userAuth } from '@kit.UserAuthenticationKit'; 1551 1552try { 1553 let authenticator = userAuth.getAuthenticator(); 1554 authenticator.execute('FACE_ONLY', 'S2').then((code)=>{ 1555 console.info('auth success'); 1556 }) 1557} catch (error) { 1558 console.error('auth fail, code = ' + error); 1559} 1560``` 1561 1562## AuthenticationResult<sup>(deprecated)</sup> 1563 1564表示认证结果的枚举。 1565 1566> **说明：** 1567> 从 API version 8 开始废弃，建议使用[ResultCode](#resultcodedeprecated)替代。 1568 1569**系统能力**：SystemCapability.UserIAM.UserAuth.Core 1570 1571| 名称 | 值 | 说明 | 1572| ------------------ | ------ | -------------------------- | 1573| NO_SUPPORT | -1 | 设备不支持当前的认证方式。 | 1574| SUCCESS | 0 | 认证成功。 | 1575| COMPARE_FAILURE | 1 | 比对失败。 | 1576| CANCELED | 2 | 用户取消认证。 | 1577| TIMEOUT | 3 | 认证超时。 | 1578| CAMERA_FAIL | 4 | 开启相机失败。 | 1579| BUSY | 5 | 认证服务忙，请稍后重试。 | 1580| INVALID_PARAMETERS | 6 | 认证参数无效。 | 1581| LOCKED | 7 | 认证失败次数过多，已锁定。 | 1582| NOT_ENROLLED | 8 | 未录入认证凭据。 | 1583| GENERAL_ERROR | 100 | 其他错误。 | 1584 1585