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