Skip to content

D
Docs

OpenHarmony / Docs
大约 2 年 前同步成功

通知 161
Star 293
Fork 28
D
Docs
未验证 提交 5bbfd682 编写于 作者: O openharmony_ci 提交者： Gitee
浏览文件
操作

!11734 IAM资料整改 

Merge pull request !11734 from youliang_1314/master
上级 90ed4873 62e0338f
隐藏空白更改
内联 并排
Showing with 1134 addition and 939 deletion
zh-cn/application-dev/reference/apis/js-apis-useriam-faceauth.md
浏览文件 @ 5bbfd682
...@@ -30,21 +30,21 @@ constructor() ...@@ -30,21 +30,21 @@ constructor()
| 类型 | 说明 | | 类型 | 说明 |
| ---------------------- | -------------------- | | ---------------------- | -------------------- |
| [FaceAuthManager](#faceauthmanager) | 人脸认证管理器对象 | | [FaceAuthManager](#faceauthmanager) | 人脸认证管理器对象。 |
**示例：** **示例：**
```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;
设置录入流程中人脸预览界面 [XComponent](../arkui-ts/ts-basic-components-xcomponent.md#getxcomponentsurfaceid) 持有 Surface 的 ID。 该接口仅用于在录入人脸时，设置人脸预览界面 [XComponent](../arkui-ts/ts-basic-components-xcomponent.md#getxcomponentsurfaceid) 持有 Surface 的 ID，需要配合[人脸录入接口](./js-apis-osAccount.md#addcredential8)来使用。
**系统能力：** SystemCapability.UserIAM.UserAuth.FaceAuth **系统能力：** SystemCapability.UserIAM.UserAuth.FaceAuth
...@@ -56,17 +56,28 @@ setSurfaceId(surfaceId: string): void; ...@@ -56,17 +56,28 @@ setSurfaceId(surfaceId: string): void;
| -------------- | ---------------------------------- | ---- | -------------------------- | | -------------- | ---------------------------------- | ---- | -------------------------- |
| surfaceId | string | 是 | [XComponent](../arkui-ts/ts-basic-components-xcomponent.md#getxcomponentsurfaceid) 持有 Surface 的 ID。 | | surfaceId | string | 是 | [XComponent](../arkui-ts/ts-basic-components-xcomponent.md#getxcomponentsurfaceid) 持有 Surface 的 ID。 |
以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errcode-useriam.md)
**错误码：**
| 错误码ID | 错误信息 |
| -------- | ------- |
| 201 | Permission verification failed. |
| 202 | The caller is not a system application. |
| 12700001 | The operation is failed. |
**示例：** **示例：**
```js ```js
import faceAuth from '@ohos.userIAM.faceAuth'; import userIAM_faceAuth from '@ohos.userIAM.faceAuth';
let surfaceId = "123456"; // 该surfaceId应该从XComponent控件获取，此处仅用作示例。
let manager = new faceAuth.FaceAuthManager(); let surfaceId = "123456";
try { let manager = new userIAM_faceAuth.FaceAuthManager();
manager.setSurfaceId(surfaceId); try {
console.info("set surface id success"); manager.setSurfaceId(surfaceId);
} catch (e) { console.info("set surface id success");
console.error("set surface id failed, error = " + e); } catch (e) {
} console.error("set surface id failed, error = " + e);
``` }
```
zh-cn/application-dev/reference/apis/js-apis-useriam-userauth.md
浏览文件 @ 5bbfd682
...@@ -12,268 +12,115 @@ ...@@ -12,268 +12,115 @@
import userIAM_userAuth from '@ohos.userIAM.userAuth'; import userIAM_userAuth from '@ohos.userIAM.userAuth';
``` ```
## 完整示例 ## AuthResultInfo<sup>9+</sup>
```js 表示认证结果信息。
// API version 9
import userIAM_userAuth from '@ohos.userIAM.userAuth';
export default { **系统能力**：以下各项对应的系统能力均为SystemCapability.UserIAM.UserAuth.Core。
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]); | result | number | 是 | 认证结果。 |
let authType = userIAM_userAuth.UserAuthType.FACE; | token | Uint8Array | 否 | 用户身份认证通过的凭证。 |
let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1; | remainAttempts | number | 否 | 剩余的认证操作次数。 |
try { | lockoutDuration | number | 否 | 认证操作的冻结时间。 |
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 need tip
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() { ## TipInfo<sup>9+</sup>
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() { 表示认证过程中的提示信息。
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 { **系统能力**：以下各项对应的系统能力均为SystemCapability.UserIAM.UserAuth.Core。
let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel);
auth.start();
auth.cancel();
console.info("cancel auth success");
} catch (error) {
console.info("cancel auth failed, error = " + error);
}
}
}
```
```js | 名称 | 类型 | 必填 | 说明 |
// API version 8 | ------------ | ---------- | ---- | -------------------- |
import userIAM_userAuth from '@ohos.userIAM.userAuth'; | module | number | 是 | 发送提示信息的模块标识。 |
let auth = new userIAM_userAuth.UserAuth(); | tip | number | 是 | 认证过程提示信息。 |
export default { ## EventInfo<sup>9+</sup>
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) {
// 此处添加认证成功逻辑
} else {
// 此处添加认证失败逻辑
}
} 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");
// 此处添加支持指定类型认证的逻辑
} else {
console.error("check auth support fail, code = " + checkCode);
// 此处添加不支持指定类型认证的逻辑
}
},
cancelAuth() {
console.info("start cancel auth");
// contextId通过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 表示认证过程中事件信息的类型。
// API version 6
import userIAM_userAuth from '@ohos.userIAM.userAuth';
export default { **系统能力**：以下各项对应的系统能力均为SystemCapability.UserIAM.UserAuth.Core。
startAuth() {
console.info("start auth");
let auth = userIAM_userAuth.getAuthenticator();
auth.execute("FACE_ONLY", "S2").then((code)=>{
console.info("auth success");
// 此处添加认证成功逻辑
}).catch((code)=>{
console.error("auth fail, code = " + code);
// 此处添加认证失败逻辑
});
}
}
```
## EventInfo<sup>9+</sup> | 取值类型 | 说明 |
| --------- | ----------------------- |
| [AuthResultInfo](#authresultinfo9) | 获取到的认证结果信息。 |
| [TipInfo](#tipinfo9) | 认证过程中的提示信息。 |
类型别名，用于表示认证事件信息的类型，取值可以为下表中的类型。 ## AuthEventKey<sup>9+</sup>
**系统能力**：SystemCapability.UserIAM.UserAuth.Core 表示认证事件类型的关键字，作为[on](#on9)接口的的参数。
| 类型 | 说明 | | 取值类型 | 说明 |
| --------- | ----------------------- | | ---------- | ----------------------- |
| [AuthResultInfo](#authresultinfo9) | 认证结果信息 | | "result" | [on](#on9)接口第一个参数为"result"时，[callback](#callback9)回调返回认证的结果信息。 |
| [TipInfo](#tipinfo9) | 认证过程中的提示信息 | | "tip" | [on](#on9)接口第一个参数为"tip"时，[callback](#callback9)回调返回认证操作中的提示信息。 |
## AuthEvent<sup>9+</sup> ## AuthEvent<sup>9+</sup>
认证事件回调的对象。 认证接口的异步回调对象。
### callback<sup>9+</sup> ### callback<sup>9+</sup>
callback: (result : EventInfo) => void callback(result : EventInfo) : void
表示在认证结束后返回结果信息或者在认证操作中返回提示信息。 通过该回调获取认证结果信息或认证过程中的提示信息。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core **系统能力**：SystemCapability.UserIAM.UserAuth.Core
**参数：** **参数：**
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| --------- | -------------------------- | ---- | -------------------------------------------------------- | | --------- | -------------------------- | ---- | ------------------------------ |
| result | [EventInfo](#eventinfo9) | 是 | 返回的认证结果信息或提示信息。 | | result | [EventInfo](#eventinfo9) | 是 | 返回的认证结果信息或提示信息。 |
**示例：** **示例：**
```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 { // 通过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
} }
``` // 通过callback获取认证过程中的提示信息
try {
## AuthResultInfo<sup>9+</sup> let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel);
auth.on("tip", {
表示认证结果信息的对象。 callback : (result : userIAM_userAuth.TipInfo) => {
switch (result.tip) {
**系统能力**：SystemCapability.UserIAM.UserAuth.Core case userIAM_userAuth.FaceTips.FACE_AUTH_TIP_TOO_BRIGHT:
// do something;
| 名称 | 参数类型 | 必填 | 说明 | case userIAM_userAuth.FaceTips.FACE_AUTH_TIP_TOO_DARK:
| ------------ | ---------- | ---- | -------------------- | // do something;
| result | number | 是 | 认证结果。 | default:
| token | Uint8Array | 否 | 用户身份认证通过的凭证。 | // do others
| remainAttempts | number | 否 | 剩余的认证操作次数。 | }
| lockoutDuration | number | 否 | 认证操作的冻结时间。 | }
});
## TipInfo<sup>9+</sup> auth.start();
console.log("authV9 start success");
表示认证过程中提示信息的对象。 } catch (error) {
console.log("authV9 error = " + error);
**系统能力**：SystemCapability.UserIAM.UserAuth.Core // do error
}
| 名称 | 参数类型 | 必填 | 说明 | ```
| ------------ | ---------- | ---- | -------------------- |
| module | number | 否 | 认证模块。 |
| tip | number | 否 | 认证过程提示信息。 |
## AuthEventKey<sup>9+</sup>
类型别名，表示认证事件的关键字，取值为表格内字符串。
| 取值 | 说明 |
| ---------- | ----------------------- |
| "result" | 取值为result时，事件回调返回认证的结果信息。 |
| "tip" | 取值为tip时，事件回调返回认证操作中的提示信息。 |
## AuthInstance<sup>9+</sup> ## AuthInstance<sup>9+</sup>
...@@ -281,9 +128,12 @@ callback: (result : EventInfo) => void ...@@ -281,9 +128,12 @@ callback: (result : EventInfo) => void
### on<sup>9+</sup> ### on<sup>9+</sup>
on(name : AuthEventKey, callback : AuthEvent) : void on : (name : AuthEventKey, callback : AuthEvent) => void
订阅指定类型的用户认证事件。
表示开启对认证事件的监听。 > **说明：**
> 使用获取到的[AuthInstance](#authinstance9)对象调用该接口进行订阅。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core **系统能力**：SystemCapability.UserIAM.UserAuth.Core
...@@ -291,151 +141,205 @@ on(name : AuthEventKey, callback : AuthEvent) : void ...@@ -291,151 +141,205 @@ on(name : AuthEventKey, callback : AuthEvent) : void
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| --------- | -------------------------- | ---- | ------------------------- | | --------- | -------------------------- | ---- | ------------------------- |
| name | AuthEventKey | 是 | 认证事件的关键字 | | name | [AuthEventKey](#autheventkey9) | 是 | 表示认证事件类型，取值为"result"时，回调函数返回认证结果；取值为"tip"时，回调函数返回认证过程中的提示信息。 |
| callback | AuthEvent | 是 | 认证事件的回调函数 | | callback | [AuthEvent](#authevent9) | 是 | 认证接口的回调函数，用于返回认证结果或认证过程中的提示信息。 |
以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errcode-useriam.md)
**错误码：**
| 错误码ID | 错误信息 |
| -------- | ------- |
| 401 | Incorrect parameters. |
| 12500002 | General operation error. |
**示例：** **示例：**
```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", { // 订阅认证结果
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 need tip // 订阅认证过程中的提示信息
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
表示关闭对认证事件的监听。 取消订阅特定类型的认证事件。
> **说明：**
> 需要使用已经成功订阅事件的[AuthInstance](#authinstance9)对象调用该接口进行取消订阅。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core **系统能力**：SystemCapability.UserIAM.UserAuth.Core
| 参数名 | 类型 | 必填 | 说明 | | 名称 | 类型 | 必填 | 说明 |
| --------- | -------------------------- | ---- | ------------------------- | | --------- | -------------------------- | ---- | ------------------------- |
| name | AuthEventKey | 是 | 认证事件的关键字 | | name | [AuthEventKey](#autheventkey9) | 是 | 表示认证事件类型，取值为"result"时，取消订阅认证结果；取值为"tip"时，取消订阅认证过程中的提示信息。 |
以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errcode-useriam.md)
**错误码：**
| 错误码ID | 错误信息 |
| -------- | ------- |
| 401 | Incorrect parameters. |
| 12500002 | General operation error. |
**示例：** **示例：**
```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); // 订阅认证结果
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 }
} // 取消订阅认证结果
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
开始认证。
表示开始认证。 > **说明：**
> 使用获取到的[AuthInstance](#authinstance9)对象调用该接口进行认证。
**需要权限**：ohos.permission.ACCESS_BIOMETRIC **需要权限**：ohos.permission.ACCESS_BIOMETRIC
**系统能力**：SystemCapability.UserIAM.UserAuth.Core **系统能力**：SystemCapability.UserIAM.UserAuth.Core
以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errcode-useriam.md)
**错误码：**
| 错误码ID | 错误信息 |
| -------- | ------- |
| 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. |
**示例：** **示例：**
```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
表示取消认证。 取消认证。
> **说明：**
> 使用获取到的[AuthInstance](#authinstance9)对象调用该接口进行取消认证，此[AuthInstance](#authinstance9)需要是正在进行认证的对象。
**需要权限**：ohos.permission.ACCESS_BIOMETRIC **需要权限**：ohos.permission.ACCESS_BIOMETRIC
**系统能力**：SystemCapability.UserIAM.UserAuth.Core **系统能力**：SystemCapability.UserIAM.UserAuth.Core
以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errcode-useriam.md)
**错误码：**
| 错误码ID | 错误信息 |
| -------- | ------- |
| 201 | Permission verification failed. |
| 401 | Incorrect parameters. |
| 12500002 | General operation error. |
**示例：** **示例：**
```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 +348,7 @@ getAuthInstance(challenge : Uint8Array, authType : UserAuthType, authTrustLevel ...@@ -444,7 +348,7 @@ getAuthInstance(challenge : Uint8Array, authType : UserAuthType, authTrustLevel
获取AuthInstance对象，用于执行用户身份认证。 获取AuthInstance对象，用于执行用户身份认证。
> **说明：** > **说明：**
> 每个AuthInstance只能用于发起一次认证，若需要再次发起认证需重新获取AuthInstance。 > 每个AuthInstance只能进行一次认证，若需要再次进行认证则需重新获取AuthInstance。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core **系统能力**：SystemCapability.UserIAM.UserAuth.Core
...@@ -462,21 +366,33 @@ getAuthInstance(challenge : Uint8Array, authType : UserAuthType, authTrustLevel ...@@ -462,21 +366,33 @@ getAuthInstance(challenge : Uint8Array, authType : UserAuthType, authTrustLevel
| ----------------------------------------- | ------------ | | ----------------------------------------- | ------------ |
| [AuthInstance](#authinstance9) | 认证器对象。 | | [AuthInstance](#authinstance9) | 认证器对象。 |
以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errcode-useriam.md)
**错误码：**
| 错误码ID | 错误信息 |
| -------- | ------- |
| 401 | Incorrect parameters. |
| 12500002 | General operation error. |
| 12500005 | The authentication type is not supported. |
| 12500006 | The authentication trust level is not supported. |
**示例：** **示例：**
```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>
...@@ -492,26 +408,35 @@ getVersion(): number ...@@ -492,26 +408,35 @@ getVersion(): number
| 类型 | 说明 | | 类型 | 说明 |
| ------ | ---------------------- | | ------ | ---------------------- |
| number | 获取的认证器版本信息。 | | number | 认证器版本信息。 |
以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errcode-useriam.md)
**错误码：**
| 错误码ID | 错误信息 |
| -------- | ------- |
| 201 | Permission verification failed. |
| 12500002 | General operation error. |
**示例：** **示例：**
```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
表示检查指定的认证等级的认证能力是否可用。 查询指定类型和等级的认证能力是否支持。
**需要权限**：ohos.permission.ACCESS_BIOMETRIC **需要权限**：ohos.permission.ACCESS_BIOMETRIC
...@@ -522,28 +447,41 @@ getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel): vo ...@@ -522,28 +447,41 @@ getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel): vo
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| -------------- | ---------------------------------- | ---- | -------------------------- | | -------------- | ---------------------------------- | ---- | -------------------------- |
| authType | [UserAuthType](#userauthtype8) | 是 | 认证类型，当前只支持FACE。 | | authType | [UserAuthType](#userauthtype8) | 是 | 认证类型，当前只支持FACE。 |
| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | 是 | 认证结果的信任等级。 | | authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | 是 | 认证信任等级。 |
以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errcode-useriam.md)
**错误码：**
| 错误码ID | 错误信息 |
| -------- | ------- |
| 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. |
**示例：** **示例：**
```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> ## ResultCodeV9<sup>9+</sup>
表示执行结果的枚举。 表示返回码的枚举。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core **系统能力**：SystemCapability.UserIAM.UserAuth.Core
| 名称 | 默认值 | 描述 | | 名称 | 值 | 说明 |
| ----------------------- | ------ | -------------------- | | ----------------------- | ------ | -------------------- |
| SUCCESS | 12500000 | 执行成功。 | | SUCCESS | 12500000 | 执行成功。 |
| FAIL | 12500001 | 执行失败。 | | FAIL | 12500001 | 执行失败。 |
...@@ -553,50 +491,49 @@ getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel): vo ...@@ -553,50 +491,49 @@ getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel): vo
| TYPE_NOT_SUPPORT | 12500005 | 不支持的认证类型。 | | TYPE_NOT_SUPPORT | 12500005 | 不支持的认证类型。 |
| TRUST_LEVEL_NOT_SUPPORT | 12500006 | 不支持的认证等级。 | | TRUST_LEVEL_NOT_SUPPORT | 12500006 | 不支持的认证等级。 |
| BUSY | 12500007 | 忙碌状态。 | | BUSY | 12500007 | 忙碌状态。 |
| INVALID_PARAMETERS | 12500008 | 无效参数。 |
| LOCKED | 12500009 | 认证器已锁定。 | | LOCKED | 12500009 | 认证器已锁定。 |
| NOT_ENROLLED | 12500010 | 用户未录入认证信息。 | | NOT_ENROLLED | 12500010 | 用户未录入认证信息。 |
## UserAuth<sup>8+</sup> ## UserAuth<sup>8+</sup>
认证器的对象。 认证器对象。
### constructor<sup>(deprecated)</sup> ### constructor<sup>(deprecated)</sup>
constructor() constructor()
创建认证器对象。
> **说明：** > **说明：**
> 从 API version 9 开始废弃，请使用[getAuthInstance](#useriam_userauthgetauthinstance9)替代。 > 从 API version 9 开始废弃，请使用[getAuthInstance](#useriam_userauthgetauthinstance9)替代。
<br/>从 API version 8 开始支持。 <br/>从 API version 8 开始支持。
表示获取的认证器对象。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core **系统能力**：SystemCapability.UserIAM.UserAuth.Core
**返回值：** **返回值：**
| 类型 | 说明 | | 类型 | 说明 |
| ---------------------- | -------------------- | | ---------------------- | -------------------- |
| [UserAuth](#userauth8) | UserAuth认证器对象。 | | [UserAuth](#userauth8) | 认证器对象。 |
**示例：** **示例：**
```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
获取认证器的版本信息。
> **说明：** > **说明：**
> 从 API version 9 开始废弃，请使用[getVersion](#useriam_userauthgetversion9)替代。 > 从 API version 9 开始废弃，请使用[getVersion](#useriam_userauthgetversion9)替代。
<br/>从 API version 8 开始支持。 <br/>从 API version 8 开始支持。
表示获取的认证器版本信息。
**需要权限**：ohos.permission.ACCESS_BIOMETRIC **需要权限**：ohos.permission.ACCESS_BIOMETRIC
**系统能力**：SystemCapability.UserIAM.UserAuth.Core **系统能力**：SystemCapability.UserIAM.UserAuth.Core
...@@ -605,28 +542,28 @@ getVersion() : number ...@@ -605,28 +542,28 @@ getVersion() : number
| 类型 | 说明 | | 类型 | 说明 |
| ------ | ---------------------- | | ------ | ---------------------- |
| number | 获取的认证器版本信息。 | | number | 认证器版本信息。 |
**示例：** **示例：**
```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
查询指定类型和等级的认证能力是否支持。
> **说明：** > **说明：**
> 从 API version 9 开始废弃，请使用开始废弃，请使用[getAvailableStatus](#useriam_userauthgetavailablestatus9)替代。 > 从 API version 9 开始废弃，请使用[getAvailableStatus](#useriam_userauthgetavailablestatus9)替代。
<br/>从 API version 8 开始支持。 <br/>从 API version 8 开始支持。
表示检查指定的认证等级的认证能力是否可用。
**需要权限**：ohos.permission.ACCESS_BIOMETRIC **需要权限**：ohos.permission.ACCESS_BIOMETRIC
**系统能力**：SystemCapability.UserIAM.UserAuth.Core **系统能力**：SystemCapability.UserIAM.UserAuth.Core
...@@ -636,40 +573,38 @@ getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel) : n ...@@ -636,40 +573,38 @@ getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel) : n
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| -------------- | ---------------------------------- | ---- | -------------------------- | | -------------- | ---------------------------------- | ---- | -------------------------- |
| authType | [UserAuthType](#userauthtype8) | 是 | 认证类型，当前只支持FACE。 | | authType | [UserAuthType](#userauthtype8) | 是 | 认证类型，当前只支持FACE。 |
| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | 是 | 认证结果的信任等级。 | | authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | 是 | 认证信任等级。 |
**返回值：** **返回值：**
| 类型 | 说明 | | 类型 | 说明 |
| ------ | ------------------------------------------------------------ | | ------ | ------------------------------------------------------------ |
| number | 获取指定的认证等级的认证能力是否可用的检查结果，返回值参见[ResultCode](#resultcodedeprecated)。 | | number | 查询结果，结果为SUCCESS时表示支持，其他返回值参见[ResultCode](#resultcodedeprecated)。 |
**示例：** **示例：**
```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");
// 此处添加支持指定类型认证的逻辑 } else {
} else { console.error("check auth support fail, code = " + checkCode);
console.error("check auth support fail, code = " + checkCode); }
// 此处添加不支持指定类型认证的逻辑 ```
}
```
### 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
执行用户认证，使用回调函数返回结果。
> **说明：** > **说明：**
> 从 API version 9 开始废弃，建议使用[start](#start9)代替。 > 从 API version 9 开始废弃，建议使用[start](#start9)代替。
<br/>从 API version 8 开始支持。 <br/>从 API version 8 开始支持。
表示执行用户认证，使用callback方式作为异步方法。
**需要权限**：ohos.permission.ACCESS_BIOMETRIC **需要权限**：ohos.permission.ACCESS_BIOMETRIC
**系统能力**：SystemCapability.UserIAM.UserAuth.Core **系统能力**：SystemCapability.UserIAM.UserAuth.Core
...@@ -680,8 +615,8 @@ auth(challenge: Uint8Array, authType: UserAuthType, authTrustLevel: AuthTrustLev ...@@ -680,8 +615,8 @@ auth(challenge: Uint8Array, authType: UserAuthType, authTrustLevel: AuthTrustLev
| -------------- | ---------------------------------------- | ---- | ------------------------ | | -------------- | ---------------------------------------- | ---- | ------------------------ |
| challenge | Uint8Array | 是 | 挑战值，可以填null。 | | challenge | Uint8Array | 是 | 挑战值，可以填null。 |
| authType | [UserAuthType](#userauthtype8) | 是 | 认证类型，当前支持FACE。 | | authType | [UserAuthType](#userauthtype8) | 是 | 认证类型，当前支持FACE。 |
| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | 是 | 信任等级。 | | authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | 是 | 认证信任等级。 |
| callback | [IUserAuthCallback](#iuserauthcallbackdeprecated) | 是 | 回调函数。 | | callback | [IUserAuthCallback](#iuserauthcallbackdeprecated) | 是 | 回调函数。 |
**返回值：** **返回值：**
...@@ -691,37 +626,37 @@ auth(challenge: Uint8Array, authType: UserAuthType, authTrustLevel: AuthTrustLev ...@@ -691,37 +626,37 @@ auth(challenge: Uint8Array, authType: UserAuthType, authTrustLevel: AuthTrustLev
**示例：** **示例：**
```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) {
// 此处添加认证成功逻辑 // 此处添加认证成功逻辑
} else { } else {
// 此处添加认证失败逻辑 // 此处添加认证失败逻辑
} }
} 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
表示通过contextID取消本次认证操作。
> **说明：** > **说明：**
> 从 API version 9 开始废弃，建议使用[cancel](#cancel9)代替。 > 从 API version 9 开始废弃，建议使用[cancel](#cancel9)代替。
<br/>从 API version 8 开始支持。 <br/>从 API version 8 开始支持。
表示通过contextID取消本次认证操作。
**需要权限**：ohos.permission.ACCESS_BIOMETRIC **需要权限**：ohos.permission.ACCESS_BIOMETRIC
**系统能力**：SystemCapability.UserIAM.UserAuth.Core **系统能力**：SystemCapability.UserIAM.UserAuth.Core
...@@ -730,170 +665,145 @@ cancelAuth(contextID : Uint8Array) : number ...@@ -730,170 +665,145 @@ cancelAuth(contextID : Uint8Array) : number
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| --------- | ---------- | ---- | ------------------------------------------ | | --------- | ---------- | ---- | ------------------------------------------ |
| contextID | Uint8Array | 是 | 上下文ID信息，通过[auth](#authdeprecated)接口获得。 | | contextID | Uint8Array | 是 | 上下文的标识，通过[auth](#authdeprecated)接口获取。 |
**返回值：** **返回值：**
| 类型 | 说明 | | 类型 | 说明 |
| ------ | ------------------------ | | ------ | ------------------------ |
| number | 取消本次认证操作的结果。 | | number | 取消认证的结果，结果为SUCCESS时表示取消成功，其他返回值参见[ResultCode](#resultcodedeprecated)。 |
**示例：** **示例：**
```js ```js
import userIAM_userAuth from '@ohos.userIAM.userAuth'; import userIAM_userAuth from '@ohos.userIAM.userAuth';
// contextId可通过auth接口获取，此处直接定义 // contextId可通过auth接口获取，此处直接定义
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>
返回认证结果的回调对象。
> **说明：** > **说明：**
> 从 API version 9 开始废弃，建议使用[AuthEvent](#authevent9)代替。 > 从 API version 9 开始废弃，建议使用[AuthEvent](#authevent9)代替。
<br/>从 API version 8 开始支持。 <br/>从 API version 8 开始支持。
认证过程中回调结果的对象。
### onResult<sup>(deprecated)</sup> ### onResult<sup>(deprecated)</sup>
onResult: (result : number, extraInfo : AuthResult) => void onResult: (result : number, extraInfo : AuthResult) => void
回调函数，返回认证结果。
> **说明：** > **说明：**
> 从 API version 9 开始废弃，建议使用[callback](#callback9)代替。 > 从 API version 9 开始废弃，建议使用[callback](#callback9)代替。
<br/>从 API version 8 开始支持。 <br/>从 API version 8 开始支持。
表示在认证操作中，获取认证结果。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core **系统能力**：SystemCapability.UserIAM.UserAuth.Core
**参数：** **参数：**
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| --------- | -------------------------- | ---- | ------------------------------------------------------------ | | --------- | -------------------------- | ---- | ------------------------------------------------ |
| result | number | 是 | 认证结果，参见[ResultCode](#resultcodedeprecated)。 | | result | number | 是 | 认证结果，参见[ResultCode](#resultcodedeprecated)。 |
| extraInfo | [AuthResult](#authresultdeprecated) | 是 | 扩展信息，不同情况下的具体信息，<br/>如果身份验证通过，则在extrainfo中返回用户认证令牌，<br/>如果身份验证失败，则在extrainfo中返回剩余的用户认证次数，<br/>如果身份验证执行器被锁定，则在extrainfo中返回冻结时间。 | | extraInfo | [AuthResult](#authresultdeprecated) | 是 | 扩展信息，不同情况下的具体信息，<br/>如果身份验证通过，则在extraInfo中返回用户认证令牌，<br/>如果身份验证失败，则在extraInfo中返回剩余的用户认证次数，<br/>如果身份验证执行器被锁定，则在extraInfo中返回冻结时间。 |
**示例：** **示例：**
```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) {
// 此处添加认证成功逻辑 // 此处添加认证成功逻辑
} else { } else {
// 此处添加认证失败逻辑 // 此处添加认证失败逻辑
} }
} 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
回调函数，返回认证过程中的提示信息，非必须实现。
> **说明：** > **说明：**
> 从 API version 9 开始废弃，建议使用[callback](#callback9)代替。 > 从 API version 9 开始废弃，建议使用[callback](#callback9)代替。
<br/>从 API version 8 开始支持。 <br/>从 API version 8 开始支持。
表示在认证过程中，获取提示码信息，非必须实现。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core **系统能力**：SystemCapability.UserIAM.UserAuth.Core
**参数：** **参数：**
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| --------- | ------ | ---- | ------------------------------ | | --------- | ------ | ---- | ------------------------------ |
| module | number | 是 | 认证执行器的类型。 | | module | number | 是 | 发送提示信息的模块标识。 |
| acquire | number | 是 | 认证执行器认证过程的交互信息。 | | acquire | number | 是 | 认证执过程中的提示信息。 |
| extraInfo | any | 是 | 预留字段。 | | extraInfo | any | 是 | 预留字段。 |
**示例：** **示例：**
```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) => { onAcquireInfo: (module, acquire, extraInfo) => {
try { try {
console.info("auth onResult result = " + result); console.info("auth onAcquireInfo module = " + module);
console.info("auth onResult extraInfo = " + JSON.stringify(extraInfo)); console.info("auth onAcquireInfo acquire = " + acquire);
if (result == userIAM_userAuth.ResultCode.SUCCESS) { console.info("auth onAcquireInfo extraInfo = " + JSON.stringify(extraInfo));
// 此处添加认证成功逻辑 } catch (e) {
} else { console.info("auth onAcquireInfo error = " + e);
// 此处添加认证失败逻辑 }
} }
} 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> ## AuthResult<sup>(deprecated)</sup>
表示认证结果的对象。
> **说明：** > **说明：**
> 从 API version 9 开始废弃，建议使用[AuthResultInfo](#authresultinfo9)代替。 > 从 API version 9 开始废弃，建议使用[AuthResultInfo](#authresultinfo9)代替。
<br/>从 API version 8 开始支持。 <br/>从 API version 8 开始支持。
表示认证结果的对象。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core **系统能力**：SystemCapability.UserIAM.UserAuth.Core
| 名称 | 参数类型 | 必填 | 说明 | | 名称 | 类型 | 必填 | 说明 |
| ------------ | ---------- | ---- | -------------------- | | ------------ | ---------- | ---- | -------------------|
| token | Uint8Array | 否 | 身份认证令牌。 | | token | Uint8Array | 否 | 认证通过的令牌信息。 |
| remainTimes | number | 否 | 剩余的认证操作次数。 | | remainTimes | number | 否 | 剩余的认证操作次数。 |
| freezingTime | number | 否 | 认证操作的冻结时间。 | | freezingTime | number | 否 | 认证操作的冻结时间。 |
## ResultCode<sup>(deprecated)</sup> ## ResultCode<sup>(deprecated)</sup>
表示返回码的枚举。
> **说明：** > **说明：**
> 从 API version 9 开始废弃，建议使用[ResultCodeV9](#resultcodev99)代替。 > 从 API version 9 开始废弃，建议使用[ResultCodeV9](#resultcodev99)代替。
表示执行结果的枚举。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core **系统能力**：SystemCapability.UserIAM.UserAuth.Core
| 名称 | 默认值 | 描述 | | 名称 | 值 | 说明 |
| ----------------------- | ------ | -------------------- | | ----------------------- | ------ | -------------------- |
| SUCCESS | 0 | 执行成功。 | | SUCCESS | 0 | 执行成功。 |
| FAIL | 1 | 执行失败。 | | FAIL | 1 | 执行失败。 |
...@@ -906,14 +816,13 @@ onAcquireInfo ?: (module : number, acquire : number, extraInfo : any) => void ...@@ -906,14 +816,13 @@ onAcquireInfo ?: (module : number, acquire : number, extraInfo : any) => void
| LOCKED | 9 | 认证器已锁定。 | | LOCKED | 9 | 认证器已锁定。 |
| NOT_ENROLLED | 10 | 用户未录入认证信息。 | | NOT_ENROLLED | 10 | 用户未录入认证信息。 |
## FaceTips<sup>8+</sup> ## FaceTips<sup>8+</sup>
表示人脸认证过程中提示码的枚举。 表示人脸认证过程中提示码的枚举。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core **系统能力**：SystemCapability.UserIAM.UserAuth.Core
| 名称 | 默认值 | 描述 | | 名称 | 值 | 说明 |
| ----------------------------- | ------ | ------------------------------------ | | ----------------------------- | ------ | ------------------------------------ |
| FACE_AUTH_TIP_TOO_BRIGHT | 1 | 光线太强，获取的图像太亮。 | | FACE_AUTH_TIP_TOO_BRIGHT | 1 | 光线太强，获取的图像太亮。 |
| FACE_AUTH_TIP_TOO_DARK | 2 | 光线太暗，获取的图像太暗。 | | FACE_AUTH_TIP_TOO_DARK | 2 | 光线太暗，获取的图像太暗。 |
...@@ -934,7 +843,7 @@ onAcquireInfo ?: (module : number, acquire : number, extraInfo : any) => void ...@@ -934,7 +843,7 @@ onAcquireInfo ?: (module : number, acquire : number, extraInfo : any) => void
**系统能力**：SystemCapability.UserIAM.UserAuth.Core **系统能力**：SystemCapability.UserIAM.UserAuth.Core
| 名称 | 默认值 | 描述 | | 名称 | 值 | 说明 |
| --------------------------------- | ------ | -------------------------------------------------- | | --------------------------------- | ------ | -------------------------------------------------- |
| FINGERPRINT_AUTH_TIP_GOOD | 0 | 获取的指纹图像良好。 | | FINGERPRINT_AUTH_TIP_GOOD | 0 | 获取的指纹图像良好。 |
| FINGERPRINT_AUTH_TIP_DIRTY | 1 | 由于传感器上可疑或检测到的污垢，指纹图像噪音过大。 | | FINGERPRINT_AUTH_TIP_DIRTY | 1 | 由于传感器上可疑或检测到的污垢，指纹图像噪音过大。 |
...@@ -950,7 +859,7 @@ onAcquireInfo ?: (module : number, acquire : number, extraInfo : any) => void ...@@ -950,7 +859,7 @@ onAcquireInfo ?: (module : number, acquire : number, extraInfo : any) => void
**系统能力**：SystemCapability.UserIAM.UserAuth.Core **系统能力**：SystemCapability.UserIAM.UserAuth.Core
| 名称 | 默认值 | 描述 | | 名称 | 值 | 说明 |
| ----------- | ------ | ---------- | | ----------- | ------ | ---------- |
| FACE | 2 | 人脸认证。 | | FACE | 2 | 人脸认证。 |
| FINGERPRINT | 4 | 指纹认证。 | | FINGERPRINT | 4 | 指纹认证。 |
...@@ -961,7 +870,7 @@ onAcquireInfo ?: (module : number, acquire : number, extraInfo : any) => void ...@@ -961,7 +870,7 @@ onAcquireInfo ?: (module : number, acquire : number, extraInfo : any) => void
**系统能力**：SystemCapability.UserIAM.UserAuth.Core **系统能力**：SystemCapability.UserIAM.UserAuth.Core
| 名称 | 默认值 | 描述 | | 名称 | 值 | 说明 |
| ---- | ------ | ------------------------- | | ---- | ------ | ------------------------- |
| ATL1 | 10000 | 认证结果的信任等级级别1。 | | ATL1 | 10000 | 认证结果的信任等级级别1。 |
| ATL2 | 20000 | 认证结果的信任等级级别2。 | | ATL2 | 20000 | 认证结果的信任等级级别2。 |
...@@ -972,11 +881,11 @@ onAcquireInfo ?: (module : number, acquire : number, extraInfo : any) => void ...@@ -972,11 +881,11 @@ onAcquireInfo ?: (module : number, acquire : number, extraInfo : any) => void
getAuthenticator(): Authenticator getAuthenticator(): Authenticator
获取Authenticator对象，用于执行用户身份认证。
> **说明：** > **说明：**
> 从 API version 8 开始废弃，建议使用[constructor](#constructordeprecated)替代。 > 从 API version 8 开始废弃，建议使用[constructor](#constructordeprecated)替代。
获取Authenticator对象，用于执行用户身份认证。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core **系统能力**：SystemCapability.UserIAM.UserAuth.Core
**返回值：** **返回值：**
...@@ -992,61 +901,61 @@ getAuthenticator(): Authenticator ...@@ -992,61 +901,61 @@ getAuthenticator(): Authenticator
## Authenticator<sup>(deprecated)</sup> ## Authenticator<sup>(deprecated)</sup>
> **说明：**
> 从 API version 8 开始废弃，建议使用[UserAuth](#userauth8)替代。
认证器对象。 认证器对象。
> **说明：**
> 从 API version 8 开始废弃，建议使用[UserAuth](#userauth8)替代。
### 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
执行用户认证，使用callback方式作为异步方法。
> **说明：** > **说明：**
> 从 API version 8 开始废弃，建议使用[auth](#authdeprecated)替代。 > 从 API version 8 开始废弃，建议使用[auth](#authdeprecated)替代。
执行用户认证，使用callback方式作为异步方法。
**需要权限**：ohos.permission.ACCESS_BIOMETRIC **需要权限**：ohos.permission.ACCESS_BIOMETRIC
**系统能力**：SystemCapability.UserIAM.UserAuth.Core **系统能力**：SystemCapability.UserIAM.UserAuth.Core
**参数：** **参数：**
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| -------- | --------------------------- | ---- | ------------------------------------------------------------ | | -------- | --------------------------- | ---- | -------------------------- |
| type | AuthType | 是 | 认证类型，当前只支持"FACE_ONLY"。<br/>ALL为预留参数，当前版本暂不支持ALL类型的认证。 | | type | AuthType | 是 | 认证类型，当前只支持"FACE_ONLY"。<br/>ALL为预留参数，当前版本暂不支持ALL类型的认证。 |
| level | SecureLevel | 是 | 安全级别，对应认证的安全级别，有效值为"S1"（最低）、"S2"、"S3"、"S4"（最高）。<br/>具备3D人脸识别能力的设备支持"S3"及以下安全级别的认证。<br/>具备2D人脸识别能力的设备支持"S2"及以下安全级别的认证。 | | level | SecureLevel | 是 | 安全级别，对应认证的安全级别，有效值为"S1"（最低）、"S2"、"S3"、"S4"（最高）。<br/>具备3D人脸识别能力的设备支持"S3"及以下安全级别的认证。<br/>具备2D人脸识别能力的设备支持"S2"及以下安全级别的认证。 |
| callback | AsyncCallback&lt;number&gt; | 否 | 回调函数。 | | callback | AsyncCallback&lt;number&gt; | 是 | 回调函数。 |
callback返回值： callback返回值：
| 类型 | 说明 | | 类型 | 说明 |
| ------ | ------------------------------------------------------------ | | ------ | ------------------------------------------------------------ |
| number | 表示认证结果，参见[AuthenticationResult](#authenticationresultdeprecated)。 | | number | 表示认证结果，参见[AuthenticationResult](#authenticationresultdeprecated)。 |
**示例：** **示例：**
```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;
执行用户认证，使用promise方式作为异步方法。
> **说明：** > **说明：**
> 从 API version 8 开始废弃，建议使用[auth](#authdeprecated)替代。 > 从 API version 8 开始废弃，建议使用[auth](#authdeprecated)替代。
执行用户认证，使用promise方式作为异步方法。
**需要权限**：ohos.permission.ACCESS_BIOMETRIC **需要权限**：ohos.permission.ACCESS_BIOMETRIC
**系统能力**：SystemCapability.UserIAM.UserAuth.Core **系统能力**：SystemCapability.UserIAM.UserAuth.Core
...@@ -1066,25 +975,25 @@ execute(type:AuthType, level:SecureLevel): Promise&lt;number&gt; ...@@ -1066,25 +975,25 @@ execute(type:AuthType, level:SecureLevel): Promise&lt;number&gt;
**示例：** **示例：**
```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>
表示认证结果的枚举。
> **说明：** > **说明：**
> 从 API version 8 开始废弃，建议使用[ResultCode](#resultcodedeprecated)替代。 > 从 API version 8 开始废弃，建议使用[ResultCode](#resultcodedeprecated)替代。
表示认证结果的枚举。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core **系统能力**：SystemCapability.UserIAM.UserAuth.Core
| 名称 | 默认值 | 描述 | | 名称 | 值 | 说明 |
| ------------------ | ------ | -------------------------- | | ------------------ | ------ | -------------------------- |
| NO_SUPPORT | -1 | 设备不支持当前的认证方式。 | | NO_SUPPORT | -1 | 设备不支持当前的认证方式。 |
| SUCCESS | 0 | 认证成功。 | | SUCCESS | 0 | 认证成功。 |
......
zh-cn/application-dev/reference/errorcodes/errcode-useriam.md 0 → 100644
浏览文件 @ 5bbfd682
# 用户认证错误码
## 201 权限验证失败
具体参见[通用错误码](./errorcode-universal.md)
## 202 调用方不是一个系统应用
具体参见[通用错误码](./errorcode-universal.md)
## 401 参数不正确
具体参见[通用错误码](./errorcode-universal.md)
## 12500002 一般的操作错误
**错误信息**
General operation error.
**可能原因**
1. NAPI层解析参数出错。
2. 用户认证服务的进程没有启动。
3. IPC通信的proxy客户端写数据出错。
4. IPC通信的stub服务端解析数据出错。
5. 获取driver服务出错。
**处理步骤**
重启设备，重新调用接口。
## 12500005 认证类型不支持
**错误信息**
The authentication type is not supported.
**可能原因**
1. 传入的认证类型参数不支持，例如调用userAuth模块的getAvailableStatus接口时传入的参数不是FACE或FINGERPRINT类型，则会返回12500005错误码。
2. 传入的认证类型参数在本设备上不支持，例如在没有部署指纹传感器的设备上发起指纹认证，则会返回12500005错误码。
**处理步骤**
请检查传入的认证类型参数，重新调用接口。
## 12500006 认证信任等级不支持
**错误信息**
The authentication trust level is not supported.
**可能原因**
1. 调用userAuth模块的getAvailableStatus或getAuthInstance接口时，传入的authTrustLevel参数不在[ATL1, ATL2, ATL3, ATL4]范围内。
2. 当前的设备不支持该认证信任等级，例如在只部署了2D摄像头的设备上发起支付级别的人脸认证，则会返回12500006错误码。
**处理步骤**
检查传入的authTrustLevel是否在合理范围，如果在合理范围，则是当前的设备不支持该认证信任等级。
## 12500010 该类型的凭据没有录入
**错误信息**
The type of credential has not been enrolled.
**可能原因**
例如调用userAuth模块的getAvailableStatus接口，传入的authType参数为FACE，但是当前的设备没有录入人脸凭据，则会返回12500010错误码。
调用start接口发起人脸认证，但是目前的设备没有录入人脸凭据，则会返回12500010错误码。
**处理步骤**
检查是否录入该类型的凭据，如果没有录入，则需要成功录入该类型凭据后再调用相关接口。
## 12700001 人脸录入过程中的操作失败
**错误信息**
The operation is failed.
**可能原因**
1. 例如调用faceAuth模块的setSurfaceId接口时，人脸认证服务未启动，则会返回12700001错误码。
2. IPC通信的proxy客户端写数据出错。
3. IPC通信的stub服务端解析数据出错。
4. 人脸driver层调用出错。
**处理步骤**
主要检查人脸认证服务的进程是否启动。
zh-cn/application-dev/security/userauth-guidelines.md
浏览文件 @ 5bbfd682
# 用户认证开发指导 # 用户认证开发指导
> **说明：** > **说明：**
> 该开发指导需匹配API Version 8或以上版本的SDK使用。 > 该开发指导需配合API version 9版本的SDK使用。
## 场景介绍 ## 场景介绍
当前用户认证支持2D人脸识别、3D人脸识别，可应用于设备解锁、应用登录、支付等身份认证场景。 当前用户认证支持人脸识别和指纹识别，可应用于设备解锁、应用登录、支付等身份认证场景。
## 接口说明 ## 接口说明
userIAM_userAuth模块提供了用户认证的相关方法，包括检测认证能力、认证和取消认证等，用户可以使用人脸等生物特征信息进行认证操作。具体接口说明可以查阅[API参考](../reference/apis/js-apis-useriam-userauth.md)。 userIAM_userAuth模块提供了用户认证的相关方法，包括查询认证能力、发起认证和取消认证等，用户可以使用人脸、指纹等生物特征信息进行认证操作。具体接口说明可以查阅[API参考文档](../reference/apis/js-apis-useriam-userauth.md)。
在执行认证前，需要检查设备是否支持该认证能力，具体指认证类型、认证等级。如果不支持，需要考虑使用其他认证能力。 在执行认证前，需要指定[认证类型](../reference/apis/js-apis-useriam-userauth.md#userauthtype8)和[认证等级](../reference/apis/js-apis-useriam-userauth.md#authtrustlevel8)，查询设备是否支持该认证能力。
**表1** 用户认证开放能力列表 **表1** 用户认证开放能力列表
| 接口名 | 功能描述 | | 接口名称 | 功能描述 |
| ------------------------------------------------------------ | ------------------------------------------------------------ | | ---------- | ----------------------- |
| getVersion() : number | 获取认证对象的版本信息。 | | getVersion() : number | 获取认证对象的版本信息。 |
| getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel) : number | 根据指定的认证类型、认证等级，检测当前设备是否支持相应的认证能力。 | | getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel): void | 根据指定的认证类型、认证等级，检测当前设备是否支持相应的认证能力。 |
| auth(challenge: Uint8Array, authType: UserAuthType, authTrustLevel: AuthTrustLevel, callback: IUserAuthCallback): Uint8Array | 执行用户认证，使用callback方式作为异步方法。 | | getAuthInstance(challenge : Uint8Array, authType : UserAuthType, authTrustLevel : AuthTrustLevel): AuthInstance | 获取AuthInstance对象，用于执行用户身份认证。 |
| cancelAuth(contextID : Uint8Array) : number | 通过contextID取消本次认证操作。 | | on(name : AuthEventKey, callback : AuthEvent) : void | 订阅指定类型的用户认证事件。 |
| off(name : AuthEventKey) : void | 取消订阅特定类型的认证事件。 |
## 开发步骤 | start: void | 执行用户认证。 |
| cancel: void | 取消本次认证操作。 |
开发前请完成以下准备工作：
## 获取认证对象的版本信息
1. 在应用配置权限文件中，增加ohos.permission.ACCESS_BIOMETRIC的权限声明。
2. 在使用用户认证能力的代码文件中增加import userIAM_userAuth from '@ohos.userIAM.userAuth'。 ### 开发步骤
开发过程： 1. 申请权限。调用[getVersion](../reference/apis/js-apis-useriam-userauth.md#useriam_userauthgetversion9)接口，需要在module.json5文件的requestPermissions对象中配置ohos.permission.ACCESS_BIOMETRIC权限。更多配置信息[应用包结构配置文件的说明](../quick-start/stage-structure.md)。
1. 获取Authenticator的单例对象，代码示例如下： 2. 调用[getVersion](../reference/apis/js-apis-useriam-userauth.md#useriam_userauthgetversion9)接口获取版本信息。
```js ```js
let auth = new userIAM_userAuth.UserAuth(); import userIAM_userAuth from '@ohos.userIAM.userAuth';
```
// 获取版本信息
2. （可选）获取认证对象的版本信息，代码示例如下： try {
let version = userIAM_userAuth.getVersion();
```js console.info("auth version = " + version);
let auth = new userIAM_userAuth.UserAuth(); } catch (error) {
let version = auth.getVersion(); console.info("get version failed, error = " + error);
console.info("auth version = " + version); }
``` ```
3. 根据指定的认证类型、认证等级，检测当前设备是否支持相应的认证能力，代码示例如下： ## 查询当前设备是否支持相应的认证能力
```js ### 开发步骤
let auth = new userIAM_userAuth.UserAuth();
let checkCode = auth.getAvailableStatus(userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1); 1. 申请权限。调用[getAvailableStatus](../reference/apis/js-apis-useriam-userauth.md#useriam_userauthgetavailablestatus9)接口，需要在module.json5文件的requestPermissions对象中配置ohos.permission.ACCESS_BIOMETRIC权限。更多配置信息[应用包结构配置文件的说明](../quick-start/stage-structure.md)。
if (checkCode == userIAM_userAuth.ResultCode.SUCCESS) {
console.info("check auth support success"); 2. 指定[认证类型](../reference/apis/js-apis-useriam-userauth.md#userauthtype8)和[认证等级](../reference/apis/js-apis-useriam-userauth.md#authtrustlevel8)，调用[getAvailableStatus](../reference/apis/js-apis-useriam-userauth.md#useriam_userauthgetavailablestatus9)接口查询当前的设备是否支持相应的认证能力。
// 此处添加支持指定类型认证的逻辑
} else { ```js
console.error("check auth support fail, code = " + checkCode); import userIAM_userAuth from '@ohos.userIAM.userAuth';
// 此处添加不支持指定类型认证的逻辑
} // 查询认证能力是否支持
``` try {
userIAM_userAuth.getAvailableStatus(userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1);
4. 执行认证操作，代码示例如下： console.info("current auth trust level is supported");
} catch (error) {
```js console.info("current auth trust level is not supported, error = " + error);
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) {
// 此处添加认证成功逻辑 1. 申请权限。调用[start](../reference/apis/js-apis-useriam-userauth.md#start9)接口，需要在module.json5文件的requestPermissions对象中配置ohos.permission.ACCESS_BIOMETRIC权限。更多配置信息[应用包结构配置文件的说明](../quick-start/stage-structure.md)。
} else {
// 此处添加认证失败逻辑 2. 指定challenge、[认证类型](../reference/apis/js-apis-useriam-userauth.md#userauthtype8)和[认证等级](../reference/apis/js-apis-useriam-userauth.md#authtrustlevel8)，获取认证对象。
}
} catch (e) { 3. 调用[on](../reference/apis/js-apis-useriam-userauth.md#on9)接口订阅认证结果。
console.info("auth onResult error = " + e);
} 4. 调用[start](../reference/apis/js-apis-useriam-userauth.md#start9)接口发起认证，通过[callback](../reference/apis/js-apis-useriam-userauth.md#callback9)回调返回认证结果。
},
5. 调用[off](../reference/apis/js-apis-useriam-userauth.md#off9)接口取消订阅认证结果。
onAcquireInfo: (module, acquire, extraInfo) => {
try { ```js
console.info("auth onAcquireInfo module = " + module); import userIAM_userAuth from '@ohos.userIAM.userAuth';
console.info("auth onAcquireInfo acquire = " + acquire);
console.info("auth onAcquireInfo extraInfo = " + JSON.stringify(extraInfo)); let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
} catch (e) { let authType = userIAM_userAuth.UserAuthType.FACE;
console.info("auth onAcquireInfo error = " + e); let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1;
}
} // 获取认证对象
}); let auth;
``` try {
auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel);
5. 认证过程中取消认证，代码示例如下： console.log("get auth instance success");
} catch (error) {
```js console.log("get auth instance failed" + error);
let auth = new userIAM_userAuth.UserAuth(); }
// contextId通过auth接口获取
let contextId = auth.auth(null, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, { // 订阅认证结果
onResult: (result, extraInfo) => { try {
console.info("auth onResult result = " + result); auth.on("result", {
}, callback: (result: userIAM_userAuth.AuthResultInfo) => {
console.log("authV9 result " + result.result);
onAcquireInfo: (module, acquire, extraInfo) => { console.log("authV9 token " + result.token);
console.info("auth onAcquireInfo module = " + module); console.log("authV9 remainAttempts " + result.remainAttempts);
} console.log("authV9 lockoutDuration " + result.lockoutDuration);
}); }
let cancelCode = auth.cancel(contextId); });
if (cancelCode == userIAM_userAuth.ResultCode.SUCCESS) { console.log("subscribe authentication event success");
console.info("cancel auth success"); } catch (error) {
} else { console.log("subscribe authentication event failed " + error);
console.error("cancel auth fail"); }
}
``` // 开始认证
try {
auth.start();
console.info("authV9 start auth success");
} catch (error) {
console.info("authV9 start auth failed, error = " + error);
}
// 取消订阅认证结果
try {
auth.off("result");
console.info("cancel subscribe authentication event success");
} catch (error) {
console.info("cancel subscribe authentication event failed, error = " + error);
}
```
## 执行认证操作并订阅认证过程中的提示信息
### 开发步骤
1. 申请权限。调用[start](../reference/apis/js-apis-useriam-userauth.md#start9)接口，需要在module.json5文件的requestPermissions对象中配置ohos.permission.ACCESS_BIOMETRIC权限。更多配置信息[应用包结构配置文件的说明](../quick-start/stage-structure.md)。
2. 指定challenge、[认证类型](../reference/apis/js-apis-useriam-userauth.md#userauthtype8)和[认证等级](../reference/apis/js-apis-useriam-userauth.md#authtrustlevel8)，获取认证对象。
3. 调用[on](../reference/apis/js-apis-useriam-userauth.md#on9)接口订阅认证过程中的提示信息。
4. 调用[start](../reference/apis/js-apis-useriam-userauth.md#start9)接口发起认证，通过[callback](../reference/apis/js-apis-useriam-userauth.md#callback9)回调返回认证过程中的提示信息。
5. 调用[off](../reference/apis/js-apis-useriam-userauth.md#off9)接口取消订阅认证过程中的提示信息。
```js
import userIAM_userAuth from '@ohos.userIAM.userAuth';
let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
let authType = userIAM_userAuth.UserAuthType.FACE;
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 {
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
}
}
});
console.log("subscribe authentication event success");
} catch (error) {
console.log("subscribe authentication event failed " + error);
}
// 开始认证
try {
auth.start();
console.info("authV9 start auth success");
} catch (error) {
console.info("authV9 start auth failed, error = " + error);
}
// 取消订阅认证过程中的提示信息
try {
auth.off("tip");
console.info("cancel subscribe tip information success");
} catch (error) {
console.info("cancel subscribe tip information failed, error = " + error);
}
```
## 认证过程中取消认证
### 开发步骤
1. 申请权限。调用[cancel](../reference/apis/js-apis-useriam-userauth.md#cancel9)接口，需要在module.json5文件的requestPermissions对象中配置ohos.permission.ACCESS_BIOMETRIC权限。更多配置信息[应用包结构配置文件的说明](../quick-start/stage-structure.md)。
2. 指定challenge、[认证类型](../reference/apis/js-apis-useriam-userauth.md#userauthtype8)和[认证等级](../reference/apis/js-apis-useriam-userauth.md#authtrustlevel8)，获取认证对象。
3. 调用[start](../reference/apis/js-apis-useriam-userauth.md#start9)接口发起认证。
4. 通过调用[cancel](../reference/apis/js-apis-useriam-userauth.md#cancel9)接口取消本次认证。
```js
import userIAM_userAuth from '@ohos.userIAM.userAuth';
let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
let authType = userIAM_userAuth.UserAuthType.FACE;
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 {
auth.start();
console.info("authV9 start auth success");
} catch (error) {
console.info("authV9 start auth failed, error = " + error);
}
// 取消认证
try {
auth.cancel();
console.info("cancel auth success");
} catch (error) {
console.info("cancel auth failed, error = " + error);
}
```
zh-cn/application-dev/security/userauth-overview.md
浏览文件 @ 5bbfd682
# 用户认证开发概述 # 用户认证开发概述
提供用户认证能力，可应用于设备解锁、支付、应用登录等身份认证场景。 ## 用户认证模块的定义
当前用户认证能力提供2D人脸识别、3D人脸识别两种人脸识别能力，设备具备哪种识别能力，取决于设备的硬件能力和技术实现。 用户认证模块提供用户认证能力，对应用开发者而言，可使用该模块进行用户身份认证，用于设备解锁、支付、应用登录等身份认证场景。
3D人脸识别技术识别率、防伪能力都优于2D人脸识别技术，但具有3D人脸能力（比如3D结构光、3D TOF等）的设备才可以使用3D人脸识别技术。 当前用户认证提供人脸识别和指纹识别能力，设备具备哪种识别能力，取决于当前设备的硬件能力和技术实现。
## 基本概念 ## 基本概念
人脸识别：基于人的脸部特征信息进行身份识别的一种生物特征识别技术，用摄像机或摄像头采集含有人脸的图像或视频流，并自动在图像中检测和跟踪人脸，进而对检测到的人脸进行脸部识别，通常也叫做人像识别、面部识别、人脸认证。 - 人脸识别：基于人的脸部特征信息进行身份识别的一种生物特征识别技术，用摄像机或摄像头采集含有人脸的图像或视频流，并自动在图像中检测和跟踪人脸，进而对检测到的人脸进行脸部识别，通常也叫做人像识别、面部识别、人脸认证。
- 指纹识别：基于人的指尖皮肤纹路进行身份识别的一种生物特征识别技术。当用户触摸指纹采集器件时，器件感知并获取到用户的指纹图像，然后传输到指纹识别模块进行一定的处理后与用户预先注册的指纹信息进行比对，从而识别出用户身份。
## 运作机制 ## 运作机制
人脸识别会在摄像头和TEE（Trusted Execution Environment）之间建立安全通道，人脸图像信息通过安全通道传递到TEE中，由于人脸图像信息从REE（Rich Execution Environment）侧无法获取，从而避免了恶意软件从REE侧进行攻击。对人脸图像采集、特征提取、活体检测、特征比对等处理完全在TEE中，基于TrustZone进行安全隔离，外部的人脸框架只负责人脸的认证发起和处理认证结果等数据，不涉及人脸数据本身。 人脸或指纹识别过程中，特征采集器件和TEE（Trusted Execution Environment）之间会建立安全通道，将采集的生物特征信息直接通过安全通道传递到TEE中，从而避免了恶意软件从REE（Rich Execution Environment）侧进行攻击。传输到TEE中的生物特征数据从活体检测、特征提取、特征存储、特征比对到特征销毁等处理都完全在TEE中完成，基于TrustZone进行安全隔离，提供API的服务框架只负责管理认证请求和处理认证结果等数据，不涉及生物特征数据本身。
人脸特征数据通过TEE的安全存储区进行存储，采用高强度的密码算法对人脸特征数据进行加密和完整性保护，外部无法获取到加密人脸特征数据的密钥，保证用户的人脸特征数据不会泄露。本能力采集和存储的人脸特征数据不会在用户未授权的情况下被传出TEE，这意味着，用户未授权时，无论是系统应用还是三方应用都无法获得人脸特征数据，也无法将人脸特征数据传送或备份到任何外部存储介质。 用户注册的生物特征数据在TEE的安全存储区进行存储，采用高强度的密码算法进行加密和完整性保护，外部无法获取到加密生物特征数据的密钥，保证了用户生物特征数据的安全性。本能力采集和存储的生物特征数据不会在用户未授权的情况下被传出TEE。这意味着，用户未授权时，无论是系统应用还是三方应用都无法获得人脸和指纹等特征数据，也无法将这些特征数据传送或备份到任何外部存储介质。
## 约束与限制 ## 约束与限制
- 当前版本提供的用户认证能力只包含人脸识别，且只支持本地认证，不提供认证界面。 - 当前版本提供的用户认证能力包含人脸识别和指纹识别，且只支持本地认证，不提供认证界面。
- 要求设备上具备摄像器件，且人脸图像像素大于100*100。 - 要求设备上具备相应的生物特征采集器，且对于人脸识别要求人脸图像分辨率大于100*100。
- 要求设备上具有TEE安全环境，人脸特征信息高强度加密保存在TEE中。 - 要求设备上具有TEE安全环境，人脸和指纹等生物特征信息高强度加密保存在TEE中。
- 对于面部特征相似的人、面部特征不断发育的儿童，人脸特征匹配率有所不同。如果对此担忧，可考虑其他认证方式。 - 对于面部特征相似的人、面部特征不断发育的儿童，人脸特征匹配率有所不同。如果对此担忧，可考虑其他认证方式。
\ No newline at end of file
zh-cn/device-dev/driver/driver-peripherals-face_auth-des.md
浏览文件 @ 5bbfd682
...@@ -6,7 +6,7 @@ ...@@ -6,7 +6,7 @@
人脸识别功能是端侧设备不可或缺的一部分，为设备提供一种用户认证能力，可应用于设备解锁、支付、应用登录等身份认证场景。它是基于人的脸部特征信息进行身份识别的一种生物特征识别技术，用摄像机或摄像头采集含有人脸的图像或视频流，并自动在图像中检测和跟踪人脸，进而对检测到的人脸进行脸部识别，通常也叫做人像识别、面部识别、人脸认证。人脸识别功能整体框架如图1。 人脸识别功能是端侧设备不可或缺的一部分，为设备提供一种用户认证能力，可应用于设备解锁、支付、应用登录等身份认证场景。它是基于人的脸部特征信息进行身份识别的一种生物特征识别技术，用摄像机或摄像头采集含有人脸的图像或视频流，并自动在图像中检测和跟踪人脸，进而对检测到的人脸进行脸部识别，通常也叫做人像识别、面部识别、人脸认证。人脸识别功能整体框架如图1。
基于HDF（Hardware Driver Foundation）驱动框架开发的Face_auth驱动，能够屏蔽硬件器件差异，为上层用户认证框架和Face_auth服务提供稳定的人脸识别基础能力接口，包括人脸识别执行器列表查询、执行器信息查询、指定人脸模板ID查询模板信息、用户认证框架和执行器间的人脸模板信息对账、人脸的录入，删除，认证和识别等。 基于HDF（Hardware Driver Foundation）驱动框架开发的Face_auth驱动，能够屏蔽硬件器件差异，为上层用户认证框架和Face_auth服务提供稳定的人脸识别基础能力接口，包括人脸识别执行器列表查询、执行器信息查询、指定人脸模板ID查询模板信息、用户认证框架和执行器间的人脸模板信息对账、人脸录入、删除、认证和识别等。
**图1** 人脸识别功能整体框架 **图1** 人脸识别功能整体框架
...@@ -21,7 +21,7 @@ ...@@ -21,7 +21,7 @@
- 执行器安全等级 - 执行器安全等级
执行器提供能力时运行环境所达到的安全级别。 执行器提供能力时所在运行环境达到的安全级别。
- 执行器角色 - 执行器角色
...@@ -51,6 +51,22 @@ ...@@ -51,6 +51,22 @@
用户认证框架统一管理用户身份和凭据ID的映射关系，执行器对接到用户认证框架时，会读取用户身份认证框架内保存的该执行器的模板ID列表，执行器需要与自己维护的模板ID列表进行比对，并删除冗余信息。 用户认证框架统一管理用户身份和凭据ID的映射关系，执行器对接到用户认证框架时，会读取用户身份认证框架内保存的该执行器的模板ID列表，执行器需要与自己维护的模板ID列表进行比对，并删除冗余信息。
- HAPs
HAPs（OpenHarmony Ability Packages），广义上指可以安装在OpenHarmony上的应用包，本章节中仅代表Face_auth驱动的上层应用。
- IDL接口
接口定义语言（Interface Definition Language）通过IDL编译器编译后，能够生成与编程语言相关的文件：客户端桩文件，服务器框架文件。本文主要是通过IDL接口生成的客户端和服务端来实现Face_auth服务和驱动的通信，详细使用方法可参考[IDL简介](https://gitee.com/openharmony/ability_idl_tool/blob/master/README.md)。
- IPC通信
IPC（Inter Process Communication），进程间通信是指两个进程的数据之间产生交互，详细原理可参考[IPC通信简介](https://gitee.com/openharmony/communication_ipc/blob/master/README_zh.md)。
- HDI
HDI（Hardware Device Interface），硬件设备接口，位于基础系统服务层和设备驱动层之间，是提供给硬件系统服务开发者使用的、统一的硬件设备功能抽象接口，其目的是为系统服务屏蔽底层硬件设备差异，具体可参考[HDI规范](../../design/hdi-design-specifications.md)。
### 运作机制 ### 运作机制
Face_auth驱动的主要工作是为上层用户认证框架和Face_auth服务提供稳定的人脸识别基础能力，保证设备上人脸识别功能可以正常运行。 Face_auth驱动的主要工作是为上层用户认证框架和Face_auth服务提供稳定的人脸识别基础能力，保证设备上人脸识别功能可以正常运行。
...@@ -74,24 +90,28 @@ Face_auth驱动的主要工作是为上层用户认证框架和Face_auth服务 ...@@ -74,24 +90,28 @@ Face_auth驱动的主要工作是为上层用户认证框架和Face_auth服务
### 接口说明 ### 接口说明
注：以下接口列举的为IDL接口描述生成的对应C++语言函数接口，接口声明见idl文件（/drivers/interface/face_auth/v1_0/）。
在本文中，人脸凭据的录入、认证、识别和删除相关的HDI接口如表1所示，表2中的回调函数分别用于人脸执行器返回操作结果给框架和返回操作过程中的提示信息给上层应用。
**表1** 接口功能介绍 **表1** 接口功能介绍
| 接口名 | 功能介绍 | | 接口名称 | 功能介绍 |
| ------------------------------------------------------------ | ------------------------------------------------------------ | | ----------------------------------- | ---------------------------------- |
| GetExecutorList(std::vector<sptr<IExecutor>>& executorList) | 获取执行器列表。 | | GetExecutorList(std::vector<sptr<IExecutor>>& executorList) | 获取执行器列表。 |
| GetExecutorInfo(ExecutorInfo& info) | 获取执行器信息，包括执行器类型、执行器角色、认证类型、安全等级、执行器公钥等信息，用于向用户认证框架注册执行器。 | | GetExecutorInfo(ExecutorInfo& info) | 获取执行器信息，包括执行器类型、执行器角色、认证类型、安全等级、执行器公钥等信息，用于向用户认证框架注册执行器。 |
| GetTemplateInfo(uint64_t templateId, TemplateInfo& info) | 获取指定人脸模板ID的模板信息。 | | GetTemplateInfo(uint64_t templateId, TemplateInfo& info) | 获取指定人脸模板ID的模板信息。 |
| OnRegisterFinish(const std::vector<uint64_t>& templateIdList,<br/> const std::vector<uint8_t>& frameworkPublicKey, const std::vector<uint8_t>& extraInfo) | 执行器注册成功后，获取用户认证框架的公钥信息；获取用户认证框架的人脸模板列表用于对账。 | | OnRegisterFinish(const std::vector<uint64_t>& templateIdList,<br/> const std::vector<uint8_t>& frameworkPublicKey, const std::vector<uint8_t>& extraInfo) | 执行器注册成功后，获取用户认证框架的公钥信息；获取用户认证框架的人脸模板列表用于对账。 |
| Enroll(uint64_t scheduleId, const std::vector<uint8_t>& extraInfo,<br/> const sptr<IExecutorCallback>& callbackObj) | 录入人脸模板。 | | Enroll(uint64_t scheduleId, const std::vector<uint8_t>& extraInfo,<br/> const sptr<IExecutorCallback>& callbackObj) | 录入人脸模板。 |
| Authenticate(uint64_t scheduleId, const std::vector<uint64_t>& templateIdList,<br/> const std::vector<uint8_t>& extraInfo, const sptr<IExecutorCallback>& callbackObj) | 认证人脸模板。 | | Authenticate(uint64_t scheduleId, const std::vector<uint64_t>& templateIdList,<br/> const std::vector<uint8_t>& extraInfo, const sptr<IExecutorCallback>& callbackObj) | 认证人脸模板。 |
| Identify(uint64_t scheduleId, const std::vector<uint8_t>& extraInfo,<br/> const sptr<IExecutorCallback>& callbackObj) | 识别人脸模板。 | | Identify(uint64_t scheduleId, const std::vector<uint8_t>& extraInfo,<br/> const sptr<IExecutorCallback>& callbackObj) | 识别人脸模板。 |
| Delete(const std::vector<uint64_t>& templateIdList) | 删除人脸模板。 | | Delete(const std::vector<uint64_t>& templateIdList) | 删除人脸模板。 |
| Cancel(uint64_t scheduleId) | 通过scheduleId取消指定录入、认证、识别操作。 | | Cancel(uint64_t scheduleId) | 通过scheduleId取消指定录入、认证、识别操作。 |
| SendCommand(int32_t commandId, const std::vector<uint8_t>& extraInfo,<br/> const sptr<IExecutorCallback>& callbackObj) | 人脸认证服务向Face_auth驱动传递参数的通用接口。 | | SendCommand(int32_t commandId, const std::vector<uint8_t>& extraInfo,<br/> const sptr<IExecutorCallback>& callbackObj) | 人脸认证服务向Face_auth驱动传递参数的通用接口。 |
**表2** 回调函数介绍 **表2** 回调函数介绍
| 接口名 | 功能介绍 | | 接口名称 | 功能介绍 |
| ------------------------------------------------------------ | ------------------------ | | ------------------------------------------------------------ | ------------------------ |
| IExecutorCallback::OnResult(int32_t code, const std::vector<uint8_t>& extraInfo) | 返回操作的最终结果。 | | IExecutorCallback::OnResult(int32_t code, const std::vector<uint8_t>& extraInfo) | 返回操作的最终结果。 |
| IExecutorCallback::OnTip(int32_t code, const std::vector<uint8_t>& extraInfo) | 返回操作的过程交互信息。 | | IExecutorCallback::OnTip(int32_t code, const std::vector<uint8_t>& extraInfo) | 返回操作的过程交互信息。 |
...@@ -102,15 +122,15 @@ Face_auth驱动的主要工作是为上层用户认证框架和Face_auth服务 ...@@ -102,15 +122,15 @@ Face_auth驱动的主要工作是为上层用户认证框架和Face_auth服务
```undefined ```undefined
// drivers/peripheral/face_auth // drivers/peripheral/face_auth
├── BUILD.gn # 编译脚本 ├── BUILD.gn # 编译脚本
├── bundle.json # 组件描述文件 ├── bundle.json # 组件描述文件
└── hdi_service # Face_auth驱动实现 └── hdi_service # Face_auth驱动实现
├── BUILD.gn # 编译脚本 ├── BUILD.gn # 编译脚本
├── include # 头文件 ├── include # 头文件
└── src └── src # 源文件
├── executor_impl.cpp # 认证、录入等功能接口实现 ├── executor_impl.cpp # 认证、录入等功能接口实现
├── face_auth_interface_driver.cpp # Face_auth驱动入口 ├── face_auth_interface_driver.cpp # Face_auth驱动入口
└── face_auth_interface_service.cpp # 获取执行器列表接口实现 └── face_auth_interface_service.cpp # 获取执行器列表接口实现
``` ```
下面结合DEMO实例介绍驱动开发的具体步骤。 下面结合DEMO实例介绍驱动开发的具体步骤。
...@@ -423,66 +443,59 @@ Face_auth驱动的主要工作是为上层用户认证框架和Face_auth服务 ...@@ -423,66 +443,59 @@ Face_auth驱动的主要工作是为上层用户认证框架和Face_auth服务
驱动开发完成后，通过[用户认证API接口](../../application-dev/reference/apis/js-apis-useriam-userauth.md)开发JS应用，基于Hi3516DV300平台验证。认证和取消功能验证的JS测试代码如下： 驱动开发完成后，通过[用户认证API接口](../../application-dev/reference/apis/js-apis-useriam-userauth.md)开发JS应用，基于Hi3516DV300平台验证。认证和取消功能验证的JS测试代码如下：
```js ```js
// API version 8 // API version 9
import userIAM_userAuth from '@ohos.userIAM.userAuth'; import userIAM_userAuth from '@ohos.userIAM.userAuth';
let auth = new userIAM_userAuth.UserAuth();
let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
export default { let authType = userIAM_userAuth.UserAuthType.FACE;
getVersion() { let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1;
console.info("start get version");
let version = this.auth.getVersion(); // 获取认证对象
console.info("auth version = " + version); let auth;
}, try {
auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel);
startAuth() { console.log("get auth instance success");
console.info("start auth"); } catch (error) {
this.auth.auth(null, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, { console.log("get auth instance failed" + error);
onResult: (result, extraInfo) => { }
try {
console.info("auth onResult result = " + result); // 订阅认证结果
console.info("auth onResult extraInfo = " + JSON.stringify(extraInfo)); try {
if (result == userIAM_userAuth.ResultCode.SUCCESS) { auth.on("result", {
// 此处添加认证成功逻辑 callback: (result: userIAM_userAuth.AuthResultInfo) => {
} else { console.log("authV9 result " + result.result);
// 此处添加认证失败逻辑 console.log("authV9 token " + result.token);
} console.log("authV9 remainAttempts " + result.remainAttempts);
} catch (e) { console.log("authV9 lockoutDuration " + result.lockoutDuration);
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);
}
}
});
},
cancelAuth() {
console.info("start cancel auth");
// contextId通过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); console.log("subscribe authentication event success");
if (cancelCode == userIAM_userAuth.ResultCode.SUCCESS) { } catch (error) {
console.info("cancel auth success"); console.log("subscribe authentication event failed " + error);
} else {
console.error("cancel auth fail");
}
} }
}
```
// 开始认证
try {
auth.start();
console.info("authV9 start auth success");
} catch (error) {
console.info("authV9 start auth failed, error = " + error);
}
// 取消认证
try {
auth.cancel();
console.info("cancel auth success");
} catch (error) {
console.info("cancel auth failed, error = " + error);
}
// 取消订阅认证结果
try {
auth.off("result");
console.info("cancel subscribe authentication event success");
} catch (error) {
console.info("cancel subscribe authentication event failed, error = " + error);
}
```
zh-cn/device-dev/driver/driver-peripherals-fingerprint_auth-des.md
浏览文件 @ 5bbfd682
...@@ -21,7 +21,7 @@ ...@@ -21,7 +21,7 @@
- 执行器安全等级 - 执行器安全等级
执行器提供能力时运行环境所达到的安全级别。 执行器提供能力时所在运行环境达到的安全级别。
- 执行器角色 - 执行器角色
...@@ -53,15 +53,19 @@ ...@@ -53,15 +53,19 @@
- HAPs - HAPs
HAPs（OpenHarmony Ability Packages），本章节中仅代表Fingerprint_auth驱动的上层应用。 HAPs（OpenHarmony Ability Packages），广义上指可以安装在OpenHarmony上的应用包，本章节中仅代表Fingerprint_auth驱动的上层应用。
- IDL接口 - IDL接口
接口定义语言（Interface Definition Language）通过IDL编译器编译后，能够生成与编程语言相关的文件：客户端桩文件，服务器框架文件。本文主要是通过IDL接口实现Fingerprint_auth服务和驱动的通信。 接口定义语言（Interface Definition Language）通过IDL编译器编译后，能够生成与编程语言相关的文件：客户端桩文件，服务器框架文件。本文主要是通过IDL接口生成的客户端和服务端来实现Fingerprint_auth服务和驱动的通信，详细使用方法可参考[IDL简介](https://gitee.com/openharmony/ability_idl_tool/blob/master/README.md)。
- IPC通信 - IPC通信
IPC（Inter Process Communication），进程间通信是指两个进程的数据之间产生交互。 IPC（Inter Process Communication），进程间通信是指两个进程的数据之间产生交互，详细原理可参考[IPC通信简介](https://gitee.com/openharmony/communication_ipc/blob/master/README_zh.md)。
- HDI
HDI（Hardware Device Interface），硬件设备接口，位于基础系统服务层和设备驱动层之间，是提供给硬件系统服务开发者使用的、统一的硬件设备功能抽象接口，其目的是为系统服务屏蔽底层硬件设备差异，具体可参考[HDI规范](../../design/hdi-design-specifications.md)。
### 运作机制 ### 运作机制
...@@ -84,24 +88,27 @@ Fingerprint_auth驱动的主要工作是为上层用户认证框架和Fingerprin ...@@ -84,24 +88,27 @@ Fingerprint_auth驱动的主要工作是为上层用户认证框架和Fingerprin
### 接口说明 ### 接口说明
注：以下接口列举的为IDL接口描述生成的对应C++语言函数接口，接口声明见idl文件（/drivers/interface/fingerprint_auth/v1_0/）。
在本文中，指纹凭据的录入、认证、识别和删除相关的HDI接口如表1所示，表2中的回调函数分别用于指纹执行器返回操作结果给框架和返回操作过程中的提示信息给上层应用。
**表1** 接口功能介绍 **表1** 接口功能介绍
| 接口名 | 功能介绍 | | 接口名称 | 功能介绍 |
| ------------------------------------------------------------ | ------------------------------------------------------------ | | -------------------------------- | ----------------------------------- |
| GetExecutorList(std::vector<sptr<IExecutor>>& executorList) | 获取执行器列表。 | | GetExecutorList(std::vector<sptr<IExecutor>>& executorList) | 获取执行器列表。 |
| GetExecutorInfo(ExecutorInfo& info) | 获取执行器信息，包括执行器类型、执行器角色、认证类型、安全等级、执行器公钥等信息，用于向用户认证框架注册执行器。 | | GetExecutorInfo(ExecutorInfo& info) | 获取执行器信息，包括执行器类型、执行器角色、认证类型、安全等级、执行器公钥等信息，用于向用户认证框架注册执行器。 |
| GetTemplateInfo(uint64_t templateId, TemplateInfo& info) | 获取指定模板ID的模板信息。 | | GetTemplateInfo(uint64_t templateId, TemplateInfo& info) | 获取指定模板ID的模板信息。 |
| OnRegisterFinish(const std::vector<uint64_t>& templateIdList,<br/> const std::vector<uint8_t>& frameworkPublicKey, const std::vector<uint8_t>& extraInfo) | 执行器注册成功后，获取用户认证框架的公钥信息；获取用户认证框架的模板列表用于对账。 | | OnRegisterFinish(const std::vector<uint64_t>& templateIdList,<br/> const std::vector<uint8_t>& frameworkPublicKey, const std::vector<uint8_t>& extraInfo) | 执行器注册成功后，获取用户认证框架的公钥信息；获取用户认证框架的模板列表用于对账。 |
| Enroll(uint64_t scheduleId, const std::vector<uint8_t>& extraInfo,<br/> const sptr<IExecutorCallback>& callbackObj) | 录入指纹模板。 | | Enroll(uint64_t scheduleId, const std::vector<uint8_t>& extraInfo,<br/> const sptr<IExecutorCallback>& callbackObj) | 录入指纹模板。 |
| Authenticate(uint64_t scheduleId, const std::vector<uint64_t>& templateIdList,<br/> const std::vector<uint8_t>& extraInfo, const sptr<IExecutorCallback>& callbackObj) | 认证指纹模板。 | | Authenticate(uint64_t scheduleId, const std::vector<uint64_t>& templateIdList,<br/> const std::vector<uint8_t>& extraInfo, const sptr<IExecutorCallback>& callbackObj) | 认证指纹模板。 |
| Identify(uint64_t scheduleId, const std::vector<uint8_t>& extraInfo,<br/> const sptr<IExecutorCallback>& callbackObj) | 识别指纹模板。 | | Identify(uint64_t scheduleId, const std::vector<uint8_t>& extraInfo,<br/> const sptr<IExecutorCallback>& callbackObj) | 识别指纹模板。 |
| Delete(const std::vector<uint64_t>& templateIdList) | 删除指纹模板。 | | Delete(const std::vector<uint64_t>& templateIdList) | 删除指纹模板。 |
| Cancel(uint64_t scheduleId) | 通过scheduleId取消指定录入、认证、识别操作。 | | Cancel(uint64_t scheduleId) | 通过scheduleId取消指定录入、认证、识别操作。 |
| SendCommand(int32_t commandId, const std::vector<uint8_t>& extraInfo,<br/> const sptr<IExecutorCallback>& callbackObj) | 指纹认证服务向Fingerprint_auth驱动传递参数的通用接口。 | | SendCommand(int32_t commandId, const std::vector<uint8_t>& extraInfo,<br/> const sptr<IExecutorCallback>& callbackObj) | 指纹认证服务向Fingerprint_auth驱动传递参数的通用接口。 |
**表2** 回调函数介绍 **表2** 回调函数介绍
| 接口名 | 功能介绍 | | 接口名称 | 功能介绍 |
| ------------------------------------------------------------ | ------------------------ | | ------------------------------------------------------------ | ------------------------ |
| IExecutorCallback::OnResult(int32_t code, const std::vector<uint8_t>& extraInfo) | 返回操作的最终结果。 | | IExecutorCallback::OnResult(int32_t code, const std::vector<uint8_t>& extraInfo) | 返回操作的最终结果。 |
| IExecutorCallback::OnTip(int32_t code, const std::vector<uint8_t>& extraInfo) | 返回操作的过程交互信息。 | | IExecutorCallback::OnTip(int32_t code, const std::vector<uint8_t>& extraInfo) | 返回操作的过程交互信息。 |
...@@ -112,15 +119,15 @@ Fingerprint_auth驱动的主要工作是为上层用户认证框架和Fingerprin ...@@ -112,15 +119,15 @@ Fingerprint_auth驱动的主要工作是为上层用户认证框架和Fingerprin
```undefined ```undefined
// drivers/peripheral/fingerprint_auth // drivers/peripheral/fingerprint_auth
├── BUILD.gn # 编译脚本 ├── BUILD.gn # 编译脚本
├── bundle.json # 组件描述文件 ├── bundle.json # 组件描述文件
└── hdi_service # Fingerprint_auth驱动实现 └── hdi_service # Fingerprint_auth驱动实现
├── BUILD.gn # 编译脚本 ├── BUILD.gn # 编译脚本
├── include # 头文件 ├── include # 头文件
└── src └── src # 源文件
├── executor_impl.cpp # 认证、录入等功能接口实现 ├── executor_impl.cpp # 认证、录入等功能接口实现
├── fingerprint_auth_interface_driver.cpp # Fingerprint_auth驱动入口 ├── fingerprint_auth_interface_driver.cpp # Fingerprint_auth驱动入口
└── fingerprint_auth_interface_service.cpp # 获取执行器列表接口实现 └── fingerprint_auth_interface_service.cpp # 获取执行器列表接口实现
``` ```
下面结合DEMO实例介绍驱动开发的具体步骤。 下面结合DEMO实例介绍驱动开发的具体步骤。
...@@ -433,47 +440,59 @@ Fingerprint_auth驱动的主要工作是为上层用户认证框架和Fingerprin ...@@ -433,47 +440,59 @@ Fingerprint_auth驱动的主要工作是为上层用户认证框架和Fingerprin
驱动开发完成后，开发者可以通过[用户认证API接口](../../application-dev/reference/apis/js-apis-useriam-userauth.md)开发JS应用，JS应用通过Fingerprint_auth服务调用Fingerprint_auth驱动，从而验证驱动开发是否符合预期。基于Hi3516DV300平台验证，认证功能验证的JS测试代码如下： 驱动开发完成后，开发者可以通过[用户认证API接口](../../application-dev/reference/apis/js-apis-useriam-userauth.md)开发JS应用，JS应用通过Fingerprint_auth服务调用Fingerprint_auth驱动，从而验证驱动开发是否符合预期。基于Hi3516DV300平台验证，认证功能验证的JS测试代码如下：
```js ```js
// API version 8 // API version 9
import userIAM_userAuth from '@ohos.userIAM.userAuth'; import userIAM_userAuth from '@ohos.userIAM.userAuth';
let auth = new userIAM_userAuth.UserAuth();
let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
export default { let authType = userIAM_userAuth.UserAuthType.FINGERPRINT;
getVersion() { let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1;
console.info("start get version");
let version = this.auth.getVersion(); // 获取认证对象
console.info("auth version = " + version); let auth;
}, try {
auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel);
startAuth() { console.log("get auth instance success");
console.info("start auth"); } catch (error) {
// auth是开发者可以调用的API接口，开发者可以指定认证类型为FINGERPRINT，从而验证驱动是否向框架注册成功以及认证接口实现是否符合预期，result即为认证结果。 console.log("get auth instance failed" + error);
this.auth.auth(null, userIAM_userAuth.UserAuthType.FINGERPRINT, userIAM_userAuth.AuthTrustLevel.ATL1, { }
onResult: (result, extraInfo) => {
try { // 订阅认证结果
console.info("auth onResult result = " + result); try {
console.info("auth onResult extraInfo = " + JSON.stringify(extraInfo)); auth.on("result", {
if (result == userIAM_userAuth.ResultCode.SUCCESS) { callback: (result: userIAM_userAuth.AuthResultInfo) => {
// 此处添加认证成功逻辑 console.log("authV9 result " + result.result);
} else { console.log("authV9 token " + result.token);
// 此处添加认证失败逻辑 console.log("authV9 remainAttempts " + result.remainAttempts);
} console.log("authV9 lockoutDuration " + result.lockoutDuration);
} 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);
}
} }
}); });
console.log("subscribe authentication event success");
} catch (error) {
console.log("subscribe authentication event failed " + error);
} }
}
```
// 开始认证
try {
auth.start();
console.info("authV9 start auth success");
} catch (error) {
console.info("authV9 start auth failed, error = " + error);
}
// 取消认证
try {
auth.cancel();
console.info("cancel auth success");
} catch (error) {
console.info("cancel auth failed, error = " + error);
}
// 取消订阅认证结果
try {
auth.off("result");
console.info("cancel subscribe authentication event success");
} catch (error) {
console.info("cancel subscribe authentication event failed, error = " + error);
}
```
zh-cn/device-dev/driver/driver-peripherals-pinauth-des.md
浏览文件 @ 5bbfd682
...@@ -21,7 +21,7 @@ ...@@ -21,7 +21,7 @@
- 执行器安全等级 - 执行器安全等级
执行器提供能力时运行环境所达到的安全级别。 执行器提供能力时所在运行环境达到的安全级别。
- 执行器角色 - 执行器角色
...@@ -52,6 +52,18 @@ ...@@ -52,6 +52,18 @@
用户认证框架统一管理用户身份和凭据ID的映射关系，执行器对接到用户认证框架时，会读取用户身份认证框架内保存的该执行器的模板ID列表，执行器需要与自己维护的模板ID列表进行比对，并删除冗余信息。 用户认证框架统一管理用户身份和凭据ID的映射关系，执行器对接到用户认证框架时，会读取用户身份认证框架内保存的该执行器的模板ID列表，执行器需要与自己维护的模板ID列表进行比对，并删除冗余信息。
- IDL接口
接口定义语言（Interface Definition Language）通过IDL编译器编译后，能够生成与编程语言相关的文件：客户端桩文件，服务器框架文件。本文主要是通过IDL接口生成的客户端和服务端来实现Pin_auth服务和驱动的通信，详细使用方法可参考[IDL简介](https://gitee.com/openharmony/ability_idl_tool/blob/master/README.md)。
- IPC通信
IPC（Inter Process Communication），进程间通信是指两个进程的数据之间产生交互，详细原理可参考[IPC通信简介](https://gitee.com/openharmony/communication_ipc/blob/master/README_zh.md)。
- HDI
HDI（Hardware Device Interface），硬件设备接口，位于基础系统服务层和设备驱动层之间，是提供给硬件系统服务开发者使用的、统一的硬件设备功能抽象接口，其目的是为系统服务屏蔽底层硬件设备差异，具体可参考[HDI规范](../../design/hdi-design-specifications.md)。
### 运作机制 ### 运作机制
Pin_auth驱动的主要工作是为上层用户认证框架和Pin_auth服务提供稳定的口令认证的基础能力，保证口令认证的功能可以正常运行。开发者可基于HDF框架对不同芯片进行各自驱动的开发以及HDI层接口的调用。 Pin_auth驱动的主要工作是为上层用户认证框架和Pin_auth服务提供稳定的口令认证的基础能力，保证口令认证的功能可以正常运行。开发者可基于HDF框架对不同芯片进行各自驱动的开发以及HDI层接口的调用。
...@@ -61,7 +73,7 @@ Pin_auth驱动的主要工作是为上层用户认证框架和Pin_auth服务提 ...@@ -61,7 +73,7 @@ Pin_auth驱动的主要工作是为上层用户认证框架和Pin_auth服务提
![image](figures/pin_auth服务与驱动交互.png "pin_auth服务与驱动交互") ![image](figures/pin_auth服务与驱动交互.png "pin_auth服务与驱动交互")
### 约束与限制 ### 约束与限制
口令认证的实现需要在TEE安全环境中实现，口令凭据等数据的保密信息需要在安全环境中存储。 口令认证的实现需要在TEE安全环境中实现，口令凭据等数据的加密信息需要在安全环境中存储。
## 开发指导 ## 开发指导
### 场景介绍 ### 场景介绍
...@@ -69,24 +81,27 @@ Pin_auth驱动的主要工作是为上层用户认证框架和Pin_auth服务提 ...@@ -69,24 +81,27 @@ Pin_auth驱动的主要工作是为上层用户认证框架和Pin_auth服务提
### 接口说明 ### 接口说明
注：以下接口列举的为IDL接口描述生成的对应C++语言函数接口，接口声明见idl文件（/drivers/interface/pin_auth/v1_0/）。
在本文中，口令凭据的录入、认证和删除相关的HDI接口如表1所示，表2中的回调函数分别用于口令执行器返回操作结果给框架和获取用户输入的口令信息。
**表1** 接口功能介绍 **表1** 接口功能介绍
| 接口名 | 功能介绍 | | 接口名称 | 功能介绍 |
| ------------------------------------------------------------ | ------------------------------------------------------------ | | ------------------------------- | ------------------------------------------- |
| GetExecutorList(std::vector<sptr<IExecutor>>& executorList) | 获取执行器列表。 | | GetExecutorList(std::vector<sptr<IExecutor>>& executorList) | 获取执行器列表。 |
| GetExecutorInfo(ExecutorInfo& info) | 获取执行器信息。 | | GetExecutorInfo(ExecutorInfo& info) | 获取执行器信息。 |
| GetTemplateInfo(uint64_t templateId, TemplateInfo& info) | 获取指定templateId的模板信息。 | | GetTemplateInfo(uint64_t templateId, TemplateInfo& info) | 获取指定templateId的模板信息。 |
| OnRegisterFinish(const std::vector<uint64_t>& templateIdList,<br/>const std::vector<uint8_t>& frameworkPublicKey,<br/>const std::vector<uint8_t>& extraInfo) | 执行器注册成功后，获取用户认证框架的公钥信息；获取用户认证框架的template 列表用于对账。 | | OnRegisterFinish(const std::vector<uint64_t>& templateIdList,<br/>const std::vector<uint8_t>& frameworkPublicKey,<br/>const std::vector<uint8_t>& extraInfo) | 执行器注册成功后，获取用户认证框架的公钥信息；获取用户认证框架的template 列表用于对账。 |
| OnSetData(uint64_t scheduleId, uint64_t authSubType, <br/>const std::vector<uint8_t> &data) | 用于回调传pin码认证的子类型和脱敏数据。 | | OnSetData(uint64_t scheduleId, uint64_t authSubType, <br/>const std::vector<uint8_t> &data) | 回调函数，返回用户录入的口令子类型和录入的口令脱敏数据。 |
| Enroll(uint64_t scheduleId, const std::vector<uint8_t>& extraInfo,<br/>const sptr<IExecutorCallback>& callbackObj) | 录入pin码。 | | Enroll(uint64_t scheduleId, const std::vector<uint8_t>& extraInfo,<br/>const sptr<IExecutorCallback>& callbackObj) | 录入pin码。 |
| Authenticate(uint64_t scheduleId, uint64_t templateId, const std::vector<uint8_t>& extraInfo, const sptr<IExecutorCallback>& callbackObj) | pin码认证。 | | Authenticate(uint64_t scheduleId, uint64_t templateId, const std::vector<uint8_t>& extraInfo, const sptr<IExecutorCallback>& callbackObj) | pin码认证。 |
| Delete(uint64_t templateId) | 删除pin码模板。 | | Delete(uint64_t templateId) | 删除pin码模板。 |
| Cancel(uint64_t scheduleId) | 通过scheduleId取消指定操作。 | | Cancel(uint64_t scheduleId) | 通过scheduleId取消指定操作。 |
| SendCommand(int32_t commandId, const std::vector<uint8_t>& extraInfo,<br/>const sptr<IExecutorCallback>& callbackObj) | 预留接口。 | | SendCommand(int32_t commandId, const std::vector<uint8_t>& extraInfo,<br/>const sptr<IExecutorCallback>& callbackObj) | 预留接口。 |
**表2** 回调函数介绍 **表2** 回调函数介绍
| 接口名 | 功能介绍 | | 接口名称 | 功能介绍 |
| ------------------------------------------------------------ | -------------------- | | ------------------------------------------------------------ | -------------------- |
| IExecutorCallback::OnResult(int32_t code, const std::vector<uint8_t>& extraInfo) | 返回操作的最终结果。 | | IExecutorCallback::OnResult(int32_t code, const std::vector<uint8_t>& extraInfo) | 返回操作的最终结果。 |
| IExecutorCallback::OnGetData(uint64_t scheduleId, const std::vector<uint8_t>& salt,<br/> uint64_t authSubType)| 返回获取pin码数据信息。 | | IExecutorCallback::OnGetData(uint64_t scheduleId, const std::vector<uint8_t>& salt,<br/> uint64_t authSubType)| 返回获取pin码数据信息。 |
...@@ -97,21 +112,21 @@ Pin_auth驱动的主要工作是为上层用户认证框架和Pin_auth服务提 ...@@ -97,21 +112,21 @@ Pin_auth驱动的主要工作是为上层用户认证框架和Pin_auth服务提
```text ```text
// drivers/peripheral/pin_auth // drivers/peripheral/pin_auth
├── BUILD.gn # 编译脚本 ├── BUILD.gn # 编译脚本
├── bundle.json # 组件描述文件 ├── bundle.json # 组件描述文件
├── test # 测试用例 ├── test # 测试用例
└── hdi_service # Pin_auth驱动实现 └── hdi_service # Pin_auth驱动实现
├── BUILD.gn # 编译脚本 ├── BUILD.gn # 编译脚本
├── adaptor # 相关算法实现 ├── adaptor # 相关算法实现
├── common # 公共接口实现 ├── common # 公共接口实现
├── database # 数据库实现 ├── database # 数据库实现
├── main # 口令相关功能实现入口 ├── main # 口令相关功能实现入口
└── service # Pin_auth驱动实现入口 └── service # Pin_auth驱动实现入口
├── inc # 头文件 ├── inc # 头文件
└── src └── src # 源文件
├── executor_impl.cpp # 认证、录入等功能接口实现 ├── executor_impl.cpp # 认证、录入等功能接口实现
├── pin_auth_interface_driver.cpp # Pin_auth驱动入口 ├── pin_auth_interface_driver.cpp # Pin_auth驱动入口
└── pin_auth_interface_service.cpp # 获取执行器列表接口实现 └── pin_auth_interface_service.cpp # 获取执行器列表接口实现
``` ```
下面结合DEMO实例介绍驱动开发的具体步骤。 下面结合DEMO实例介绍驱动开发的具体步骤。
......
zh-cn/device-dev/driver/driver-peripherals-user-auth-des.md
浏览文件 @ 5bbfd682
...@@ -21,7 +21,7 @@ ...@@ -21,7 +21,7 @@
- 认证凭据模板 - 认证凭据模板
认证凭据模板在用户设置认证凭据时由认证服务产生并存储。每个模板有一个ID，用于索引模板信息文件。在认证时，读取模板信息并用和当次认证过程中产生的认证数据做对比，完成身份认证。 认证凭据模板在用户设置认证凭据时由认证服务产生并存储。每个模板有一个ID，用于索引模板信息文件。在认证时，读取模板信息并和当次认证过程中产生的认证数据做对比，完成身份认证。
- 执行器 - 执行器
...@@ -41,11 +41,11 @@ ...@@ -41,11 +41,11 @@
- 执行器安全等级 - 执行器安全等级
执行器提供能力时运行环境所达到的安全级别，如操作运行在无访问控制安全等级低于操作运行硬件可信执行环境的安全等级。 执行器提供能力时所在运行环境达到的安全级别。
- 用户认证框架公钥 & 执行器公钥 - 用户认证框架公钥 & 执行器公钥
用户身份认证处理需要保证用户数据安全以及认证结果的准确性，用户认证框架与基础认证服务间的关键交互信息需要做数据完整性保护，各基础认证服务将提供的执行器能力对接到用户认证框架时，需要交互各自的公钥，其中： 用户身份认证处理需要保证用户数据安全以及认证结果的准确性，用户认证框架与基础认证服务间的关键交互信息需要做数据完整性保护，各基础认证服务将提供的执行器能力对接到用户认证框架时，需要交换各自的公钥，其中：
- 执行器通过用户认证框架公钥校验调度指令的准确性，如锁定一个人脸模板，这种情况导致无法使用人脸功能，属于敏感操作，需要确保指令准确，才可处理。 - 执行器通过用户认证框架公钥校验调度指令的准确性，如锁定一个人脸模板，这种情况导致无法使用人脸功能，属于敏感操作，需要确保指令准确，才可处理。
...@@ -76,6 +76,18 @@ ...@@ -76,6 +76,18 @@
OpenHarmony系统向系统应用提供的应用编程接口。 OpenHarmony系统向系统应用提供的应用编程接口。
- IDL接口
接口定义语言（Interface Definition Language），通过IDL编译器编译后，能够生成与编程语言相关的文件：客户端桩文件，服务器框架文件。本文主要是通过IDL接口生成的客户端和服务端来实现User_auth服务和驱动的通信，详细使用方法可参考[IDL简介](https://gitee.com/openharmony/ability_idl_tool/blob/master/README.md)。
- IPC通信
IPC（Inter Process Communication），进程间通信是指两个进程的数据之间产生交互，详细原理可参考[IPC通信简介](https://gitee.com/openharmony/communication_ipc/blob/master/README_zh.md)。
- HDI
HDI（Hardware Device Interface），硬件设备接口，位于基础系统服务层和设备驱动层之间，是提供给硬件系统服务开发者使用的、统一的硬件设备功能抽象接口，其目的是为系统服务屏蔽底层硬件设备差异，具体可参考[HDI规范](../../design/hdi-design-specifications.md)。
### 运作机制 ### 运作机制
User_auth驱动主要工作是屏蔽不同安全器件和安全环境的差异，通过统一的认证能力注册、录入、认证接口，向User_auth服务提供认证执行器管理、认证凭据管理和认证方案生成管理等能力。 User_auth驱动主要工作是屏蔽不同安全器件和安全环境的差异，通过统一的认证能力注册、录入、认证接口，向User_auth服务提供认证执行器管理、认证凭据管理和认证方案生成管理等能力。
...@@ -97,31 +109,34 @@ User_auth驱动的主要工作是为User_auth服务提供稳定的用户凭据 ...@@ -97,31 +109,34 @@ User_auth驱动的主要工作是为User_auth服务提供稳定的用户凭据
### 接口说明 ### 接口说明
注：以下接口列举的为IDL接口描述生成的对应C++语言函数接口，接口声明见idl文件（/drivers/interface/user_auth/v1_0/）。
在本文中，执行器注册、凭据录入、凭据删除、用户认证和用户识别相关的HDI接口如表1所示。
**表1** 接口功能介绍 **表1** 接口功能介绍
| 接口名 | 功能介绍 | | 接口名称 | 功能介绍 |
| ------------------------------------------------------------ | ------------------------------------------------------------ | | --------------------------- | --------------------------- |
| Init() | 初始化缓存信息。 | | Init() | 初始化缓存信息。 |
| AddExecutor(const ExecutorRegisterInfo& info, uint64_t& index, std::vector<uint8_t>& publicKey,<br/> std::vector<uint64_t>& templateIds) | 添加认证执行器，获得此认证能力。 | | AddExecutor(const ExecutorRegisterInfo& info, uint64_t& index, std::vector<uint8_t>& publicKey,<br/> std::vector<uint64_t>& templateIds) | 添加认证执行器，获得此认证能力。 |
| DeleteExecutor(uint64_t index) | 根据索引值index删除认证执行器。 | | DeleteExecutor(uint64_t index) | 根据索引值index删除认证执行器。 |
| OpenSession(int32_t userId, std::vector<uint8_t>& challenge) | 开启认证凭据管理Session。 | | OpenSession(int32_t userId, std::vector<uint8_t>& challenge) | 开启认证凭据管理Session。 |
| CloseSession(int32_t userId) | 关闭认证凭据管理Session。 | | CloseSession(int32_t userId) | 关闭认证凭据管理Session。 |
| BeginEnrollment(int32_t userId, const std::vector<uint8_t>& authToken, const EnrollParam& param,<br/> ScheduleInfo& info) | 发起用户的认证凭据的录入，当录入类型为PIN码且当前用户已录入PIN码的情况下会更新PIN码。 | | BeginEnrollment(int32_t userId, const std::vector<uint8_t>& authToken, const EnrollParam& param,<br/> ScheduleInfo& info) | 发起用户的认证凭据的录入，当录入类型为PIN码且当前用户已录入PIN码的情况下会更新PIN码。 |
| UpdateEnrollmentResult(int32_t userId, const std::vector<uint8_t>& scheduleResult, uint64_t& credentialId,<br/> CredentialInfo& oldInfo) | 更新录入结果，完成此次录入。 | | UpdateEnrollmentResult(int32_t userId, const std::vector<uint8_t>& scheduleResult, uint64_t& credentialId,<br/> CredentialInfo& oldInfo) | 更新录入结果，完成此次录入。 |
| CancelEnrollment(int32_t userId) | 取消此次录入。 | | CancelEnrollment(int32_t userId) | 取消此次录入。 |
| DeleteCredential(int32_t userId, uint64_t credentialId, const std::vector<uint8_t>& authToken,<br/> CredentialInfo& info) | 根据credentialId删除凭据信息。 | | DeleteCredential(int32_t userId, uint64_t credentialId, const std::vector<uint8_t>& authToken,<br/> CredentialInfo& info) | 根据credentialId删除凭据信息。 |
| DeleteUser(int32_t userId, const std::vector<uint8_t>& authToken,<br/> std::vector<CredentialInfo>& deletedInfos) | 删除PIN码即在用户认证框架中删除用户。 | | DeleteUser(int32_t userId, const std::vector<uint8_t>& authToken,<br/> std::vector<CredentialInfo>& deletedInfos) | 删除PIN码即在用户认证框架中删除用户。 |
| EnforceDeleteUser(int32_t userId, std::vector<CredentialInfo>& deletedInfos) | 强制删除用户，当系统内此用户被删除时强制调用。 | | EnforceDeleteUser(int32_t userId, std::vector<CredentialInfo>& deletedInfos) | 强制删除用户，当系统内此用户被删除时强制调用。 |
| GetCredential(int32_t userId, AuthType authType, std::vector<CredentialInfo>& infos) | 查询用户某种认证类型下的凭据信息。 | | GetCredential(int32_t userId, AuthType authType, std::vector<CredentialInfo>& infos) | 查询用户某种认证类型下的凭据信息。 |
| GetSecureInfo(int32_t userId, uint64_t& secureUid, std::vector<EnrolledInfo>& infos) | 查询用户的安全用户Id和每种认证类型的录入标记Id。 | | GetSecureInfo(int32_t userId, uint64_t& secureUid, std::vector<EnrolledInfo>& infos) | 查询用户的安全用户Id和每种认证类型的录入标记Id。 |
| BeginAuthentication(uint64_t contextId, const AuthSolution& param,<br/> std::vector<ScheduleInfo>& scheduleInfos) | 发起认证，生成认证方案和调度信息。 | | BeginAuthentication(uint64_t contextId, const AuthSolution& param,<br/> std::vector<ScheduleInfo>& scheduleInfos) | 发起认证，生成认证方案和调度信息。 |
| UpdateAuthenticationResult(uint64_t contextId, const std::vector<uint8_t>& scheduleResult,<br/> AuthResultInfo& info) | 更新认证结果，进行此次认证方案结果的评估。 | | UpdateAuthenticationResult(uint64_t contextId, const std::vector<uint8_t>& scheduleResult,<br/> AuthResultInfo& info) | 更新认证结果，进行此次认证方案结果的评估。 |
| CancelAuthentication(uint64_t contextId) | 取消此次认证。 | | CancelAuthentication(uint64_t contextId) | 取消此次认证。 |
| BeginIdentification(uint64_t contextId, AuthType authType, const std::vector<int8_t>& challenge,<br/> uint32_t executorId, ScheduleInfo& scheduleInfo) | 发起识别，生成识别方案和调度信息。 | | BeginIdentification(uint64_t contextId, AuthType authType, const std::vector<int8_t>& challenge,<br/> uint32_t executorId, ScheduleInfo& scheduleInfo) | 发起识别，生成识别方案和调度信息。 |
| UpdateIdentificationResult(uint64_t contextId, const std::vector<uint8_t>& scheduleResult,<br/> IdentifyResultInfo& info) | 更新识别结果，进行此次识别方案结果的评估。 | | UpdateIdentificationResult(uint64_t contextId, const std::vector<uint8_t>& scheduleResult,<br/> IdentifyResultInfo& info) | 更新识别结果，进行此次识别方案结果的评估。 |
| CancelIdentification(uint64_t contextId) | 取消此次识别。 | | CancelIdentification(uint64_t contextId) | 取消此次识别。 |
| GetAuthTrustLevel(int32_t userId, AuthType authType, uint32_t& authTrustLevel) | 获取此用户当前认证类型的认证可信等级。 | | GetAuthTrustLevel(int32_t userId, AuthType authType, uint32_t& authTrustLevel) | 获取此用户当前认证类型的认证可信等级。 |
| GetValidSolution(int32_t userId, const std::vector<AuthType>& authTypes, uint32_t authTrustLevel,<br/> std::vector<AuthType>& validTypes) | 筛选此用户当前认证可信等级下可用认证方式。 | | GetValidSolution(int32_t userId, const std::vector<AuthType>& authTypes, uint32_t authTrustLevel,<br/> std::vector<AuthType>& validTypes) | 筛选此用户当前认证可信等级下可用的认证方式。 |
### 开发步骤 ### 开发步骤
...@@ -129,14 +144,14 @@ User_auth驱动的主要工作是为User_auth服务提供稳定的用户凭据 ...@@ -129,14 +144,14 @@ User_auth驱动的主要工作是为User_auth服务提供稳定的用户凭据
```undefined ```undefined
// drivers/peripheral/user_auth // drivers/peripheral/user_auth
├── BUILD.gn # 编译脚本 ├── BUILD.gn # 编译脚本
├── bundle.json # 组件描述文件 ├── bundle.json # 组件描述文件
└── hdi_service # User_auth驱动实现 └── hdi_service # User_auth驱动实现
├── BUILD.gn # 编译脚本 ├── BUILD.gn # 编译脚本
├── module # 功能实现 ├── module # 功能实现
└── service └── service
├── user_auth_interface_driver.cpp # User_auth驱动入口 ├── user_auth_interface_driver.cpp # User_auth驱动入口
└── user_auth_interface_service.cpp # 获取执行器列表接口实现 └── user_auth_interface_service.cpp # 获取执行器列表接口实现
``` ```
下面结合DEMO实例介绍驱动开发的具体步骤。 下面结合DEMO实例介绍驱动开发的具体步骤。
...@@ -494,66 +509,59 @@ User_auth驱动的主要工作是为User_auth服务提供稳定的用户凭据 ...@@ -494,66 +509,59 @@ User_auth驱动的主要工作是为User_auth服务提供稳定的用户凭据
驱动开发完成后，通过[用户认证API接口](../../application-dev/reference/apis/js-apis-useriam-userauth.md)开发JS应用，基于Hi3516DV300平台验证。认证和取消功能验证的JS测试代码如下： 驱动开发完成后，通过[用户认证API接口](../../application-dev/reference/apis/js-apis-useriam-userauth.md)开发JS应用，基于Hi3516DV300平台验证。认证和取消功能验证的JS测试代码如下：
```js ```js
// API version 8 // API version 9
import userIAM_userAuth from '@ohos.userIAM.userAuth'; import userIAM_userAuth from '@ohos.userIAM.userAuth';
let auth = new userIAM_userAuth.UserAuth();
let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
export default { let authType = userIAM_userAuth.UserAuthType.FACE;
getVersion() { let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1;
console.info("start get version");
let version = this.auth.getVersion(); // 获取认证对象
console.info("auth version = " + version); let auth;
}, try {
auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel);
startAuth() { console.log("get auth instance success");
console.info("start auth"); } catch (error) {
this.auth.auth(null, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, { console.log("get auth instance failed" + error);
onResult: (result, extraInfo) => { }
try {
console.info("auth onResult result = " + result); // 订阅认证结果
console.info("auth onResult extraInfo = " + JSON.stringify(extraInfo)); try {
if (result == 'SUCCESS') { auth.on("result", {
// 此处添加认证成功逻辑 callback: (result: userIAM_userAuth.AuthResultInfo) => {
} else { console.log("authV9 result " + result.result);
// 此处添加认证失败逻辑 console.log("authV9 token " + result.token);
} console.log("authV9 remainAttempts " + result.remainAttempts);
} catch (e) { console.log("authV9 lockoutDuration " + result.lockoutDuration);
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);
}
}
});
},
cancelAuth() {
console.info("start cancel auth");
// contextId通过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); console.log("subscribe authentication event success");
if (cancelCode == userIAM_userAuth.Result.SUCCESS) { } catch (error) {
console.info("cancel auth success"); console.log("subscribe authentication event failed " + error);
} else { }
console.error("cancel auth fail");
} // 开始认证
try {
auth.start();
console.info("authV9 start auth success");
} catch (error) {
console.info("authV9 start auth failed, error = " + error);
}
// 取消认证
try {
auth.cancel();
console.info("cancel auth success");
} catch (error) {
console.info("cancel auth failed, error = " + error);
} }
}
```
// 取消订阅认证结果
try {
auth.off("result");
console.info("cancel subscribe authentication event success");
} catch (error) {
console.info("cancel subscribe authentication event failed, error = " + error);
}
```
zh-cn/readme/用户IAM子系统.md
浏览文件 @ 5bbfd682
...@@ -2,7 +2,7 @@ ...@@ -2,7 +2,7 @@
## 简介 ## 简介
用户身份和访问管理子系统，下称用户IAM（Identity and Access Management），旨在为OpenHarmony提供统一用户身份凭据信息管理和用户身份认证框架能力，支持多用户分别设置认证凭据信息，并根据用户设置的认证凭据信息提供用户身份认证功能，支撑锁屏等安全场景。同时，用户IAM子系统也提供API，支持三方开发者调用系统提供的身份认证能力来实现业务对用户的访问控制要求。 用户身份和访问管理子系统，下称用户IAM（Identity and Access Management），旨在为OpenHarmony提供统一用户身份凭据管理和身份认证的能力，支持多用户分别设置凭据信息，并根据用户设置的凭据信息提供用户身份认证功能，支撑锁屏和支付等安全场景。同时，用户IAM子系统也提供对外的接口供三方应用调用，实现业务对用户的访问控制要求。
**图1** 子系统架构图 **图1** 子系统架构图
...@@ -14,16 +14,15 @@ ...@@ -14,16 +14,15 @@
- **用户身份凭据管理：** 向上提供系统内统一的用户身份凭据信息管理接口，向下通过认证执行器管理模块，调用系统内的认证资源，完成用户身份凭据的生命周期管理和安全存储。 - **用户身份凭据管理：** 向上提供系统内统一的用户身份凭据信息管理接口，向下通过认证执行器管理模块，调用系统内的认证资源，完成用户身份凭据的生命周期管理和安全存储。
- **认证执行器管理：** 提供认证资源管理和认证会话管理功能，支持系统内身份认证相关**执行器**<sup>注</sup>统一管理和协同调度，支持不同类型的身份认证执行器灵活对接。 - **认证执行器管理：** 提供认证资源管理和认证会话管理功能，支持系统内身份认证相关**执行器**<sup>注</sup>统一管理和协同调度，支持不同类型的身份认证执行器灵活对接。
基于统一用户认证框架，系统可以扩展支持多种认证能力。OpenHarmony框架当前已经支持的**认证执行器**包含口令认证和人脸认证，开发者如果想实现新的认证执行器，只需要在新的部件内实现认证相关功能，并且按照执行器管理模块定义的接口与统一用户认证框架对接即可。 基于统一用户认证框架，系统可以扩展支持多种认证能力。OpenHarmony框架当前已经支持的**认证执行器**包含口令执行器和人脸执行器，开发者如果想实现新的认证执行器，只需要在新的部件内实现认证相关功能，并且按照执行器管理模块定义的接口与统一用户认证框架对接即可。
*注：在用户IAM子系统内，将一个用户身份认证操作的最小执行单元称为**执行器**，如一个口令认证模块，处理口令采集、口令处理和比对、口令安全存储的全过程，因此可以抽象为一个口令认证的全功能执行器。* *注：在用户IAM子系统内，将一个用户身份认证操作的最小执行单元称为**执行器**，如一个口令认证模块，包含口令采集、处理、安全存储和口令比对的全过程，因此可以抽象为一个口令认证的全功能执行器。*
## 目录 ## 目录
```undefined ```undefined
//base/user_iam //base/useriam
├── user_auth_framework # 用户认证框架，包括用户认证、凭据管理和执行器管理 ├── user_auth_framework # 用户认证框架，包括用户认证、凭据管理和执行器管理
├── face_auth # 人脸认证部件，与认证执行器管理对接，支持人脸录入、删除和人脸认证功能 ├── face_auth # 人脸认证部件，与认证执行器管理对接，支持人脸录入、删除和人脸认证功能
├── pin_auth # 口令认证部件，与认证执行器管理对接，支持口令录入、删除和口令认证功能 ├── pin_auth # 口令认证部件，与认证执行器管理对接，支持口令录入、删除和口令认证功能
...@@ -31,7 +30,7 @@ ...@@ -31,7 +30,7 @@
## 约束 ## 约束
1. 用户身份凭据信息管理类操作，是系统内的关键操作，相关接口只支持系统基础应用调用。 1. 用户身份凭据信息管理类操作，是系统内的关键操作，相关接口只支持系统基础应用的调用。
2. 执行器内部真正完成用户凭据信息的处理，因此只支持系统服务实现执行器的功能，与认证执行器管理模块对接。 2. 执行器内部真正完成用户凭据信息的处理，因此只支持系统服务实现执行器的功能，与认证执行器管理模块对接。
## 说明 ## 说明
...@@ -39,7 +38,7 @@ ...@@ -39,7 +38,7 @@
### 使用说明 ### 使用说明
1. 统一用户认证框架必须配合一个认证执行器才可以使用。 1. 统一用户认证框架必须配合一个认证执行器才可以使用。
2. 系统内默认存在的第一个认证执行器应该是口令执行器。 2. 系统内默认存在的第一个认证执行器是口令执行器。
## 相关仓 ## 相关仓
......
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或