Skip to content

D
Docs

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

通知 159
Star 292
Fork 28
D
Docs

体验新版 GitCode，发现更多精彩内容 >>

未验证 提交 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()
| 类型 | 说明 |
| ---------------------- | -------------------- |
| [FaceAuthManager](#faceauthmanager) | 人脸认证管理器对象 |
| [FaceAuthManager](#faceauthmanager) | 人脸认证管理器对象。 |
**示例：**
```js
import userIAM_faceAuth from '@ohos.userIAM.faceAuth';
```js
import userIAM_faceAuth from '@ohos.userIAM.faceAuth';
let faceAuthManager = new userIAM_faceAuth.FaceAuthManager();
```
let faceAuthManager = new userIAM_faceAuth.FaceAuthManager();
```
### setSurfaceId
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
......@@ -56,17 +56,28 @@ setSurfaceId(surfaceId: string): void;
| -------------- | ---------------------------------- | ---- | -------------------------- |
| 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
import faceAuth from '@ohos.userIAM.faceAuth';
let surfaceId = "123456";
let manager = new faceAuth.FaceAuthManager();
try {
manager.setSurfaceId(surfaceId);
console.info("set surface id success");
} catch (e) {
console.error("set surface id failed, error = " + e);
}
```
```js
import userIAM_faceAuth from '@ohos.userIAM.faceAuth';
// 该surfaceId应该从XComponent控件获取，此处仅用作示例。
let surfaceId = "123456";
let manager = new userIAM_faceAuth.FaceAuthManager();
try {
manager.setSurfaceId(surfaceId);
console.info("set surface id success");
} catch (e) {
console.error("set surface id failed, error = " + e);
}
```
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** 用户认证开放能力列表
| 接口名 | 功能描述 |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| getVersion() : number | 获取认证对象的版本信息。 |
| getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel) : number | 根据指定的认证类型、认证等级，检测当前设备是否支持相应的认证能力。 |
| auth(challenge: Uint8Array, authType: UserAuthType, authTrustLevel: AuthTrustLevel, callback: IUserAuthCallback): Uint8Array | 执行用户认证，使用callback方式作为异步方法。 |
| cancelAuth(contextID : Uint8Array) : number | 通过contextID取消本次认证操作。 |
## 开发步骤
开发前请完成以下准备工作：
1. 在应用配置权限文件中，增加ohos.permission.ACCESS_BIOMETRIC的权限声明。
2. 在使用用户认证能力的代码文件中增加import userIAM_userAuth from '@ohos.userIAM.userAuth'。
开发过程：
1. 获取Authenticator的单例对象，代码示例如下：
```js
let auth = new userIAM_userAuth.UserAuth();
```
2. （可选）获取认证对象的版本信息，代码示例如下：
```js
let auth = new userIAM_userAuth.UserAuth();
let version = auth.getVersion();
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);
if (checkCode == userIAM_userAuth.ResultCode.SUCCESS) {
console.info("check auth support success");
// 此处添加支持指定类型认证的逻辑
} else {
console.error("check auth support fail, code = " + checkCode);
// 此处添加不支持指定类型认证的逻辑
}
```
4. 执行认证操作，代码示例如下：
```js
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) {
// 此处添加认证成功逻辑
} 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);
}
}
});
```
5. 认证过程中取消认证，代码示例如下：
```js
let auth = new userIAM_userAuth.UserAuth();
// 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 = auth.cancel(contextId);
if (cancelCode == userIAM_userAuth.ResultCode.SUCCESS) {
console.info("cancel auth success");
} else {
console.error("cancel auth fail");
}
```
| 接口名称 | 功能描述 |
| ---------- | ----------------------- |
| getVersion() : number | 获取认证对象的版本信息。 |
| getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel): void | 根据指定的认证类型、认证等级，检测当前设备是否支持相应的认证能力。 |
| getAuthInstance(challenge : Uint8Array, authType : UserAuthType, authTrustLevel : AuthTrustLevel): AuthInstance | 获取AuthInstance对象，用于执行用户身份认证。 |
| on(name : AuthEventKey, callback : AuthEvent) : void | 订阅指定类型的用户认证事件。 |
| off(name : AuthEventKey) : void | 取消订阅特定类型的认证事件。 |
| start: void | 执行用户认证。 |
| cancel: void | 取消本次认证操作。 |
## 获取认证对象的版本信息
### 开发步骤
1. 申请权限。调用[getVersion](../reference/apis/js-apis-useriam-userauth.md#useriam_userauthgetversion9)接口，需要在module.json5文件的requestPermissions对象中配置ohos.permission.ACCESS_BIOMETRIC权限。更多配置信息[应用包结构配置文件的说明](../quick-start/stage-structure.md)。
2. 调用[getVersion](../reference/apis/js-apis-useriam-userauth.md#useriam_userauthgetversion9)接口获取版本信息。
```js
import userIAM_userAuth from '@ohos.userIAM.userAuth';
// 获取版本信息
try {
let version = userIAM_userAuth.getVersion();
console.info("auth version = " + version);
} catch (error) {
console.info("get version failed, error = " + error);
}
```
## 查询当前设备是否支持相应的认证能力
### 开发步骤
1. 申请权限。调用[getAvailableStatus](../reference/apis/js-apis-useriam-userauth.md#useriam_userauthgetavailablestatus9)接口，需要在module.json5文件的requestPermissions对象中配置ohos.permission.ACCESS_BIOMETRIC权限。更多配置信息[应用包结构配置文件的说明](../quick-start/stage-structure.md)。
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)接口查询当前的设备是否支持相应的认证能力。
```js
import userIAM_userAuth from '@ohos.userIAM.userAuth';
// 查询认证能力是否支持
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);
}
```
## 执行认证操作并请阅认证结果
### 开发步骤
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("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);
}
});
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("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。
- 要求设备上具有TEE安全环境，人脸特征信息高强度加密保存在TEE中。
- 当前版本提供的用户认证能力包含人脸识别和指纹识别，且只支持本地认证，不提供认证界面。
- 要求设备上具备相应的生物特征采集器，且对于人脸识别要求人脸图像分辨率大于100*100。
- 要求设备上具有TEE安全环境，人脸和指纹等生物特征信息高强度加密保存在TEE中。
- 对于面部特征相似的人、面部特征不断发育的儿童，人脸特征匹配率有所不同。如果对此担忧，可考虑其他认证方式。
\ No newline at end of file
zh-cn/device-dev/driver/driver-peripherals-face_auth-des.md
浏览文件 @ 5bbfd682
......@@ -6,7 +6,7 @@
人脸识别功能是端侧设备不可或缺的一部分，为设备提供一种用户认证能力，可应用于设备解锁、支付、应用登录等身份认证场景。它是基于人的脸部特征信息进行身份识别的一种生物特征识别技术，用摄像机或摄像头采集含有人脸的图像或视频流，并自动在图像中检测和跟踪人脸，进而对检测到的人脸进行脸部识别，通常也叫做人像识别、面部识别、人脸认证。人脸识别功能整体框架如图1。
基于HDF（Hardware Driver Foundation）驱动框架开发的Face_auth驱动，能够屏蔽硬件器件差异，为上层用户认证框架和Face_auth服务提供稳定的人脸识别基础能力接口，包括人脸识别执行器列表查询、执行器信息查询、指定人脸模板ID查询模板信息、用户认证框架和执行器间的人脸模板信息对账、人脸的录入，删除，认证和识别等。
基于HDF（Hardware Driver Foundation）驱动框架开发的Face_auth驱动，能够屏蔽硬件器件差异，为上层用户认证框架和Face_auth服务提供稳定的人脸识别基础能力接口，包括人脸识别执行器列表查询、执行器信息查询、指定人脸模板ID查询模板信息、用户认证框架和执行器间的人脸模板信息对账、人脸录入、删除、认证和识别等。
**图1** 人脸识别功能整体框架
......@@ -21,7 +21,7 @@
- 执行器安全等级
执行器提供能力时运行环境所达到的安全级别。
执行器提供能力时所在运行环境达到的安全级别。
- 执行器角色
......@@ -51,6 +51,22 @@
用户认证框架统一管理用户身份和凭据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服务提供稳定的人脸识别基础能力，保证设备上人脸识别功能可以正常运行。
......@@ -74,24 +90,28 @@ Face_auth驱动的主要工作是为上层用户认证框架和Face_auth服务
### 接口说明
注：以下接口列举的为IDL接口描述生成的对应C++语言函数接口，接口声明见idl文件（/drivers/interface/face_auth/v1_0/）。
在本文中，人脸凭据的录入、认证、识别和删除相关的HDI接口如表1所示，表2中的回调函数分别用于人脸执行器返回操作结果给框架和返回操作过程中的提示信息给上层应用。
**表1** 接口功能介绍
| 接口名 | 功能介绍 |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| GetExecutorList(std::vector<sptr<IExecutor>>& executorList) | 获取执行器列表。 |
| GetExecutorInfo(ExecutorInfo& info) | 获取执行器信息，包括执行器类型、执行器角色、认证类型、安全等级、执行器公钥等信息，用于向用户认证框架注册执行器。 |
| GetTemplateInfo(uint64_t templateId, TemplateInfo& info) | 获取指定人脸模板ID的模板信息。 |
| 接口名称 | 功能介绍 |
| ----------------------------------- | ---------------------------------- |
| GetExecutorList(std::vector<sptr<IExecutor>>& executorList) | 获取执行器列表。 |
| GetExecutorInfo(ExecutorInfo& info) | 获取执行器信息，包括执行器类型、执行器角色、认证类型、安全等级、执行器公钥等信息，用于向用户认证框架注册执行器。 |
| 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) | 执行器注册成功后，获取用户认证框架的公钥信息；获取用户认证框架的人脸模板列表用于对账。 |
| 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) | 认证人脸模板。 |
| 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) | 认证人脸模板。 |
| Identify(uint64_t scheduleId, const std::vector<uint8_t>& extraInfo,<br/> const sptr<IExecutorCallback>& callbackObj) | 识别人脸模板。 |
| Delete(const std::vector<uint64_t>& templateIdList) | 删除人脸模板。 |
| Cancel(uint64_t scheduleId) | 通过scheduleId取消指定录入、认证、识别操作。 |
| Delete(const std::vector<uint64_t>& templateIdList) | 删除人脸模板。 |
| Cancel(uint64_t scheduleId) | 通过scheduleId取消指定录入、认证、识别操作。 |
| SendCommand(int32_t commandId, const std::vector<uint8_t>& extraInfo,<br/> const sptr<IExecutorCallback>& callbackObj) | 人脸认证服务向Face_auth驱动传递参数的通用接口。 |
**表2** 回调函数介绍
| 接口名 | 功能介绍 |
| 接口名称 | 功能介绍 |
| ------------------------------------------------------------ | ------------------------ |
| IExecutorCallback::OnResult(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服务
```undefined
// drivers/peripheral/face_auth
├── BUILD.gn # 编译脚本
├── bundle.json # 组件描述文件
└── hdi_service # Face_auth驱动实现
├── BUILD.gn # 编译脚本
├── include # 头文件
└── src
├── executor_impl.cpp # 认证、录入等功能接口实现
├── face_auth_interface_driver.cpp # Face_auth驱动入口
└── face_auth_interface_service.cpp # 获取执行器列表接口实现
├── BUILD.gn # 编译脚本
├── bundle.json # 组件描述文件
└── hdi_service # Face_auth驱动实现
├── BUILD.gn # 编译脚本
├── include # 头文件
└── src # 源文件
├── executor_impl.cpp # 认证、录入等功能接口实现
├── face_auth_interface_driver.cpp # Face_auth驱动入口
└── face_auth_interface_service.cpp # 获取执行器列表接口实现
```
下面结合DEMO实例介绍驱动开发的具体步骤。
......@@ -423,66 +443,59 @@ Face_auth驱动的主要工作是为上层用户认证框架和Face_auth服务
驱动开发完成后，通过[用户认证API接口](../../application-dev/reference/apis/js-apis-useriam-userauth.md)开发JS应用，基于Hi3516DV300平台验证。认证和取消功能验证的JS测试代码如下：
```js
// API version 8
import userIAM_userAuth from '@ohos.userIAM.userAuth';
let auth = new userIAM_userAuth.UserAuth();
export default {
getVersion() {
console.info("start get version");
let version = this.auth.getVersion();
console.info("auth version = " + version);
},
startAuth() {
console.info("start auth");
this.auth.auth(null, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, {
onResult: (result, extraInfo) => {
try {
console.info("auth onResult result = " + result);
console.info("auth onResult extraInfo = " + JSON.stringify(extraInfo));
if (result == 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);
}
}
});
},
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);
```js
// API version 9
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("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);
}
});
let cancelCode = this.auth.cancel(contextId);
if (cancelCode == userIAM_userAuth.ResultCode.SUCCESS) {
console.info("cancel auth success");
} else {
console.error("cancel auth fail");
}
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-fingerprint_auth-des.md
浏览文件 @ 5bbfd682
......@@ -21,7 +21,7 @@
- 执行器安全等级
执行器提供能力时运行环境所达到的安全级别。
执行器提供能力时所在运行环境达到的安全级别。
- 执行器角色
......@@ -53,15 +53,19 @@
- HAPs
HAPs（OpenHarmony Ability Packages），本章节中仅代表Fingerprint_auth驱动的上层应用。
HAPs（OpenHarmony Ability Packages），广义上指可以安装在OpenHarmony上的应用包，本章节中仅代表Fingerprint_auth驱动的上层应用。
- 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（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
### 接口说明
注：以下接口列举的为IDL接口描述生成的对应C++语言函数接口，接口声明见idl文件（/drivers/interface/fingerprint_auth/v1_0/）。
在本文中，指纹凭据的录入、认证、识别和删除相关的HDI接口如表1所示，表2中的回调函数分别用于指纹执行器返回操作结果给框架和返回操作过程中的提示信息给上层应用。
**表1** 接口功能介绍
| 接口名 | 功能介绍 |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| GetExecutorList(std::vector<sptr<IExecutor>>& executorList) | 获取执行器列表。 |
| 接口名称 | 功能介绍 |
| -------------------------------- | ----------------------------------- |
| GetExecutorList(std::vector<sptr<IExecutor>>& executorList) | 获取执行器列表。 |
| 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) | 执行器注册成功后，获取用户认证框架的公钥信息；获取用户认证框架的模板列表用于对账。 |
| 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) | 认证指纹模板。 |
| Identify(uint64_t scheduleId, const std::vector<uint8_t>& extraInfo,<br/> const sptr<IExecutorCallback>& callbackObj) | 识别指纹模板。 |
| Delete(const std::vector<uint64_t>& templateIdList) | 删除指纹模板。 |
| Cancel(uint64_t scheduleId) | 通过scheduleId取消指定录入、认证、识别操作。 |
| 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) | 识别指纹模板。 |
| Delete(const std::vector<uint64_t>& templateIdList) | 删除指纹模板。 |
| Cancel(uint64_t scheduleId) | 通过scheduleId取消指定录入、认证、识别操作。 |
| SendCommand(int32_t commandId, const std::vector<uint8_t>& extraInfo,<br/> const sptr<IExecutorCallback>& callbackObj) | 指纹认证服务向Fingerprint_auth驱动传递参数的通用接口。 |
**表2** 回调函数介绍
| 接口名 | 功能介绍 |
| 接口名称 | 功能介绍 |
| ------------------------------------------------------------ | ------------------------ |
| IExecutorCallback::OnResult(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
```undefined
// drivers/peripheral/fingerprint_auth
├── BUILD.gn # 编译脚本
├── bundle.json # 组件描述文件
└── hdi_service # Fingerprint_auth驱动实现
├── BUILD.gn # 编译脚本
├── include # 头文件
└── src
├── executor_impl.cpp # 认证、录入等功能接口实现
├── fingerprint_auth_interface_driver.cpp # Fingerprint_auth驱动入口
└── fingerprint_auth_interface_service.cpp # 获取执行器列表接口实现
├── BUILD.gn # 编译脚本
├── bundle.json # 组件描述文件
└── hdi_service # Fingerprint_auth驱动实现
├── BUILD.gn # 编译脚本
├── include # 头文件
└── src # 源文件
├── executor_impl.cpp # 认证、录入等功能接口实现
├── fingerprint_auth_interface_driver.cpp # Fingerprint_auth驱动入口
└── fingerprint_auth_interface_service.cpp # 获取执行器列表接口实现
```
下面结合DEMO实例介绍驱动开发的具体步骤。
......@@ -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测试代码如下：
```js
// API version 8
import userIAM_userAuth from '@ohos.userIAM.userAuth';
let auth = new userIAM_userAuth.UserAuth();
export default {
getVersion() {
console.info("start get version");
let version = this.auth.getVersion();
console.info("auth version = " + version);
},
startAuth() {
console.info("start auth");
// auth是开发者可以调用的API接口，开发者可以指定认证类型为FINGERPRINT，从而验证驱动是否向框架注册成功以及认证接口实现是否符合预期，result即为认证结果。
this.auth.auth(null, userIAM_userAuth.UserAuthType.FINGERPRINT, 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);
}
```js
// API version 9
import userIAM_userAuth from '@ohos.userIAM.userAuth';
let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
let authType = userIAM_userAuth.UserAuthType.FINGERPRINT;
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("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);
}
});
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 @@
- 执行器安全等级
执行器提供能力时运行环境所达到的安全级别。
执行器提供能力时所在运行环境达到的安全级别。
- 执行器角色
......@@ -52,6 +52,18 @@
用户认证框架统一管理用户身份和凭据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层接口的调用。
......@@ -61,7 +73,7 @@ Pin_auth驱动的主要工作是为上层用户认证框架和Pin_auth服务提
![image](figures/pin_auth服务与驱动交互.png "pin_auth服务与驱动交互")
### 约束与限制
口令认证的实现需要在TEE安全环境中实现，口令凭据等数据的保密信息需要在安全环境中存储。
口令认证的实现需要在TEE安全环境中实现，口令凭据等数据的加密信息需要在安全环境中存储。
## 开发指导
### 场景介绍
......@@ -69,24 +81,27 @@ Pin_auth驱动的主要工作是为上层用户认证框架和Pin_auth服务提
### 接口说明
注：以下接口列举的为IDL接口描述生成的对应C++语言函数接口，接口声明见idl文件（/drivers/interface/pin_auth/v1_0/）。
在本文中，口令凭据的录入、认证和删除相关的HDI接口如表1所示，表2中的回调函数分别用于口令执行器返回操作结果给框架和获取用户输入的口令信息。
**表1** 接口功能介绍
| 接口名 | 功能介绍 |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| GetExecutorList(std::vector<sptr<IExecutor>>& executorList) | 获取执行器列表。 |
| GetExecutorInfo(ExecutorInfo& info) | 获取执行器信息。 |
| GetTemplateInfo(uint64_t templateId, TemplateInfo& info) | 获取指定templateId的模板信息。 |
| 接口名称 | 功能介绍 |
| ------------------------------- | ------------------------------------------- |
| GetExecutorList(std::vector<sptr<IExecutor>>& executorList) | 获取执行器列表。 |
| GetExecutorInfo(ExecutorInfo& info) | 获取执行器信息。 |
| 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 列表用于对账。 |
| OnSetData(uint64_t scheduleId, uint64_t authSubType, <br/>const std::vector<uint8_t> &data) | 用于回调传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码认证。 |
| Delete(uint64_t templateId) | 删除pin码模板。 |
| Cancel(uint64_t scheduleId) | 通过scheduleId取消指定操作。 |
| SendCommand(int32_t commandId, const std::vector<uint8_t>& extraInfo,<br/>const sptr<IExecutorCallback>& callbackObj) | 预留接口。 |
| 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码。 |
| Authenticate(uint64_t scheduleId, uint64_t templateId, const std::vector<uint8_t>& extraInfo, const sptr<IExecutorCallback>& callbackObj) | pin码认证。 |
| Delete(uint64_t templateId) | 删除pin码模板。 |
| Cancel(uint64_t scheduleId) | 通过scheduleId取消指定操作。 |
| SendCommand(int32_t commandId, const std::vector<uint8_t>& extraInfo,<br/>const sptr<IExecutorCallback>& callbackObj) | 预留接口。 |
**表2** 回调函数介绍
| 接口名 | 功能介绍 |
| 接口名称 | 功能介绍 |
| ------------------------------------------------------------ | -------------------- |
| 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码数据信息。 |
......@@ -97,21 +112,21 @@ Pin_auth驱动的主要工作是为上层用户认证框架和Pin_auth服务提
```text
// drivers/peripheral/pin_auth
├── BUILD.gn # 编译脚本
├── bundle.json # 组件描述文件
├── test # 测试用例
└── hdi_service # Pin_auth驱动实现
├── BUILD.gn # 编译脚本
├── adaptor # 相关算法实现
├── common # 公共接口实现
├── database # 数据库实现
├── main # 口令相关功能实现入口
└── service # Pin_auth驱动实现入口
├── inc # 头文件
└── src
├── executor_impl.cpp # 认证、录入等功能接口实现
├── pin_auth_interface_driver.cpp # Pin_auth驱动入口
└── pin_auth_interface_service.cpp # 获取执行器列表接口实现
├── BUILD.gn # 编译脚本
├── bundle.json # 组件描述文件
├── test # 测试用例
└── hdi_service # Pin_auth驱动实现
├── BUILD.gn # 编译脚本
├── adaptor # 相关算法实现
├── common # 公共接口实现
├── database # 数据库实现
├── main # 口令相关功能实现入口
└── service # Pin_auth驱动实现入口
├── inc # 头文件
└── src # 源文件
├── executor_impl.cpp # 认证、录入等功能接口实现
├── pin_auth_interface_driver.cpp # Pin_auth驱动入口
└── pin_auth_interface_service.cpp # 获取执行器列表接口实现
```
下面结合DEMO实例介绍驱动开发的具体步骤。
......
zh-cn/device-dev/driver/driver-peripherals-user-auth-des.md
浏览文件 @ 5bbfd682
......@@ -21,7 +21,7 @@
- 认证凭据模板
认证凭据模板在用户设置认证凭据时由认证服务产生并存储。每个模板有一个ID，用于索引模板信息文件。在认证时，读取模板信息并用和当次认证过程中产生的认证数据做对比，完成身份认证。
认证凭据模板在用户设置认证凭据时由认证服务产生并存储。每个模板有一个ID，用于索引模板信息文件。在认证时，读取模板信息并和当次认证过程中产生的认证数据做对比，完成身份认证。
- 执行器
......@@ -41,11 +41,11 @@
- 执行器安全等级
执行器提供能力时运行环境所达到的安全级别，如操作运行在无访问控制安全等级低于操作运行硬件可信执行环境的安全等级。
执行器提供能力时所在运行环境达到的安全级别。
- 用户认证框架公钥 & 执行器公钥
用户身份认证处理需要保证用户数据安全以及认证结果的准确性，用户认证框架与基础认证服务间的关键交互信息需要做数据完整性保护，各基础认证服务将提供的执行器能力对接到用户认证框架时，需要交互各自的公钥，其中：
用户身份认证处理需要保证用户数据安全以及认证结果的准确性，用户认证框架与基础认证服务间的关键交互信息需要做数据完整性保护，各基础认证服务将提供的执行器能力对接到用户认证框架时，需要交换各自的公钥，其中：
- 执行器通过用户认证框架公钥校验调度指令的准确性，如锁定一个人脸模板，这种情况导致无法使用人脸功能，属于敏感操作，需要确保指令准确，才可处理。
......@@ -76,6 +76,18 @@
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服务提供认证执行器管理、认证凭据管理和认证方案生成管理等能力。
......@@ -97,31 +109,34 @@ User_auth驱动的主要工作是为User_auth服务提供稳定的用户凭据
### 接口说明
注：以下接口列举的为IDL接口描述生成的对应C++语言函数接口，接口声明见idl文件（/drivers/interface/user_auth/v1_0/）。
在本文中，执行器注册、凭据录入、凭据删除、用户认证和用户识别相关的HDI接口如表1所示。
**表1** 接口功能介绍
| 接口名 | 功能介绍 |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| Init() | 初始化缓存信息。 |
| AddExecutor(const ExecutorRegisterInfo& info, uint64_t& index, std::vector<uint8_t>& publicKey,<br/> std::vector<uint64_t>& templateIds) | 添加认证执行器，获得此认证能力。 |
| DeleteExecutor(uint64_t index) | 根据索引值index删除认证执行器。 |
| OpenSession(int32_t userId, std::vector<uint8_t>& challenge) | 开启认证凭据管理Session。 |
| CloseSession(int32_t userId) | 关闭认证凭据管理Session。 |
| 接口名称 | 功能介绍 |
| --------------------------- | --------------------------- |
| Init() | 初始化缓存信息。 |
| AddExecutor(const ExecutorRegisterInfo& info, uint64_t& index, std::vector<uint8_t>& publicKey,<br/> std::vector<uint64_t>& templateIds) | 添加认证执行器，获得此认证能力。 |
| DeleteExecutor(uint64_t index) | 根据索引值index删除认证执行器。 |
| OpenSession(int32_t userId, std::vector<uint8_t>& challenge) | 开启认证凭据管理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码。 |
| UpdateEnrollmentResult(int32_t userId, const std::vector<uint8_t>& scheduleResult, uint64_t& credentialId,<br/> CredentialInfo& oldInfo) | 更新录入结果，完成此次录入。 |
| CancelEnrollment(int32_t userId) | 取消此次录入。 |
| UpdateEnrollmentResult(int32_t userId, const std::vector<uint8_t>& scheduleResult, uint64_t& credentialId,<br/> CredentialInfo& oldInfo) | 更新录入结果，完成此次录入。 |
| CancelEnrollment(int32_t userId) | 取消此次录入。 |
| 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码即在用户认证框架中删除用户。 |
| 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。 |
| 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) | 更新认证结果，进行此次认证方案结果的评估。 |
| 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) | 发起识别，生成识别方案和调度信息。 |
| UpdateIdentificationResult(uint64_t contextId, const std::vector<uint8_t>& scheduleResult,<br/> IdentifyResultInfo& info) | 更新识别结果，进行此次识别方案结果的评估。 |
| CancelIdentification(uint64_t contextId) | 取消此次识别。 |
| 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) | 筛选此用户当前认证可信等级下可用认证方式。 |
| CancelIdentification(uint64_t contextId) | 取消此次识别。 |
| 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) | 筛选此用户当前认证可信等级下可用的认证方式。 |
### 开发步骤
......@@ -129,14 +144,14 @@ User_auth驱动的主要工作是为User_auth服务提供稳定的用户凭据
```undefined
// drivers/peripheral/user_auth
├── BUILD.gn # 编译脚本
├── bundle.json # 组件描述文件
└── hdi_service # User_auth驱动实现
├── BUILD.gn # 编译脚本
├── module # 功能实现
├── BUILD.gn # 编译脚本
├── bundle.json # 组件描述文件
└── hdi_service # User_auth驱动实现
├── BUILD.gn # 编译脚本
├── module # 功能实现
└── service
├── user_auth_interface_driver.cpp # User_auth驱动入口
└── user_auth_interface_service.cpp # 获取执行器列表接口实现
├── user_auth_interface_driver.cpp # User_auth驱动入口
└── user_auth_interface_service.cpp # 获取执行器列表接口实现
```
下面结合DEMO实例介绍驱动开发的具体步骤。
......@@ -494,66 +509,59 @@ User_auth驱动的主要工作是为User_auth服务提供稳定的用户凭据
驱动开发完成后，通过[用户认证API接口](../../application-dev/reference/apis/js-apis-useriam-userauth.md)开发JS应用，基于Hi3516DV300平台验证。认证和取消功能验证的JS测试代码如下：
```js
// API version 8
import userIAM_userAuth from '@ohos.userIAM.userAuth';
let auth = new userIAM_userAuth.UserAuth();
export default {
getVersion() {
console.info("start get version");
let version = this.auth.getVersion();
console.info("auth version = " + version);
},
startAuth() {
console.info("start auth");
this.auth.auth(null, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, {
onResult: (result, extraInfo) => {
try {
console.info("auth onResult result = " + result);
console.info("auth onResult extraInfo = " + JSON.stringify(extraInfo));
if (result == 'SUCCESS') {
// 此处添加认证成功逻辑
} 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);
}
}
});
},
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);
```js
// API version 9
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("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);
}
});
let cancelCode = this.auth.cancel(contextId);
if (cancelCode == userIAM_userAuth.Result.SUCCESS) {
console.info("cancel auth success");
} else {
console.error("cancel auth fail");
}
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/readme/用户IAM子系统.md
浏览文件 @ 5bbfd682
......@@ -2,7 +2,7 @@
## 简介
用户身份和访问管理子系统，下称用户IAM（Identity and Access Management），旨在为OpenHarmony提供统一用户身份凭据信息管理和用户身份认证框架能力，支持多用户分别设置认证凭据信息，并根据用户设置的认证凭据信息提供用户身份认证功能，支撑锁屏等安全场景。同时，用户IAM子系统也提供API，支持三方开发者调用系统提供的身份认证能力来实现业务对用户的访问控制要求。
用户身份和访问管理子系统，下称用户IAM（Identity and Access Management），旨在为OpenHarmony提供统一用户身份凭据管理和身份认证的能力，支持多用户分别设置凭据信息，并根据用户设置的凭据信息提供用户身份认证功能，支撑锁屏和支付等安全场景。同时，用户IAM子系统也提供对外的接口供三方应用调用，实现业务对用户的访问控制要求。
**图1** 子系统架构图
......@@ -14,16 +14,15 @@
- **用户身份凭据管理：** 向上提供系统内统一的用户身份凭据信息管理接口，向下通过认证执行器管理模块，调用系统内的认证资源，完成用户身份凭据的生命周期管理和安全存储。
- **认证执行器管理：** 提供认证资源管理和认证会话管理功能，支持系统内身份认证相关**执行器**<sup>注</sup>统一管理和协同调度，支持不同类型的身份认证执行器灵活对接。
基于统一用户认证框架，系统可以扩展支持多种认证能力。OpenHarmony框架当前已经支持的**认证执行器**包含口令认证和人脸认证，开发者如果想实现新的认证执行器，只需要在新的部件内实现认证相关功能，并且按照执行器管理模块定义的接口与统一用户认证框架对接即可。
基于统一用户认证框架，系统可以扩展支持多种认证能力。OpenHarmony框架当前已经支持的**认证执行器**包含口令执行器和人脸执行器，开发者如果想实现新的认证执行器，只需要在新的部件内实现认证相关功能，并且按照执行器管理模块定义的接口与统一用户认证框架对接即可。
*注：在用户IAM子系统内，将一个用户身份认证操作的最小执行单元称为**执行器**，如一个口令认证模块，处理口令采集、口令处理和比对、口令安全存储的全过程，因此可以抽象为一个口令认证的全功能执行器。*
*注：在用户IAM子系统内，将一个用户身份认证操作的最小执行单元称为**执行器**，如一个口令认证模块，包含口令采集、处理、安全存储和口令比对的全过程，因此可以抽象为一个口令认证的全功能执行器。*
## 目录
```undefined
//base/user_iam
├── user_auth_framework # 用户认证框架，包括用户认证、凭据管理和执行器管理
//base/useriam
├── user_auth_framework # 用户认证框架，包括用户认证、凭据管理和执行器管理
├── face_auth # 人脸认证部件，与认证执行器管理对接，支持人脸录入、删除和人脸认证功能
├── pin_auth # 口令认证部件，与认证执行器管理对接，支持口令录入、删除和口令认证功能
......@@ -31,7 +30,7 @@
## 约束
1. 用户身份凭据信息管理类操作，是系统内的关键操作，相关接口只支持系统基础应用调用。
1. 用户身份凭据信息管理类操作，是系统内的关键操作，相关接口只支持系统基础应用的调用。
2. 执行器内部真正完成用户凭据信息的处理，因此只支持系统服务实现执行器的功能，与认证执行器管理模块对接。
## 说明
......@@ -39,7 +38,7 @@
### 使用说明
1. 统一用户认证框架必须配合一个认证执行器才可以使用。
2. 系统内默认存在的第一个认证执行器应该是口令执行器。
2. 系统内默认存在的第一个认证执行器是口令执行器。
## 相关仓
......
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或