| type | string | Yes | Authentication type. Only **FACE_ONLY** is supported.<br>**ALL** is reserved and not supported by the current version.|
| level | string | Yes | Security level of the authentication. It can be S1 (lowest), S2, S3, or S4 (highest).<br>Devices capable of 3D facial recognition support S3 and lower-level authentication.<br>Devices capable of 2D facial recognition support S2 and lower-level authentication.|
| type | string | Yes | Authentication type. Only **FACE_ONLY** is supported.<br>**ALL** is reserved and not supported by the current version.|
| level | string | Yes | Security level of the authentication. It can be S1 (lowest), S2, S3, or S4 (highest).<br>Devices capable of 3D facial recognition support S3 and lower-level authentication.<br>Devices capable of 2D facial recognition support S2 and lower-level authentication.|
| callback | AsyncCallback<number> | No | Callback used to return the result. |
| type | string | Yes | Authentication type. Only **FACE_ONLY** is supported.<br>**ALL** is reserved and not supported by the current version.|
| level | string | Yes | Security level of the authentication. It can be S1 (lowest), S2, S3, or S4 (highest).<br>Devices capable of 3D facial recognition support S3 and lower-level authentication.<br>Devices capable of 2D facial recognition support S2 and lower-level authentication.|
| type | string | Yes | Authentication type. Only **FACE_ONLY** is supported.<br>**ALL** is reserved and not supported by the current version.|
| level | string | Yes | Security level of the authentication. It can be S1 (lowest), S2, S3, or S4 (highest).<br>Devices capable of 3D facial recognition support S3 and lower-level authentication.<br>Devices capable of 2D facial recognition support S2 and lower-level authentication.|
| Promise<number> | Promise used to return the authentication result, which is a number. For details, see [AuthenticationResult](#authenticationresultdeprecated).|
| Promise<number> | Promise used to return the authentication result, which is a number. For details, see [AuthenticationResult](#authenticationresultdeprecated).|
| result | number | Yes | Authentication result obtained. For details, see [ResultCode](#resultcode8). |
| extraInfo | [AuthResult](#authresult8) | Yes | Extended information, which varies depending on the authentication result.<br>If the authentication is successful, the user authentication token will be returned in **extraInfo**.<br>If the authentication fails, the remaining number of authentication times will be returned in **extraInfo**.<br>If the authentication executor is locked, the freeze time will be returned in **extraInfo**.|
| extraInfo | [AuthResult](#authresult8) | Yes | Extended information, which varies depending on the authentication result.<br>If the authentication is successful, the user authentication token will be returned in **extraInfo**.<br>If the authentication fails, the remaining number of authentication times will be returned in **extraInfo**.<br>If the authentication executor is locked, the freeze time will be returned in **extraInfo**.|
**Example**
...
...
@@ -443,7 +443,7 @@ Obtains the authentication result.
@@ -101,7 +101,7 @@ The permissions open to apps vary with the permission level. The permission leve
As described above, permission levels and app APLs are in one-to-one correspondence. In principle, **an app with a lower APL cannot apply for higher permissions by default**.
The Access Control List (ACL) makes low-level apps to have high-level permissions.
The Access Control List (ACL) makes low-level apps have high-level permissions.
Facial authentication provides user authentication capabilities in identity authentication scenarios, such as device unlocking, payment, and app logins. It uses biometric recognition technologies to identify individuals based on facial characteristics. A camera is used to collect images or video streams that contain human faces, and automatically detect, track, and recognize human faces. Facial authentication is also called facial recognition or face recognition. The figure below shows the architecture of facial authentication.
Facial authentication provides user authentication capabilities in identity authentication scenarios, such as device unlocking, payment, and app logins. It uses biometric recognition technologies to identify individuals based on facial characteristics. A camera is used to collect images or video streams that contain human faces, and automatically detect, track, and recognize human faces. Facial authentication is also called facial recognition. The figure below shows the architecture of facial authentication.
The face authentication driver (Face_auth) driver is developed based on the Hardware Driver Foundation (HDF) driver framework. It shields hardware differences and provides stable facial authentication capabilities for the user authentication framework (User_auth) and Face_auth service. The facial authentication capabilities include obtaining facial recognition executor list, executor information, and template information by template ID, comparing face image template information of the executor and that of User_auth, enrolling or deleting face templates, and performing facial authentication.
The face authentication (Face_auth) driver is developed based on the Hardware Driver Foundation (HDF). It shields hardware differences and provides stable facial authentication capabilities for the user authentication framework (User_auth) and Face_auth service. The facial authentication capabilities include obtaining facial recognition executor list, executor information, and template information by template ID, comparing face image template information of the executor and that of User_auth, enrolling or deleting face image templates, and performing facial authentication.
**Figure 1** Facial authentication architecture
...
...
@@ -14,14 +14,14 @@ The face authentication driver (Face_auth) driver is developed based on the Hard
### Basic Concepts
The identity authentication consists of User_auth and basic authentication services (including PIN authentication and facial authentication). It supports basic functions such as setting and deleting user credentials and performing authentication. The system supports user identity authentication and provides data collection, processing, storage, and comparison capabilities.
The identity authentication consists of User_auth and basic authentication services (including PIN authentication and facial authentication). It supports basic functions such as setting and deleting user credentials and performing authentication. The system supports user identity authentication and data collection, processing, storage, and comparison.
- Executor
The executor collects, processes, stores, and compares data for authentication. Each authentication service provides the executor capabilities, which are scheduled by User_auth to implement basic capabilities.
- Executor security level
Certain security level is required for the execution environment of an executor. For example, the executor security level is low for an operation performed without access control and high for an operation performed in a Trusted Execution Environment (TEE).
Security level required for the execution environment of an executor.
- Executor role
...
...
@@ -39,11 +39,11 @@ The identity authentication consists of User_auth and basic authentication servi
To ensure user data security and authentication result accuracy, measures must be taken to protect the integrity of the key information exchanged between User_auth and basic authentication services. Public keys must be exchanged when the executor provided by a basic authentication service interworks with User_auth.
The executor uses the User_auth public key to verify scheduling instructions. For example, if a face image template is locked, the related facial authentication capability cannot be used. The instruction for unlocking the face image template must be verified before being executed.
The executor uses the User_auth public key to verify scheduling instructions.
User_auth uses the executor public key to verify the authentication result accuracy and the integrity of the information exchanged with the executor.
-Facial authentication credential template
-Authentication credential template
Authentication credentials are generated and stored by the authentication service when users set authentication credentials. Each template has an ID to index a set of template information files. The template information needs to be compared with the authentication data generated during authentication to complete identity authentication.
...
...
@@ -53,7 +53,7 @@ The identity authentication consists of User_auth and basic authentication servi
### Working Principles
The Face_auth driver provides basic facial authentication capabilities for the User_auth framework and Face_auth service to ensure successful facial authentication.
The Face_auth driver provides basic facial authentication capabilities for the User_auth and Face_auth service to ensure successful facial authentication.
You can develop drivers to call Hardware Device Interface (HDI) APIs based on the HDF and the chip you use.
**Figure 2** Face_auth service and Face_auth driver interaction
...
...
@@ -62,15 +62,15 @@ You can develop drivers to call Hardware Device Interface (HDI) APIs based on th
### Constraints
- To implement facial authentication, the device must have a camera with a face image pixel greater than 100x100.
-TEE must be available, and facial feature information must be encrypted and stored in a TEE.
- To implement facial authentication, the device must have a camera and the face image must be greater than 100 x 100 pixels.
-A Trusted Execution Environment (TEE) must be available, and facial feature information must be encrypted and stored in a TEE.
- The face matching accuracy varies with people with similar looks and children whose facial features keep changing. If you are concerned about this, consider using other authentication modes.
## Development Guidelines
### When to Use
The Face_auth driver provides basic facial authentication capabilities for the User_auth framework and Face_auth service to ensure successful facial authentication.
The Face_auth driver provides basic facial authentication capabilities for the User_auth and Face_auth service to ensure successful facial authentication.
### Available APIs
...
...
@@ -79,12 +79,12 @@ The Face_auth driver provides basic facial authentication capabilities for the U
| GetExecutorList(std::vector<sptr<IExecutor>>& executorList) | Obtains the executor list. |
| GetExecutorInfo(ExecutorInfo& info) | Obtain the executor information, including the executor type, executor role, authentication type, security level, and executor public key.|
| GetExecutorInfo(ExecutorInfo& info) | Obtains the executor information, including the executor type, executor role, authentication type, security level, and executor public key.|
| GetTemplateInfo(uint64_t templateId, TemplateInfo& info) | Obtains information about a face image template based on the specified template ID. |
| OnRegisterFinish(const std::vector<uint64_t>& templateIdList,<br> const std::vector<uint8_t>& frameworkPublicKey, const std::vector<uint8_t>& extraInfo) | Obtains the public key and template ID list from User_auth after the executor is registered successfully.|
| Enroll(uint64_t scheduleId, const std::vector<uint8_t>& extraInfo,<br> const sptr<IExecutorCallback>& callbackObj) | Enrolls a face image template. |
| Delete(const std::vector<uint64_t>& templateIdList) | Deletes a face image template. |
| Cancel(uint64_t scheduleId) | Cancels a face enrolling, authentication, or identification operation based on the **scheduleId**. |
| SendCommand(int32_t commandId, const std::vector<uint8_t>& extraInfo,<br> const sptr<IExecutorCallback>& callbackObj) | Sends commands to the Face_auth service. |
...
...
@@ -98,7 +98,7 @@ The Face_auth driver provides basic facial authentication capabilities for the U
### How to Develop
The following uses the Hi3516DV300 platform as an example to demonstrate how to develop the Face_auth driver. <br/>The directory structure is as follows:
The following uses the Hi3516D V300 development board as an example to demonstrate how to develop the Face_auth driver. <br/>The directory structure is as follows:
```undefined
// drivers/peripheral/face_auth
...
...
@@ -118,7 +118,7 @@ The development procedure is as follows:
1. Develop the Face_auth driver based on the HDF. The **Bind()**, **Init()**, **Release()**, and **Dispatch()** functions are used. For details about the code, see [face_auth_interface_driver.cpp](https://gitee.com/openharmony/drivers_peripheral/blob/master/face_auth/hdi_service/src/face_auth_interface_driver.cpp).
```c++
// Create the IRemoteObject object by using the custom HdfFaceAuthInterfaceHost object, which consists of the IoService object and HDI service.
// Create an IRemoteObject object by using the custom HdfFaceAuthInterfaceHost object, which consists of the IoService object and HDI service.
structHdfFaceAuthInterfaceHost{
structIDeviceIoServiceioService;
OHOS::sptr<OHOS::IRemoteObject>stub;
...
...
@@ -152,6 +152,10 @@ The development procedure is as follows:
@@ -417,7 +421,7 @@ The development procedure is as follows:
### Verification
Use the [User Authentication APIs](../../application-dev/reference/apis/js-apis-useriam-userauth.md) to develop a JavaScript application and verify the application on the Hi3516DV300 platform. The sample code for verifying the authentication and authentication cancellation is as follows:
Use the [User Authentication APIs](../../application-dev/reference/apis/js-apis-useriam-userauth.md) to develop a JavaScript application and verify the application on the Hi3516D V300 development board. The sample code for verifying and canceling the authentication is as follows:
```js
// API version 8
...
...
@@ -426,7 +430,7 @@ let auth = new userIAM_userAuth.UserAuth();
Personal Identification Number (PIN) authentication provides user authentication capabilities in identity authentication scenarios, such as device unlocking, payment, and app logins. After a user registers a PIN, the PIN authentication (Pin_auth) module unlocks the device only when a correct PIN is entered. The figure below shows the architecture of PIN authentication.
Personal Identification Number (PIN) authentication provides user authentication capabilities in identity authentication scenarios, such as device unlocking, payment, and app logins. After a user registers a PIN, the PIN authentication (Pin_auth) module unlocks the device only when the correct PIN is entered. The figure below shows the architecture of PIN authentication.
The Pin_auth driver is developed based on the Hardware Driver Foundation (HDF). The Pin_auth driver model shields hardware differences and provides stable PIN authentication capabilities for the user User_auth framework (User_auth) and PIN authentication system ability (SA). The PIN authentication capabilities include obtaining the PIN authentication executor list, executor information, and anti-brute force information of the specified template, comparing the template ID list of the executor and that of User_auth, enrolling or deleting PINs, and performing PIN authentication.
...
...
@@ -21,7 +21,7 @@ The identity authentication consists of User_auth and basic authentication servi
- Executor security level
Certain security level is required for the execution environment of an executor. For example, the executor security level is low for an operation performed without access control and high for an operation performed in a Trusted Execution Environment (TEE).
Security level required for the execution environment of an executor.
- Executor role
...
...
@@ -58,10 +58,10 @@ The Pin_auth driver provides basic PIN authentication capabilities for the upper
**Figure 2** Pin_auth service and pin_auth driver APIs
![image](figures/pin_auth_service_and_driver_interaction.png"interaction between the Pin_auth service and driver")
![image](figures/pin_auth_service_and_driver_interaction.png"interaction between the pin_auth service and driver")
### Constraints
PIN authentication must be implemented in a TEE, and the confidential information, such as PINs and credentials, must be stored in a TEE.
PIN authentication must be implemented in a Trusted Execution Environment (TEE), and the confidential information, such as PINs and credentials, must be stored in a TEE.
## Development Guidelines
### When to Use
...
...
@@ -526,8 +526,7 @@ The development procedure is as follows:
### Verification
Verify whether PIN authentication can be successfully performed on the RK3568 platform as follows:
1. Set a PIN.
1. Set a PIN.<br/>
Touch **Settings** > **Biometrics & passwords** > **Password**, and enter your password.
User authentication is indispensable in identity authentication scenarios, such as device unlocking, payment, and app logins. The user authentication framework (User_auth) manages the mappings between user identities and authentication credential templates in a unified manner. It schedules executors implemented by basic authentication services (including PIN authentication and facial recognition) to register user authentication credentials, delete credentials, obtain related information, and complete authentication. The figure below shows the architecture of user authentication.
The User_auth driver is developed based on the Hardware Driver Foundation (HDF). It shields hardware differences and provides stable user authentication capabilities for apps and account management system ability (SA). It supports user credential management, authentication information enrollment, authentication scheme generation, and authentication executor information management.
The User_auth driver is developed based on the Hardware Driver Foundation (HDF). It shields hardware differences and provides stable user authentication capabilities for apps and account management system ability (SA). It supports user credential management, authentication information enrollment, authentication scheme generation, and executor information management.
**Figure 1** User authentication architecture
...
...
@@ -41,7 +41,7 @@ The identity authentication consists of the User_auth framework and basic authen
- Executor security level
Certain security level is required for the execution environment of an executor. For example, the executor security level is low for an operation performed without access control and high for an operation performed in a Trusted Execution Environment (TEE).
Security level required for the execution environment of an executor.
- User_auth public key & executor public key
...
...
@@ -66,11 +66,11 @@ The identity authentication consists of the User_auth framework and basic authen
- SA
SAs are loaded by the System Ability Manager service to provide basic system capabilities for the OpenHarmony system.
SAs are loaded by the System Ability Manager to provide basic system capabilities for OpenHarmony devices.
- Kit
The kit provides basic application programming interfaces (APIs) for third-party applications.
The kit provides basic APIs for third-party applications.
- Inner API
...
...
@@ -78,22 +78,22 @@ The identity authentication consists of the User_auth framework and basic authen
### Working Principles
The User_auth driver shields the differences of security devices and environments. It provides unified interface for the User_auth service to implement management of authentication executors and credentials as well as authentication scheme generation.
The User_auth driver shields the differences of security devices and environments. It provides unified interfaces for the User_auth service to implement management of executors and credentials as well as authentication scheme generation.
You can develop drivers to call Hardware Device Interface (HDI) APIs based on the HDF and the chip you use.
**Figure 2** User_auth service and User_auth driver APIs
![image](figures/user_auth_service_and_driver_api.png"interaction between the uin_auth service and driver")
![image](figures/user_auth_service_and_driver_api.png"interaction between the user_auth service and driver")
### Constraints
The User_auth driver must be implemented in a TEE to ensure secure storage of user credential information and trustworthiness of user authentication results.
The User_auth driver must be implemented in a Trusted Execution Environment (TEE) to ensure secure storage of user credentials and trustworthiness of user authentication results.
## Development Guidelines
### When to Use
The User_auth driver provides stable user credential management, authentication session management, and executor information management capabilities for the User_auth service to ensure successful PIN authentication and biometric recognition on devices.
The User_auth driver provides stable user credential management, authentication session management, and executor information management for the User_auth service to ensure successful PIN authentication and biometric recognition on devices.
### Available APIs
...
...
@@ -106,7 +106,7 @@ The User_auth driver provides stable user credential management, authentication
| DeleteExecutor(uint64_t index) | Deletes an executor. |
| OpenSession(int32_t userId, std::vector<uint8_t>& challenge) | Opens a session for authentication credential management. |
| CloseSession(int32_t userId) | Closes a session for authentication credential management. |
| BeginEnrollment(int32_t userId, const std::vector<uint8_t>& authToken, const EnrollParam& param,<br> ScheduleInfo& info) | Enrolls the user authentication credential. If a user has enrolled a PIN, the new PIN enrolled will replace the old PIN.|
| BeginEnrollment(int32_t userId, const std::vector<uint8_t>& authToken, const EnrollParam& param,<br> ScheduleInfo& info) | Enrolls the user authentication credential. If a user has enrolled a PIN, the old PIN will be overwritten.|
| UpdateEnrollmentResult(int32_t userId, const std::vector<uint8_t>& scheduleResult, uint64_t& credentialId,<br> CredentialInfo& oldInfo) | Updates the data to complete this enrollment. |
| CancelEnrollment(int32_t userId) | Cancels an enrollment operation. |
| DeleteCredential(int32_t userId, uint64_t credentialId, const std::vector<uint8_t>& authToken,<br> CredentialInfo& info) | Deletes credential information based on the specified **credentialId**. |
...
...
@@ -119,13 +119,13 @@ The User_auth driver provides stable user credential management, authentication
| CancelAuthentication(uint64_t contextId) | Cancels an authentication. |
| BeginIdentification(uint64_t contextId, AuthType authType, const std::vector<int8_t>& challenge,<br> uint32_t executorId, ScheduleInfo& scheduleInfo) | Starts an identification to generate the identification scheme and scheduling information. |
| UpdateIdentificationResult(uint64_t contextId, const std::vector<uint8_t>& scheduleResult,<br> IdentifyResultInfo& info) | Updates the identification result to evaluate the identification scheme. |
| CancelIdentification(uint64_t contextId) | Cancel an identification. |
| CancelIdentification(uint64_t contextId) | Cancels an identification. |
| GetAuthTrustLevel(int32_t userId, AuthType authType, uint32_t& authTrustLevel) | Obtains the authentication trust level of the specified authentication type. |
| GetValidSolution(int32_t userId, const std::vector<AuthType>& authTypes, uint32_t authTrustLevel,<br> std::vector<AuthType>& validTypes) | Obtains the valid authentication scheme based on the authentication trust level for a user. |
### How to Develop
The following uses the Hi3516DV300 platform as an example to demonstrate how to develop the User_auth driver. <br/>The directory structure is as follows:
The following uses the Hi3516D V300 development board as an example to demonstrate how to develop the User_auth driver. <br/>The directory structure is as follows:
```undefined
// drivers/peripheral/user_auth
...
...
@@ -144,7 +144,7 @@ The development procedure is as follows:
1. Develop the User_auth driver based on the HDF. The **Bind()**, **Init()**, **Release()**, and **Dispatch()** functions are used. For details about the code, see [user_auth_interface_driver.cpp](https://gitee.com/openharmony/drivers_peripheral/blob/master/user_auth/hdi_service/service/user_auth_interface_driver.cpp).
```c++
// Create the IRemoteObject object by using the custom HdfUserAuthInterfaceHost object, which consists of the IoService object and HDI service.
// Create an IRemoteObject object by using the custom HdfUserAuthInterfaceHost object, which consists of the IoService object and HDI service.
structHdfUserAuthInterfaceHost{
structIDeviceIoServiceioService;
OHOS::sptr<OHOS::IRemoteObject>stub;
...
...
@@ -197,7 +197,7 @@ The development procedure is as follows:
autoserviceImpl=IUserAuthInterface::Get(true);
if(serviceImpl==nullptr){
HDF_LOGE("%{public}s: failed to get of implement service",__func__);
HDF_LOGE("%{public}s: Failed to obtain service",__func__);
returnHDF_FAILURE;
}
...
...
@@ -310,18 +310,18 @@ The development procedure is as follows:
@@ -492,7 +492,7 @@ The development procedure is as follows:
### Verification
Use the [User Authentication APIs](../../application-dev/reference/apis/js-apis-useriam-userauth.md) to develop a JavaScript application and verify the application on the Hi3516DV300 platform. The sample code for verifying the authentication and authentication cancellation is as follows:
Use the [User Authentication APIs](../../application-dev/reference/apis/js-apis-useriam-userauth.md) to develop a JavaScript application and verify the application on the Hi3516D V300 development board. The sample code for verifying and canceling the authentication is as follows:
