1# @ohos.userIAM.userAuth (User Authentication)
2
3The **userIAM.userAuth** module provides user authentication capabilities in identity authentication scenarios, such as device unlocking, payment, and app login.
4
5> **NOTE**<br>
6> The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.
7
8
9## Modules to Import
10
11```ts
12import { userAuth } from '@kit.UserAuthenticationKit';
13```
14
15## Constant
16
17Represents the maximum period for which the device unlocking result can be reused.
18
19**Atomic service API**: This API can be used in atomic services since API version 12.
20
21**System capability**: SystemCapability.UserIAM.UserAuth.Core
22
23| Name       | Value  | Description      |
24| ----------- | ---- | ---------- |
25| MAX_ALLOWABLE_REUSE_DURATION<sup>12+</sup>    | 300000   | Maximum period for which the device unlocking result can be reused. The value is **300,000** ms.|
26
27## EnrolledState<sup>12+</sup>
28
29Represents information about the enrolled credentials.
30
31**Atomic service API**: This API can be used in atomic services since API version 12.
32
33**System capability**: SystemCapability.UserIAM.UserAuth.Core
34
35| Name        | Type   | Readable| Writable| Description                |
36| ------------ | ---------- | ---- | ---- | -------------------- |
37| credentialDigest       | number | Yes  |  No| Credential digest, which is randomly generated when a credential is added.|
38| credentialCount        | number | Yes  |  No| Number of enrolled credentials.      |
39
40## ReuseMode<sup>12+</sup>
41
42Represents the mode for reusing the device unlocking result.
43
44**Atomic service API**: This API can be used in atomic services since API version 12.
45
46**System capability**: SystemCapability.UserIAM.UserAuth.Core
47
48| Name       | Value  | Description      |
49| ----------- | ---- | ---------- |
50| AUTH_TYPE_RELEVANT    | 1   | The device unlocking result can be reused within the validity period if the authentication type matches any of the authentication types specified for this authentication.<br> **Atomic service API**: This API can be used in atomic services since API version 12.|
51| AUTH_TYPE_IRRELEVANT  | 2   | The device unlocking result can be reused within the validity period regardless of the authentication type.<br>**Atomic service API**: This API can be used in atomic services since API version 12.|
52| CALLER_IRRELEVANT_AUTH_TYPE_RELEVANT<sup>14+</sup>    | 3   | Any identity authentication (including device unlocking) result can be reused within the validity period if the authentication type matches any of the authentication types specified for this authentication.<br>**Atomic service API**: This API can be used in atomic services since API version 14.|
53| CALLER_IRRELEVANT_AUTH_TYPE_IRRELEVANT<sup>14+</sup>  | 4   | Any identity authentication (including device unlocking) result can be reused within the validity period regardless of the authentication type.<br>**Atomic service API**: This API can be used in atomic services since API version 14.|
54
55## ReuseUnlockResult<sup>12+</sup>
56
57Represents the device unlocking result.
58> **NOTE**
59>
60> If the credential changes within the validity period after the screen is unlocked, the screen lock authentication result can still be reused, and the actual **EnrolledState** is returned in the authentication result. If the credential is completely deleted when the lock screen authentication result is reused,
61> both **credentialCount** and **credentialDigest** in **EnrolledState** are **0**.
62
63**Atomic service API**: This API can be used in atomic services since API version 12.
64
65**System capability**: SystemCapability.UserIAM.UserAuth.Core
66
67| Name        | Type  | Mandatory| Description                |
68| ------------ | ---------- | ---- | -------------------- |
69| reuseMode        | [ReuseMode](#reusemode12) | Yes  | Mode for reusing the device unlocking result.      |
70| reuseDuration    | number | Yes  | Period for which the device unlocking result can be reused. <br>Value range: 0 to [MAX_ALLOWABLE_REUSE_DURATION](#constant)|
71
72## userAuth.getEnrolledState<sup>12+</sup>
73
74getEnrolledState(authType : UserAuthType): EnrolledState
75
76Obtains information about the credentials enrolled. With this API, you can obtain the change of the credentials.
77
78**Required permissions**: ohos.permission.ACCESS_BIOMETRIC
79
80**Atomic service API**: This API can be used in atomic services since API version 12.
81
82**System capability**: SystemCapability.UserIAM.UserAuth.Core
83
84**Parameters**
85
86| Name        | Type                              | Mandatory| Description                      |
87| -------------- | ---------------------------------- | ---- | -------------------------- |
88| authType       | [UserAuthType](#userauthtype8)     | Yes  | Authentication type.|
89
90**Return value**
91
92| Type                 | Description                                                        |
93| --------------------- | ------------------------------------------------------------ |
94| [EnrolledState](#enrolledstate12) | Information about the enrolled credentials.|
95
96**Error codes**
97
98For details about the error codes, see [User Authentication Error Codes](errorcode-useriam.md).
99
100| ID| Error Message|
101| -------- | ------- |
102| 201 | Permission verification failed. |
103| 401 | Incorrect parameters. Possible causes: 1.Mandatory parameters are left unspecified. |
104| 12500002 | General operation error. |
105| 12500005 | The authentication type is not supported. |
106| 12500010 | The type of credential has not been enrolled. |
107
108**Example**
109
110```ts
111import { userAuth } from '@kit.UserAuthenticationKit';
112
113try {
114  let enrolledState = userAuth.getEnrolledState(userAuth.UserAuthType.FACE);
115  console.info(`get current enrolled state success, enrolledState = ${JSON.stringify(enrolledState)}`);
116} catch (error) {
117  console.error(`get current enrolled state failed, error = ${JSON.stringify(error)}`);
118}
119```
120
121## AuthParam<sup>10+</sup>
122
123Defines the user authentication parameters.
124
125**Atomic service API**: This API can be used in atomic services since API version 12.
126
127**System capability**: SystemCapability.UserIAM.UserAuth.Core
128
129| Name          | Type                              | Mandatory| Description                                                        |
130| -------------- | ---------------------------------- | ---- | ------------------------------------------------------------ |
131| challenge      | Uint8Array                         | Yes  | Random challenge value, which is used to prevent replay attacks. It cannot exceed 32 bytes and can be passed in **Uint8Array([])** format.|
132| authType       | [UserAuthType](#userauthtype8)[]   | Yes  | Authentication type list, which specifies the types of authentication provided on the user authentication page.          |
133| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | Yes  | Authentication trust level.                                              |
134| reuseUnlockResult<sup>12+</sup> | [ReuseUnlockResult](#reuseunlockresult12) | No  |Device unlocking result that can be reused.|
135
136## WidgetParam<sup>10+</sup>
137
138Represents the information presented on the user authentication page.
139
140**Atomic service API**: This API can be used in atomic services since API version 12.
141
142**System capability**: SystemCapability.UserIAM.UserAuth.Core
143
144| Name                | Type                               | Mandatory| Description                                                        |
145| -------------------- | ----------------------------------- | ---- | ------------------------------------------------------------ |
146| title                | string                              | Yes  | Title of the user authentication page. It cannot exceed 500 characters.                     |
147| navigationButtonText | string                              | No  | Text on the navigation button. It cannot exceed 60 characters. This parameter is valid only in fingerprint or facial authentication only.|
148
149## UserAuthResult<sup>10+</sup>
150
151Represents the user authentication result. If the authentication is successful, the authentication type and token information are returned.
152
153**Atomic service API**: This API can be used in atomic services since API version 12.
154
155**System capability**: SystemCapability.UserIAM.UserAuth.Core
156
157| Name    | Type                          | Mandatory| Description                                                        |
158| -------- | ------------------------------ | ---- | ------------------------------------------------------------ |
159| result   | number                         | Yes  | User authentication result. If the operation is successful, **SUCCESS** is returned. If the operation fails, an error code is returned. For details, see [UserAuthResultCode](#userauthresultcode9).|
160| token    | Uint8Array                     | No  | Token that has passed the authentication.                |
161| authType | [UserAuthType](#userauthtype8) | No  | Type of the authentication.                          |
162| enrolledState<sup>12+</sup> | [EnrolledState](#enrolledstate12) | No  |  Enrolled credential information.        |
163
164## IAuthCallback<sup>10+</sup>
165
166Provides callbacks to return the authentication result.
167
168### onResult<sup>10+</sup>
169
170onResult(result: UserAuthResult): void
171
172Called to return the authentication result. If the authentication is successful, the token information can be obtained from **UserAuthResult**.
173
174**Atomic service API**: This API can be used in atomic services since API version 12.
175
176**System capability**: SystemCapability.UserIAM.UserAuth.Core
177
178**Parameters**
179
180| Name| Type                               | Mandatory| Description      |
181| ------ | ----------------------------------- | ---- | ---------- |
182| result | [UserAuthResult](#userauthresult10) | Yes  | Authentication result.|
183
184**Example 1**
185
186Initiate facial authentication and lock screen password authentication with the authentication trust level greater than or equal to ATL3.
187
188```ts
189import { BusinessError } from '@kit.BasicServicesKit';
190import { cryptoFramework } from '@kit.CryptoArchitectureKit';
191import { userAuth } from '@kit.UserAuthenticationKit';
192
193try {
194  const rand = cryptoFramework.createRandom();
195  const len: number = 16;
196  const randData: Uint8Array = rand?.generateRandomSync(len)?.data;
197  const authParam: userAuth.AuthParam = {
198    challenge: randData,
199    authType: [userAuth.UserAuthType.PIN],
200    authTrustLevel: userAuth.AuthTrustLevel.ATL3,
201  };
202  const widgetParam: userAuth.WidgetParam = {
203    title:'Enter password',
204  };
205
206  const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam);
207  console.info('get userAuth instance success');
208  // The authentication result is returned by onResult only after the authentication is started by start() of UserAuthInstance.
209  userAuthInstance.on('result', {
210    onResult (result) {
211      console.info(`userAuthInstance callback result = ${JSON.stringify(result)}`);
212    }
213  });
214  console.info('auth on success');
215} catch (error) {
216  const err: BusinessError = error as BusinessError;
217  console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`);
218}
219```
220
221**Example 2**
222
223Initiate facial authentication with the authentication trust level greater than or equal to ATL3, and enable the device unlock result to be reused for the same type of authentication within the specified time.
224
225```ts
226import { BusinessError } from '@kit.BasicServicesKit';
227import { cryptoFramework } from '@kit.CryptoArchitectureKit';
228import { userAuth } from '@kit.UserAuthenticationKit';
229
230let reuseUnlockResult: userAuth.ReuseUnlockResult = {
231  reuseMode: userAuth.ReuseMode.AUTH_TYPE_RELEVANT,
232  reuseDuration: userAuth.MAX_ALLOWABLE_REUSE_DURATION,
233}
234try {
235  const rand = cryptoFramework.createRandom();
236  const len: number = 16;
237  const randData: Uint8Array = rand?.generateRandomSync(len)?.data;
238  const authParam: userAuth.AuthParam = {
239    challenge: randData,
240    authType: [userAuth.UserAuthType.PIN],
241    authTrustLevel: userAuth.AuthTrustLevel.ATL3,
242    reuseUnlockResult: reuseUnlockResult,
243  };
244  const widgetParam: userAuth.WidgetParam = {
245    title:'Enter password',
246  };
247  const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam);
248  console.info('get userAuth instance success');
249  // The authentication result is returned by onResult only after the authentication is started by start() of UserAuthInstance.
250  userAuthInstance.on('result', {
251    onResult (result) {
252      console.info(`userAuthInstance callback result = ${JSON.stringify(result)}`);
253    }
254  });
255  console.info('auth on success');
256} catch (error) {
257  const err: BusinessError = error as BusinessError;
258  console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`);
259}
260```
261
262**Example 3**
263
264Initiate facial authentication with the authentication trust level greater than or equal to ATL3, and enable the device unlock result to be reused for any type of authentication within the maximum authentication validity of any application.
265
266```ts
267import { BusinessError } from '@kit.BasicServicesKit';
268import { cryptoFramework } from '@kit.CryptoArchitectureKit';
269import { userAuth } from '@kit.UserAuthenticationKit';
270
271let reuseUnlockResult: userAuth.ReuseUnlockResult = {
272  reuseMode: userAuth.ReuseMode.CALLER_IRRELEVANT_AUTH_TYPE_RELEVANT,
273  reuseDuration: userAuth.MAX_ALLOWABLE_REUSE_DURATION,
274}
275try {
276  const rand = cryptoFramework.createRandom();
277  const len: number = 16;
278  const randData: Uint8Array = rand?.generateRandomSync(len)?.data;
279  const authParam: userAuth.AuthParam = {
280    challenge: randData,
281    authType: [userAuth.UserAuthType.PIN],
282    authTrustLevel: userAuth.AuthTrustLevel.ATL3,
283    reuseUnlockResult: reuseUnlockResult,
284  };
285  const widgetParam: userAuth.WidgetParam = {
286    title:'Enter password',
287  };
288  const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam);
289  console.info('get userAuth instance success');
290  // The authentication result is returned by onResult only after the authentication is started by start() of UserAuthInstance.
291  userAuthInstance.on('result', {
292    onResult (result) {
293      console.info(`userAuthInstance callback result = ${JSON.stringify(result)}`);
294    }
295  });
296  console.info('auth on success');
297} catch (error) {
298  const err: BusinessError = error as BusinessError;
299  console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`);
300}
301```
302
303## UserAuthInstance<sup>10+</sup>
304
305Provides APIs for user authentication. The user authentication widget is supported.
306Before using the APIs, you need to obtain a **UserAuthInstance** instance by using [getUserAuthInstance](#userauthgetuserauthinstance10).
307
308### on<sup>10+</sup>
309
310on(type: 'result', callback: IAuthCallback): void
311
312Subscribes to the user authentication result.
313
314**Atomic service API**: This API can be used in atomic services since API version 12.
315
316**System capability**: SystemCapability.UserIAM.UserAuth.Core
317
318**Parameters**
319
320| Name  | Type                             | Mandatory| Description                                      |
321| -------- | --------------------------------- | ---- | ------------------------------------------ |
322| type     | 'result'                          | Yes  | Event type. The value is **result**, which indicates the authentication result.|
323| callback | [IAuthCallback](#iauthcallback10) | Yes  | Callback used to return the user authentication result.    |
324
325**Error codes**
326
327For details about the error codes, see [User Authentication Error Codes](errorcode-useriam.md).
328
329| ID| Error Message                |
330| -------- | ------------------------ |
331| 401      | Incorrect parameters. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. |
332| 12500002 | General operation error. |
333
334**Example**
335
336```ts
337import { BusinessError } from '@kit.BasicServicesKit';
338import { cryptoFramework } from '@kit.CryptoArchitectureKit';
339import { userAuth } from '@kit.UserAuthenticationKit';
340
341try {
342  const rand = cryptoFramework.createRandom();
343  const len: number = 16;
344  const randData: Uint8Array = rand?.generateRandomSync(len)?.data;
345  const authParam: userAuth.AuthParam = {
346    challenge: randData,
347    authType: [userAuth.UserAuthType.PIN],
348    authTrustLevel: userAuth.AuthTrustLevel.ATL3,
349  };
350  const widgetParam: userAuth.WidgetParam = {
351    title:'Enter password',
352  };
353  const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam);
354  console.info('get userAuth instance success');
355  // The authentication result is returned by onResult only after the authentication is started by start() of UserAuthInstance.
356  userAuthInstance.on('result', {
357    onResult (result) {
358      console.info(`userAuthInstance callback result = ${JSON.stringify(result)}`);
359    }
360  });
361  console.info('auth on success');
362} catch (error) {
363  const err: BusinessError = error as BusinessError;
364  console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`);
365}
366```
367
368### off<sup>10+</sup>
369
370off(type: 'result', callback?: IAuthCallback): void
371
372Unsubscribes from the user authentication result.
373
374> **NOTE**
375>
376> The [UserAuthInstance](#userauthinstance10) instance used to invoke this API must be the one used to subscribe to the event.
377
378**Atomic service API**: This API can be used in atomic services since API version 12.
379
380**System capability**: SystemCapability.UserIAM.UserAuth.Core
381
382**Parameters**
383
384| Name  | Type                             | Mandatory| Description                                      |
385| -------- | --------------------------------- | ---- | ------------------------------------------ |
386| type     | 'result'                          | Yes  | Event type. The value is **result**, which indicates the authentication result.|
387| callback | [IAuthCallback](#iauthcallback10) | No  | Callback to unregister.    |
388
389**Error codes**
390
391For details about the error codes, see [User Authentication Error Codes](errorcode-useriam.md).
392
393| ID| Error Message                |
394| -------- | ------------------------ |
395| 401      | Incorrect parameters. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. |
396| 12500002 | General operation error. |
397
398**Example**
399
400```ts
401import { BusinessError } from '@kit.BasicServicesKit';
402import { cryptoFramework } from '@kit.CryptoArchitectureKit';
403import { userAuth } from '@kit.UserAuthenticationKit';
404
405try {
406  const rand = cryptoFramework.createRandom();
407  const len: number = 16;
408  const randData: Uint8Array = rand?.generateRandomSync(len)?.data;
409  const authParam: userAuth.AuthParam = {
410    challenge: randData,
411    authType: [userAuth.UserAuthType.PIN],
412    authTrustLevel: userAuth.AuthTrustLevel.ATL3,
413  };
414  const widgetParam: userAuth.WidgetParam = {
415    title:'Enter password',
416  };
417  const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam);
418  console.info('get userAuth instance success');
419  userAuthInstance.off('result', {
420    onResult (result) {
421      console.info(`auth off result = ${JSON.stringify(result)}`);
422    }
423  });
424  console.info('auth off success');
425} catch (error) {
426  const err: BusinessError = error as BusinessError;
427  console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`);
428}
429```
430
431### start<sup>10+</sup>
432
433start(): void
434
435Starts authentication.
436
437> **NOTE**<br>
438> A **UserAuthInstance** instance can be used for an authentication only once.
439
440**Required permissions**: ohos.permission.ACCESS_BIOMETRIC
441
442**Atomic service API**: This API can be used in atomic services since API version 12.
443
444**System capability**: SystemCapability.UserIAM.UserAuth.Core
445
446**Error codes**
447
448For details about the error codes, see [User Authentication Error Codes](errorcode-useriam.md).
449
450| ID| Error Message                                        |
451| -------- | ------------------------------------------------ |
452| 201      | Permission verification failed.                  |
453| 401      | Incorrect parameters. Possible causes: 1.Incorrect parameter types. |
454| 12500001 | Authentication failed.                           |
455| 12500002 | General operation error.                         |
456| 12500003 | Authentication canceled.                         |
457| 12500004 | Authentication timeout.                          |
458| 12500005 | The authentication type is not supported.        |
459| 12500006 | The authentication trust level is not supported. |
460| 12500007 | Authentication service is busy.                  |
461| 12500009 | Authentication is locked out.                    |
462| 12500010 | The type of credential has not been enrolled.    |
463| 12500011 | Switched to the custom authentication process.   |
464| 12500013 | Operation failed because of PIN expired. |
465
466**Example**
467
468```ts
469import { BusinessError } from '@kit.BasicServicesKit';
470import { cryptoFramework } from '@kit.CryptoArchitectureKit';
471import { userAuth } from '@kit.UserAuthenticationKit';
472
473try {
474  const rand = cryptoFramework.createRandom();
475  const len: number = 16;
476  const randData: Uint8Array = rand?.generateRandomSync(len)?.data;
477  const authParam: userAuth.AuthParam = {
478    challenge: randData,
479    authType: [userAuth.UserAuthType.PIN],
480    authTrustLevel: userAuth.AuthTrustLevel.ATL3,
481  };
482  const widgetParam: userAuth.WidgetParam = {
483    title:'Enter password',
484  };
485  const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam);
486  console.info('get userAuth instance success');
487  userAuthInstance.start();
488  console.info('auth start success');
489} catch (error) {
490  const err: BusinessError = error as BusinessError;
491  console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`);
492}
493```
494
495### cancel<sup>10+</sup>
496
497cancel(): void
498
499Cancels this authentication.
500
501> **NOTE**
502>
503> **UserAuthInstance** must be the instance being authenticated.
504
505**Required permissions**: ohos.permission.ACCESS_BIOMETRIC
506
507**Atomic service API**: This API can be used in atomic services since API version 12.
508
509**System capability**: SystemCapability.UserIAM.UserAuth.Core
510
511**Error codes**
512
513| ID| Error Message                       |
514| -------- | ------------------------------- |
515| 201      | Permission verification failed. |
516| 401      | Incorrect parameters. Possible causes: 1.Incorrect parameter types. |
517| 12500002 | General operation error.        |
518
519**Example**
520
521```ts
522import { BusinessError } from '@kit.BasicServicesKit';
523import { cryptoFramework } from '@kit.CryptoArchitectureKit';
524import { userAuth } from '@kit.UserAuthenticationKit';
525
526try {
527  const rand = cryptoFramework.createRandom();
528  const len: number = 16;
529  const randData: Uint8Array = rand?.generateRandomSync(len)?.data;
530  const authParam : userAuth.AuthParam = {
531    challenge: randData,
532    authType: [userAuth.UserAuthType.PIN],
533    authTrustLevel: userAuth.AuthTrustLevel.ATL3,
534  };
535  const widgetParam: userAuth.WidgetParam = {
536    title:'Enter password',
537  };
538  const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam);
539  console.info('get userAuth instance success');
540  // The cancel() API can be called only after the authentication is started by start() of UserAuthInstance.
541  userAuthInstance.cancel();
542  console.info('auth cancel success');
543} catch (error) {
544  const err: BusinessError = error as BusinessError;
545  console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`);
546}
547```
548
549## userAuth.getUserAuthInstance<sup>10+</sup>
550
551getUserAuthInstance(authParam: AuthParam, widgetParam: WidgetParam): UserAuthInstance
552
553Obtains a [UserAuthInstance](#userauthinstance10) instance for user authentication. The user authentication widget is also supported.
554
555> **NOTE**<br>
556> A **UserAuthInstance** instance can be used for an authentication only once.
557
558**Atomic service API**: This API can be used in atomic services since API version 12.
559
560**System capability**: SystemCapability.UserIAM.UserAuth.Core
561
562**Parameters**
563
564| Name     | Type                         | Mandatory| Description                      |
565| ----------- | ----------------------------- | ---- | -------------------------- |
566| authParam   | [AuthParam](#authparam10)      | Yes  | User authentication parameters.        |
567| widgetParam | [WidgetParam](#widgetparam10) | Yes  | Parameters on the user authentication page.|
568
569**Return value**
570
571| Type                                   | Description                      |
572| --------------------------------------- | -------------------------- |
573| [UserAuthInstance](#userauthinstance10) | **UserAuthInstance** instance that supports UI.|
574
575**Error codes**
576
577For details about the error codes, see [User Authentication Error Codes](errorcode-useriam.md).
578
579| ID| Error Message                                        |
580| -------- | ------------------------------------------------ |
581| 401      | Incorrect parameters. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.   |
582| 12500002 | General operation error.                         |
583| 12500005 | The authentication type is not supported.        |
584| 12500006 | The authentication trust level is not supported. |
585
586**Example**
587
588```ts
589import { BusinessError } from '@kit.BasicServicesKit';
590import { cryptoFramework } from '@kit.CryptoArchitectureKit';
591import { userAuth } from '@kit.UserAuthenticationKit';
592
593try {
594  const rand = cryptoFramework.createRandom();
595  const len: number = 16;
596  const randData: Uint8Array = rand?.generateRandomSync(len)?.data;
597  const authParam: userAuth.AuthParam = {
598    challenge: randData,
599    authType: [userAuth.UserAuthType.PIN],
600    authTrustLevel: userAuth.AuthTrustLevel.ATL3,
601  };
602  const widgetParam: userAuth.WidgetParam = {
603    title:'Enter password',
604  };
605  let userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam);
606  console.info('get userAuth instance success');
607} catch (error) {
608  const err: BusinessError = error as BusinessError;
609  console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`);
610}
611```
612
613## AuthResultInfo<sup>(deprecated)</sup>
614
615Defines the authentication result.
616
617> **NOTE**<br>
618> This API is supported since API version 9 and deprecated since API version 11.
619
620**System capability**: SystemCapability.UserIAM.UserAuth.Core
621
622| Name        | Type  | Mandatory| Description                |
623| ------------ | ---------- | ---- | -------------------- |
624| result        | number | Yes  | Authentication result.      |
625| token        | Uint8Array | No  | Token that has passed the user identity authentication.|
626| remainAttempts  | number     | No  | Number of remaining authentication attempts.|
627| lockoutDuration | number     | No  | Lock duration of the authentication operation, in ms.|
628
629## TipInfo<sup>(deprecated)</sup>
630
631Defines the authentication tip information.
632
633> **NOTE**<br>
634> This API is supported since API version 9 and deprecated since API version 11.
635
636**System capability**: SystemCapability.UserIAM.UserAuth.Core
637
638| Name        | Type  | Mandatory| Description                |
639| ------------ | ---------- | ---- | -------------------- |
640| module        | number | Yes  | ID of the module that sends the tip information.      |
641| tip        | number | Yes  | Tip to be given during the authentication process.      |
642
643## EventInfo<sup>(deprecated)</sup>
644
645type EventInfo = AuthResultInfo | TipInfo
646
647Enumerates the authentication event information types.
648
649The event information type consists of the fields in **Type** in the following table.
650
651> **NOTE**<br>
652> This parameter is supported since API version 9 and deprecated since API version 11. Use [UserAuthResult](#userauthresult10) instead.
653
654**System capability**: SystemCapability.UserIAM.UserAuth.Core
655
656| Type   | Description                      |
657| --------- | ----------------------- |
658| [AuthResultInfo](#authresultinfodeprecated)    | Authentication result. |
659| [TipInfo](#tipinfodeprecated)    | Authentication tip information.     |
660
661## AuthEventKey<sup>(deprecated)</sup>
662
663type AuthEventKey = 'result' | 'tip'
664
665Defines the keyword of the authentication event type. It is used as a parameter of [on](#ondeprecated).
666
667It consists of the fields in **Type** in the following table.
668
669> **NOTE**<br>
670> This API is supported since API version 9 and deprecated since API version 11.
671
672**System capability**: SystemCapability.UserIAM.UserAuth.Core
673
674| Type      | Description                   |
675| ---------- | ----------------------- |
676| 'result' | If the first parameter of [on](#ondeprecated) is **result**, the [callback](#callbackdeprecated) returns the authentication result.|
677| 'tip'    | If the first parameter of [on](#ondeprecated) is **tip**, the [callback](#callbackdeprecated) returns the authentication tip information.|
678
679## AuthEvent<sup>(deprecated)</sup>
680
681Provides an asynchronous callback to return the authentication event information.
682
683> **NOTE**<br>
684> This API is supported since API version 9 and deprecated since API version 11. Use [IAuthCallback](#iauthcallback10) instead.
685
686### callback<sup>(deprecated)</sup>
687
688callback(result : EventInfo) : void
689
690Called to return the authentication result or authentication tip information.
691
692> **NOTE**<br>
693> This API is supported since API version 9 and deprecated since API version 11. Use [onResult](#onresult10) instead.
694
695**System capability**: SystemCapability.UserIAM.UserAuth.Core
696
697**Parameters**
698
699| Name   | Type                      | Mandatory| Description                          |
700| --------- | -------------------------- | ---- | ------------------------------ |
701| result    | [EventInfo](#eventinfodeprecated)     | Yes  | Authentication result or tip information. |
702
703**Example**
704
705```ts
706import { userAuth } from '@kit.UserAuthenticationKit';
707
708let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
709let authType = userAuth.UserAuthType.FACE;
710let authTrustLevel = userAuth.AuthTrustLevel.ATL1;
711// Obtain the authentication result through a callback.
712try {
713  let auth = userAuth.getAuthInstance(challenge, authType, authTrustLevel);
714  auth.on('result', {
715    callback: (result: userAuth.AuthResultInfo) => {
716      console.info(`authV9 result ${result.result}`);
717      console.info(`authV9 token ${result.token}`);
718      console.info(`authV9 remainAttempts ${result.remainAttempts}`);
719      console.info(`authV9 lockoutDuration ${result.lockoutDuration}`);
720    }
721  } as userAuth.AuthEvent);
722  auth.start();
723  console.info('authV9 start success');
724} catch (error) {
725  console.error(`authV9 error = ${error}`);
726  // do error
727}
728// Obtain the authentication tip information through a callback.
729try {
730  let auth = userAuth.getAuthInstance(challenge, authType, authTrustLevel);
731  auth.on('tip', {
732    callback : (result : userAuth.TipInfo) => {
733      switch (result.tip) {
734        case userAuth.FaceTips.FACE_AUTH_TIP_TOO_BRIGHT:
735          // Do something.
736        case userAuth.FaceTips.FACE_AUTH_TIP_TOO_DARK:
737          // Do something.
738        default:
739          // Do others.
740      }
741    }
742  } as userAuth.AuthEvent);
743  auth.start();
744  console.info('authV9 start success');
745} catch (error) {
746  console.error(`authV9 error = ${error}`);
747  // do error
748}
749```
750
751## AuthInstance<sup>(deprecated)</sup>
752
753Implements user authentication.
754
755> **NOTE**<br>
756> This API is supported since API version 9 and deprecated since API version 10. Use [UserAuthInstance](#userauthinstance10) instead.
757
758### on<sup>(deprecated)</sup>
759
760on : (name : AuthEventKey, callback : AuthEvent) => void
761
762Subscribes to the user authentication events of the specified type.
763
764> **NOTE**<br>
765> - This API is supported since API version 9 and deprecated since API version 10.
766> - Use the [AuthInstance](#authinstancedeprecated) instance obtained to call this API.
767
768**System capability**: SystemCapability.UserIAM.UserAuth.Core
769
770**Parameters**
771
772| Name   | Type                       | Mandatory| Description                      |
773| --------- | -------------------------- | ---- | ------------------------- |
774| name  | [AuthEventKey](#autheventkeydeprecated) | Yes  | Authentication event type. If the value is **result**, the callback returns the authentication result. If the value is **tip**, the callback returns the authentication tip information.|
775| callback  | [AuthEvent](#autheventdeprecated)   | Yes  | Callback used to return the authentication result or tip information.|
776
777**Error codes**
778
779For details about the error codes, see [User Authentication Error Codes](errorcode-useriam.md).
780
781| ID| Error Message|
782| -------- | ------- |
783| 401 | Incorrect parameters. |
784| 12500002 | General operation error. |
785
786**Example**
787
788```ts
789import { userAuth } from '@kit.UserAuthenticationKit';
790
791let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
792let authType = userAuth.UserAuthType.FACE;
793let authTrustLevel = userAuth.AuthTrustLevel.ATL1;
794try {
795  let auth = userAuth.getAuthInstance(challenge, authType, authTrustLevel);
796  // Subscribe to the authentication result.
797  auth.on('result', {
798    callback: (result: userAuth.AuthResultInfo) => {
799      console.info(`authV9 result ${result.result}`);
800      console.info(`authV9 token ${result.token}`);
801      console.info(`authV9 remainAttempts ${result.remainAttempts}`);
802      console.info(`authV9 lockoutDuration ${result.lockoutDuration}`);
803    }
804  });
805  // Subscribe to authentication tip information.
806  auth.on('tip', {
807    callback : (result : userAuth.TipInfo) => {
808      switch (result.tip) {
809        case userAuth.FaceTips.FACE_AUTH_TIP_TOO_BRIGHT:
810          // Do something.
811        case userAuth.FaceTips.FACE_AUTH_TIP_TOO_DARK:
812          // Do something.
813        default:
814          // Do others.
815      }
816    }
817  } as userAuth.AuthEvent);
818  auth.start();
819  console.info('authV9 start success');
820} catch (error) {
821  console.error(`authV9 error = ${error}`);
822  // do error
823}
824```
825
826### off<sup>(deprecated)</sup>
827
828off : (name : AuthEventKey) => void
829
830Unsubscribes from the user authentication events of the specific type.
831
832> **NOTE**<br>
833> - This API is supported since API version 9 and deprecated since API version 10.
834> - The [AuthInstance](#authinstancedeprecated) instance used to call this API must be the one used to subscribe to the events.
835
836**System capability**: SystemCapability.UserIAM.UserAuth.Core
837
838| Name   | Type                       | Mandatory| Description                      |
839| --------- | -------------------------- | ---- | ------------------------- |
840| name    | [AuthEventKey](#autheventkeydeprecated)      | Yes  | Authentication event type. If the value is **result**, the authentication result is unsubscribed from. If the value is **tip**, the authentication tip information is unsubscribed from.|
841
842**Error codes**
843
844For details about the error codes, see [User Authentication Error Codes](errorcode-useriam.md).
845
846| ID| Error Message|
847| -------- | ------- |
848| 401 | Incorrect parameters. |
849| 12500002 | General operation error. |
850
851**Example**
852
853```ts
854import { userAuth } from '@kit.UserAuthenticationKit';
855
856let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
857let authType = userAuth.UserAuthType.FACE;
858let authTrustLevel = userAuth.AuthTrustLevel.ATL1;
859try {
860  let auth = userAuth.getAuthInstance(challenge, authType, authTrustLevel);
861  // Subscribe to the authentication result.
862  auth.on('result', {
863    callback: (result: userAuth.AuthResultInfo) => {
864      console.info(`authV9 result ${result.result}`);
865      console.info(`authV9 token ${result.token}`);
866      console.info(`authV9 remainAttempts ${result.remainAttempts}`);
867      console.info(`authV9 lockoutDuration ${result.lockoutDuration}`);
868    }
869  });
870  // Unsubscription result.
871  auth.off('result');
872  console.info('cancel subscribe authentication event success');
873} catch (error) {
874  console.error(`cancel subscribe authentication event failed, error = ${error}`);
875  // do error
876}
877```
878
879### start<sup>(deprecated)</sup>
880
881start : () => void
882
883Starts authentication.
884
885> **NOTE**<br>
886> - This API is supported since API version 9 and deprecated since API version 10.
887> - Use the [AuthInstance](#authinstancedeprecated) instance obtained to call this API.
888
889**Required permissions**: ohos.permission.ACCESS_BIOMETRIC
890
891**System capability**: SystemCapability.UserIAM.UserAuth.Core
892
893**Error codes**
894
895For details about the error codes, see [User Authentication Error Codes](errorcode-useriam.md).
896
897| ID| Error Message|
898| -------- | ------- |
899| 201 | Permission verification failed. |
900| 401 | Incorrect parameters. |
901| 12500001 | Authentication failed. |
902| 12500002 | General operation error. |
903| 12500003 | The operation is canceled. |
904| 12500004 | The operation is time-out.  |
905| 12500005 | The authentication type is not supported. |
906| 12500006 | The authentication trust level is not supported. |
907| 12500007 | The authentication task is busy. |
908| 12500009 | The authenticator is locked. |
909| 12500010 | The type of credential has not been enrolled. |
910
911**Example**
912
913```ts
914import { userAuth } from '@kit.UserAuthenticationKit';
915
916let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
917let authType = userAuth.UserAuthType.FACE;
918let authTrustLevel = userAuth.AuthTrustLevel.ATL1;
919
920try {
921  let auth = userAuth.getAuthInstance(challenge, authType, authTrustLevel);
922  auth.start();
923  console.info('authV9 start auth success');
924} catch (error) {
925  console.error(`authV9 start auth failed, error = ${error}`);
926}
927```
928
929### cancel<sup>(deprecated)</sup>
930
931cancel : () => void
932
933Cancels this authentication.
934
935> **NOTE**<br>
936>
937> - This API is supported since API version 9 and deprecated since API version 10.
938> - Use the [AuthInstance](#authinstancedeprecated) instance obtained to invoke this API. The [AuthInstance](#authinstancedeprecated) instance must be the instance being authenticated.
939
940**Required permissions**: ohos.permission.ACCESS_BIOMETRIC
941
942**System capability**: SystemCapability.UserIAM.UserAuth.Core
943
944**Error codes**
945
946For details about the error codes, see [User Authentication Error Codes](errorcode-useriam.md).
947
948| ID| Error Message|
949| -------- | ------- |
950| 201 | Permission verification failed. |
951| 401 | Incorrect parameters. |
952| 12500002 | General operation error. |
953
954**Example**
955
956```ts
957import { userAuth } from '@kit.UserAuthenticationKit';
958
959let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
960let authType = userAuth.UserAuthType.FACE;
961let authTrustLevel = userAuth.AuthTrustLevel.ATL1;
962
963try {
964  let auth = userAuth.getAuthInstance(challenge, authType, authTrustLevel);
965  auth.cancel();
966  console.info('cancel auth success');
967} catch (error) {
968  console.error(`cancel auth failed, error = ${error}`);
969}
970```
971
972## userAuth.getAuthInstance<sup>(deprecated)</sup>
973
974getAuthInstance(challenge : Uint8Array, authType : UserAuthType, authTrustLevel : AuthTrustLevel): AuthInstance
975
976Obtains an **AuthInstance** instance for user authentication.
977
978> **NOTE**<br>
979>
980> - This API is supported since API version 9 and deprecated since API version 10. Use [getUserAuthInstance](#userauthgetuserauthinstance10) instead.
981> - An **AuthInstance** instance can be used for an authentication only once.
982
983
984**System capability**: SystemCapability.UserIAM.UserAuth.Core
985
986**Parameters**
987
988| Name        | Type                                    | Mandatory| Description                    |
989| -------------- | ---------------------------------------- | ---- | ------------------------ |
990| challenge      | Uint8Array                               | Yes  | Challenge value. It cannot exceed 32 bytes and can be passed in Uint8Array([]) format.|
991| authType       | [UserAuthType](#userauthtype8)           | Yes  | Authentication type. Currently, **FACE** and **FINGERPRINT** are supported.|
992| authTrustLevel | [AuthTrustLevel](#authtrustlevel8)       | Yes  | Authentication trust level.              |
993
994**Return value**
995
996| Type                                   | Description        |
997| --------------------------------------- | ------------ |
998| [AuthInstance](#authinstancedeprecated) | **AuthInstance** instance obtained.|
999
1000**Error codes**
1001
1002For details about the error codes, see [User Authentication Error Codes](errorcode-useriam.md).
1003
1004| ID| Error Message|
1005| -------- | ------- |
1006| 401 | Incorrect parameters. |
1007| 12500002 | General operation error. |
1008| 12500005 | The authentication type is not supported. |
1009| 12500006 | The authentication trust level is not supported. |
1010
1011**Example**
1012
1013```ts
1014import { userAuth } from '@kit.UserAuthenticationKit';
1015
1016let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
1017let authType = userAuth.UserAuthType.FACE;
1018let authTrustLevel = userAuth.AuthTrustLevel.ATL1;
1019
1020try {
1021  let auth = userAuth.getAuthInstance(challenge, authType, authTrustLevel);
1022  console.info('let auth instance success');
1023} catch (error) {
1024  console.error(`get auth instance success failed, error = ${error}`);
1025}
1026```
1027
1028## userAuth.getAvailableStatus<sup>9+</sup>
1029
1030getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel): void
1031
1032Checks whether the specified authentication capability is supported.
1033
1034**Required permissions**: ohos.permission.ACCESS_BIOMETRIC
1035
1036**Atomic service API**: This API can be used in atomic services since API version 12.
1037
1038**System capability**: SystemCapability.UserIAM.UserAuth.Core
1039
1040**Parameters**
1041
1042| Name        | Type                              | Mandatory| Description                      |
1043| -------------- | ---------------------------------- | ---- | -------------------------- |
1044| authType       | [UserAuthType](#userauthtype8)     | Yes  | Authentication type. PIN is supported since API version 11.|
1045| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | Yes  | Authentication trust level.      |
1046
1047> The mechanism for returning the error code is as follows:
1048>
1049> - The error code 12500005 is returned if the corresponding executor is not registered.
1050> - The error code 12500006 is returned if the corresponding executor is registered, the function is not disabled, but the authentication security level is lower than that specified for the service.
1051> - The error code 12500010 is returned if the corresponding executor is registered, the function is not disabled, but the user has not enrolled the credential.
1052> - The error code 12500013 is returned if the corresponding executor is registered, the function is not disabled, but the PIN has expired.
1053
1054**Error codes**
1055
1056For details about the error codes, see [User Authentication Error Codes](errorcode-useriam.md).
1057
1058| ID| Error Message|
1059| -------- | ------- |
1060| 201 | Permission verification failed. |
1061| 401 | Incorrect parameters. Possible causes: 1.Mandatory parameters are left unspecified. |
1062| 12500002 | General operation error. |
1063| 12500005 | The authentication type is not supported. |
1064| 12500006 | The authentication trust level is not supported. |
1065| 12500010 | The type of credential has not been enrolled. |
1066| 12500013 | Operation failed because of PIN expired. |
1067
1068**Example**
1069
1070```ts
1071import { userAuth } from '@kit.UserAuthenticationKit';
1072
1073try {
1074  userAuth.getAvailableStatus(userAuth.UserAuthType.FACE, userAuth.AuthTrustLevel.ATL1);
1075  console.info('current auth trust level is supported');
1076} catch (error) {
1077  console.error(`current auth trust level is not supported, error = ${error}`);
1078}
1079```
1080
1081## UserAuthResultCode<sup>9+</sup>
1082
1083Enumerates the authentication result codes.
1084
1085**Atomic service API**: This API can be used in atomic services since API version 12.
1086
1087**System capability**: SystemCapability.UserIAM.UserAuth.Core
1088
1089| Name                   |   Value  | Description                |
1090| ----------------------- | ------ | -------------------- |
1091| SUCCESS                 | 12500000      | The authentication is successful.          |
1092| FAIL                    | 12500001      | The authentication failed.          |
1093| GENERAL_ERROR           | 12500002      | A general operation error occurred.      |
1094| CANCELED                | 12500003      | The authentication is canceled.          |
1095| TIMEOUT                 | 12500004      | The authentication timed out.          |
1096| TYPE_NOT_SUPPORT        | 12500005      | The authentication type is not supported.  |
1097| TRUST_LEVEL_NOT_SUPPORT | 12500006      | The authentication trust level is not supported.  |
1098| BUSY                    | 12500007      | Indicates the busy state.          |
1099| LOCKED                  | 12500009      | The authentication executor is locked.      |
1100| NOT_ENROLLED            | 12500010      | The user has not entered the authentication information.|
1101| CANCELED_FROM_WIDGET<sup>10+</sup> | 12500011 | The authentication is canceled by the user from the user authentication widget. If this error code is returned, the authentication is customized by the application.|
1102| PIN_EXPIRED<sup>12+</sup> | 12500013 | The authentication failed because the lock screen password has expired.|
1103
1104## UserAuth<sup>(deprecated)</sup>
1105
1106Provides APIs for user authentication.
1107
1108### constructor<sup>(deprecated)</sup>
1109
1110constructor()
1111
1112A constructor used to create a **UserAuth** instance.
1113
1114> **NOTE**<br>
1115> This API is supported since API version 8 and deprecated since API version 9. Use [getAuthInstance](#userauthgetauthinstancedeprecated) instead.
1116
1117**System capability**: SystemCapability.UserIAM.UserAuth.Core
1118
1119**Example**
1120
1121```ts
1122import { userAuth } from '@kit.UserAuthenticationKit';
1123
1124let auth = new userAuth.UserAuth();
1125```
1126
1127### getVersion<sup>(deprecated)</sup>
1128
1129getVersion() : number
1130
1131Obtains the version of this authenticator.
1132
1133> **NOTE**<br>
1134> This API is supported since API version 8 and deprecated since API version 9.
1135
1136**Required permissions**: ohos.permission.ACCESS_BIOMETRIC
1137
1138**System capability**: SystemCapability.UserIAM.UserAuth.Core
1139
1140**Return value**
1141
1142| Type  | Description                  |
1143| ------ | ---------------------- |
1144| number | Authenticator version obtained.|
1145
1146**Example**
1147
1148```ts
1149import { userAuth } from '@kit.UserAuthenticationKit';
1150
1151let auth = new userAuth.UserAuth();
1152let version = auth.getVersion();
1153console.info(`auth version = ${version}`);
1154```
1155
1156### getAvailableStatus<sup>(deprecated)</sup>
1157
1158getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel) : number
1159
1160Checks whether the specified authentication capability is supported.
1161
1162> **NOTE**<br>
1163> This API is supported since API version 8 and deprecated since API version 9. Use [getAvailableStatus](#userauthgetavailablestatus9) instead.
1164
1165**Required permissions**: ohos.permission.ACCESS_BIOMETRIC
1166
1167**System capability**: SystemCapability.UserIAM.UserAuth.Core
1168
1169**Parameters**
1170
1171| Name        | Type                              | Mandatory| Description                      |
1172| -------------- | ---------------------------------- | ---- | -------------------------- |
1173| authType       | [UserAuthType](#userauthtype8)     | Yes  | Authentication type. Currently, **FACE** and **FINGERPRINT** are supported.|
1174| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | Yes  | Authentication trust level.      |
1175
1176**Return value**
1177
1178| Type  | Description                                                        |
1179| ------ | ------------------------------------------------------------ |
1180| number | Query result. If the authentication capability is supported, **SUCCESS** is returned. Otherwise, a [ResultCode](#resultcodedeprecated) is returned.|
1181
1182**Example**
1183
1184```ts
1185import { userAuth } from '@kit.UserAuthenticationKit';
1186
1187let auth = new userAuth.UserAuth();
1188let checkCode = auth.getAvailableStatus(userAuth.UserAuthType.FACE, userAuth.AuthTrustLevel.ATL1);
1189if (checkCode == userAuth.ResultCode.SUCCESS) {
1190  console.info('check auth support success');
1191} else {
1192  console.error(`check auth support fail, code = ${checkCode}`);
1193}
1194```
1195
1196### auth<sup>(deprecated)</sup>
1197
1198auth(challenge: Uint8Array, authType: UserAuthType, authTrustLevel: AuthTrustLevel, callback: IUserAuthCallback): Uint8Array
1199
1200Starts user authentication. This API uses a callback to return the result.
1201
1202> **NOTE**<br>
1203> This API is supported since API version 8 and deprecated since API version 9. Use [start](#startdeprecated) instead.
1204
1205**Required permissions**: ohos.permission.ACCESS_BIOMETRIC
1206
1207**System capability**: SystemCapability.UserIAM.UserAuth.Core
1208
1209**Parameters**
1210
1211| Name        | Type                                    | Mandatory| Description                    |
1212| -------------- | ---------------------------------------- | ---- | ------------------------ |
1213| challenge      | Uint8Array                               | Yes  | Challenge value, which can be passed in Uint8Array([]) format.|
1214| authType       | [UserAuthType](#userauthtype8)           | Yes  | Authentication type. Currently, **FACE** and **FINGERPRINT** are supported.|
1215| authTrustLevel | [AuthTrustLevel](#authtrustlevel8)       | Yes  | Authentication trust level.            |
1216| callback       | [IUserAuthCallback](#iuserauthcallbackdeprecated) | Yes  | Callback used to return the result.       |
1217
1218**Return value**
1219
1220| Type      | Description                                                        |
1221| ---------- | ------------------------------------------------------------ |
1222| Uint8Array | Context ID, which is used as the input parameter of [cancelAuth](#cancelauthdeprecated).|
1223
1224**Example**
1225
1226```ts
1227import { userAuth } from '@kit.UserAuthenticationKit';
1228
1229let auth = new userAuth.UserAuth();
1230let challenge = new Uint8Array([]);
1231auth.auth(challenge, userAuth.UserAuthType.FACE, userAuth.AuthTrustLevel.ATL1, {
1232  onResult: (result, extraInfo) => {
1233    try {
1234      console.info(`auth onResult result = ${result}`);
1235      console.info(`auth onResult extraInfo = ${JSON.stringify(extraInfo)}`);
1236      if (result == userAuth.ResultCode.SUCCESS) {
1237        // Add the logic to be executed when the authentication is successful.
1238      } else {
1239        // Add the logic to be executed when the authentication fails.
1240      }
1241    } catch (error) {
1242      console.error(`auth onResult error = ${error}`);
1243    }
1244  }
1245});
1246```
1247
1248### cancelAuth<sup>(deprecated)</sup>
1249
1250cancelAuth(contextID : Uint8Array) : number
1251
1252Cancels an authentication based on the context ID.
1253
1254> **NOTE**<br>
1255> This API is supported since API version 8 and deprecated since API version 9. Use [cancel](#canceldeprecated) instead.
1256
1257**Required permissions**: ohos.permission.ACCESS_BIOMETRIC
1258
1259**System capability**: SystemCapability.UserIAM.UserAuth.Core
1260
1261**Parameters**
1262
1263| Name   | Type      | Mandatory| Description                                      |
1264| --------- | ---------- | ---- | ------------------------------------------ |
1265| contextID | Uint8Array | Yes  | Context ID, which is obtained by [auth](#authdeprecated).|
1266
1267**Return value**
1268
1269| Type  | Description                    |
1270| ------ | ------------------------ |
1271| number | Returns **SUCCESS** if the cancellation is successful. Returns a [ResultCode](#resultcodedeprecated) otherwise.|
1272
1273**Example**
1274
1275```ts
1276import { userAuth } from '@kit.UserAuthenticationKit';
1277
1278// contextId can be obtained by auth(). In this example, it is defined here.
1279let contextId = new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7]);
1280let auth = new userAuth.UserAuth();
1281let cancelCode = auth.cancelAuth(contextId);
1282if (cancelCode == userAuth.ResultCode.SUCCESS) {
1283  console.info('cancel auth success');
1284} else {
1285  console.error('cancel auth fail');
1286}
1287```
1288
1289## IUserAuthCallback<sup>(deprecated)</sup>
1290
1291Provides callbacks to return the authentication result.
1292
1293> **NOTE**<br>
1294> This API is supported since API version 8 and deprecated since API version 9. Use [AuthEvent](#autheventdeprecated) instead.
1295
1296### onResult<sup>(deprecated)</sup>
1297
1298onResult: (result : number, extraInfo : AuthResult) => void
1299
1300Called to return the authentication result.
1301
1302> **NOTE**<br>
1303> This API is supported since API version 8 and deprecated since API version 9. Use [callback](#callbackdeprecated) instead.
1304
1305**System capability**: SystemCapability.UserIAM.UserAuth.Core
1306
1307**Parameters**
1308
1309| Name   | Type                      | Mandatory| Description       |
1310| --------- | -------------------------- | ---- | ------------------------------------------------ |
1311| result    | number           | Yes  | Authentication result. For details, see [ResultCode](#resultcodedeprecated).|
1312| extraInfo | [AuthResult](#authresultdeprecated) | Yes  | Extended information, which varies depending on the authentication result.<br>If the authentication is successful, the user authentication token will be returned in **extraInfo**.<br>If the authentication fails, the remaining number of authentication times will be returned in **extraInfo**.<br>If the authentication executor is locked, the freeze time will be returned in **extraInfo**.|
1313
1314**Example**
1315
1316```ts
1317import { userAuth } from '@kit.UserAuthenticationKit';
1318
1319let auth = new userAuth.UserAuth();
1320let challenge = new Uint8Array([]);
1321auth.auth(challenge, userAuth.UserAuthType.FACE, userAuth.AuthTrustLevel.ATL1, {
1322  onResult: (result, extraInfo) => {
1323    try {
1324      console.info(`auth onResult result = ${result}`);
1325      console.info(`auth onResult extraInfo = ${JSON.stringify(extraInfo)}`);
1326      if (result == userAuth.ResultCode.SUCCESS) {
1327        // Add the logic to be executed when the authentication is successful.
1328      }  else {
1329        // Add the logic to be executed when the authentication fails.
1330      }
1331    } catch (error) {
1332      console.error(`auth onResult error = ${error}`);
1333    }
1334  }
1335});
1336```
1337
1338### onAcquireInfo<sup>(deprecated)</sup>
1339
1340onAcquireInfo ?: (module : number, acquire : number, extraInfo : any) => void
1341
1342Called to acquire authentication tip information. This API is optional.
1343
1344> **NOTE**<br>
1345> This API is supported since API version 8 and deprecated since API version 9. Use [callback](#callbackdeprecated) instead.
1346
1347**System capability**: SystemCapability.UserIAM.UserAuth.Core
1348
1349**Parameters**
1350
1351| Name   | Type  | Mandatory| Description                          |
1352| --------- | ------ | ---- | ------------------------------ |
1353| module    | number | Yes  | ID of the module that sends the tip information.            |
1354| acquire   | number | Yes  | Authentication tip information.|
1355| extraInfo | any    | Yes  | Reserved field.                    |
1356
1357**Example**
1358
1359```ts
1360import { userAuth } from '@kit.UserAuthenticationKit';
1361
1362let auth = new userAuth.UserAuth();
1363let challenge = new Uint8Array([]);
1364auth.auth(challenge, userAuth.UserAuthType.FACE, userAuth.AuthTrustLevel.ATL1, {
1365  onResult: (result, extraInfo) => {
1366    try {
1367      console.info(`auth onResult result = ${result}`);
1368      console.info(`auth onResult extraInfo = ${JSON.stringify(extraInfo)}`);
1369      if (result == userAuth.ResultCode.SUCCESS) {
1370        // Add the logic to be executed when the authentication is successful.
1371      }  else {
1372        // Add the logic to be executed when the authentication fails.
1373      }
1374    } catch (error) {
1375      console.error(`auth onResult error = ${error}`);
1376    }
1377  },
1378  onAcquireInfo: (module, acquire, extraInfo : userAuth.AuthResult) => {
1379    try {
1380      console.info(`auth onAcquireInfo module = ${module}`);
1381      console.info(`auth onAcquireInfo acquire = ${acquire}`);
1382      console.info(`auth onAcquireInfo extraInfo = ${JSON.stringify(extraInfo)}`);
1383    } catch (error) {
1384      console.error(`auth onAcquireInfo error = ${error}`);
1385    }
1386  }
1387});
1388```
1389
1390## AuthResult<sup>(deprecated)</sup>
1391
1392Represents the authentication result object.
1393
1394> **NOTE**<br>
1395> This API is supported since API version 8 and deprecated since API version 9. Use [AuthResultInfo](#authresultinfodeprecated) instead.
1396
1397**System capability**: SystemCapability.UserIAM.UserAuth.Core
1398
1399| Name        | Type  | Mandatory| Description                |
1400| ------------ | ---------- | ---- | -------------------|
1401| token        | Uint8Array | No  | Authentication token information.|
1402| remainTimes  | number     | No  | Number of remaining authentication operations.|
1403| freezingTime | number     | No  | Time for which the authentication operation is frozen.|
1404
1405## ResultCode<sup>(deprecated)</sup>
1406
1407Enumerates the authentication result codes.
1408
1409> **NOTE**<br>
1410> This object is deprecated since API version 9. Use [UserAuthResultCode](#userauthresultcode9) instead.
1411
1412**System capability**: SystemCapability.UserIAM.UserAuth.Core
1413
1414| Name                   | Value| Description                |
1415| ----------------------- | ------ | -------------------- |
1416| SUCCESS                 | 0      | The operation is successful.          |
1417| FAIL                    | 1      | The authentication failed.          |
1418| GENERAL_ERROR           | 2      | A general operation error occurred.      |
1419| CANCELED                | 3      | The authentication is canceled.          |
1420| TIMEOUT                 | 4      | The authentication timed out.          |
1421| TYPE_NOT_SUPPORT        | 5      | The authentication type is not supported.  |
1422| TRUST_LEVEL_NOT_SUPPORT | 6      | The authentication trust level is not supported.  |
1423| BUSY                    | 7      | Indicates the busy state.          |
1424| INVALID_PARAMETERS      | 8      | Invalid parameters are detected.          |
1425| LOCKED                  | 9      | The authentication executor is locked.      |
1426| NOT_ENROLLED            | 10     | The user has not entered the authentication information.|
1427
1428## FaceTips<sup>(deprecated)</sup>
1429
1430Enumerates the tip codes used during the facial authentication process.
1431
1432> **NOTE**<br>
1433> This API is supported since API version 8 and deprecated since API version 11.
1434
1435**System capability**: SystemCapability.UserIAM.UserAuth.Core
1436
1437| Name                         |   Value  |    Description                            |
1438| ----------------------------- | ------ | ------------------------------------ |
1439| FACE_AUTH_TIP_TOO_BRIGHT      | 1      | The obtained facial image is too bright due to high illumination.          |
1440| FACE_AUTH_TIP_TOO_DARK        | 2      | The obtained facial image is too dark due to low illumination.          |
1441| FACE_AUTH_TIP_TOO_CLOSE       | 3      | The face is too close to the device.                  |
1442| FACE_AUTH_TIP_TOO_FAR         | 4      | The face is too far away from the device.                  |
1443| FACE_AUTH_TIP_TOO_HIGH        | 5      | Only the upper part of the face is captured because the device is angled too high.        |
1444| FACE_AUTH_TIP_TOO_LOW         | 6      | Only the lower part of the face is captured because the device is angled too low.        |
1445| FACE_AUTH_TIP_TOO_RIGHT       | 7      | Only the right part of the face is captured because the device is deviated to the right.      |
1446| FACE_AUTH_TIP_TOO_LEFT        | 8      | Only the left part of the face is captured because the device is deviated to the left.      |
1447| FACE_AUTH_TIP_TOO_MUCH_MOTION | 9      | The face moves too fast during facial information collection.|
1448| FACE_AUTH_TIP_POOR_GAZE       | 10     | The face is not facing the camera.                    |
1449| FACE_AUTH_TIP_NOT_DETECTED    | 11     | No face is detected.                |
1450
1451
1452## FingerprintTips<sup>(deprecated)</sup>
1453
1454Enumerates the tip codes used during the fingerprint authentication process.
1455
1456> **NOTE**<br>
1457> This API is supported since API version 8 and deprecated since API version 11.
1458
1459**System capability**: SystemCapability.UserIAM.UserAuth.Core
1460
1461| Name                             |   Value  | Description                                              |
1462| --------------------------------- | ------ | -------------------------------------------------- |
1463| FINGERPRINT_AUTH_TIP_GOOD         | 0      | The obtained fingerprint image is in good condition.                              |
1464| FINGERPRINT_AUTH_TIP_DIRTY        | 1      | Large fingerprint image noise is detected due to suspicious or detected dirt on the sensor.|
1465| FINGERPRINT_AUTH_TIP_INSUFFICIENT | 2      | The noise of the fingerprint image is too large to be processed.    |
1466| FINGERPRINT_AUTH_TIP_PARTIAL      | 3      | Incomplete fingerprint image is detected.                            |
1467| FINGERPRINT_AUTH_TIP_TOO_FAST     | 4      | The fingerprint image is incomplete due to fast movement.                        |
1468| FINGERPRINT_AUTH_TIP_TOO_SLOW     | 5      | Failed to obtain the fingerprint image because the finger seldom moves.                      |
1469
1470
1471## UserAuthType<sup>8+</sup>
1472
1473Enumerates the identity authentication types.
1474
1475**Atomic service API**: This API can be used in atomic services since API version 12.
1476
1477**System capability**: SystemCapability.UserIAM.UserAuth.Core
1478
1479| Name       | Value  | Description      |
1480| ----------- | ---- | ---------- |
1481| PIN<sup>10+</sup>         | 1    | PIN authentication.|
1482| FACE        | 2    | Facial authentication.|
1483| FINGERPRINT | 4    | Fingerprint authentication.|
1484
1485## AuthTrustLevel<sup>8+</sup>
1486
1487Enumerates the trust levels of the authentication result.
1488
1489**Atomic service API**: This API can be used in atomic services since API version 12.
1490
1491**System capability**: SystemCapability.UserIAM.UserAuth.Core
1492
1493| Name| Value   | Description                                                        |
1494| ---- | ----- | ------------------------------------------------------------ |
1495| ATL1 | 10000 | Authentication trust level 1. The authentication of this level can identify individual users and provides limited liveness detection capabilities. It is usually used in service risk control and query of general personal data.|
1496| ATL2 | 20000 | Authentication trust level 2. The authentication of this level can accurately identify individual users and provides regular liveness detection capabilities. It is usually used in scenarios such as application logins and keeping the unlocking state of a device.|
1497| ATL3 | 30000 | Authentication trust level 3. The authentication of this level can accurately identify individual users and provides strong liveness detection capabilities. It is usually used in scenarios such as unlocking a device.|
1498| ATL4 | 40000 | Authentication trust level 4. The authentication of this level can accurately identify individual users and provides powerful liveness detection capabilities. It is usually used in scenarios such as small-amount payment.|
1499
1500## SecureLevel<sup>(deprecated)</sup>
1501
1502Enumerates the authentication security levels.
1503
1504> **NOTE**<br>This API is supported since API version 6 and deprecated since API version 8.
1505
1506**System capability**: SystemCapability.UserIAM.UserAuth.Core
1507
1508| Name| Value   | Description                                                        |
1509| ---- | ----- | ------------------------------------------------------------ |
1510| S1 | 'S1' | Authentication trust level 1. The authentication of this level can identify individual users and provides limited liveness detection capabilities. It is usually used in service risk control and query of general personal data.|
1511| S2 | 'S2' | Authentication trust level 2. The authentication of this level can accurately identify individual users and provides regular liveness detection capabilities. It is usually used in scenarios such as application logins and keeping the unlocking state of a device.|
1512| S3 | 'S3' | Authentication trust level 3. The authentication of this level can accurately identify individual users and provides strong liveness detection capabilities. It is usually used in scenarios such as unlocking a device.|
1513| S4 | 'S4' | Authentication trust level 4. The authentication of this level can accurately identify individual users and provides powerful liveness detection capabilities. It is usually used in scenarios such as small-amount payment.|
1514
1515## AuthType<sup>(deprecated)</sup>
1516
1517Enumerates the authentication types.
1518
1519> **NOTE**<br>This API is supported since API version 6 and deprecated since API version 8.
1520
1521**System capability**: SystemCapability.UserIAM.UserAuth.Core
1522
1523| Name| Value   | Description                                                        |
1524| ---- | ----- | ------------------------------------------------------------ |
1525| ALL  | 'ALL' | A reserved parameter not supported by the current version.|
1526| FACE_ONLY | 'FACE_ONLY' | Facial authentication.|
1527
1528## userAuth.getAuthenticator<sup>(deprecated)</sup>
1529
1530getAuthenticator(): Authenticator
1531
1532Obtains an **Authenticator** instance for user authentication.
1533
1534> **NOTE**<br>
1535> This API is deprecated since API version 8. Use [constructor](#constructordeprecated) instead.
1536
1537**System capability**: SystemCapability.UserIAM.UserAuth.Core
1538
1539**Return value**
1540
1541| Type                                     | Description        |
1542| ----------------------------------------- | ------------ |
1543| [Authenticator](#authenticatordeprecated) | **Authenticator** instance obtained.|
1544
1545**Example**
1546  ```ts
1547  import { userAuth } from '@kit.UserAuthenticationKit';
1548
1549  let authenticator = userAuth.getAuthenticator();
1550  ```
1551
1552## Authenticator<sup>(deprecated)</sup>
1553
1554Defines the **Authenticator** object.
1555
1556> **NOTE**<br>
1557> This API is deprecated since API version 8. Use [UserAuth](#userauthdeprecated) instead.
1558
1559### execute<sup>(deprecated)</sup>
1560
1561execute(type: AuthType, level: SecureLevel, callback: AsyncCallback&lt;number&gt;): void
1562
1563Starts user authentication. This API uses an asynchronous callback to return the result.
1564
1565> **NOTE**<br>
1566> This API is deprecated since API version 8. Use [auth](#authdeprecated) instead.
1567
1568**Required permissions**: ohos.permission.ACCESS_BIOMETRIC
1569
1570**System capability**: SystemCapability.UserIAM.UserAuth.Core
1571
1572**Parameters**
1573
1574| Name  | Type                       | Mandatory| Description                                                                                                                   |
1575| -------- | --------------------------- | ---- |-----------------------------------------------------------------------------------------------------------------------|
1576| type     | AuthType                      | Yes  | Authentication type. Currently, only **FACE_ONLY** is supported.<br>**ALL** is reserved and not supported by the current version.                                                                |
1577| level    | SecureLevel  | Yes  | Security level of the authentication. It can be **S1** (lowest), **S2**, **S3**, or **S4** (highest).<br>Devices capable of 3D facial recognition support S3 and lower-level authentication.<br>Devices capable of 2D facial recognition support S2 and lower-level authentication.|
1578| callback | AsyncCallback&lt;number&gt; | Yes| Callback used to return the result. **number** indicates the [AuthenticationResult](#authenticationresultdeprecated).|
1579
1580**Example**
1581
1582```ts
1583import { userAuth } from '@kit.UserAuthenticationKit';
1584
1585let authenticator = userAuth.getAuthenticator();
1586authenticator.execute('FACE_ONLY', 'S2', (error, code)=>{
1587  if (code === userAuth.ResultCode.SUCCESS) {
1588    console.info('auth success');
1589    return;
1590  }
1591  console.error(`auth fail, code = ${code}`);
1592});
1593```
1594
1595
1596### execute<sup>(deprecated)</sup>
1597
1598execute(type : AuthType, level : SecureLevel): Promise&lt;number&gt;
1599
1600Starts user authentication. This API uses a promise to return the result.
1601
1602> **NOTE**<br>
1603> This API is deprecated since API version 8. Use [auth](#authdeprecated) instead.
1604
1605**Required permissions**: ohos.permission.ACCESS_BIOMETRIC
1606
1607**System capability**: SystemCapability.UserIAM.UserAuth.Core
1608
1609**Parameters**
1610
1611| Name| Type  | Mandatory| Description                                                                                                                   |
1612| ------ | ------ | ---- |-----------------------------------------------------------------------------------------------------------------------|
1613| type   | AuthType | Yes  | Authentication type. Currently, only **FACE_ONLY** is supported.<br>**ALL** is reserved and not supported by the current version.                                                                |
1614| level  | SecureLevel | Yes  | Security level of the authentication. It can be **S1** (lowest), **S2**, **S3**, or **S4** (highest).<br>Devices capable of 3D facial recognition support S3 and lower-level authentication.<br>Devices capable of 2D facial recognition support S2 and lower-level authentication.|
1615
1616**Return value**
1617
1618| Type                 | Description                                                        |
1619| --------------------- | ------------------------------------------------------------ |
1620| Promise&lt;number&gt; | Promise used to return the authentication result, which is a number. For details, see [AuthenticationResult](#authenticationresultdeprecated).|
1621
1622**Example**
1623
1624```ts
1625import { userAuth } from '@kit.UserAuthenticationKit';
1626
1627try {
1628  let authenticator = userAuth.getAuthenticator();
1629  authenticator.execute('FACE_ONLY', 'S2').then((code)=>{
1630    console.info('auth success');
1631  })
1632} catch (error) {
1633  console.error(`auth fail, code = ${error}`);
1634}
1635```
1636
1637## AuthenticationResult<sup>(deprecated)</sup>
1638
1639Enumerates the authentication results.
1640
1641> **NOTE**<br>
1642> This object is deprecated since API version 8. Use [ResultCode](#resultcodedeprecated) instead.
1643
1644**System capability**: SystemCapability.UserIAM.UserAuth.Core
1645
1646| Name              |   Value  | Description                      |
1647| ------------------ | ------ | -------------------------- |
1648| NO_SUPPORT         | -1     | The device does not support the current authentication mode.|
1649| SUCCESS            | 0      | The authentication is successful.                |
1650| COMPARE_FAILURE    | 1      | The feature comparison failed.                |
1651| CANCELED           | 2      | The authentication was canceled by the user.            |
1652| TIMEOUT            | 3      | The authentication has timed out.                |
1653| CAMERA_FAIL        | 4      | The camera failed to start.            |
1654| BUSY               | 5      | The authentication service is not available. Try again later.  |
1655| INVALID_PARAMETERS | 6      | The authentication parameters are invalid.            |
1656| LOCKED             | 7      | The user account is locked because the number of authentication failures has reached the threshold.|
1657| NOT_ENROLLED       | 8      | No authentication credential is registered.          |
1658| GENERAL_ERROR      | 100    | Other errors.                |
1659