Skip to content

D
Docs

OpenHarmony / Docs
1 年多 前同步成功

通知 159
Star 292
Fork 28
D
Docs
未验证 提交 1fc45a9f 编写于 作者: O openharmony_ci 提交者： Gitee
浏览文件
操作

!13618 [翻译完成】#I63LMS 

Merge pull request !13618 from Annie_wang/PR11919A
上级 6051acd7 969d0513
隐藏空白更改
内联 并排
Showing with 693 addition and 591 deletion
en/application-dev/reference/apis/js-apis-useriam-faceauth.md
浏览文件 @ 1fc45a9f
# @ohos.userIAM.faceAuth (Facial Authentication) # @ohos.userIAM.faceAuth (Facial Authentication)
The **userIAM.faceAuth** module provides APIs for face enrollment. The **userIAM.faceAuth** module provides APIs for face enrollment.
...@@ -34,17 +34,17 @@ A constructor used to create a **FaceAuthManager** object. ...@@ -34,17 +34,17 @@ A constructor used to create a **FaceAuthManager** object.
**Example** **Example**
```js ```js
import userIAM_faceAuth from '@ohos.userIAM.faceAuth'; import userIAM_faceAuth from '@ohos.userIAM.faceAuth';
let faceAuthManager = new userIAM_faceAuth.FaceAuthManager(); let faceAuthManager = new userIAM_faceAuth.FaceAuthManager();
``` ```
### setSurfaceId ### setSurfaceId
setSurfaceId(surfaceId: string): void; setSurfaceId(surfaceId: string): void;
Sets an [XComponent surface ID](../arkui-ts/ts-basic-components-xcomponent.md#getxcomponentsurfaceid) for the face preview page in the face enrollment process. Sets an [XComponent surface ID](../arkui-ts/ts-basic-components-xcomponent.md#getxcomponentsurfaceid) for the face preview page in the face enrollment process. This API must be used with [AddCredential](./js-apis-osAccount.md#addcredential8).
**System capability**: SystemCapability.UserIAM.UserAuth.FaceAuth **System capability**: SystemCapability.UserIAM.UserAuth.FaceAuth
...@@ -56,17 +56,28 @@ Sets an [XComponent surface ID](../arkui-ts/ts-basic-components-xcomponent.md#ge ...@@ -56,17 +56,28 @@ Sets an [XComponent surface ID](../arkui-ts/ts-basic-components-xcomponent.md#ge
| -------------- | ---------------------------------- | ---- | -------------------------- | | -------------- | ---------------------------------- | ---- | -------------------------- |
| surfaceId | string | Yes | ID of the surface held by the [XComponent](../arkui-ts/ts-basic-components-xcomponent.md#getxcomponentsurfaceid).| | surfaceId | string | Yes | ID of the surface held by the [XComponent](../arkui-ts/ts-basic-components-xcomponent.md#getxcomponentsurfaceid).|
For details about the following error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
**Error codes**
| ID| Error Message|
| -------- | ------- |
| 201 | Permission verification failed. |
| 202 | The caller is not a system application. |
| 12700001 | The operation is failed. |
**Example** **Example**
```js ```js
import faceAuth from '@ohos.userIAM.faceAuth'; import userIAM_faceAuth from '@ohos.userIAM.faceAuth';
let surfaceId = "123456"; // The surfaceId is obtained from the XComponent control. The surfaceId here is only an example.
let manager = new faceAuth.FaceAuthManager(); let surfaceId = "123456";
try { let manager = new userIAM_faceAuth.FaceAuthManager();
manager.setSurfaceId(surfaceId); try {
console.info("Set the surface ID successfully"); manager.setSurfaceId(surfaceId);
} catch (e) { console.info("Set the surface ID successfully");
console.error("Failed to set the surface ID, error = " + e); } catch (e) {
} console.error("Failed to set the surface ID, error = " + e);
``` }
```
en/application-dev/reference/apis/js-apis-useriam-userauth.md
浏览文件 @ 1fc45a9f
# @ohos.userIAM.userAuth (User Authentication) # @ohos.userIAM.userAuth (User Authentication)
The **userIAM.userAuth** module provides user authentication capabilities in identity authentication scenarios, such as device unlocking, payment, and app login. The **userIAM.userAuth** module provides user authentication capabilities in identity authentication scenarios, such as device unlocking, payment, and app login.
...@@ -12,268 +12,115 @@ The **userIAM.userAuth** module provides user authentication capabilities in ide ...@@ -12,268 +12,115 @@ The **userIAM.userAuth** module provides user authentication capabilities in ide
import userIAM_userAuth from '@ohos.userIAM.userAuth'; import userIAM_userAuth from '@ohos.userIAM.userAuth';
``` ```
## Sample Code ## AuthResultInfo<sup>9+</sup>
```js
// API version 9
import userIAM_userAuth from '@ohos.userIAM.userAuth';
export default {
getVersion() {
try {
let version = userIAM_userAuth.getVersion();
console.info("auth version = " + version);
} catch (error) {
console.info("get version failed, error = " + error);
}
},
start() {
console.info("start auth");
let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
let authType = userIAM_userAuth.UserAuthType.FACE;
let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1;
try {
let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel);
auth.on("result", {
callback: (result: userIAM_userAuth.AuthResultInfo) => {
console.log("authV9 result " + result.result);
console.log("authV9 token " + result.token);
console.log("authV9 remainAttempts " + result.remainAttempts);
console.log("authV9 lockoutDuration " + result.lockoutDuration);
}
});
// If tips are needed
auth.on("tip", {
callback : (result : userIAM_userAuth.TipInfo) => {
switch (result.tip) {
case userIAM_userAuth.FaceTips.FACE_AUTH_TIP_TOO_BRIGHT:
// Do something;
case userIAM_userAuth.FaceTips.FACE_AUTH_TIP_TOO_DARK:
// Do something;
// ...
default:
// Do others.
}
}
});
auth.start();
console.log("authV9 start success");
} catch (error) {
console.log("authV9 error = " + error);
// do error
}
},
getAvailableStatus() { Defines the authentication result.
console.info("start check auth support");
try {
userIAM_userAuth.getAvailableStatus(userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1);
console.info("current auth trust level is supported");
} catch (error) {
console.info("current auth trust level is not supported, error = " + error);
}
},
cancel() { **System capability**: SystemCapability.UserIAM.UserAuth.Core
console.info("start cancel auth");
let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
let authType = userIAM_userAuth.UserAuthType.FACE;
let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1;
try { | Name | Type | Mandatory| Description |
let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel); | ------------ | ---------- | ---- | -------------------- |
auth.start(); | result | number | Yes | Authentication result. |
auth.cancel(); | token | Uint8Array | No | Token that has passed the user identity authentication.|
console.info("cancel auth success"); | remainAttempts | number | No | Number of remaining authentication times allowed.|
} catch (error) { | lockoutDuration | number | No | Time for which the authentication operation is frozen.|
console.info("cancel auth failed, error = " + error);
}
}
}
```
```js ## TipInfo<sup>9+</sup>
// API version 8
import userIAM_userAuth from '@ohos.userIAM.userAuth';
let auth = new userIAM_userAuth.UserAuth();
export default { Defines the authentication tip information.
getVersion() {
console.info("start get version");
let version = auth.getVersion();
console.info("auth version = " + version);
},
startAuth() {
console.info("start auth");
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);
}
},
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 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 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.
}
},
cancelAuth() {
console.info("start cancel auth");
// 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.ResultCode.SUCCESS) {
console.info("cancel auth success");
} else {
console.error("cancel auth fail");
}
}
}
```
```js **System capability**: SystemCapability.UserIAM.UserAuth.Core
// API version 6
import userIAM_userAuth from '@ohos.userIAM.userAuth';
export default { | Name | Type | Mandatory| Description |
startAuth() { | ------------ | ---------- | ---- | -------------------- |
console.info("start auth"); | module | number | Yes | ID of the module that sends the tip information. |
let auth = userIAM_userAuth.getAuthenticator(); | tip | number | Yes | Tip to be given during the authentication process. |
auth.execute("FACE_ONLY", "S2").then((code)=>{
console.info("auth success");
// Add the logic to be executed when the authentication is successful.
}).catch((code)=>{
console.error("auth fail, code = " + code);
// Add the logic to be executed when the authentication fails.
});
}
}
```
## EventInfo<sup>9+</sup> ## EventInfo<sup>9+</sup>
Defines the event information used in authentication. Enumerates the authentication event information types.
**System capability**: SystemCapability.UserIAM.UserAuth.Core **System capability**: SystemCapability.UserIAM.UserAuth.Core
| Type | Description | | Value | Description |
| --------- | ----------------------- | | --------- | ----------------------- |
| [AuthResultInfo](#authresultinfo9) | Authentication result information. | | [AuthResultInfo](#authresultinfo9) | Authentication result. |
| [TipInfo](#tipinfo9) | Authentication tip information. | | [TipInfo](#tipinfo9) | Authentication tip information. |
## AuthEventKey<sup>9+</sup>
Defines the keyword of the authentication event type. It is used as a parameter of [on](#on9).
| Value | Description |
| ---------- | ----------------------- |
| "result" | If the first parameter of [on](#on9) is **result**, the [callback](#callback9) returns the authentication result.|
| "tip" | If the first parameter of [on](#on9) is **tip**, the [callback](#callback9) returns the authentication tip information.|
## AuthEvent<sup>9+</sup> ## AuthEvent<sup>9+</sup>
Provides callbacks to return authentication events. Provides an asynchronous callback to return the authentication event information.
### callback<sup>9+</sup> ### callback<sup>9+</sup>
callback: (result : EventInfo) => void callback(result : EventInfo) : void
Called to return the authentication result or authentication tips. Called to return the authentication result or authentication tip information.
**System capability**: SystemCapability.UserIAM.UserAuth.Core **System capability**: SystemCapability.UserIAM.UserAuth.Core
**Parameters** **Parameters**
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| --------- | -------------------------- | ---- | -------------------------------------------------------- | | --------- | -------------------------- | ---- | ------------------------------ |
| result | [EventInfo](#eventinfo9) | Yes | Authentication result or tip information. | | result | [EventInfo](#eventinfo9) | Yes | Authentication result or tip information. |
**Example** **Example**
```js ```js
import userIAM_userAuth from '@ohos.userIAM.userAuth'; import userIAM_userAuth from '@ohos.userIAM.userAuth';
let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
let authType = userIAM_userAuth.UserAuthType.FACE; let authType = userIAM_userAuth.UserAuthType.FACE;
let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1; let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1;
try { // Obtain the authentication result through a callback.
let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel); try {
auth.on("result", { let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel);
auth.on("result", {
callback: (result: userIAM_userAuth.AuthResultInfo) => { callback: (result: userIAM_userAuth.AuthResultInfo) => {
console.log("authV9 result " + result.result); console.log("authV9 result " + result.result);
console.log("authV9 token " + result.token); console.log("authV9 token " + result.token);
console.log("authV9 remainAttempts " + result.remainAttempts); console.log("authV9 remainAttempts " + result.remainAttempts);
console.log("authV9 lockoutDuration " + result.lockoutDuration); console.log("authV9 lockoutDuration " + result.lockoutDuration);
} }
}); });
auth.start(); auth.start();
console.log("authV9 start success"); console.log("authV9 start success");
} catch (error) { } catch (error) {
console.log("authV9 error = " + error); console.log("authV9 error = " + error);
// do error // do error
} }
``` // Obtain the authentication tip information through a callback.
try {
## AuthResultInfo<sup>9+</sup> let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel);
auth.on("tip", {
Defines the authentication result information. callback : (result : userIAM_userAuth.TipInfo) => {
switch (result.tip) {
**System capability**: SystemCapability.UserIAM.UserAuth.Core case userIAM_userAuth.FaceTips.FACE_AUTH_TIP_TOO_BRIGHT:
// Do something;
| Name | Type | Mandatory| Description | case userIAM_userAuth.FaceTips.FACE_AUTH_TIP_TOO_DARK:
| ------------ | ---------- | ---- | -------------------- | // Do something.
| result | number | Yes | Authentication result. | default:
| token | Uint8Array | No | Token that has passed the user identity authentication.| // Do others.
| remainAttempts | number | No | Number of remaining authentication times allowed.| }
| lockoutDuration | number | No | Time for which the authentication operation is frozen.| }
});
## TipInfo<sup>9+</sup> auth.start();
console.log("authV9 start success");
Defines the authentication tip information. } catch (error) {
console.log("authV9 error = " + error);
**System capability**: SystemCapability.UserIAM.UserAuth.Core // do error
}
| Name | Type | Mandatory| Description | ```
| ------------ | ---------- | ---- | -------------------- |
| module | number | No | Authentication module. |
| tip | number | No | Tip to be given during the authentication process. |
## AuthEventKey<sup>9+</sup>
Defines the keyword of an authentication event.
| Value | Description |
| ---------- | ----------------------- |
| "result" | Indicates authentication result.|
| "tip" | If **AuthEventKey** is **result**, the callback returns the authentication tip information.|
## AuthInstance<sup>9+</sup> ## AuthInstance<sup>9+</sup>
...@@ -281,9 +128,12 @@ Implements user authentication. ...@@ -281,9 +128,12 @@ Implements user authentication.
### on<sup>9+</sup> ### on<sup>9+</sup>
on(name : AuthEventKey, callback : AuthEvent) : void on : (name : AuthEventKey, callback : AuthEvent) => void
Enables authentication event listening. Subscribes to the user authentication events of the specified type.
> **NOTE**<br>
> Use the [AuthInstance](#authinstance9) instance obtained to invoke this API to subscribe to events.
**System capability**: SystemCapability.UserIAM.UserAuth.Core **System capability**: SystemCapability.UserIAM.UserAuth.Core
...@@ -291,151 +141,210 @@ Enables authentication event listening. ...@@ -291,151 +141,210 @@ Enables authentication event listening.
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| --------- | -------------------------- | ---- | ------------------------- | | --------- | -------------------------- | ---- | ------------------------- |
| name | AuthEventKey | Yes | Keyword of the authentication event to listen for. | | name | [AuthEventKey](#autheventkey9) | 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.|
| callback | AuthEvent | Yes | Callback invoked to return the authentication event. | | callback | [AuthEvent](#authevent9) | Yes | Callback invoked to return the authentication result or tip information.|
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
**Error codes**
| ID| Error Message|
| -------- | ------- |
| 401 | Incorrect parameters. |
| 12500002 | General operation error. |
**Example** **Example**
```js ```js
import userIAM_userAuth from '@ohos.userIAM.userAuth'; import userIAM_userAuth from '@ohos.userIAM.userAuth';
let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
let authType = userIAM_userAuth.UserAuthType.FACE; let authType = userIAM_userAuth.UserAuthType.FACE;
let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1; let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1;
try { try {
let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel); let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel);
auth.on("result", { // Subscribe to the authentication result.
auth.on("result", {
callback: (result: userIAM_userAuth.AuthResultInfo) => { callback: (result: userIAM_userAuth.AuthResultInfo) => {
console.log("authV9 result " + result.result); console.log("authV9 result " + result.result);
console.log("authV9 token " + result.token); console.log("authV9 token " + result.token);
console.log("authV9 remainAttempts " + result.remainAttempts); console.log("authV9 remainAttempts " + result.remainAttempts);
console.log("authV9 lockoutDuration " + result.lockoutDuration); console.log("authV9 lockoutDuration " + result.lockoutDuration);
} }
}); });
// If tips are needed // Subscribe to authentication tip information.
auth.on("tip", { auth.on("tip", {
callback : (result : userIAM_userAuth.TipInfo) => { callback : (result : userIAM_userAuth.TipInfo) => {
switch (result.tip) { switch (result.tip) {
case userIAM_userAuth.FaceTips.FACE_AUTH_TIP_TOO_BRIGHT: case userIAM_userAuth.FaceTips.FACE_AUTH_TIP_TOO_BRIGHT:
// Do something; // Do something;
case userIAM_userAuth.FaceTips.FACE_AUTH_TIP_TOO_DARK: case userIAM_userAuth.FaceTips.FACE_AUTH_TIP_TOO_DARK:
// Do something; // Do something;
// ...
default: default:
// Do others. // Do others.
} }
} }
}); });
auth.start(); auth.start();
console.log("authV9 start success"); console.log("authV9 start success");
} catch (error) { } catch (error) {
console.log("authV9 error = " + error); console.log("authV9 error = " + error);
// do error // do error
} }
``` ```
### off<sup>9+</sup> ### off<sup>9+</sup>
off(name : AuthEventKey) : void off : (name : AuthEventKey) => void
Disables authentication event listening. Unsubscribes from the user authentication events of the specific type.
> **NOTE**<br>
> Use the [AuthInstance](#authinstance9) instance obtained to invoke this API to unsubscribe from events.
**System capability**: SystemCapability.UserIAM.UserAuth.Core **System capability**: SystemCapability.UserIAM.UserAuth.Core
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| --------- | -------------------------- | ---- | ------------------------- | | --------- | -------------------------- | ---- | ------------------------- |
| name | AuthEventKey | Yes | Keyword of the authentication event. | | name | [AuthEventKey](#autheventkey9) | Yes | Type of the authentication event to unsubscribe from. If the value is **result**, the authentication result is unsubscribed from. If the value is **tip**, the authentication tip information is unsubscribed from.|
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
**Error codes**
| ID| Error Message|
| -------- | ------- |
| 401 | Incorrect parameters. |
| 12500002 | General operation error. |
**Example** **Example**
```js ```js
import userIAM_userAuth from '@ohos.userIAM.userAuth'; import userIAM_userAuth from '@ohos.userIAM.userAuth';
let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
let authType = userIAM_userAuth.UserAuthType.FACE; let authType = userIAM_userAuth.UserAuthType.FACE;
let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1; let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1;
let auth;
try {
auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel);
console.log("get auth instance success");
} catch (error) {
console.log("get auth instance failed" + error);
}
try { try {
let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel); // Subscribe to the authentication result.
auth.on("result", { auth.on("result", {
callback: (result: userIAM_userAuth.AuthResultInfo) => { callback: (result: userIAM_userAuth.AuthResultInfo) => {
console.log("authV9 result " + result.result); console.log("authV9 result " + result.result);
console.log("authV9 token " + result.token); console.log("authV9 token " + result.token);
console.log("authV9 remainAttempts " + result.remainAttempts); console.log("authV9 remainAttempts " + result.remainAttempts);
console.log("authV9 lockoutDuration " + result.lockoutDuration); console.log("authV9 lockoutDuration " + result.lockoutDuration);
} }
}); });
console.log("turn on authentication event listening success"); console.log("subscribe authentication event success");
} catch (error) { } catch (error) {
console.log("turn off authentication event listening failed " + error); console.log("subscribe authentication event failed " + error);
// do error }
} // Unsubscribe from the authentication result.
try {
try { auth.off("result");
let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel); console.info("cancel subscribe authentication event success");
auth.off("result"); } catch (error) {
console.info("turn off authentication event listening success"); console.info("cancel subscribe authentication event failed, error = " + error);
} catch (error) { }
console.info("turn off authentication event listening failed, error = " + error); ```
}
```
### start<sup>9+</sup> ### start<sup>9+</sup>
start() : void start : () => void
Starts authentication. Starts authentication.
> **NOTE**<br>
> Use the [AuthInstance](#authinstance9) instance obtained to invoke this API.
**Required permissions**: ohos.permission.ACCESS_BIOMETRIC **Required permissions**: ohos.permission.ACCESS_BIOMETRIC
**System capability**: SystemCapability.UserIAM.UserAuth.Core **System capability**: SystemCapability.UserIAM.UserAuth.Core
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
**Error codes**
| ID| Error Message|
| -------- | ------- |
| 201 | Permission verification failed. |
| 401 | Incorrect parameters. |
| 12500001 | Authentication failed. |
| 12500002 | General operation error. |
| 12500003 | The operation is canceled. |
| 12500004 | The operation is time-out. |
| 12500005 | The authentication type is not supported. |
| 12500006 | The authentication trust level is not supported. |
| 12500007 | The authentication task is busy. |
| 12500009 | The authenticator is locked. |
| 12500010 | The type of credential has not been enrolled. |
**Example** **Example**
```js ```js
import userIAM_userAuth from '@ohos.userIAM.userAuth'; import userIAM_userAuth from '@ohos.userIAM.userAuth';
let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
let authType = userIAM_userAuth.UserAuthType.FACE; let authType = userIAM_userAuth.UserAuthType.FACE;
let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1; let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1;
try { try {
let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel); let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel);
auth.start(); auth.start();
console.info("authV9 start auth success"); console.info("authV9 start auth success");
} catch (error) { } catch (error) {
console.info("authV9 start auth failed, error = " + error); console.info("authV9 start auth failed, error = " + error);
} }
``` ```
### cancel<sup>9+</sup> ### cancel<sup>9+</sup>
cancel(): void cancel : () => void
Cancels the authentication. Cancels this authentication.
> **NOTE**<br>
> Use the [AuthInstance](#authinstance9) instance obtained to invoke this API. The [AuthInstance](#authinstance9) instance must be the one being authenticated.
**Required permissions**: ohos.permission.ACCESS_BIOMETRIC **Required permissions**: ohos.permission.ACCESS_BIOMETRIC
**System capability**: SystemCapability.UserIAM.UserAuth.Core **System capability**: SystemCapability.UserIAM.UserAuth.Core
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
**Error codes**
| ID| Error Message|
| -------- | ------- |
| 201 | Permission verification failed. |
| 401 | Incorrect parameters. |
| 12500002 | General operation error. |
**Example** **Example**
```js ```js
import userIAM_userAuth from '@ohos.userIAM.userAuth'; import userIAM_userAuth from '@ohos.userIAM.userAuth';
let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
let authType = userIAM_userAuth.UserAuthType.FACE; let authType = userIAM_userAuth.UserAuthType.FACE;
let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1; let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1;
try { try {
let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel); let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel);
auth.start(); auth.cancel();
auth.cancel(); console.info("cancel auth success");
console.info("cancel auth success"); } catch (error) {
} catch (error) { console.info("cancel auth failed, error = " + error);
console.info("cancel auth failed, error = " + error); }
} ```
```
## userIAM_userAuth.getAuthInstance<sup>9+</sup> ## userIAM_userAuth.getAuthInstance<sup>9+</sup>
...@@ -444,7 +353,7 @@ getAuthInstance(challenge : Uint8Array, authType : UserAuthType, authTrustLevel ...@@ -444,7 +353,7 @@ getAuthInstance(challenge : Uint8Array, authType : UserAuthType, authTrustLevel
Obtains an **AuthInstance** instance for user authentication. Obtains an **AuthInstance** instance for user authentication.
> **NOTE**<br> > **NOTE**<br>
> Each **AuthInstance** can be used to initiate an authentication only once. > An **AuthInstance** instance can be used for an authentication only once.
**System capability**: SystemCapability.UserIAM.UserAuth.Core **System capability**: SystemCapability.UserIAM.UserAuth.Core
...@@ -460,23 +369,35 @@ Obtains an **AuthInstance** instance for user authentication. ...@@ -460,23 +369,35 @@ Obtains an **AuthInstance** instance for user authentication.
| Type | Description | | Type | Description |
| ----------------------------------------- | ------------ | | ----------------------------------------- | ------------ |
| [AuthInstance](#authinstance9) | **Authenticator** object obtained.| | [AuthInstance](#authinstance9) | **Authenticator** instance obtained.|
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
**Error codes**
| ID| Error Message|
| -------- | ------- |
| 401 | Incorrect parameters. |
| 12500002 | General operation error. |
| 12500005 | The authentication type is not supported. |
| 12500006 | The authentication trust level is not supported. |
**Example** **Example**
```js
import userIAM_userAuth from '@ohos.userIAM.userAuth';
let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); ```js
let authType = userIAM_userAuth.UserAuthType.FACE; import userIAM_userAuth from '@ohos.userIAM.userAuth';
let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1;
try { let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel); let authType = userIAM_userAuth.UserAuthType.FACE;
console.info("get auth instance success"); let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1;
} catch (error) {
console.info("get auth instance success failed, error = " + error); try {
} let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel);
``` console.info("get auth instance success");
} catch (error) {
console.info("get auth instance success failed, error = " + error);
}
```
## userIAM_userAuth.getVersion<sup>9+</sup> ## userIAM_userAuth.getVersion<sup>9+</sup>
...@@ -494,24 +415,33 @@ Obtains the version of this authenticator. ...@@ -494,24 +415,33 @@ Obtains the version of this authenticator.
| ------ | ---------------------- | | ------ | ---------------------- |
| number | Authenticator version obtained.| | number | Authenticator version obtained.|
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
**Error codes**
| ID| Error Message|
| -------- | ------- |
| 201 | Permission verification failed. |
| 12500002 | General operation error. |
**Example** **Example**
```js ```js
import userIAM_userAuth from '@ohos.userIAM.userAuth'; import userIAM_userAuth from '@ohos.userIAM.userAuth';
try { try {
let version = userIAM_userAuth.getVersion(); let version = userIAM_userAuth.getVersion();
console.info("auth version = " + version); console.info("auth version = " + version);
} catch (error) { } catch (error) {
console.info("get version failed, error = " + error); console.info("get version failed, error = " + error);
} }
``` ```
## userIAM_userAuth.getAvailableStatus<sup>9+</sup> ## userIAM_userAuth.getAvailableStatus<sup>9+</sup>
getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel): void getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel): void
Checks whether the authentication capability of the specified trust level is available. Checks whether the specified authentication capability is supported.
**Required permissions**: ohos.permission.ACCESS_BIOMETRIC **Required permissions**: ohos.permission.ACCESS_BIOMETRIC
...@@ -522,54 +452,65 @@ Checks whether the authentication capability of the specified trust level is ava ...@@ -522,54 +452,65 @@ Checks whether the authentication capability of the specified trust level is ava
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------------- | ---------------------------------- | ---- | -------------------------- | | -------------- | ---------------------------------- | ---- | -------------------------- |
| authType | [UserAuthType](#userauthtype8) | Yes | Authentication type. Only **FACE** is supported.| | authType | [UserAuthType](#userauthtype8) | Yes | Authentication type. Only **FACE** is supported.|
| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | Yes | Trust level of the authentication result. | | authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | Yes | Authentication trust level. |
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
**Error codes**
| ID| Error Message|
| -------- | ------- |
| 201 | Permission verification failed. |
| 401 | Incorrect parameters. |
| 12500002 | General operation error. |
| 12500005 | The authentication type is not supported. |
| 12500006 | The authentication trust level is not supported. |
| 12500010 | The type of credential has not been enrolled. |
**Example** **Example**
```js ```js
import userIAM_userAuth from '@ohos.userIAM.userAuth'; import userIAM_userAuth from '@ohos.userIAM.userAuth';
try { try {
userIAM_userAuth.getAvailableStatus(userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1); userIAM_userAuth.getAvailableStatus(userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1);
console.info("current auth trust level is supported"); console.info("current auth trust level is supported");
} catch (error) { } catch (error) {
console.info("current auth trust level is not supported, error = " + error); console.info("current auth trust level is not supported, error = " + error);
} }
``` ```
## ResultCodeV9<sup>9+</sup> ## UserAuthResultCode<sup>9+</sup>
Enumerates the operation results. Enumerates the authentication result codes.
**System capability**: SystemCapability.UserIAM.UserAuth.Core **System capability**: SystemCapability.UserIAM.UserAuth.Core
| Name | Default Value| Description | | Name | Value | Description |
| ----------------------- | ------ | -------------------- | | ----------------------- | ------ | -------------------- |
| SUCCESS | 12500000 | The operation is successful. | | SUCCESS | 12500000 | The authentication is successful. |
| FAIL | 12500001 | The operation failed. | | FAIL | 12500001 | The authentication failed. |
| GENERAL_ERROR | 12500002 | A common operation error occurred. | | GENERAL_ERROR | 12500002 | A general operation error occurred. |
| CANCELED | 12500003 | The operation is canceled. | | CANCELED | 12500003 | The authentication is canceled. |
| TIMEOUT | 12500004 | The operation timed out. | | TIMEOUT | 12500004 | The authentication timed out. |
| TYPE_NOT_SUPPORT | 12500005 | The authentication type is not supported. | | TYPE_NOT_SUPPORT | 12500005 | The authentication type is not supported. |
| TRUST_LEVEL_NOT_SUPPORT | 12500006 | The authentication trust level is not supported. | | TRUST_LEVEL_NOT_SUPPORT | 12500006 | The authentication trust level is not supported. |
| BUSY | 12500007 | Indicates the busy state. | | BUSY | 12500007 | Indicates the busy state. |
| INVALID_PARAMETERS | 12500008 | Invalid parameters are detected. |
| LOCKED | 12500009 | The authentication executor is locked. | | LOCKED | 12500009 | The authentication executor is locked. |
| NOT_ENROLLED | 12500010 | The user has not entered the authentication information.| | NOT_ENROLLED | 12500010 | The user has not entered the authentication information.|
## UserAuth<sup>8+</sup> ## UserAuth<sup>8+</sup>
Provides methods to manage an **Authenticator** object. Provides APIs to manage an **Authenticator** object.
### constructor<sup>(deprecated)</sup> ### constructor<sup>(deprecated)</sup>
constructor() constructor()
> **NOTE** A constructor used to create an authenticator instance.
>
>This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getAuthInstance](#useriam_userauthgetauthinstance9).
A constructor used to create an **authenticator** object. > **NOTE**<br>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getAuthInstance](#useriam_userauthgetauthinstance9).
**System capability**: SystemCapability.UserIAM.UserAuth.Core **System capability**: SystemCapability.UserIAM.UserAuth.Core
...@@ -577,25 +518,24 @@ A constructor used to create an **authenticator** object. ...@@ -577,25 +518,24 @@ A constructor used to create an **authenticator** object.
| Type | Description | | Type | Description |
| ---------------------- | -------------------- | | ---------------------- | -------------------- |
| [UserAuth](#userauth8) | **Authenticator** object obtained.| | [UserAuth](#userauth8) | **Authenticator** instance obtained.|
**Example** **Example**
```js ```js
import userIAM_userAuth from '@ohos.userIAM.userAuth'; import userIAM_userAuth from '@ohos.userIAM.userAuth';
let auth = new userIAM_userAuth.UserAuth(); let auth = new userIAM_userAuth.UserAuth();
``` ```
### getVersion<sup>(deprecated)</sup> ### getVersion<sup>(deprecated)</sup>
getVersion() : number getVersion() : number
> **NOTE** Obtains the version of this authenticator.
>
>This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getVersion](#useriam_userauthgetversion9).
Obtains the authentication executor version. > **NOTE**<br>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getVersion](#useriam_userauthgetversion9).
**Required permissions**: ohos.permission.ACCESS_BIOMETRIC **Required permissions**: ohos.permission.ACCESS_BIOMETRIC
...@@ -609,23 +549,22 @@ Obtains the authentication executor version. ...@@ -609,23 +549,22 @@ Obtains the authentication executor version.
**Example** **Example**
```js ```js
import userIAM_userAuth from '@ohos.userIAM.userAuth'; import userIAM_userAuth from '@ohos.userIAM.userAuth';
let auth = new userIAM_userAuth.UserAuth(); let auth = new userIAM_userAuth.UserAuth();
let version = auth.getVersion(); let version = auth.getVersion();
console.info("auth version = " + version); console.info("auth version = " + version);
``` ```
### getAvailableStatus<sup>(deprecated)</sup> ### getAvailableStatus<sup>(deprecated)</sup>
getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel) : number getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel) : number
> **NOTE** Checks whether the specified authentication capability is supported.
>
>This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getAvailableStatus](#useriam_userauthgetavailablestatus9).
Obtains the available status of the specified authentication trust level. > **NOTE**<br>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getAvailableStatus](#useriam_userauthgetavailablestatus9).
**Required permissions**: ohos.permission.ACCESS_BIOMETRIC **Required permissions**: ohos.permission.ACCESS_BIOMETRIC
...@@ -636,40 +575,37 @@ Obtains the available status of the specified authentication trust level. ...@@ -636,40 +575,37 @@ Obtains the available status of the specified authentication trust level.
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------------- | ---------------------------------- | ---- | -------------------------- | | -------------- | ---------------------------------- | ---- | -------------------------- |
| authType | [UserAuthType](#userauthtype8) | Yes | Authentication type. Only **FACE** is supported.| | authType | [UserAuthType](#userauthtype8) | Yes | Authentication type. Only **FACE** is supported.|
| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | Yes | Trust level of the authentication result. | | authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | Yes | Authentication trust level. |
**Return value** **Return value**
| Type | Description | | Type | Description |
| ------ | ------------------------------------------------------------ | | ------ | ------------------------------------------------------------ |
| number | Available status obtained. For details, see [ResultCode](#resultcodedeprecated).| | number | Query result. If the authentication capability is supported, **SUCCESS** is returned. Otherwise, a [ResultCode](#resultcodedeprecated) is returned.|
**Example** **Example**
```js ```js
import userIAM_userAuth from '@ohos.userIAM.userAuth'; import userIAM_userAuth from '@ohos.userIAM.userAuth';
let auth = new userIAM_userAuth.UserAuth(); let auth = new userIAM_userAuth.UserAuth();
let checkCode = auth.getAvailableStatus(userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1); let checkCode = auth.getAvailableStatus(userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1);
if (checkCode == userIAM_userAuth.ResultCode.SUCCESS) { if (checkCode == userIAM_userAuth.ResultCode.SUCCESS) {
console.info("check auth support success"); console.info("check auth support success");
// Add the logic to be executed if the specified authentication type is supported. } else {
} else { console.error("check auth support fail, code = " + checkCode);
console.error("check auth support fail, code = " + checkCode); }
// Add the logic to be executed if the specified authentication type is not supported. ```
}
```
### auth<sup>(deprecated)</sup> ### auth<sup>(deprecated)</sup>
auth(challenge: Uint8Array, authType: UserAuthType, authTrustLevel: AuthTrustLevel, callback: IUserAuthCallback): Uint8Array auth(challenge: Uint8Array, authType: UserAuthType, authTrustLevel: AuthTrustLevel, callback: IUserAuthCallback): Uint8Array
> **NOTE**
>
>This API is supported since API version 8 and deprecated since API version 9. You are advised to use [start](#start9).
Performs user authentication. This API uses a callback to return the result. Performs user authentication. This API uses a callback to return the result.
> **NOTE**<br>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [start](#start9).
**Required permissions**: ohos.permission.ACCESS_BIOMETRIC **Required permissions**: ohos.permission.ACCESS_BIOMETRIC
**System capability**: SystemCapability.UserIAM.UserAuth.Core **System capability**: SystemCapability.UserIAM.UserAuth.Core
...@@ -680,8 +616,8 @@ Performs user authentication. This API uses a callback to return the result. ...@@ -680,8 +616,8 @@ Performs user authentication. This API uses a callback to return the result.
| -------------- | ---------------------------------------- | ---- | ------------------------ | | -------------- | ---------------------------------------- | ---- | ------------------------ |
| challenge | Uint8Array | Yes | Challenge value, which can be null. | | challenge | Uint8Array | Yes | Challenge value, which can be null. |
| authType | [UserAuthType](#userauthtype8) | Yes | Authentication type. Only **FACE** is supported.| | authType | [UserAuthType](#userauthtype8) | Yes | Authentication type. Only **FACE** is supported.|
| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | Yes | Trust level. | | authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | Yes | Authentication trust level. |
| callback | [IUserAuthCallback](#iuserauthcallbackdeprecated) | Yes | Callback used to return the result. | | callback | [IUserAuthCallback](#iuserauthcallbackdeprecated) | Yes | Callback used to return the result. |
**Return value** **Return value**
...@@ -691,36 +627,35 @@ Performs user authentication. This API uses a callback to return the result. ...@@ -691,36 +627,35 @@ Performs user authentication. This API uses a callback to return the result.
**Example** **Example**
```js ```js
import userIAM_userAuth from '@ohos.userIAM.userAuth'; import userIAM_userAuth from '@ohos.userIAM.userAuth';
let auth = new userIAM_userAuth.UserAuth(); let auth = new userIAM_userAuth.UserAuth();
auth.auth(null, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, { auth.auth(null, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, {
onResult: (result, extraInfo) => { onResult: (result, extraInfo) => {
try { try {
console.info("auth onResult result = " + result); console.info("auth onResult result = " + result);
console.info("auth onResult extraInfo = " + JSON.stringify(extraInfo)); console.info("auth onResult extraInfo = " + JSON.stringify(extraInfo));
if (result == userIAM_userAuth.ResultCode.SUCCESS) { if (result == userIAM_userAuth.ResultCode.SUCCESS) {
// Add the logic to be executed when the authentication is successful. // Add the logic to be executed when the authentication is successful.
} else { } else {
// Add the logic to be executed when the authentication fails. // Add the logic to be executed when the authentication fails.
} }
} catch (e) { } catch (e) {
console.info("auth onResult error = " + e); console.info("auth onResult error = " + e);
} }
} }
}); });
``` ```
### cancelAuth<sup>(deprecated)</sup> ### cancelAuth<sup>(deprecated)</sup>
cancelAuth(contextID : Uint8Array) : number cancelAuth(contextID : Uint8Array) : number
> **NOTE** Cancels an authentication based on the context ID.
>
>This API is supported since API version 8 and deprecated since API version 9. You are advised to use [cancel](#cancel9).
Cancels an authentication. > **NOTE**<br>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [cancel](#cancel9).
**Required permissions**: ohos.permission.ACCESS_BIOMETRIC **Required permissions**: ohos.permission.ACCESS_BIOMETRIC
...@@ -730,100 +665,86 @@ Cancels an authentication. ...@@ -730,100 +665,86 @@ Cancels an authentication.
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| --------- | ---------- | ---- | ------------------------------------------ | | --------- | ---------- | ---- | ------------------------------------------ |
| contextID | Uint8Array | Yes | Context ID, which is obtained by using [auth](#authdeprecated).| | contextID | Uint8Array | Yes | Context ID, which is obtained by [auth](#authdeprecated).|
**Return value** **Return value**
| Type | Description | | Type | Description |
| ------ | ------------------------ | | ------ | ------------------------ |
| number | Whether the authentication is canceled.| | number | Returns **SUCCESS** if the cancellation is successful. Returns a [ResultCode](#resultcodedeprecated) otherwise.|
**Example** **Example**
```js ```js
import userIAM_userAuth from '@ohos.userIAM.userAuth'; import userIAM_userAuth from '@ohos.userIAM.userAuth';
// contextId can be obtained using auth(). In this example, it is defined here. // contextId can be obtained by auth(). In this example, it is defined here.
let contextId = new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7]); let contextId = new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7]);
let auth = new userIAM_userAuth.UserAuth(); let auth = new userIAM_userAuth.UserAuth();
let cancelCode = auth.cancelAuth(contextId); let cancelCode = auth.cancelAuth(contextId);
if (cancelCode == userIAM_userAuth.ResultCode.SUCCESS) { if (cancelCode == userIAM_userAuth.ResultCode.SUCCESS) {
console.info("cancel auth success"); console.info("cancel auth success");
} else { } else {
console.error("cancel auth fail"); console.error("cancel auth fail");
} }
``` ```
## IUserAuthCallback<sup>(deprecated)</sup> ## IUserAuthCallback<sup>(deprecated)</sup>
> **NOTE** Provides callbacks to return the authentication result.
>
>This object is supported since API version 8 and deprecated since API version 9. You are advised to use [AuthEvent](#authevent9).
Defines the object of the result returned by the callback during authentication. > **NOTE**<br>
> This object is supported since API version 8 and deprecated since API version 9. You are advised to use [AuthEvent](#authevent9).
### onResult<sup>(deprecated)</sup> ### onResult<sup>(deprecated)</sup>
onResult: (result : number, extraInfo : AuthResult) => void onResult: (result : number, extraInfo : AuthResult) => void
> **NOTE** Called to return the authentication result.
>
>This API is supported since API version 8 and deprecated since API version 9. You are advised to use [callback](#callback9).
Obtains the authentication result. > **NOTE**<br>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [callback](#callback9).
**System capability**: SystemCapability.UserIAM.UserAuth.Core **System capability**: SystemCapability.UserIAM.UserAuth.Core
**Parameters** **Parameters**
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| --------- | -------------------------- | ---- | ------------------------------------------------------------ | | --------- | -------------------------- | ---- | ------------------------------------------------ |
| result | number | Yes | Authentication result. For details, see [ResultCode](#resultcodedeprecated). | | result | number | Yes | Authentication result. For details, see [ResultCode](#resultcodedeprecated).|
| 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**.| | 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**.|
**Example** **Example**
```js ```js
import userIAM_userAuth from '@ohos.userIAM.userAuth'; import userIAM_userAuth from '@ohos.userIAM.userAuth';
let auth = new userIAM_userAuth.UserAuth(); let auth = new userIAM_userAuth.UserAuth();
auth.auth(null, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, { auth.auth(null, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, {
onResult: (result, extraInfo) => { onResult: (result, extraInfo) => {
try { try {
console.info("auth onResult result = " + result); console.info("auth onResult result = " + result);
console.info("auth onResult extraInfo = " + JSON.stringify(extraInfo)); console.info("auth onResult extraInfo = " + JSON.stringify(extraInfo));
if (result == userIAM_userAuth.ResultCode.SUCCESS) { if (result == userIAM_userAuth.ResultCode.SUCCESS) {
// Add the logic to be executed when the authentication is successful. // Add the logic to be executed when the authentication is successful.
} else { } else {
// Add the logic to be executed when the authentication fails. // Add the logic to be executed when the authentication fails.
} }
} catch (e) { } catch (e) {
console.info("auth onResult error = " + 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);
}
}
});
```
### onAcquireInfo<sup>(deprecated)</sup> ### onAcquireInfo<sup>(deprecated)</sup>
onAcquireInfo ?: (module : number, acquire : number, extraInfo : any) => void onAcquireInfo ?: (module : number, acquire : number, extraInfo : any) => void
> **NOTE** Called to acquire authentication tip information. This API is optional.
>
>This API is supported since API version 8 and deprecated since API version 9. You are advised to use [callback](#callback9).
Obtains the tip code information during authentication. This function is optional. > **NOTE**<br>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [callback](#callback9).
**System capability**: SystemCapability.UserIAM.UserAuth.Core **System capability**: SystemCapability.UserIAM.UserAuth.Core
...@@ -831,89 +752,74 @@ Obtains the tip code information during authentication. This function is optiona ...@@ -831,89 +752,74 @@ Obtains the tip code information during authentication. This function is optiona
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| --------- | ------ | ---- | ------------------------------ | | --------- | ------ | ---- | ------------------------------ |
| module | number | Yes | Type of the authentication executor. | | module | number | Yes | ID of the module that sends the tip information. |
| acquire | number | Yes | Interaction information of the authentication executor during the authentication process.| | acquire | number | Yes | Authentication tip information.|
| extraInfo | any | Yes | Reserved field. | | extraInfo | any | Yes | Reserved field. |
**Example** **Example**
```js ```js
import userIAM_userAuth from '@ohos.userIAM.userAuth'; 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);
}
},
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);
}
}
});
```
## AuthResult<sup>(deprecated)</sup> let auth = new userIAM_userAuth.UserAuth();
auth.auth(null, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, {
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);
}
}
});
```
> **NOTE** ## AuthResult<sup>(deprecated)</sup>
>
>This object is supported since API version 8 and deprecated since API version 9. You are advised to use [AuthResultInfo](#authresultinfo9).
Represents the authentication result object. Represents the authentication result object.
> **NOTE**<br>
> This object is supported since API version 8 and deprecated since API version 9. You are advised to use [AuthResultInfo](#authresultinfo9).
**System capability**: SystemCapability.UserIAM.UserAuth.Core **System capability**: SystemCapability.UserIAM.UserAuth.Core
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| ------------ | ---------- | ---- | -------------------- | | ------------ | ---------- | ---- | -------------------|
| token | Uint8Array | No | Identity authentication token. | | token | Uint8Array | No | Authentication token information.|
| remainTimes | number | No | Number of remaining authentication operations.| | remainTimes | number | No | Number of remaining authentication operations.|
| freezingTime | number | No | Time for which the authentication operation is frozen.| | freezingTime | number | No | Time for which the authentication operation is frozen.|
## ResultCode<sup>(deprecated)</sup> ## ResultCode<sup>(deprecated)</sup>
> **NOTE**<br> Enumerates the authentication result codes.
> This object is deprecated since API version 9. You are advised to use [ResultCodeV9](#resultcodev99).
Enumerates the operation results. > **NOTE**<br>
> This object is deprecated since API version 9. You are advised to use [UserAuthResultCode](#userauthresultcode9).
**System capability**: SystemCapability.UserIAM.UserAuth.Core **System capability**: SystemCapability.UserIAM.UserAuth.Core
| Name | Default Value| Description | | Name | Value| Description |
| ----------------------- | ------ | -------------------- | | ----------------------- | ------ | -------------------- |
| SUCCESS | 0 | The operation is successful. | | SUCCESS | 0 | The operation is successful. |
| FAIL | 1 | The operation failed. | | FAIL | 1 | The authentication failed. |
| GENERAL_ERROR | 2 | A common operation error occurred. | | GENERAL_ERROR | 2 | A general operation error occurred. |
| CANCELED | 3 | The operation is canceled. | | CANCELED | 3 | The authentication is canceled. |
| TIMEOUT | 4 | The operation timed out. | | TIMEOUT | 4 | The authentication timed out. |
| TYPE_NOT_SUPPORT | 5 | The authentication type is not supported. | | TYPE_NOT_SUPPORT | 5 | The authentication type is not supported. |
| TRUST_LEVEL_NOT_SUPPORT | 6 | The authentication trust level is not supported. | | TRUST_LEVEL_NOT_SUPPORT | 6 | The authentication trust level is not supported. |
| BUSY | 7 | Indicates the busy state. | | BUSY | 7 | Indicates the busy state. |
| INVALID_PARAMETERS | 8 | Invalid parameters are detected. |
| LOCKED | 9 | The authentication executor is locked. | | LOCKED | 9 | The authentication executor is locked. |
| NOT_ENROLLED | 10 | The user has not entered the authentication information.| | NOT_ENROLLED | 10 | The user has not entered the authentication information.|
## FaceTips<sup>8+</sup> ## FaceTips<sup>8+</sup>
Enumerates the tip codes used during the facial authentication process. Enumerates the tip codes used during the facial authentication process.
**System capability**: SystemCapability.UserIAM.UserAuth.Core **System capability**: SystemCapability.UserIAM.UserAuth.Core
| Name | Default Value| Description | | Name | Value | Description |
| ----------------------------- | ------ | ------------------------------------ | | ----------------------------- | ------ | ------------------------------------ |
| FACE_AUTH_TIP_TOO_BRIGHT | 1 | The obtained facial image is too bright due to high illumination. | | 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_DARK | 2 | The obtained facial image is too dark due to low illumination. |
...@@ -934,7 +840,7 @@ Enumerates the tip codes used during the fingerprint authentication process. ...@@ -934,7 +840,7 @@ Enumerates the tip codes used during the fingerprint authentication process.
**System capability**: SystemCapability.UserIAM.UserAuth.Core **System capability**: SystemCapability.UserIAM.UserAuth.Core
| Name | Default Value| Description | | Name | Value | Description |
| --------------------------------- | ------ | -------------------------------------------------- | | --------------------------------- | ------ | -------------------------------------------------- |
| FINGERPRINT_AUTH_TIP_GOOD | 0 | The obtained fingerprint image is in good condition. | | 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_DIRTY | 1 | Large fingerprint image noise is detected due to suspicious or detected dirt on the sensor.|
...@@ -950,7 +856,7 @@ Enumerates the identity authentication types. ...@@ -950,7 +856,7 @@ Enumerates the identity authentication types.
**System capability**: SystemCapability.UserIAM.UserAuth.Core **System capability**: SystemCapability.UserIAM.UserAuth.Core
| Name | Default Value| Description | | Name | Value | Description |
| ----------- | ------ | ---------- | | ----------- | ------ | ---------- |
| FACE | 2 | Facial authentication.| | FACE | 2 | Facial authentication.|
| FINGERPRINT | 4 | Fingerprint authentication.| | FINGERPRINT | 4 | Fingerprint authentication.|
...@@ -961,7 +867,7 @@ Enumerates the trust levels of the authentication result. ...@@ -961,7 +867,7 @@ Enumerates the trust levels of the authentication result.
**System capability**: SystemCapability.UserIAM.UserAuth.Core **System capability**: SystemCapability.UserIAM.UserAuth.Core
| Name| Default Value| Description | | Name| Value | Description |
| ---- | ------ | ------------------------- | | ---- | ------ | ------------------------- |
| ATL1 | 10000 | Trust level 1.| | ATL1 | 10000 | Trust level 1.|
| ATL2 | 20000 | Trust level 2.| | ATL2 | 20000 | Trust level 2.|
...@@ -972,18 +878,18 @@ Enumerates the trust levels of the authentication result. ...@@ -972,18 +878,18 @@ Enumerates the trust levels of the authentication result.
getAuthenticator(): Authenticator getAuthenticator(): Authenticator
Obtains an **Authenticator** instance for user authentication.
> **NOTE**<br> > **NOTE**<br>
> This API is deprecated since API version 8. You are advised to use [constructor](#constructordeprecated). > This API is deprecated since API version 8. You are advised to use [constructor](#constructordeprecated).
Obtains an **Authenticator** object for user authentication.
**System capability**: SystemCapability.UserIAM.UserAuth.Core **System capability**: SystemCapability.UserIAM.UserAuth.Core
**Return value** **Return value**
| Type | Description | | Type | Description |
| ----------------------------------------- | ------------ | | ----------------------------------------- | ------------ |
| [Authenticator](#authenticatordeprecated) | **Authenticator** object obtained.| | [Authenticator](#authenticatordeprecated) | **Authenticator** instance obtained.|
**Example** **Example**
```js ```js
...@@ -992,61 +898,61 @@ Obtains an **Authenticator** object for user authentication. ...@@ -992,61 +898,61 @@ Obtains an **Authenticator** object for user authentication.
## Authenticator<sup>(deprecated)</sup> ## Authenticator<sup>(deprecated)</sup>
Defines the **Authenticator** object.
> **NOTE**<br> > **NOTE**<br>
> This object is deprecated since API version 8. You are advised to use [UserAuth](#userauth8). > This object is deprecated since API version 8. You are advised to use [UserAuth](#userauth8).
Provides methods to manage an **Authenticator** object.
### execute<sup>(deprecated)</sup> ### execute<sup>(deprecated)</sup>
execute(type: AuthType, level: SecureLevel, callback: AsyncCallback&lt;number&gt;): void execute(type: AuthType, level: SecureLevel, callback: AsyncCallback&lt;number&gt;): void
Performs user authentication. This API uses asynchronous callback to return the result.
> **NOTE**<br> > **NOTE**<br>
> This API is deprecated since API version 8. You are advised to use [auth](#authdeprecated). > This API is deprecated since API version 8. You are advised to use [auth](#authdeprecated).
Performs user authentication. This API uses asynchronous callback to return the result.
**Required permissions**: ohos.permission.ACCESS_BIOMETRIC **Required permissions**: ohos.permission.ACCESS_BIOMETRIC
**System capability**: SystemCapability.UserIAM.UserAuth.Core **System capability**: SystemCapability.UserIAM.UserAuth.Core
**Parameters** **Parameters**
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | --------------------------- | ---- | ------------------------------------------------------------ | | -------- | --------------------------- | ---- | -------------------------- |
| type | AuthType | Yes | Authentication type. Only **FACE_ONLY** is supported.<br>**ALL** is reserved and not supported by the current version.| | type | AuthType | Yes | Authentication type. Only **FACE_ONLY** is supported.<br>**ALL** is reserved and not supported by the current version.|
| 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.| | 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.|
| callback | AsyncCallback&lt;number&gt; | No | Callback used to return the result. | | callback | AsyncCallback&lt;number&gt; | Yes | Callback used to return the result. |
Parameters returned in callback Parameters returned in callback
| Type | Description | | Type | Description |
| ------ | ------------------------------------------------------------ | | ------ | ------------------------------------------------------------ |
| number | Authentication result. For details, see [AuthenticationResult](#authenticationresultdeprecated).| | number | Authentication result. For details, see [AuthenticationResult](#authenticationresultdeprecated).|
**Example** **Example**
```js
let authenticator = userIAM_userAuth.getAuthenticator(); ```js
authenticator.execute("FACE_ONLY", "S2", (error, code)=>{ let authenticator = userIAM_userAuth.getAuthenticator();
if (code === userIAM_userAuth.ResultCode.SUCCESS) { authenticator.execute("FACE_ONLY", "S2", (error, code)=>{
console.info("auth success"); if (code === userIAM_userAuth.ResultCode.SUCCESS) {
return; console.info("auth success");
} return;
console.error("auth fail, code = " + code); }
}); console.error("auth fail, code = " + code);
``` });
```
### execute<sup>(deprecated)</sup> ### execute<sup>(deprecated)</sup>
execute(type:AuthType, level:SecureLevel): Promise&lt;number&gt; execute(type : AuthType, level : SecureLevel): Promise&lt;number&gt;
Performs user authentication. This API uses a promise to return the result.
> **NOTE**<br> > **NOTE**<br>
> This API is deprecated since API version 8. You are advised to use [auth](#authdeprecated). > This API is deprecated since API version 8. You are advised to use [auth](#authdeprecated).
Performs user authentication. This API uses a promise to return the result.
**Required permissions**: ohos.permission.ACCESS_BIOMETRIC **Required permissions**: ohos.permission.ACCESS_BIOMETRIC
**System capability**: SystemCapability.UserIAM.UserAuth.Core **System capability**: SystemCapability.UserIAM.UserAuth.Core
...@@ -1066,25 +972,25 @@ Performs user authentication. This API uses a promise to return the result. ...@@ -1066,25 +972,25 @@ Performs user authentication. This API uses a promise to return the result.
**Example** **Example**
```js ```js
let authenticator = userIAM_userAuth.getAuthenticator(); let authenticator = userIAM_userAuth.getAuthenticator();
authenticator.execute("FACE_ONLY", "S2").then((code)=>{ authenticator.execute("FACE_ONLY", "S2").then((code)=>{
console.info("auth success"); console.info("auth success");
}).catch((error)=>{ }).catch((error)=>{
console.error("auth fail, code = " + error); console.error("auth fail, code = " + error);
}); });
``` ```
## AuthenticationResult<sup>(deprecated)</sup> ## AuthenticationResult<sup>(deprecated)</sup>
Enumerates the authentication results.
> **NOTE**<br> > **NOTE**<br>
> This object is discarded since API version 8. You are advised to use [ResultCode](#resultcodedeprecated). > This object is discarded since API version 8. You are advised to use [ResultCode](#resultcodedeprecated).
Enumerates the authentication results.
**System capability**: SystemCapability.UserIAM.UserAuth.Core **System capability**: SystemCapability.UserIAM.UserAuth.Core
| Name | Default Value| Description | | Name | Value | Description |
| ------------------ | ------ | -------------------------- | | ------------------ | ------ | -------------------------- |
| NO_SUPPORT | -1 | The device does not support the current authentication mode.| | NO_SUPPORT | -1 | The device does not support the current authentication mode.|
| SUCCESS | 0 | The authentication is successful. | | SUCCESS | 0 | The authentication is successful. |
......
en/application-dev/reference/errorcodes/Readme-EN.md
浏览文件 @ 1fc45a9f
...@@ -33,8 +33,11 @@ ...@@ -33,8 +33,11 @@
- Security - Security
- [Ability Access Control Error Codes](errorcode-access-token.md) - [Ability Access Control Error Codes](errorcode-access-token.md)
- [HUKS Error Codes](errorcode-huks.md) - [HUKS Error Codes](errorcode-huks.md)
- [User Authentication Error Codes](errorcode-useriam.md)
- Data Management - Data Management
- [RDB Error Codes](errorcode-data-rdb.md) - [RDB Error Codes](errorcode-data-rdb.md)
- [DataShare Error Codes](errorcode-datashare.md)
- [Distributed Data Object Error Codes](errorcode-distributed-dataObject.md)
- [Distributed KV Store Error Codes](errorcode-distributedKVStore.md) - [Distributed KV Store Error Codes](errorcode-distributedKVStore.md)
- [Preferences Error Codes](errorcode-preferences.md) - [Preferences Error Codes](errorcode-preferences.md)
- File Management - File Management
......
en/application-dev/reference/errorcodes/errorcode-distributed-dataObject.md 0 → 100644
浏览文件 @ 1fc45a9f
# Distributed Data Object Error Codes
## 15400001 Failed to Create the In-Memory Database
**Error Message**
Create table failed.
**Description**
The in-memory database fails to be created.
**Possible Causes**
An object with the same session ID already exists.
**Solution**
Check for the object has been added to the same session.
en/application-dev/reference/errorcodes/errorcode-useriam.md 0 → 100644
浏览文件 @ 1fc45a9f
# User Authentication Error Codes
## 201 Permission Verification Failed
For details, see [Universal Error Codes](./errorcode-universal.md).
## 202 Invoker Is Not a System Application
For details, see [Universal Error Codes](./errorcode-universal.md).
## 401 Parameter Check Failed.
For details, see [Universal Error Codes](./errorcode-universal.md).
## 12500001 Authentication Failed
**Error Message**
Authentication failed.
**Possible Causes**
The credential does not match the credential enrolled.
**Solution**
Initiate authentication again.
## 12500002 General Operation Error
**Error Message**
General operation error.
**Possible Causes**
1. An error occurs when the NAPI layer parses parameters.
2. The process of the user authentication service is not started.
3. The proxy client fails to write data over IPC.
4. The stub server fails to parse data over IPC.
5. The driver service is not obtained.
**Solution**
Call the API again later or restart the device.
## 12500003 Authentication Canceled
**Error Message**
Authentication canceled.
**Possible Causes**
The authentication operation has been canceled.
**Solution**
Initiate the authentication again.
## 12500004 Authentication Timed Out
**Error Message**
Authentication timeout.
**Possible Causes**
The authentication is not complete within the specified time.
**Solution**
Initiate the authentication again.
## 12500005 Unsupported Authentication Type
**Error Message**
The authentication type is not supported.
**Possible Causes**
1. The input authentication type parameter is not supported. For example, if the authentication type passed in **getAvailableStatus** of the **userAuth** module is not **FACE** or **FINGERPRINT**, error code 12500005 is returned.
2. The device does not support the authentication type. For example, if fingerprint authentication is initiated on a device that has no fingerprint sensor, error code 12500005 is returned.
**Solution**
Check the authentication type parameter and call the API again.
## 12500006 Unsupported Authentication Trust Level
**Error Message**
The authentication trust level is not supported.
**Possible Causes**
1. The **authTrustLevel** value in **getAvailableStatus** or **getAuthInstance** of the **userAuth** module is not in the range [ATL1, ATL2, ATL3, ATL4].
2. The device does not support the authentication trust level. For example, if facial authentication for payment is initiated on a device that has only 2D cameras, error code 12500006 is returned.
**Solution**
Check that the **authTrustLevel** passed in is within the value range, and the device supports the specified authentication trust level.
## 12500007 Authentication Service Unavailable
**Error Message**
Authentication service is busy.
**Possible Causes**
Another authentication is initiated when the current authentication has not been finished yet.
**Solution**
Initiate authentication again later.
## 12500009 Authentication Locked
**Error Message**
Authentication is lockout.
**Possible Causes**
The number of authentication failures exceeds the limit.
**Solution**
Initiate authentication later.
## 12500010 Credential Not Enrolled
**Error Message**
The type of credential has not been enrolled.
**Possible Causes**
The **authType** parameter set in **getAvailableStatus** of the **userAuth** module is **FACE**, but no facial credential is enrolled in the device.
**start()** is called to initiate facial authentication, but no facial credential is enrolled in the device.
**Solution**
Check that the related type of credential has been enrolled in the device.
## 12700001 Failed to Enroll Faces
**Error Message**
The operation is failed.
**Possible Causes**
1. The facial authentication service is not started when **setSurfaceId()** of the **userAuth** module is called.
2. The proxy client fails to write data over IPC.
3. The stub server fails to parse data over IPC.
4. An error occurs when the facial authentication driver is invoked.
**Solution**
Call the API again later or restart the device.
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或