diff --git a/en/application-dev/reference/apis/js-apis-useriam-userauth.md b/en/application-dev/reference/apis/js-apis-useriam-userauth.md index 1ce2456d568800cb8fe2cddd48d697e6acfd3d0e..e4091d048a31efc214a0745c3afa5b3566c1750e 100644 --- a/en/application-dev/reference/apis/js-apis-useriam-userauth.md +++ b/en/application-dev/reference/apis/js-apis-useriam-userauth.md @@ -1,66 +1,102 @@ -# User Authentication +# User Authentication ->**NOTE:** ->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. +> ![icon-note.gif](public_sys-resources/icon-note.gif)**NOTE**
+> 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. -## Modules to Import +## Modules to Import -``` +```js import userIAM_userAuth from '@ohos.userIAM.userAuth'; ``` -## System Capabilities - -SystemCapability.UserIAM.UserAuth - -## Required Permissions - -ohos.permission.ACCESS\_BIOMETRIC - -## Sample Code +## Example -``` +```js +// API version 6 import userIAM_userAuth from '@ohos.userIAM.userAuth'; export default { startAuth() { console.info("start auth"); - let tipCallback = (tip)=>{ - console.info("receive tip: errorCode(" + tip.errorCode + ") code(" + tip.tipCode + ") event(" + - tip.tipEvent + ") info(" + tip.tipInfo + ")"); - // Add the logic for displaying the prompt message. - }; let auth = userIAM_userAuth.getAuthenticator(); - auth.on("tip", tipCallback); auth.execute("FACE_ONLY", "S2").then((code)=>{ - auth.off("tip", tipCallback); console.info("auth success"); - // Add the logic for authentication success. + // Add the logic to be executed when the authentication is successful. }).catch((code)=>{ - auth.off("tip", tipCallback); console.error("auth fail, code = " + code); - // Add the logic for authentication failure. + // Add the logic to be executed when the authentication fails. + }); + } +} +``` + +```js +// API version 8 +import userIAM_userAuth from '@ohos.userIAM.userAuth'; +let auth = new userIAM_userAuth.UserAuth(); + +export default { + getVersion() { + console.info("start get version"); + let version = this.auth.getVersion(); + console.info("auth version = " + version); + }, + + startAuth() { + console.info("start auth"); + this.auth.auth(null, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, { + onResult: (result, extraInfo) => { + try { + console.info("auth onResult result = " + result); + console.info("auth onResult extraInfo = " + JSON.stringify(extraInfo)); + if (result == 'SUCCESS') { + // Add the logic to be executed when the authentication is successful. + } else { + // Add the logic to be executed when the authentication fails. + } + } catch (e) { + console.info("auth onResult error = " + e); + } + }, + + onAcquireInfo: (module, acquire, extraInfo) => { + try { + console.info("auth onAcquireInfo module = " + module); + console.info("auth onAcquireInfo acquire = " + acquire); + console.info("auth onAcquireInfo extraInfo = " + JSON.stringify(extraInfo)); + } catch (e) { + console.info("auth onAcquireInfo error = " + e); + } + } }); }, checkAuthSupport() { console.info("start check auth support"); - let auth = userIAM_userAuth.getAuthenticator(); - let checkCode = auth.checkAvailability("FACE_ONLY", "S2"); - if (checkCode == userIAM_userAuth.CheckAvailabilityResult.SUPPORTED) { + let checkCode = this.auth.getAvailableStatus(userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1); + if (checkCode == userIAM_userAuth.ResultCode.SUCCESS) { console.info("check auth support success"); - // Add the logic for the specified authentication type supported. + // Add the logic to be executed if the specified authentication type is supported. } else { console.error("check auth support fail, code = " + checkCode); - // Add the logic for the authentication type that is not supported. + // Add the logic to be executed if the specified authentication type is not supported. } }, cancelAuth() { console.info("start cancel auth"); - let auth = userIAM_userAuth.getAuthenticator(); - let cancelCode = auth.cancel(); + // Obtain contextId using auth(). + let contextId = auth.auth(null, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, { + onResult: (result, extraInfo) => { + console.info("auth onResult result = " + result); + }, + + onAcquireInfo: (module, acquire, extraInfo) => { + console.info("auth onAcquireInfo module = " + module); + } + }); + let cancelCode = this.auth.cancel(contextId); if (cancelCode == userIAM_userAuth.Result.SUCCESS) { console.info("cancel auth success"); } else { @@ -70,800 +106,504 @@ export default { } ``` -## userIAM\_userAuth.getAuthenticator - -getAuthenticator\(\): Authenticator - -Obtains an **Authenticator** object for user authentication. 6+ - -Obtains an **Authenticator** object to check the device's capability of user authentication, perform or cancel user authentication, and obtain the tips generated in the authentication process. 7+ - -- Return values - - - - - - - - - - -

Type

-

Description

-

Authenticator

-

Authenticator object obtained.

-
- -- Example - - ``` - let authenticator = userIAM_userAuth.getAuthenticator(); - ``` - - -## Authenticator - -Provides an **Authenticator** object. - -### execute - -execute\(type: string, level: string, callback: AsyncCallback\): void - -Performs user authentication and returns the authentication result using an asynchronous callback. - -- Parameters - - - - - - - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

type

-

string

-

Yes

-

Authentication type. Only FACE_ONLY is supported.

-

ALL is reserved and not supported by the current version.

-

level

-

string

-

Yes

-

Security level of the authentication. It can be S1 (lowest), S2, S3, or S4 (highest).

-

Devices capable of 3D facial recognition support S3 and lower-level authentication.

-

Devices capable of 2D facial recognition support S2 and lower-level authentication.

-

callback

-

AsyncCallback<number>

-

No

-

Callback invoked to return the authentication result

-
- - Callback return values - - - - - - - - - - -

Type

-

Description

-

number

-

Authentication result. See AuthenticationResult.

-
- -- Example - - ``` - authenticator.execute("FACE_ONLY", "S2", (code)=>{ - if (code == userIAM_userAuth.AuthenticationResult.SUCCESS) { - console.info("auth success"); - return; - } - console.error("auth fail, code = " + code); - }) - ``` - - -### execute - -execute\(type:string, level:string\): Promise - -Performs user authentication and returns the authentication result using a promise. - -- Parameters - - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

type

-

string

-

Yes

-

Authentication type. Only FACE_ONLY is supported.

-

ALL is reserved and not supported by the current version.

-

level

-

string

-

Yes

-

Security level of the authentication. It can be S1 (lowest), S2, S3, or S4 (highest).

-

Devices capable of 3D facial recognition support S3 and lower-level authentication.

-

Devices capable of 2D facial recognition support S2 and lower-level authentication.

-
- -- Return values - - - - - - - - - - -

Type

-

Description

-

Promise<number>

-

Promise used to return the authentication result. The number in the promise indicates the authentication result. See AuthenticationResult.

-
- -- Example - - ``` - let authenticator = userIAM_userAuth.getAuthenticator(); - authenticator.execute("FACE_ONLY", "S2").then((code)=>{ - authenticator.off("tip", tipCallback); - console.info("auth success"); - }).catch((code)=>{ - authenticator.off("tip", tipCallback); - console.error("auth fail, code = " + code); - }); - ``` - - -### cancel7+ - -cancel\(\): number - -Cancels the current authentication. - -- Return values - - - - - - - - - - -

Type

-

Description

-

number

-

Whether the authentication is canceled. For details, see Result.

-
- -- Example - - ``` - let authenticator = userIAM_userAuth.getAuthenticator(); - let cancelCode = authenticator.cancel(); - if (cancelCode == userIAM_userAuth.Result.SUCCESS) { - console.info("cancel auth success"); - } else { - console.error("cancel auth fail"); - } - ``` - - -### checkAvailability7+ - -checkAvailability\(type: AuthType, level: SecureLevel\): number - -Checks whether the device supports the specified authentication type and security level. - -- Parameters - - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

type

-

string

-

Yes

-

Authentication type. Only FACE_ONLY is supported.

-

ALL is reserved and not supported by the current version.

-

level

-

string

-

Yes

-

Security level of the authentication. It can be S1 (lowest), S2, S3, or S4 (highest).

-

Devices capable of 3D facial recognition support S3 and lower-level authentication.

-

Devices capable of 2D facial recognition support S2 and lower-level authentication.

-
- -- Return values - - - - - - - - - - -

Type

-

Description

-

number

-

Check result. For details, see CheckAvailabilityResult.

-
- -- Example - - ``` - let authenticator = userIAM_userAuth.getAuthenticator(); - let checkCode = authenticator.checkAvailability("FACE_ONLY", "S2"); - if (checkCode == userIAM_userAuth.CheckAvailabilityResult.SUPPORTED) { - console.info("check auth support success"); - } else { - console.error("check auth support fail, code = " + checkCode); - } - ``` - - -### on7+ - -on\(type: "tip", callback: Callback\) : void; - -Subscribes to the events of the specified type. - -- Parameters - - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

type

-

string

-

Yes

-

Event type. Currently, only tip is supported. An event is triggered when the authentication service sends a message to the caller.

-

callback

-

Callback<Tip>

-

Yes

-

Callback used to report the event of the specified type. Currently, only the tip event is supported.

-
- - -- Example - - ``` - let authenticator = userIAM_userAuth.getAuthenticator(); - let tipCallback = (tip)=>{ - console.info("receive tip: errorCode(" + tip.errorCode + ") code(" + tip.tipCode +") event(" + - tip.tipEvent + ") info(" + tip.tipInfo + ")"); - }; - authenticator.on("tip", tipCallback); - ``` - - -### off7+ - -off\(type: "tip", callback?: Callback\) : void; - -Unsubscribes from the events of the specified type. - -- Parameters - - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

type

-

string

-

Yes

-

Event type. Currently, only tip is supported.

-

callback

-

Callback<Tip>

-

No

-

Callback used to report the event of the specified type. Currently, only the tip event is supported. If this parameter is not specified, all callbacks corresponding to type will be canceled.

-
- - -- Example - - ``` - let authenticator = userIAM_userAuth.getAuthenticator(); - let tipCallback = (tip)=>{ - console.info("receive tip: errorCode(" + tip.errorCode + ") code(" + tip.tipCode + ") event(" + - tip.tipEvent + ") info(" + tip.tipInfo + ")"); - }; - // Unsubscribe from a specified callback. - authenticator.off("tip", tipCallback); - - // Unsubscribe from all callbacks. - authenticator.off("tip"); - ``` - - -## AuthenticationResult +## userIAM_userAuth.getAuthenticator(deprecated) + +getAuthenticator(): Authenticator + +> **NOTE**
+> This API is not longer maintained since API version 8. You are advised to use [constructor](#constructor8). + +Obtains an **Authenticator** object for user authentication. + +**Required permissions**: ohos.permission.ACCESS_BIOMETRIC + +**System capability**: SystemCapability.UserIAM.UserAuth.Core + +**Return value** +| Type | Description | +| ----------------------------------------- | ------------ | +| [Authenticator](#authenticatordeprecated) | **Authenticator** object obtained.| + +**Example** + ```js + let authenticator = userIAM_userAuth.getAuthenticator(); + ``` + +## Authenticator(deprecated) + +> **NOTE**
+> This object is not longer maintained since API version 8. You are advised to use [UserAuth](#userauth8). + +Provides methods to manage an **Authenticator** object. + + +### execute(deprecated) + +execute(type: string, level: string, callback: AsyncCallback<number>): void + +> **NOTE**
+> This API is not longer maintained since API version 8. You are advised to use [auth](#auth8). + +Performs user authentication. This method uses asynchronous callback to return the result. + +**Required permissions**: ohos.permission.ACCESS_BIOMETRIC + +**System capability**: SystemCapability.UserIAM.UserAuth.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | --------------------------- | ---- | ------------------------------------------------------------ | +| type | string | Yes | Authentication type. Only **FACE_ONLY** is supported.
**ALL** is reserved and not supported by the current version.| +| level | string | Yes | Security level of the authentication. It can be S1 (lowest), S2, S3, or S4 (highest).
Devices capable of 3D facial recognition support S3 and lower-level authentication.
Devices capable of 2D facial recognition support S2 and lower-level authentication.| +| callback | AsyncCallback<number> | No | Callback used to return the result. | + + Parameters returned in callback + +| Type | Description | +| ------ | ------------------------------------------------------------ | +| number | Authentication result. For details, see [AuthenticationResult](#authenticationresultdeprecated).| + +**Example** + ```js + authenticator.execute("FACE_ONLY", "S2", (code)=>{ + if (code == userIAM_userAuth.AuthenticationResult.SUCCESS) { + console.info("auth success"); + return; + } + console.error("auth fail, code = " + code); + }) + ``` + + +### execute(deprecated) + +execute(type:string, level:string): Promise<number> + +> **NOTE**
+> This API is not longer maintained since API version 8. You are advised to use [auth](#auth8). + +Performs user authentication. This method uses a promise to return the result. + +**Required permissions**: ohos.permission.ACCESS_BIOMETRIC + +**System capability**: SystemCapability.UserIAM.UserAuth.Core + +**Parameters** +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------------------------------------------------------------ | +| type | string | Yes | Authentication type. Only **FACE_ONLY** is supported.
**ALL** is reserved and not supported by the current version.| +| level | string | Yes | Security level of the authentication. It can be S1 (lowest), S2, S3, or S4 (highest).
Devices capable of 3D facial recognition support S3 and lower-level authentication.
Devices capable of 2D facial recognition support S2 and lower-level authentication.| + +**Return value** +| Type | Description | +| --------------------- | ------------------------------------------------------------ | +| Promise<number> | Promise used to return the authentication result, which is a number. For details, see [AuthenticationResult](#authenticationresultdeprecated).| + +**Example** + +```js +let authenticator = userIAM_userAuth.getAuthenticator(); +authenticator.execute("FACE_ONLY", "S2").then((code)=>{ + console.info("auth success"); +}).catch((code)=>{ + console.error("auth fail, code = " + code); +}); +``` + +## AuthenticationResult(deprecated) + +> **NOTE**
+> This parameter is not longer maintained since API version 8. You are advised to use [ResultCode](#resultcode8). Enumerates the authentication results. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Name

-

Default Value

-

Description

-

NO_SUPPORT

-

-1

-

The device does not support the current authentication mode.

-

SUCCESS

-

0

-

The authentication is successful.

-

COMPARE_FAILURE

-

1

-

The feature comparison failed.

-

CANCELED

-

2

-

The user cancels the authentication.

-

TIMEOUT

-

3

-

The authentication has timed out.

-

CAMERA_FAIL

-

4

-

The camera failed to start.

-

BUSY

-

5

-

The authentication service is not available. Try again later.

-

INVALID_PARAMETERS

-

6

-

The authentication parameters are invalid.

-

LOCKED

-

7

-

The user account is locked because the number of authentication failures has reached the threshold.

-

NOT_ENROLLED

-

8

-

No authentication credential is registered.

-

GENERAL_ERROR

-

100

-

Other errors.

-
- -## Tip7+ - -Defines the object of the tip generated during the authentication process. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

errorCode

-

number

-

Yes

-

Whether the tip is obtained successfully. For details, see Result.

-

tipEvent

-

number

-

Yes

-

Tip event. For details, see TipEvent. Currently, only RESULT and ACQUIRE are supported.

-

tipCode

-

number

-

Yes

-

Tip code.

-
  • If tipEvent is RESULT, the tip code provides the authentication result. For details, see AuthenticationResult.
  • If tipEvent is ACQUIRE, the tip code provides prompt information. For details, see TipCode.
-

tipInfo

-

string

-

Yes

-

Description of the tip code.

-
- -## Result7+ +**System capability**: SystemCapability.UserIAM.UserAuth.Core + +| Name | Default Value| Description | +| ------------------ | ------ | -------------------------- | +| NO_SUPPORT | -1 | The device does not support the current authentication mode.| +| SUCCESS | 0 | The authentication is successful. | +| COMPARE_FAILURE | 1 | The feature comparison failed. | +| CANCELED | 2 | The authentication was canceled by the user. | +| TIMEOUT | 3 | The authentication has timed out. | +| CAMERA_FAIL | 4 | The camera failed to start. | +| BUSY | 5 | The authentication service is not available. Try again later. | +| INVALID_PARAMETERS | 6 | The authentication parameters are invalid. | +| LOCKED | 7 | The user account is locked because the number of authentication failures has reached the threshold.| +| NOT_ENROLLED | 8 | No authentication credential is registered. | +| GENERAL_ERROR | 100 | Other errors. | + +## UserAuth8+ + +Provides methods to manage an **Authenticator** object. + +### constructor8+ + +constructor() + +A constructor used to create an **authenticator** object. + +**Required permissions**: ohos.permission.ACCESS_BIOMETRIC + +**System capability**: SystemCapability.UserIAM.UserAuth.Core + +**Return value** + +| Type | Description | +| ---------------------- | -------------------- | +| [UserAuth](#userauth8) | **Authenticator** object obtained.| + +**Example** + + ```js + import userIAM_userAuth from '@ohos.userIAM.userAuth'; + + let auth = new userIAM_userAuth.UserAuth(); + ``` + +### getVersion8+ + +getVersion() : number + +Obtains the authenticator version. + +**Required permissions**: ohos.permission.ACCESS_BIOMETRIC + +**System capability**: SystemCapability.UserIAM.UserAuth.Core + +**Return value** + +| Type | Description | +| ------ | ---------------------- | +| number | Authenticator version obtained.| + +**Example** + + ```js + import userIAM_userAuth from '@ohos.userIAM.userAuth'; + + let auth = new userIAM_userAuth.UserAuth(); + let version = auth.getVersion(); + console.info("auth version = " + version); + ``` + +### getAvailableStatus8+ + +getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel) : number + +Checks whether the authentication capability of the specified trust level is available. + +**Required permissions**: ohos.permission.ACCESS_BIOMETRIC + +**System capability**: SystemCapability.UserIAM.UserAuth.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------------- | ---------------------------------- | ---- | -------------------------- | +| authType | [UserAuthType](#userauthtype8) | Yes | Authentication type. Only **FACE** is supported.| +| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | Yes | Trust level of the authentication result. | + +**Return value** + +| Type | Description | +| ------ | ------------------------------------------------------------ | +| number | Whether the authentication capability of the specified trust level is available. For details, see [ResultCode](#resultcode8).| + +**Example** + + ```js + import userIAM_userAuth from '@ohos.userIAM.userAuth'; + + let auth = new userIAM_userAuth.UserAuth(); + let checkCode = auth.getAvailableStatus(userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1); + if (checkCode == userIAM_userAuth.ResultCode.SUCCESS) { + console.info("check auth support success"); + // Add the logic to be executed if the specified authentication type is supported. + } else { + console.error("check auth support fail, code = " + checkCode); + // Add the logic to be executed if the specified authentication type is not supported. + } + ``` + +### auth8+ + +auth(challenge: Uint8Array, authType: UserAuthType, authTrustLevel: AuthTrustLevel, callback: IUserAuthCallback): Uint8Array + +Performs user authentication. This method uses a callback to return the result. + +**Required permissions**: ohos.permission.ACCESS_BIOMETRIC + +**System capability**: SystemCapability.UserIAM.UserAuth.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------------- | ---------------------------------------- | ---- | ------------------------ | +| challenge | Uint8Array | Yes | Challenge value, which can be null. | +| authType | [UserAuthType](#userauthtype8) | Yes | Authentication type. Only **FACE** is supported.| +| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | Yes | Trust level. | +| callback | [IUserAuthCallback](#iuserauthcallback8) | Yes | Callback used to return the result. | + +**Return value** + +| Type | Description | +| ---------- | ------------------------------------------------------------ | +| Uint8Array | ContextId, which is used as the input parameter of [cancelAuth](#cancelauth8).| + +**Example** + + ```js + import userIAM_userAuth from '@ohos.userIAM.userAuth'; + + let auth = new userIAM_userAuth.UserAuth(); + auth.auth(null, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, { + onResult: (result, extraInfo) => { + try { + console.info("auth onResult result = " + result); + console.info("auth onResult extraInfo = " + JSON.stringify(extraInfo)); + if (result == userIAM_userAuth.ResultCode.SUCCESS) { + // Add the logic to be executed when the authentication is successful. + } else { + // Add the logic to be executed when the authentication fails. + } + } catch (e) { + console.info("auth onResult error = " + e); + } + } + }); + ``` + +### cancelAuth8+ + +cancelAuth(contextID : Uint8Array) : number + +Cancels an authentication. + +**Required permissions**: ohos.permission.ACCESS_BIOMETRIC + +**System capability**: SystemCapability.UserIAM.UserAuth.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| --------- | ---------- | ---- | ------------------------------------------ | +| contextID | Uint8Array | Yes | Context ID, which is obtained using [auth](#auth8).| + +**Return value** + +| Type | Description | +| ------ | ------------------------ | +| number | Whether the authentication is canceled.| + +**Example** + + ```js + import userIAM_userAuth from '@ohos.userIAM.userAuth'; + + // contextId can be obtained using auth(). In this example, it is defined here. + let contextId = new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7]); + let cancelCode = auth.cancel(contextId); + if (cancelCode == userIAM_userAuth.ResultCode.SUCCESS) { + console.info("cancel auth success"); + } else { + console.error("cancel auth fail"); + } + ``` + +## IUserAuthCallback8+ + +Defines the object of the result returned by the callback during authentication. + +### onResult8+ + +onResult: (result : number, extraInfo : AuthResult) => void + +Obtains the authentication result. + +**System capability**: SystemCapability.UserIAM.UserAuth.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| --------- | -------------------------- | ---- | ------------------------------------------------------------ | +| result | number | Yes | Authentication result obtained. For details, see [ResultCode](#resultcode8). | +| extraInfo | [AuthResult](#authresult8) | Yes | Extended information, which varies depending on the authentication result.
If the authentication is successful, the user authentication token will be returned in **extraInfo**.
If the authentication fails, the remaining number of authentication times will be returned in **extraInfo**.
If the authenticator is locked, the freeze time will be returned in **extraInfo**.| + + +**Example** + + ```js + import userIAM_userAuth from '@ohos.userIAM.userAuth'; + + let auth = new userIAM_userAuth.UserAuth(); + auth.auth(null, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, { + onResult: (result, extraInfo) => { + try { + console.info("auth onResult result = " + result); + console.info("auth onResult extraInfo = " + JSON.stringify(extraInfo)); + if (result == SUCCESS) { + // Add the logic to be executed when the authentication is successful. + } else { + // Add the logic to be executed when the authentication fails. + } + } catch (e) { + console.info("auth onResult error = " + e); + } + }, + + onAcquireInfo: (module, acquire, extraInfo) => { + try { + console.info("auth onAcquireInfo module = " + module); + console.info("auth onAcquireInfo acquire = " + acquire); + console.info("auth onAcquireInfo extraInfo = " + JSON.stringify(extraInfo)); + } catch (e) { + console.info("auth onAcquireInfo error = " + e); + } + } + }); + ``` + +### onAcquireInfo8+ + +onAcquireInfo ?: (module : number, acquire : number, extraInfo : any) => void + +Obtains the tip code information during authentication. This function is optional. + +**System capability**: SystemCapability.UserIAM.UserAuth.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| --------- | ------ | ---- | ------------------------------ | +| module | number | Yes | Type of the authenticator. | +| acquire | number | Yes | Interaction information of the authenticator during the authentication process.| +| extraInfo | any | Yes | Reserved field. | + +**Example** + + ```js + import userIAM_userAuth from '@ohos.userIAM.userAuth'; + + let auth = new userIAM_userAuth.UserAuth(); + auth.auth(null, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, { + onResult: (result, extraInfo) => { + try { + console.info("auth onResult result = " + result); + console.info("auth onResult extraInfo = " + JSON.stringify(extraInfo)); + if (result == SUCCESS) { + // Add the logic to be executed when the authentication is successful. + } else { + // Add the logic to be executed when the authentication fails. + } + } catch (e) { + console.info("auth onResult error = " + e); + } + }, + + onAcquireInfo: (module, acquire, extraInfo) => { + try { + console.info("auth onAcquireInfo module = " + module); + console.info("auth onAcquireInfo acquire = " + acquire); + console.info("auth onAcquireInfo extraInfo = " + JSON.stringify(extraInfo)); + } catch (e) { + console.info("auth onAcquireInfo error = " + e); + } + } + }); + ``` + +## AuthResult8+ + +Represents the authentication result object. + +**System capability**: SystemCapability.UserIAM.UserAuth.Core + +| Name | Type | Mandatory| Description | +| ------------ | ---------- | ---- | -------------------- | +| token | Uint8Array | No | Identity authentication token. | +| remainTimes | number | No | Number of remaining authentication operations.| +| freezingTime | number | No | Time for which the authentication operation is frozen.| + +## ResultCode8+ Enumerates the operation results. - - - - - - - - - - - - - - - -

Name

-

Default Value

-

Description

-

SUCCESS

-

0

-

Successful

-

FAILED

-

1

-

Failed

-
- -## CheckAvailabilityResult7+ - -Enumerates the device authentication capability check results. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Name

-

Default Value

-

Description

-

SUPPORTED

-

0

-

The device supports the specified authentication type and security level.

-

AUTH_TYPE_NOT_SUPPORT

-

1

-

The device does not support the specified authentication type.

-

SECURE_LEVEL_NOT_SUPPORT

-

2

-

The device does not support the specified authentication security level.

-

DISTRIBUTED_AUTH_NOT_SUPPORT

-

3

-

The device does not support distributed authentication.

-

NOT_ENROLLED

-

4

-

The device does not have the authentication credential.

-

PARAM_NUM_ERROR

-

5

-

The number of parameters is incorrect.

-
- -## TipEvent7+ - -Enumerates the tip events occurred during the authentication process. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Name

-

Default Value

-

Description

-

RESULT

-

1

-

Credential enrollment result or authentication result.

-

CANCEL

-

2

-

Credential enrollment or authentication canceled.

-

ACQUIRE

-

3

-

Tips generated in the credential enrollment or authentication process.

-

BUSY

-

4

-

Credential enrollment or authentication unavailable.

-

OUT_OF_MEM

-

5

-

Insufficient memory.

-

FACE_ID

-

6

-

Index of a face authentication credential.

-
- -## TipCode7+ - -Enumerates the tip codes generated during the authentication process. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Name

-

Default Value

-

Description

-

FACE_AUTH_TIP_TOO_BRIGHT

-

1

-

The obtained facial image is too bright due to high illumination.

-

FACE_AUTH_TIP_TOO_DARK

-

2

-

The obtained facial image is too dark due to low illumination.

-

FACE_AUTH_TIP_TOO_CLOSE

-

3

-

The face is too close to the device.

-

FACE_AUTH_TIP_TOO_FAR

-

4

-

The face is too far away from the device.

-

FACE_AUTH_TIP_TOO_HIGH

-

5

-

Only the upper part of the face is captured because the device is angled too high.

-

FACE_AUTH_TIP_TOO_LOW

-

6

-

Only the lower part of the face is captured because the device is angled too low.

-

FACE_AUTH_TIP_TOO_RIGHT

-

7

-

Only the right part of the face is captured because the device is deviated to the right.

-

FACE_AUTH_TIP_TOO_LEFT

-

8

-

Only the left part of the face is captured because the device is deviated to the left.

-

FACE_AUTH_TIP_TOO_MUCH_MOTION

-

9

-

The face moves too fast during facial information collection.

-

FACE_AUTH_TIP_POOR_GAZE

-

10

-

The face is not facing the camera.

-

FACE_AUTH_TIP_NOT_DETECTED

-

11

-

No face is detected.

-
+**System capability**: SystemCapability.UserIAM.UserAuth.Core + +| Name | Default Value| Description | +| ----------------------- | ------ | -------------------- | +| SUCCESS | 0 | The operation is successful. | +| FAIL | 1 | The operation failed. | +| GENERAL_ERROR | 2 | A common operation error occurred. | +| CANCELED | 3 | The operation is canceled. | +| TIMEOUT | 4 | The operation timed out. | +| TYPE_NOT_SUPPORT | 5 | The authentication type is not supported. | +| TRUST_LEVEL_NOT_SUPPORT | 6 | The authentication trust level is not supported. | +| BUSY | 7 | Indicates the busy state. | +| INVALID_PARAMETERS | 8 | Invalid parameters are detected. | +| LOCKED | 9 | The authenticator is locked. | +| NOT_ENROLLED | 10 | The user has not entered the authentication information.| + + +## FaceTips8+ + +Enumerates the tip codes used during the facial authentication process. + +**System capability**: SystemCapability.UserIAM.UserAuth.Core + +| Name | Default Value| Description | +| ----------------------------- | ------ | ------------------------------------ | +| FACE_AUTH_TIP_TOO_BRIGHT | 1 | The obtained facial image is too bright due to high illumination. | +| FACE_AUTH_TIP_TOO_DARK | 2 | The obtained facial image is too dark due to low illumination. | +| FACE_AUTH_TIP_TOO_CLOSE | 3 | The face is too close to the device. | +| FACE_AUTH_TIP_TOO_FAR | 4 | The face is too far away from the device. | +| FACE_AUTH_TIP_TOO_HIGH | 5 | Only the upper part of the face is captured because the device is angled too high. | +| FACE_AUTH_TIP_TOO_LOW | 6 | Only the lower part of the face is captured because the device is angled too low. | +| FACE_AUTH_TIP_TOO_RIGHT | 7 | Only the right part of the face is captured because the device is deviated to the right. | +| FACE_AUTH_TIP_TOO_LEFT | 8 | Only the left part of the face is captured because the device is deviated to the left. | +| FACE_AUTH_TIP_TOO_MUCH_MOTION | 9 | The face moves too fast during facial information collection.| +| FACE_AUTH_TIP_POOR_GAZE | 10 | The face is not facing the camera. | +| FACE_AUTH_TIP_NOT_DETECTED | 11 | No face is detected. | + + +## FingerprintTips8+ + +Enumerates the tip codes used during the fingerprint authentication process. + +**System capability**: SystemCapability.UserIAM.UserAuth.Core + +| Name | Default Value| Description | +| --------------------------------- | ------ | -------------------------------------------------- | +| FINGERPRINT_AUTH_TIP_GOOD | 0 | The obtained fingerprint image is in good condition. | +| FINGERPRINT_AUTH_TIP_DIRTY | 1 | Large fingerprint image noise is detected due to suspicious or detected dirt on the sensor.| +| FINGERPRINT_AUTH_TIP_INSUFFICIENT | 2 | The noise of the fingerprint image is too large to be processed. | +| FINGERPRINT_AUTH_TIP_PARTIAL | 3 | Incomplete fingerprint image is detected. | +| FINGERPRINT_AUTH_TIP_TOO_FAST | 4 | The fingerprint image is incomplete due to fast movement. | +| FINGERPRINT_AUTH_TIP_TOO_SLOW | 5 | Failed to obtain the fingerprint image because the finger seldom moves. | + + +## UserAuthType8+ + +Enumerates the identity authentication types. + +**System capability**: SystemCapability.UserIAM.UserAuth.Core + +| Name | Default Value| Description | +| ----------- | ------ | ---------- | +| FACE | 2 | Facial authentication.| +| FINGERPRINT | 4 | Fingerprint authentication.| + +## AuthTrustLevel8+ + +Enumerates the trust levels of the authentication result. + +**System capability**: SystemCapability.UserIAM.UserAuth.Core + +| Name| Default Value| Description | +| ---- | ------ | ------------------------- | +| ATL1 | 10000 | Trust level 1.| +| ATL2 | 20000 | Trust level 2.| +| ATL3 | 30000 | Trust level 3.| +| ATL4 | 40000 | Trust level 4.|