!1223 新增用户认证相关开发文档

Merge pull request !1223 from zengyawen/master

!1223 新增用户认证相关开发文档
Merge pull request !1223 from zengyawen/master
6b6f38f5 · openharmony_ci · Gitee · 3f9e4316 · feb3132d · 6b6f38f5
6 changed file
--- a/zh-cn/application-dev/Readme-CN.md
+++ b/zh-cn/application-dev/Readme-CN.md
@@ -9,6 +9,7 @@
    -  [基于JS扩展的类Web开发范式](ui/ui-arkui-js.md)
    -  [基于TS扩展的声明式开发范式](ui/ui-arkui-ts.md)
 - [音频](media/audio.md)
+- [用户认证](security/Readme-CN.md)
 - [IPC与RPC通信](connectivity/ipc-rpc.md)
 - [分布式数据服务](database/Readme-CN.md)
 - [USB服务](usb/Readme-CN.md)

--- a/zh-cn/application-dev/reference/apis/Readme-CN.md
+++ b/zh-cn/application-dev/reference/apis/Readme-CN.md
@@ -16,6 +16,8 @@
 - 媒体
    - [音频管理](js-apis-audio.md)
    - [音频播放和录制](js-apis-media.md)
+- 安全
+    - [用户认证](js-apis-useriam-userauth.md)
 - 数据管理
    - [轻量级存储](js-apis-data-storage.md)
    - [分布式数据管理](js-apis-distributed-data.md)

--- a/zh-cn/application-dev/reference/apis/js-apis-useriam-userauth.md
+++ b/zh-cn/application-dev/reference/apis/js-apis-useriam-userauth.md
+# 用户认证
+
+> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**
+> 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
+
+
+## 导入模块
+
+```
+import userIAM_userAuth from '@ohos.userIAM.userAuth';
+```
+
+
+## 权限列表
+
+ohos.permission.ACCESS_BIOMETRIC
+
+
+## 完整示例
+
+```
+import userIAM_userAuth from '@ohos.userIAM.userAuth';
+
+export default {
+    startAuth() {
+        console.info("start auth");
+        let tipCallback = (tip)=>{
+            console.info("receive tip: errorCode(" + tip.errorCode + ") code(" + tip.tipCode + ") event(" +
+                tip.tipEvent + ") info(" + tip.tipInfo + ")");
+            // 此处添加提示信息显示逻辑
+        };
+        let auth = userIAM_userAuth.getAuthenticator();
+        auth.on("tip", tipCallback);
+        auth.execute("FACE_ONLY", "S2").then((code)=>{
+            auth.off("tip", tipCallback);
+            console.info("auth success");
+            // 此处添加认证成功逻辑
+        }).catch((code)=>{
+            auth.off("tip", tipCallback);
+            console.error("auth fail, code = " + code);
+            // 此处添加认证失败逻辑
+        });
+    },
+
+    checkAuthSupport() {
+        console.info("start check auth support");
+        let auth = userIAM_userAuth.getAuthenticator();
+        let checkCode = auth.checkAvailability("FACE_ONLY", "S2");
+        if (checkCode == userIAM_userAuth.CheckAvailabilityResult.SUPPORTED) {
+            console.info("check auth support success");
+            // 此处添加支持指定类型认证的逻辑
+        } else {
+            console.error("check auth support fail, code = " + checkCode);
+            // 此处添加不支持指定类型认证的逻辑
+        }
+    },
+
+    cancelAuth() {
+        console.info("start cancel auth");
+        let auth = userIAM_userAuth.getAuthenticator();
+        let cancelCode = auth.cancel();
+        if (cancelCode == userIAM_userAuth.Result.SUCCESS) {
+            console.info("cancel auth success");
+        } else {
+            console.error("cancel auth fail");
+        }
+    }
+}
+```
+
+
+## userIAM_userAuth.getAuthenticator
+
+getAuthenticator(): Authenticator
+
+获取Authenticator对象，用于执行用户身份认证。<sup>6+</sup>
+
+获取Authenticator对象，用于检测设备身份认证能力、执行和取消用户身份认证，获取认证过程中的提示信息。<sup>7+</sup>
+
+- 返回值：
+  | 类型 | 说明 |
+  | -------- | -------- |
+  | [Authenticator](#authenticator) | 认证器对象。 |
+
+- 示例：
+  ```
+  let authenticator = userIAM_userAuth.getAuthenticator();
+  ```
+
+
+## Authenticator
+
+认证器对象。
+
+
+### execute
+
+execute(type: string, level: string, callback: AsyncCallback&lt;number&gt;): void
+
+执行用户认证，使用callback方式作为异步方法。
+
+- 参数：
+  | 参数名 | 类型 | 必填 | 说明 |
+  | -------- | -------- | -------- | -------- |
+  | type | string | 是 | 认证类型，当前只支持FACE_ONLY。<br/>ALL为预留参数，当前版本暂不支持ALL类型的认证。 |
+  | level | string | 是 | 安全级别，对应认证的安全级别，有效值为S1（最低）、S2、S3、S4（最高）。<br/>具备3D人脸识别能力的设备支持S3及以下安全级别的认证。<br/>具备2D人脸识别能力的设备支持S2及以下安全级别的认证。 |
+  | callback | AsyncCallback&lt;number&gt; | 否 | 回调函数。 |
+
+  callback返回值：
+
+  | 类型 | 说明 |
+  | -------- | -------- |
+  | number | 表示认证结果，参见[AuthenticationResult](#authenticationresult)。 |
+
+- 示例：
+  ```
+  authenticator.execute("FACE_ONLY", "S2", (code)=>{
+      if (code == userIAM_userAuth.AuthenticationResult.SUCCESS) {
+          console.info("auth success");
+          return;
+      }
+      console.error("auth fail, code = " + code);
+  })
+  ```
+
+
+### execute
+
+execute(type:string, level:string): Promise&lt;number&gt;
+
+执行用户认证，使用promise方式作为异步方法。
+
+- 参数：
+  | 参数名 | 类型 | 必填 | 说明 |
+  | -------- | -------- | -------- | -------- |
+  | type | string | 是 | 认证类型，当前只支持FACE_ONLY。<br/>ALL为预留参数，当前版本暂不支持ALL类型的认证。 |
+  | level | string | 是 | 安全级别，对应认证的安全级别，有效值为S1（最低）、S2、S3、S4（最高）。<br/>具备3D人脸识别能力的设备支持S3及以下安全级别的认证。<br/>具备2D人脸识别能力的设备支持S2及以下安全级别的认证。 |
+
+- 返回值：
+  | 类型 | 说明 |
+  | -------- | -------- |
+  | Promise&lt;number&gt; | 返回携带一个number的Promise。number&nbsp;为认证结果，参见[AuthenticationResult](#authenticationresult)。 |
+
+- 示例
+  ```
+  let authenticator = userIAM_userAuth.getAuthenticator();
+  authenticator.execute("FACE_ONLY", "S2").then((code)=>{
+      authenticator.off("tip", tipCallback);
+      console.info("auth success");
+  }).catch((code)=>{
+      authenticator.off("tip", tipCallback);
+      console.error("auth fail, code = " + code);
+  });
+  ```
+
+
+### cancel<sup>7+</sup>
+
+cancel(): number
+
+取消当前的认证流程。
+
+- 返回值：
+  | 类型 | 说明 |
+  | -------- | -------- |
+  | number | 返回取消当前认证的结果，参见[Result](#result7)。 |
+
+- 示例：
+  ```
+  let authenticator = userIAM_userAuth.getAuthenticator();
+  let cancelCode = authenticator.cancel();
+  if (cancelCode == userIAM_userAuth.Result.SUCCESS) {
+      console.info("cancel auth success");
+  } else {
+      console.error("cancel auth fail");
+  }
+  ```
+
+
+### checkAvailability<sup>7+</sup>
+
+checkAvailability(type: AuthType, level: SecureLevel): number
+
+根据指定的认证类型、安全等级，检测当前设备是否支持相应的认证能力。
+
+- 参数：
+  | 参数名 | 类型 | 必填 | 说明 |
+  | -------- | -------- | -------- | -------- |
+  | type | string | 是 | 认证类型，当前只支持FACE_ONLY。<br/>ALL为预留参数，当前版本暂不支持ALL类型的认证。 |
+  | level | string | 是 | 安全级别，对应认证的安全级别，有效值为S1（最低）、S2、S3、S4（最高）。<br/>具备3D人脸识别能力的设备支持S3及以下安全级别的认证。<br/>具备2D人脸识别能力的设备支持S2及以下安全级别的认证。 |
+
+- 返回值：
+  | 类型 | 说明 |
+  | -------- | -------- |
+  | number | 返回检测当前设备认证能力的结果，参见[CheckAvailabilityResult](#checkavailabilityresult7)。 |
+
+- 示例：
+  ```
+  let authenticator = userIAM_userAuth.getAuthenticator();
+  let checkCode = authenticator.checkAvailability("FACE_ONLY", "S2");
+  if (checkCode == userIAM_userAuth.CheckAvailabilityResult.SUPPORTED) {
+      console.info("check auth support success");
+  } else {
+      console.error("check auth support fail, code = " + checkCode);
+  }
+  ```
+
+
+### on<sup>7+</sup>
+
+on(type: "tip", callback: Callback&lt;Tip&gt;) : void;
+
+订阅指定类型的事件。
+
+- 参数：
+  | 参数名 | 类型 | 必填 | 说明 |
+  | -------- | -------- | -------- | -------- |
+  | type | string | 是 | 事件类型，当前只支持"tip"。在认证服务发送提示信息给调用者时，会触发此事件。 |
+  | callback | Callback&lt;Tip&gt; | 是 | 事件发生时的回调，当前只支持以Tip为参数的回调函数。 |
+
+- 示例：
+  ```
+  let authenticator = userIAM_userAuth.getAuthenticator();
+  let tipCallback = (tip)=>{
+      console.info("receive tip: errorCode(" + tip.errorCode + ") code(" + tip.tipCode +") event(" +
+          tip.tipEvent + ") info(" + tip.tipInfo + ")");
+  };
+  authenticator.on("tip", tipCallback);
+  ```
+
+
+### off<sup>7+</sup>
+
+off(type: "tip", callback?: Callback&lt;Tip&gt;) : void;
+
+取消订阅指定类型的事件。
+
+- 参数：
+  | 参数名 | 类型 | 必填 | 说明 |
+  | -------- | -------- | -------- | -------- |
+  | type | string | 是 | 事件类型，当前只支持"tip"。 |
+  | callback | Callback&lt;Tip&gt; | 否 | 取消订阅的回调函数，当前只支持以Tip为参数的回调函数。如未指定此参数，同事件类型的所有回调都会被取消。 |
+
+- 示例：
+  ```
+  let authenticator = userIAM_userAuth.getAuthenticator();
+  let tipCallback = (tip)=>{
+      console.info("receive tip: errorCode(" + tip.errorCode + ") code(" + tip.tipCode + ") event(" +
+          tip.tipEvent + ") info(" + tip.tipInfo + ")");
+  };
+  // 取消订阅指定回调
+  authenticator.off("tip", tipCallback);
+  
+  // 取消订阅所有回调
+  authenticator.off("tip");
+  ```
+
+
+## AuthenticationResult
+
+表示认证结果的枚举。
+
+| 名称 | 默认值 | 描述 |
+| -------- | -------- | -------- |
+| NO_SUPPORT | -1 | 设备不支持当前的认证方式。 |
+| SUCCESS | 0 | 认证成功。 |
+| COMPARE_FAILURE | 1 | 比对失败。 |
+| CANCELED | 2 | 用户取消认证。 |
+| TIMEOUT | 3 | 认证超时。 |
+| CAMERA_FAIL | 4 | 开启相机失败。 |
+| BUSY | 5 | 认证服务忙，请稍后重试。 |
+| INVALID_PARAMETERS | 6 | 认证参数无效。 |
+| LOCKED | 7 | 认证失败次数过多，已锁定。 |
+| NOT_ENROLLED | 8 | 未录入认证凭据。 |
+| GENERAL_ERROR | 100 | 其他错误。 |
+
+
+## Tip<sup>7+</sup>
+
+表示认证过程中提示信息的对象。
+
+| 名称 | 参数类型 | 必填 | 说明 |
+| -------- | -------- | -------- | -------- |
+| errorCode | number | 是 | 是否成功获取到提示信息，参考[Result](#result7)。 |
+| tipEvent | number | 是 | 认证提示事件,&nbsp;参考[TipEvent](#tipevent7)。当前只支持RESULT、ACQUIRE。 |
+| tipCode | number | 是 | 认证提示的事件提示码。<br/>-&nbsp;当tipEvent为RESULT时，含义为认证结果，参考[AuthenticationResult](#authenticationresult)。<br/>-&nbsp;当tipEvent为ACQUIRE时，含义为提示信息，参考[TipCode](#tipcode7)。 |
+| tipInfo | string | 是 | 认证提示的事件提示码的描述信息。 |
+
+
+## Result<sup>7+</sup>
+
+表示执行结果的枚举。
+
+| 名称 | 默认值 | 描述 |
+| -------- | -------- | -------- |
+| SUCCESS | 0 | 执行成功。 |
+| FAILED | 1 | 执行失败。 |
+
+
+## CheckAvailabilityResult<sup>7+</sup>
+
+表示检测设备认证能力结果的枚举。
+
+| 名称 | 默认值 | 描述 |
+| -------- | -------- | -------- |
+| SUPPORTED | 0 | 设备支持指定的认证类型和认证安全等级。 |
+| AUTH_TYPE_NOT_SUPPORT | 1 | 设备不支持指定的认证类型。 |
+| SECURE_LEVEL_NOT_SUPPORT | 2 | 设备不支持指定的认证安全等级。 |
+| DISTRIBUTED_AUTH_NOT_SUPPORT | 3 | 设备不支持分布式认证。 |
+| NOT_ENROLLED | 4 | 设备中认证凭据未录入。 |
+| PARAM_NUM_ERROR | 5 | 参数个数错误。 |
+
+
+## TipEvent<sup>7+</sup>
+
+表示认证过程中提示事件的枚举。
+
+| 名称 | 默认值 | 描述 |
+| -------- | -------- | -------- |
+| RESULT | 1 | 录入或认证结果。 |
+| CANCEL | 2 | 录入或认证取消。 |
+| ACQUIRE | 3 | 录入或认证过程中提示。 |
+| BUSY | 4 | 录入或认证功能被占用。 |
+| OUT_OF_MEM | 5 | 内存不足。 |
+| FACE_ID | 6 | 人脸认证凭据索引号。 |
+
+
+## TipCode<sup>7+</sup>
+
+表示认证过程中提示码的枚举。
+
+| 名称 | 默认值 | 描述 |
+| -------- | -------- | -------- |
+| FACE_AUTH_TIP_TOO_BRIGHT | 1 | 光线太强，获取的图像太亮。 |
+| FACE_AUTH_TIP_TOO_DARK | 2 | 光线太暗，获取的图像太暗。 |
+| FACE_AUTH_TIP_TOO_CLOSE | 3 | 人脸距离设备过近。 |
+| FACE_AUTH_TIP_TOO_FAR | 4 | 人脸距离设备过远。 |
+| FACE_AUTH_TIP_TOO_HIGH | 5 | 设备太高，仅获取到的人脸上部。 |
+| FACE_AUTH_TIP_TOO_LOW | 6 | 设备太低，仅获取到的人脸下部。 |
+| FACE_AUTH_TIP_TOO_RIGHT | 7 | 设备太靠右，仅获取到的人脸右部。 |
+| FACE_AUTH_TIP_TOO_LEFT | 8 | 设备太靠左，仅获取到的人脸左部。 |
+| FACE_AUTH_TIP_TOO_MUCH_MOTION | 9 | 在图像采集过程中，用户人脸移动太快。 |
+| FACE_AUTH_TIP_POOR_GAZE | 10 | 没有正视摄像头。 |
+| FACE_AUTH_TIP_NOT_DETECTED | 11 | 没有检测到人脸信息。 |
--- a/zh-cn/application-dev/security/Readme-CN.md
+++ b/zh-cn/application-dev/security/Readme-CN.md
+# 安全
+
+- 用户认证
+  - [用户认证开发概述](userauth-overview.md)
+  - [用户认证开发指导](userauth-guidelines.md)
\ No newline at end of file
--- a/zh-cn/application-dev/security/userauth-guidelines.md
+++ b/zh-cn/application-dev/security/userauth-guidelines.md
+# 用户认证开发指导
+
+## 场景介绍
+
+当前用户认证支持2D人脸识别、3D人脸识别，可应用于设备解锁、应用登录、支付等身份认证场景。
+
+## 接口说明
+
+userIAM_userAuth模块提供了用户认证的相关方法，包括检测认证能力、认证和取消认证等，用户可以通过人脸等生物特征信息进行认证操作。具体接口说明可以查阅[API参考](../reference/apis/js-apis-useriam-userauth.md)。
+
+在执行认证前，需要检查设备是否支持该认证能力，具体指认证类型、安全级别和是否本地认证。如果不支持，需要考虑使用其他认证能力。
+
+**表1** 用户认证开放能力列表
+
+| 接口名                                                       | 功能描述                                                     |
+| ------------------------------------------------------------ | ------------------------------------------------------------ |
+| getAuthenticator(): Authenticator                            | 获取Authenticator对象，用于执行用户身份认证。<sup>6+</sup><br>获取Authenticator对象，用于检测设备身份认证能力、执行和取消用户身份认证，获取认证过程中的提示信息。<sup>7+</sup> |
+| checkAvailability(type: AuthType, level: SecureLevel): number | 根据指定的认证类型、安全等级，检测当前设备是否支持相应的认证能力。 |
+| execute(type: AuthType, level: SecureLevel, callback: AsyncCallback\<number>): void | 执行用户认证，使用callback方式作为异步方法。                 |
+| execute(type: AuthType, level: SecureLevel): Promise\<number> | 执行用户认证，使用Promise方式作为异步方法。                  |
+| cancel(): void                                               | 取消当前的认证流程。                                         |
+| on(type: "tip", callback: Callback\<Tip>): void              | 订阅指定类型的事件。                                         |
+| off(type: "tip", callback?: Callback\<Tip>): void            | 取消订阅指定类型的事件。                                     |
+
+## 开发步骤
+
+开发前请完成以下准备工作：
+
+1. 在应用配置权限文件中，增加ohos.permission.ACCESS_BIOMETRIC的权限声明。
+2. 在使用用户认证能力的代码文件中增加import userIAM_userAuth from '@ohos.userIAM.userAuth'。
+
+开发过程：
+
+1. 获取Authenticator的单例对象，代码示例如下：
+
+   ```js
+   let auth = userIAM_userAuth.getAuthenticator();
+   ```
+
+2. 检测设备是否具有指定级别的认证能力：
+
+   2D人脸识别支持低于S2级别的认证，3D人脸识别支持低于S3级别的认证。代码示例如下：
+
+   ```js
+   let authenticator = userIAM_userAuth.getAuthenticator();
+   let checkCode = authenticator.checkAvailability("FACE_ONLY", "S2");
+   if (checkCode == userIAM_userAuth.CheckAvailabilityResult.SUPPORTED) {
+       console.info("check auth support success");
+   } else {
+       console.error("check auth support fail, code = " + checkCode);
+   }
+   ```
+
+3. （可选）订阅人脸tip信息，代码示例如下：
+
+   ```js
+   let authenticator = userIAM_userAuth.getAuthenticator();
+   let tipCallback = (tip)=>{
+       console.info("receive tip: errorCode(" + tip.errorCode + ") code(" + tip.tipCode +") event(" +
+           tip.tipEvent + ") info(" + tip.tipInfo + ")");
+   };
+   authenticator.on("tip", tipCallback);
+   ```
+
+4. 执行认证操作，代码示例如下：
+
+   ```js
+   let authenticator = userIAM_userAuth.getAuthenticator();
+   authenticator.execute("FACE_ONLY", "S2").then((code)=>{
+       authenticator.off("tip", tipCallback);
+       console.info("auth success");
+   }).catch((code)=>{
+       authenticator.off("tip", tipCallback);
+       console.error("auth fail, code = " + code);
+   });
+   ```
+
+5. （仅执行订阅信息后需要）取消订阅人脸tip信息：
+
+   ```js
+   let authenticator = userIAM_userAuth.getAuthenticator();
+   let tipCallback = (tip)=>{
+       console.info("receive tip: errorCode(" + tip.errorCode + ") code(" + tip.tipCode + ") event(" +
+           tip.tipEvent + ") info(" + tip.tipInfo + ")");
+   };
+   // 取消订阅指定回调
+   authenticator.off("tip", tipCallback);
+   // 取消订阅所有回调authenticator.off("tip");
+   ```
+
+6. 认证过程中取消认证，代码示例如下：
+
+   ```js
+   let authenticator = userIAM_userAuth.getAuthenticator();
+   let cancelCode = authenticator.cancel();
+   if (cancelCode == userIAM_userAuth.Result.SUCCESS) {
+       console.info("cancel auth success");
+   } else {
+       console.error("cancel auth fail");
+   }
+   ```
\ No newline at end of file
--- a/zh-cn/application-dev/security/userauth-overview.md
+++ b/zh-cn/application-dev/security/userauth-overview.md
+# 用户认证开发概述
+
+提供用户认证能力，可应用于设备解锁、支付、应用登录等身份认证场景。
+
+当前用户认证能力提供2D人脸识别、3D人脸识别两种人脸识别能力，设备具备哪种识别能力，取决于设备的硬件能力和技术实现。
+
+3D人脸识别技术识别率、防伪能力都优于2D人脸识别技术，但具有3D人脸能力（比如3D结构光、3D TOF等）的设备才可以使用3D人脸识别技术。
+
+## 基本概念
+
+人脸识别：基于人的脸部特征信息进行身份识别的一种生物特征识别技术，用摄像机或摄像头采集含有人脸的图像或视频流，并自动在图像中检测和跟踪人脸，进而对检测到的人脸进行脸部识别，通常也叫做人像识别、面部识别、人脸认证。
+
+## 运作机制
+
+人脸识别会在摄像头和TEE（Trusted Execution Environment）之间建立安全通道，人脸图像信息通过安全通道传递到TEE中，由于人脸图像信息从REE（Rich Execution Environment）侧无法获取，从而避免了恶意软件从REE侧进行攻击。对人脸图像采集、特征提取、活体检测、特征比对等处理完全在TEE中，基于TrustZone进行安全隔离，外部的人脸框架只负责人脸的认证发起和处理认证结果等数据，不涉及人脸数据本身。
+
+人脸特征数据通过TEE的安全存储区进行存储，采用高强度的密码算法对人脸特征数据进行加密和完整性保护，外部无法获取到加密人脸特征数据的密钥，保证用户的人脸特征数据不会泄露。本能力采集和存储的人脸特征数据不会在用户未授权的情况下被传出TEE，这意味着，用户未授权时，无论是系统应用还是三方应用都无法获得人脸特征数据，也无法将人脸特征数据传送或备份到任何外部存储介质。
+
+## 约束与限制
+
+- 当前版本提供的用户认证能力只包含人脸识别，且只支持本地认证，不提供认证界面。
+- 要求设备上具备摄像器件，且人脸图像像素大于100*100。
+- 要求设备上具有TEE安全环境，人脸特征信息高强度加密保存在TEE中。
+- 对于面部特征相似的人、面部特征不断发育的儿童，人脸特征匹配率有所不同。如果对此担忧，可考虑其他认证方式。
\ No newline at end of file