Skip to content

D
Docs

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

通知 161
Star 293
Fork 28
D
Docs
提交 e876fcc7 编写于 作者: Y youliang_1314
浏览文件
操作

update iam 

Signed-off-by: Nyouliang_1314 <youliang4@huawei.com>
上级 a572afec
显示空白变更内容
内联 并排
Showing with 333 addition and 247 deletion
zh-cn/application-dev/reference/apis/js-apis-useriam-faceauth.md
浏览文件 @ e876fcc7
......@@ -56,6 +56,12 @@ setSurfaceId(surfaceId: string): void;
| -------------- | ---------------------------------- | ---- | -------------------------- |
| surfaceId | string | 是 | [XComponent](../arkui-ts/ts-basic-components-xcomponent.md#getxcomponentsurfaceid) 持有 Surface 的 ID。 |
| 错误码ID | 错误信息 |
| -------- | ------- |
| 201 | Permission verification failed. |
| 202 | The caller is not a system application. |
| 12700001 | The operation is failed. |
**示例：**
```js
......@@ -70,13 +76,3 @@ setSurfaceId(surfaceId: string): void;
console.error("set surface id failed, error = " + e);
}
```
## ResultCode
表示执行结果的枚举。
**系统能力：** SystemCapability.UserIAM.UserAuth.FaceAuth
| 名称 | 默认值 | 描述 |
| ----------------------- | ------ | -------------------- |
| FAIL | 12700001 | 执行失败。 |
zh-cn/application-dev/reference/apis/js-apis-useriam-userauth.md
浏览文件 @ e876fcc7
......@@ -187,26 +187,59 @@ export default {
}
```
## AuthResultInfo<sup>9+</sup>
表示认证结果信息。
**系统能力**：以下各项对应的系统能力均为SystemCapability.UserIAM.UserAuth.Core。
| 参数名 | 参数类型 | 必填 | 说明 |
| ------------ | ---------- | ---- | -------------------- |
| result | number | 是 | 认证结果。 |
| token | Uint8Array | 否 | 用户身份认证通过的凭证。 |
| remainAttempts | number | 否 | 剩余的认证操作次数。 |
| lockoutDuration | number | 否 | 认证操作的冻结时间。 |
## TipInfo<sup>9+</sup>
表示认证过程中的提示信息。
**系统能力**：以下各项对应的系统能力均为SystemCapability.UserIAM.UserAuth.Core。
| 参数名称 | 参数类型 | 必填 | 说明 |
| ------------ | ---------- | ---- | -------------------- |
| module | number | 是 | 发送提示信息的模块标识。 |
| tip | number | 是 | 认证过程提示信息。 |
## EventInfo<sup>9+</sup>
类型别名，用于表示认证事件信息的类型，取值可以为下表中的类型。
表示认证过程中事件信息的类型。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core
**系统能力**：以下各项对应的系统能力均为SystemCapability.UserIAM.UserAuth.Core。
| 类型 | 说明 |
| 取值类型 | 说明 |
| --------- | ----------------------- |
| [AuthResultInfo](#authresultinfo9) | 认证结果信息 |
| [AuthResultInfo](#authresultinfo9) | 获取到的认证结果信息 |
| [TipInfo](#tipinfo9) | 认证过程中的提示信息 |
## AuthEventKey<sup>9+</sup>
表示认证事件类型的关键字，作为[on](#on9)接口的的参数。
| 取值类型 | 说明 |
| ---------- | ----------------------- |
| "result" | [on](#on9)接口第一个参数为"result"时，[callback](#callback9)回调返回认证的结果信息。 |
| "tip" | [on](#on9)接口第一个参数为"tip"时，[callback](#callback9)回调返回认证操作中的提示信息。 |
## AuthEvent<sup>9+</sup>
认证事件回调的对象。
认证接口的异步回调对象。
### callback<sup>9+</sup>
callback: (result : EventInfo) => void
表示在认证结束后返回结果信息或者在认证操作中返回提示信息。
通过该回调获取认证结果信息或认证过程中的提示信息。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core
......@@ -224,6 +257,7 @@ callback: (result : EventInfo) => void
let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
let authType = userIAM_userAuth.UserAuthType.FACE;
let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1;
// 通过callback获取认证结果
try {
let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel);
auth.on("result", {
......@@ -240,41 +274,29 @@ callback: (result : EventInfo) => void
console.log("authV9 error = " + error);
// do error
}
// 通过callback获取认证过程中的提示信息
try {
let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel);
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
}
```
## AuthResultInfo<sup>9+</sup>
表示认证结果信息的对象。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core
| 名称 | 参数类型 | 必填 | 说明 |
| ------------ | ---------- | ---- | -------------------- |
| result | number | 是 | 认证结果。 |
| token | Uint8Array | 否 | 用户身份认证通过的凭证。 |
| remainAttempts | number | 否 | 剩余的认证操作次数。 |
| lockoutDuration | number | 否 | 认证操作的冻结时间。 |
## TipInfo<sup>9+</sup>
表示认证过程中提示信息的对象。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core
| 名称 | 参数类型 | 必填 | 说明 |
| ------------ | ---------- | ---- | -------------------- |
| module | number | 否 | 认证模块。 |
| tip | number | 否 | 认证过程提示信息。 |
## AuthEventKey<sup>9+</sup>
类型别名，表示认证事件的关键字，取值为表格内字符串。
| 取值 | 说明 |
| ---------- | ----------------------- |
| "result" | 取值为result时，事件回调返回认证的结果信息。 |
| "tip" | 取值为tip时，事件回调返回认证操作中的提示信息。 |
## AuthInstance<sup>9+</sup>
执行用户认证的对象。
......@@ -283,7 +305,7 @@ callback: (result : EventInfo) => void
on(name : AuthEventKey, callback : AuthEvent) : void
表示开启对认证事件的监听。
订阅指定类型的用户认证事件。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core
......@@ -291,8 +313,15 @@ on(name : AuthEventKey, callback : AuthEvent) : void
| 参数名 | 类型 | 必填 | 说明 |
| --------- | -------------------------- | ---- | ------------------------- |
| name | AuthEventKey | 是 | 认证事件的关键字 |
| callback | AuthEvent | 是 | 认证事件的回调函数 |
| name | [AuthEventKey](#autheventkey9) | 是 | 表示认证事件类型，取值为"result"时，回调函数返回认证结果；取值为"tip"时，回调函数返回认证过程中的提示信息。 |
| callback | [AuthEvent](#authevent9) | 是 | 认证接口的回调函数，用于返回认证结果或认证过程中的提示信息。 |
**错误码：**
| 错误码ID | 错误信息 |
| -------- | ------- |
| 401 | Incorrect parameters. |
| 12500002 | General operation error. |
**示例：**
......@@ -304,6 +333,7 @@ on(name : AuthEventKey, callback : AuthEvent) : void
let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1;
try {
let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel);
// 订阅认证结果
auth.on("result", {
callback: (result: userIAM_userAuth.AuthResultInfo) => {
console.log("authV9 result " + result.result);
......@@ -312,7 +342,7 @@ on(name : AuthEventKey, callback : AuthEvent) : void
console.log("authV9 lockoutDuration " + result.lockoutDuration);
}
});
// if need tip
// 订阅认证过程中的提示信息
auth.on("tip", {
callback : (result : userIAM_userAuth.TipInfo) => {
switch (result.tip) {
......@@ -320,7 +350,6 @@ on(name : AuthEventKey, callback : AuthEvent) : void
// do something;
case userIAM_userAuth.FaceTips.FACE_AUTH_TIP_TOO_DARK:
// do something;
// ...
default:
// do others
}
......@@ -338,13 +367,20 @@ on(name : AuthEventKey, callback : AuthEvent) : void
off(name : AuthEventKey) : void
表示关闭对认证事件的监听。
取消订阅特定类型的认证事件。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core
| 参数名 | 类型 | 必填 | 说明 |
| --------- | -------------------------- | ---- | ------------------------- |
| name | AuthEventKey | 是 | 认证事件的关键字 |
| name | [AuthEventKey](#autheventkey9) | 是 | 表示认证事件类型，取值为"result"时，取消订阅认证结果；取值为"tip"时，取消订阅认证过程中的提示信息。 |
**错误码：**
| 错误码ID | 错误信息 |
| -------- | ------- |
| 401 | Incorrect parameters. |
| 12500002 | General operation error. |
**示例：**
......@@ -354,9 +390,16 @@ off(name : AuthEventKey) : void
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 {
let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel);
// 订阅认证结果
auth.on("result", {
callback: (result: userIAM_userAuth.AuthResultInfo) => {
console.log("authV9 result " + result.result);
......@@ -365,18 +408,16 @@ off(name : AuthEventKey) : void
console.log("authV9 lockoutDuration " + result.lockoutDuration);
}
});
console.log("turn on authentication event listening success");
console.log("subscribe authentication event success");
} catch (error) {
console.log("turn off authentication event listening failed " + error);
// do error
console.log("subscribe authentication event failed " + error);
}
// 取消订阅认证结果
try {
let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel);
auth.off("result");
console.info("turn off authentication event listening success");
console.info("cancel subscribe authentication event success");
} catch (error) {
console.info("turn off authentication event listening failed, error = " + error);
console.info("cancel subscribe authentication event failed, error = " + error);
}
```
......@@ -384,12 +425,26 @@ off(name : AuthEventKey) : void
start() : void
表示开始认证。
开始认证。
> **说明：**
> 使用获取到的[AuthInstance](#authinstance9)对象调用该接口进行认证。
**需要权限**：ohos.permission.ACCESS_BIOMETRIC
**系统能力**：SystemCapability.UserIAM.UserAuth.Core
**错误码：**
| 错误码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
......@@ -412,12 +467,23 @@ start() : void
cancel(): void
表示取消认证。
取消认证。
> **说明：**
> 使用获取到的[AuthInstance](#authinstance9)对象调用该接口进行取消认证，此[AuthInstance](#authinstance9)应该是正在进行认证的对象。
**需要权限**：ohos.permission.ACCESS_BIOMETRIC
**系统能力**：SystemCapability.UserIAM.UserAuth.Core
**错误码：**
| 错误码ID | 错误信息 |
| -------- | ------- |
| 201 | Permission verification failed. |
| 401 | Incorrect parameters. |
| 12500002 | General operation error. |
**示例：**
```js
......@@ -429,7 +495,6 @@ cancel(): void
try {
let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel);
auth.start();
auth.cancel();
console.info("cancel auth success");
} catch (error) {
......@@ -444,7 +509,7 @@ getAuthInstance(challenge : Uint8Array, authType : UserAuthType, authTrustLevel
获取AuthInstance对象，用于执行用户身份认证。
> **说明：**
> 每个AuthInstance只能用于发起一次认证，若需要再次发起认证需重新获取AuthInstance。
> 每个AuthInstance只能进行一次认证，若需要再次进行认证则需重新获取AuthInstance。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core
......@@ -462,6 +527,15 @@ getAuthInstance(challenge : Uint8Array, authType : UserAuthType, authTrustLevel
| ----------------------------------------- | ------------ |
| [AuthInstance](#authinstance9) | 认证器对象。 |
**错误码：**
| 错误码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';
......@@ -492,7 +566,14 @@ getVersion(): number
| 类型 | 说明 |
| ------ | ---------------------- |
| number | 获取的认证器版本信息。 |
| number | 认证器版本信息。 |
**错误码：**
| 错误码ID | 错误信息 |
| -------- | ------- |
| 201 | Permission verification failed. |
| 12500002 | General operation error. |
**示例：**
......@@ -511,7 +592,7 @@ getVersion(): number
getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel): void
表示检查指定的认证等级的认证能力是否可用。
查询指定类型和等级的认证能力是否支持。
**需要权限**：ohos.permission.ACCESS_BIOMETRIC
......@@ -522,7 +603,18 @@ getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel): vo
| 参数名 | 类型 | 必填 | 说明 |
| -------------- | ---------------------------------- | ---- | -------------------------- |
| authType | [UserAuthType](#userauthtype8) | 是 | 认证类型，当前只支持FACE。 |
| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | 是 | 认证结果的信任等级。 |
| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | 是 | 认证信任等级。 |
**错误码：**
| 错误码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. |
**示例：**
......@@ -539,7 +631,7 @@ getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel): vo
## ResultCodeV9<sup>9+</sup>
表示执行结果的枚举。
表示返回码的枚举。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core
......@@ -553,31 +645,30 @@ getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel): vo
| TYPE_NOT_SUPPORT | 12500005 | 不支持的认证类型。 |
| TRUST_LEVEL_NOT_SUPPORT | 12500006 | 不支持的认证等级。 |
| BUSY | 12500007 | 忙碌状态。 |
| INVALID_PARAMETERS | 12500008 | 无效参数。 |
| LOCKED | 12500009 | 认证器已锁定。 |
| NOT_ENROLLED | 12500010 | 用户未录入认证信息。 |
## UserAuth<sup>8+</sup>
认证器的对象。
认证器对象。
### constructor<sup>(deprecated)</sup>
constructor()
创建认证器对象。
> **说明：**
> 从 API version 9 开始废弃，请使用[getAuthInstance](#useriam_userauthgetauthinstance9)替代。
<br/>从 API version 8 开始支持。
表示获取的认证器对象。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core
**返回值：**
| 类型 | 说明 |
| ---------------------- | -------------------- |
| [UserAuth](#userauth8) | UserAuth认证器对象。 |
| [UserAuth](#userauth8) | 认证器对象。 |
**示例：**
......@@ -591,12 +682,12 @@ constructor()
getVersion() : number
获取认证器的版本信息。
> **说明：**
> 从 API version 9 开始废弃，请使用[getVersion](#useriam_userauthgetversion9)替代。
<br/>从 API version 8 开始支持。
表示获取的认证器版本信息。
**需要权限**：ohos.permission.ACCESS_BIOMETRIC
**系统能力**：SystemCapability.UserIAM.UserAuth.Core
......@@ -605,7 +696,7 @@ getVersion() : number
| 类型 | 说明 |
| ------ | ---------------------- |
| number | 获取的认证器版本信息。 |
| number | 认证器版本信息。 |
**示例：**
......@@ -621,12 +712,12 @@ getVersion() : number
getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel) : number
查询指定类型和等级的认证能力是否支持。
> **说明：**
> 从 API version 9 开始废弃，请使用开始废弃，请使用[getAvailableStatus](#useriam_userauthgetavailablestatus9)替代。
> 从 API version 9 开始废弃，请使用[getAvailableStatus](#useriam_userauthgetavailablestatus9)替代。
<br/>从 API version 8 开始支持。
表示检查指定的认证等级的认证能力是否可用。
**需要权限**：ohos.permission.ACCESS_BIOMETRIC
**系统能力**：SystemCapability.UserIAM.UserAuth.Core
......@@ -636,13 +727,13 @@ getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel) : n
| 参数名 | 类型 | 必填 | 说明 |
| -------------- | ---------------------------------- | ---- | -------------------------- |
| authType | [UserAuthType](#userauthtype8) | 是 | 认证类型，当前只支持FACE。 |
| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | 是 | 认证结果的信任等级。 |
| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | 是 | 认证信任等级。 |
**返回值：**
| 类型 | 说明 |
| ------ | ------------------------------------------------------------ |
| number | 获取指定的认证等级的认证能力是否可用的检查结果，返回值参见[ResultCode](#resultcodedeprecated)。 |
| number | 查询结果，结果为SUCCESS时表示支持，其他返回值参见[ResultCode](#resultcodedeprecated)。 |
**示例：**
......@@ -653,10 +744,8 @@ getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel) : n
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);
// 此处添加不支持指定类型认证的逻辑
}
```
......@@ -664,12 +753,12 @@ getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel) : n
auth(challenge: Uint8Array, authType: UserAuthType, authTrustLevel: AuthTrustLevel, callback: IUserAuthCallback): Uint8Array
执行用户认证，使用回调函数返回结果。
> **说明：**
> 从 API version 9 开始废弃，建议使用[start](#start9)代替。
<br/>从 API version 8 开始支持。
表示执行用户认证，使用callback方式作为异步方法。
**需要权限**：ohos.permission.ACCESS_BIOMETRIC
**系统能力**：SystemCapability.UserIAM.UserAuth.Core
......@@ -680,7 +769,7 @@ auth(challenge: Uint8Array, authType: UserAuthType, authTrustLevel: AuthTrustLev
| -------------- | ---------------------------------------- | ---- | ------------------------ |
| challenge | Uint8Array | 是 | 挑战值，可以填null。 |
| authType | [UserAuthType](#userauthtype8) | 是 | 认证类型，当前支持FACE。 |
| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | 是 | 信任等级。 |
| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | 是 | 认证信任等级。 |
| callback | [IUserAuthCallback](#iuserauthcallbackdeprecated) | 是 | 回调函数。 |
**返回值：**
......@@ -716,12 +805,12 @@ auth(challenge: Uint8Array, authType: UserAuthType, authTrustLevel: AuthTrustLev
cancelAuth(contextID : Uint8Array) : number
表示通过contextID取消本次认证操作。
> **说明：**
> 从 API version 9 开始废弃，建议使用[cancel](#cancel9)代替。
<br/>从 API version 8 开始支持。
表示通过contextID取消本次认证操作。
**需要权限**：ohos.permission.ACCESS_BIOMETRIC
**系统能力**：SystemCapability.UserIAM.UserAuth.Core
......@@ -730,13 +819,13 @@ cancelAuth(contextID : Uint8Array) : number
| 参数名 | 类型 | 必填 | 说明 |
| --------- | ---------- | ---- | ------------------------------------------ |
| contextID | Uint8Array | 是 | 上下文ID信息，通过[auth](#authdeprecated)接口获得。 |
| contextID | Uint8Array | 是 | 上下文的标识，通过[auth](#authdeprecated)接口获取。 |
**返回值：**
| 类型 | 说明 |
| ------ | ------------------------ |
| number | 取消本次认证操作的结果。 |
| number | 取消认证的结果，结果为SUCCESS时表示取消成功，其他返回值参见[ResultCode](#resultcodedeprecated)。 |
**示例：**
......@@ -756,22 +845,22 @@ cancelAuth(contextID : Uint8Array) : number
## IUserAuthCallback<sup>(deprecated)</sup>
返回认证结果的回调对象。
> **说明：**
> 从 API version 9 开始废弃，建议使用[AuthEvent](#authevent9)代替。
<br/>从 API version 8 开始支持。
认证过程中回调结果的对象。
### onResult<sup>(deprecated)</sup>
onResult: (result : number, extraInfo : AuthResult) => void
回调函数，返回认证结果。
> **说明：**
> 从 API version 9 开始废弃，建议使用[callback](#callback9)代替。
<br/>从 API version 8 开始支持。
表示在认证操作中，获取认证结果。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core
**参数：**
......@@ -779,7 +868,7 @@ onResult: (result : number, extraInfo : AuthResult) => void
| 参数名 | 类型 | 必填 | 说明 |
| --------- | -------------------------- | ---- | ------------------------------------------------------------ |
| result | number | 是 | 认证结果，参见[ResultCode](#resultcodedeprecated)。 |
| extraInfo | [AuthResult](#authresultdeprecated) | 是 | 扩展信息，不同情况下的具体信息，<br/>如果身份验证通过，则在extrainfo中返回用户认证令牌，<br/>如果身份验证失败，则在extrainfo中返回剩余的用户认证次数，<br/>如果身份验证执行器被锁定，则在extrainfo中返回冻结时间。 |
| extraInfo | [AuthResult](#authresultdeprecated) | 是 | 扩展信息，不同情况下的具体信息，<br/>如果身份验证通过，则在extraInfo中返回用户认证令牌，<br/>如果身份验证失败，则在extraInfo中返回剩余的用户认证次数，<br/>如果身份验证执行器被锁定，则在extraInfo中返回冻结时间。 |
**示例：**
......@@ -801,16 +890,6 @@ onResult: (result : number, extraInfo : AuthResult) => void
} 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);
}
}
});
```
......@@ -819,20 +898,20 @@ onResult: (result : number, extraInfo : AuthResult) => void
onAcquireInfo ?: (module : number, acquire : number, extraInfo : any) => void
回调函数，返回认证过程中的提示信息，非必须实现。
> **说明：**
> 从 API version 9 开始废弃，建议使用[callback](#callback9)代替。
<br/>从 API version 8 开始支持。
表示在认证过程中，获取提示码信息，非必须实现。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --------- | ------ | ---- | ------------------------------ |
| module | number | 是 | 认证执行器的类型。 |
| acquire | number | 是 | 认证执行器认证过程的交互信息。 |
| module | number | 是 | 发送提示信息的模块标识。 |
| acquire | number | 是 | 认证执过程中的提示信息。 |
| extraInfo | any | 是 | 预留字段。 |
**示例：**
......@@ -842,20 +921,6 @@ onAcquireInfo ?: (module : number, acquire : number, extraInfo : any) => void
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);
......@@ -870,27 +935,27 @@ onAcquireInfo ?: (module : number, acquire : number, extraInfo : any) => void
## AuthResult<sup>(deprecated)</sup>
表示认证结果的对象。
> **说明：**
> 从 API version 9 开始废弃，建议使用[AuthResultInfo](#authresultinfo9)代替。
<br/>从 API version 8 开始支持。
表示认证结果的对象。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core
| 名称 | 参数类型 | 必填 | 说明 |
| ------------ | ---------- | ---- | -------------------- |
| token | Uint8Array | 否 | 身份认证令牌。 |
| token | Uint8Array | 否 | 认证通过的令牌信息。 |
| remainTimes | number | 否 | 剩余的认证操作次数。 |
| freezingTime | number | 否 | 认证操作的冻结时间。 |
## ResultCode<sup>(deprecated)</sup>
表示返回码的枚举。
> **说明：**
> 从 API version 9 开始废弃，建议使用[ResultCodeV9](#resultcodev99)代替。
表示执行结果的枚举。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core
| 名称 | 默认值 | 描述 |
......@@ -907,7 +972,6 @@ onAcquireInfo ?: (module : number, acquire : number, extraInfo : any) => void
| LOCKED | 9 | 认证器已锁定。 |
| NOT_ENROLLED | 10 | 用户未录入认证信息。 |
## FaceTips<sup>8+</sup>
表示人脸认证过程中提示码的枚举。
......@@ -973,11 +1037,11 @@ onAcquireInfo ?: (module : number, acquire : number, extraInfo : any) => void
getAuthenticator(): Authenticator
获取Authenticator对象，用于执行用户身份认证。
> **说明：**
> 从 API version 8 开始废弃，建议使用[constructor](#constructordeprecated)替代。
获取Authenticator对象，用于执行用户身份认证。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core
**返回值：**
......@@ -993,21 +1057,20 @@ getAuthenticator(): Authenticator
## Authenticator<sup>(deprecated)</sup>
> **说明：**
> 从 API version 8 开始废弃，建议使用[UserAuth](#userauth8)替代。
认证器对象。
> **说明：**
> 从 API version 8 开始废弃，建议使用[UserAuth](#userauth8)替代。
### execute<sup>(deprecated)</sup>
execute(type: AuthType, level: SecureLevel, callback: AsyncCallback&lt;number&gt;): void
执行用户认证，使用callback方式作为异步方法。
> **说明：**
> 从 API version 8 开始废弃，建议使用[auth](#authdeprecated)替代。
执行用户认证，使用callback方式作为异步方法。
**需要权限**：ohos.permission.ACCESS_BIOMETRIC
**系统能力**：SystemCapability.UserIAM.UserAuth.Core
......@@ -1041,13 +1104,13 @@ execute(type: AuthType, level: SecureLevel, callback: AsyncCallback&lt;number&gt
### 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)替代。
执行用户认证，使用promise方式作为异步方法。
**需要权限**：ohos.permission.ACCESS_BIOMETRIC
**系统能力**：SystemCapability.UserIAM.UserAuth.Core
......@@ -1078,11 +1141,11 @@ execute(type:AuthType, level:SecureLevel): Promise&lt;number&gt;
## AuthenticationResult<sup>(deprecated)</sup>
表示认证结果的枚举。
> **说明：**
> 从 API version 8 开始废弃，建议使用[ResultCode](#resultcodedeprecated)替代。
表示认证结果的枚举。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core
| 名称 | 默认值 | 描述 |
......
zh-cn/application-dev/security/userauth-guidelines.md
浏览文件 @ e876fcc7
# 用户认证开发指导
> **说明：**
> 该开发指导需匹配API Version 8或以上版本的SDK使用。
> 该开发指导需配合API Version 8或以上版本的SDK使用。
## 场景介绍
当前用户认证支持2D人脸识别、3D人脸识别，可应用于设备解锁、应用登录、支付等身份认证场景。
当前用户认证支持人脸识别和指纹识别，可应用于设备解锁、应用登录、支付等身份认证场景。
## 接口说明
userIAM_userAuth模块提供了用户认证的相关方法，包括检测认证能力、认证和取消认证等，用户可以使用人脸等生物特征信息进行认证操作。具体接口说明可以查阅[API参考](../reference/apis/js-apis-useriam-userauth.md)。
userIAM_userAuth模块提供了用户认证的相关方法，包括检测认证能力、认证和取消认证等，用户可以使用人脸、指纹等生物特征信息进行认证操作。具体接口说明可以查阅[API参考](../reference/apis/js-apis-useriam-userauth.md)。
在执行认证前，需要检查设备是否支持该认证能力，具体指认证类型、认证等级。如果不支持，需要考虑使用其他认证能力。
......@@ -19,51 +19,66 @@ userIAM_userAuth模块提供了用户认证的相关方法，包括检测认证
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| getVersion() : number | 获取认证对象的版本信息。 |
| getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel) : number | 根据指定的认证类型、认证等级，检测当前设备是否支持相应的认证能力。 |
| auth(challenge: Uint8Array, authType: UserAuthType, authTrustLevel: AuthTrustLevel, callback: IUserAuthCallback): Uint8Array | 执行用户认证，使用callback方式作为异步方法。 |
| 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. 申请权限。调用getVersion接口，需要在module.json5文件的requestPermissions对象中配置ohos.permission.ACCESS_BIOMETRIC权限。更多配置信息[应用包结构配置文件的说明](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/quick-start/stage-structure.md)。
开发过程：
2. 获取认证对象。
1. 获取Authenticator的单例对象，代码示例如下：
3. 调用getVersion接口获取版本信息。
```js
let auth = new userIAM_userAuth.UserAuth();
```
```js
import userIAM_userAuth from '@ohos.userIAM.userAuth'
2. （可选）获取认证对象的版本信息，代码示例如下：
let auth = new userIAM_userAuth.UserAuth();
let version = auth.getVersion();
console.info("auth version = " + version);
```
```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) {
1. 申请权限。调用getAvailableStatus接口，需要在module.json5文件的requestPermissions对象中配置ohos.permission.ACCESS_BIOMETRIC权限。更多配置信息[应用包结构配置文件的说明](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/quick-start/stage-structure.md)。
2. 获取认证对象。
3. 指定认证类型和认证等级，调用getAvailableStatus接口查询当前的设备是否支持相应的认证能力。
```js
import userIAM_userAuth from '@ohos.userIAM.userAuth'
let auth = new userIAM_userAuth.UserAuth();
let checkCode = auth.getAvailableStatus(userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1);
if (checkCode == userIAM_userAuth.ResultCode.SUCCESS) {
console.info("check auth support success");
// 此处添加支持指定类型认证的逻辑
} else {
// 此处添加支持相应认证能力的逻辑
} else {
console.error("check auth support fail, code = " + checkCode);
// 此处添加不支持指定类型认证的逻辑
}
```
// 此处添加不支持相应认证能力的逻辑
}
```
## 执行认证操作
### 开发步骤
1. 申请权限。调用auth接口，需要在module.json5文件的requestPermissions对象中配置ohos.permission.ACCESS_BIOMETRIC权限。更多配置信息[应用包结构配置文件的说明](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/quick-start/stage-structure.md)。
2. 获取认证对象。
4. 执行认证操作，代码示例如下：
3. 指定认证类型和认证等级，调用auth接口发起认证，通过onResult回调返回认证结果，通过onAcquireInfo回调返回认证过程中的提示信息。
```js
let auth = new userIAM_userAuth.UserAuth();
auth.auth(null, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, {
```js
import userIAM_userAuth from '@ohos.userIAM.userAuth'
let auth = new userIAM_userAuth.UserAuth();
auth.auth(null, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, {
onResult: (result, extraInfo) => {
try {
console.info("auth onResult result = " + result);
......@@ -87,15 +102,27 @@ userIAM_userAuth模块提供了用户认证的相关方法，包括检测认证
console.info("auth onAcquireInfo error = " + e);
}
}
});
```
});
```
## 认证过程中取消认证
### 开发步骤
1. 申请权限。调用cancelAuth接口，需要在module.json5文件的requestPermissions对象中配置ohos.permission.ACCESS_BIOMETRIC权限。更多配置信息[应用包结构配置文件的说明](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/quick-start/stage-structure.md)。
2. 获取认证对象。
5. 认证过程中取消认证，代码示例如下：
3. 指定认证类型和认证等级，调用auth接口发起认证，通过onResult回调返回认证结果，通过onAcquireInfo回调返回认证过程中的提示信息。
```js
let auth = new userIAM_userAuth.UserAuth();
// contextId通过auth接口获取
let contextId = auth.auth(null, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, {
4. 通过调用cancelAuth接口取消本次认证。
```js
import userIAM_userAuth from '@ohos.userIAM.userAuth'
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);
},
......@@ -103,11 +130,11 @@ userIAM_userAuth模块提供了用户认证的相关方法，包括检测认证
onAcquireInfo: (module, acquire, extraInfo) => {
console.info("auth onAcquireInfo module = " + module);
}
});
let cancelCode = auth.cancel(contextId);
if (cancelCode == userIAM_userAuth.ResultCode.SUCCESS) {
});
let cancelCode = auth.cancelAuth(contextId);
if (cancelCode == userIAM_userAuth.ResultCode.SUCCESS) {
console.info("cancel auth success");
} else {
} else {
console.error("cancel auth fail");
}
```
}
```
zh-cn/application-dev/security/userauth-overview.md
浏览文件 @ e876fcc7
......@@ -2,23 +2,23 @@
提供用户认证能力，可应用于设备解锁、支付、应用登录等身份认证场景。
当前用户认证能力提供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
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或