diff --git a/zh-cn/application-dev/security/userauth-guidelines-api6.md b/zh-cn/application-dev/security/userauth-guidelines-api6.md new file mode 100644 index 0000000000000000000000000000000000000000..e10c9df90a98a5afb31585f06813fb43e4a5e05b --- /dev/null +++ b/zh-cn/application-dev/security/userauth-guidelines-api6.md @@ -0,0 +1,46 @@ +# 用户认证开发指导 + +> **说明：** +> 该开发指导匹配@ohos.userIAM.userAuth API Version 6开始支持的接口。对应接口已在API Version 8废弃，建议使用[新接口](userauth-guidelines-api8.md)。 + +## 场景介绍 + +当前用户认证支持2D人脸识别、3D人脸识别，可应用于设备解锁、应用登录、支付等身份认证场景。 + +## 接口说明 + +userIAM_userAuth模块提供了用户认证的相关方法，包括获取认证对象、认证，用户可以使用人脸等生物特征信息进行认证操作。具体接口说明可以查阅[API参考](../reference/apis/js-apis-useriam-userauth.md)。 + +**表1** 用户认证开放能力列表 + +| 接口名 | 功能描述 | +| ------------------------------------------------------------ | --------------------------------------------- | +| getAuthenticator(): Authenticator | 获取Authenticator对象，用于执行用户身份认证。 | +| execute(type: AuthType, level: SecureLevel, callback: AsyncCallback\): void | 执行用户认证，使用callback方式作为异步方法。 | +| execute(type: AuthType, level: SecureLevel): Promise\ | 执行用户认证，使用Promise方式作为异步方法。 | + +## 开发步骤 + +开发前请完成以下准备工作： + +1. 在应用配置权限文件中，增加ohos.permission.ACCESS_BIOMETRIC的权限声明。 +2. 在使用用户认证能力的代码文件中增加import userIAM_userAuth from '@ohos.userIAM.userAuth'。 + +开发过程： + +1. 获取Authenticator的单例对象，代码示例如下： + + ```js + let auth = userIAM_userAuth.getAuthenticator(); + ``` + +2. 执行认证操作，代码示例如下： + + ```js + let authenticator = userIAM_userAuth.getAuthenticator(); + authenticator.execute("FACE_ONLY", "S2").then((code) => { + console.info("auth success"); + }).catch((code) => { + console.error("auth fail, code = " + code); + }); + ``` diff --git a/zh-cn/application-dev/security/userauth-guidelines-api8.md b/zh-cn/application-dev/security/userauth-guidelines-api8.md new file mode 100644 index 0000000000000000000000000000000000000000..273a12699590968c098f322a0c7d06c96d49d036 --- /dev/null +++ b/zh-cn/application-dev/security/userauth-guidelines-api8.md @@ -0,0 +1,113 @@ +# 用户认证开发指导 + +> **说明：** +> 该开发指导匹配@ohos.userIAM.userAuth API Version 8开始支持的接口。 + +## 场景介绍 + +当前用户认证支持2D人脸识别、3D人脸识别，可应用于设备解锁、应用登录、支付等身份认证场景。 + +## 接口说明 + +userIAM_userAuth模块提供了用户认证的相关方法，包括检测认证能力、认证和取消认证等，用户可以使用人脸等生物特征信息进行认证操作。具体接口说明可以查阅[API参考](../reference/apis/js-apis-useriam-userauth.md)。 + +在执行认证前，需要检查设备是否支持该认证能力，具体指认证类型、认证等级。如果不支持，需要考虑使用其他认证能力。 + +**表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 == '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"); + } + ``` diff --git a/zh-cn/application-dev/security/userauth-guidelines.md b/zh-cn/application-dev/security/userauth-guidelines.md deleted file mode 100644 index 2250ecf1901d683c630388bb267737eea0d56dc5..0000000000000000000000000000000000000000 --- a/zh-cn/application-dev/security/userauth-guidelines.md +++ /dev/null @@ -1,101 +0,0 @@ -# 用户认证开发指导 - -## 场景介绍 - -当前用户认证支持2D人脸识别、3D人脸识别，可应用于设备解锁、应用登录、支付等身份认证场景。 - -## 接口说明 - -userIAM_userAuth模块提供了用户认证的相关方法，包括检测认证能力、认证和取消认证等，用户可以通过人脸等生物特征信息进行认证操作。具体接口说明可以查阅[API参考](../reference/apis/js-apis-useriam-userauth.md)。 - -在执行认证前，需要检查设备是否支持该认证能力，具体指认证类型、安全级别和是否本地认证。如果不支持，需要考虑使用其他认证能力。 - -**表1** 用户认证开放能力列表 - -| 接口名 | 功能描述 | -| ------------------------------------------------------------ | ------------------------------------------------------------ | -| getAuthenticator(): Authenticator | 获取Authenticator对象，用于执行用户身份认证。6+
获取Authenticator对象，用于检测设备身份认证能力、执行和取消用户身份认证，获取认证过程中的提示信息。7+ | -| checkAvailability(type: AuthType, level: SecureLevel): number | 根据指定的认证类型、安全等级，检测当前设备是否支持相应的认证能力。 | -| execute(type: AuthType, level: SecureLevel, callback: AsyncCallback\): void | 执行用户认证，使用callback方式作为异步方法。 | -| execute(type: AuthType, level: SecureLevel): Promise\ | 执行用户认证，使用Promise方式作为异步方法。 | -| cancel(): void | 取消当前的认证流程。 | -| on(type: "tip", callback: Callback\): void | 订阅指定类型的事件。 | -| off(type: "tip", callback?: Callback\): 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