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 identity authentication consists of the User_auth framework and basic authentication services (including PIN authentication and facial recognition). It supports basic functions such as setting and deleting user credentials and performing authentication.
- Authentication credential information
An authentication credential template is generated when a user sets a password or enrolls facial information. The credential information consists of the user identity information and credential template information. The authentication is successful when the credential data generated matches the credential template information.
- Authentication credential template
The authentication credential template is generated and stored by the authentication service when a user sets the authentication credential. The template information needs to be compared with the authentication data generated during authentication to complete identity authentication. Each template has an ID to index a set of template information files.
- 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 role
- Executor: independently completes the entire process of credential registration and identity authentication. The executor can collect, process, store, and compare data to complete the authentication.
- Collector: only collects data during user authentication. It needs to work with the authenticator to complete user authentication.
- Authenticator: processes data, obtains the stored credential template, and compares it with the authentication information generated.
- Executor type
The authentication algorithm varies depending on the authentication mode and device used. Different executor types are defined based on the supported algorithm type or the device in use.
- 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).
- User_auth public key & executor public key
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.
- User_auth uses the executor public key to verify the authentication result accuracy and the integrity of the information exchanged with the executor.
- Authentication result trust level
The trust level of the authentication result varies, depending on the authentication mode and the security level of the authentication execution environment.
- Authentication scheme
An authentication scheme contains information about the authentication mode, trust level of the authentication result, executor, and credential.
- Scheduling information
Scheduling information includes the executor information and credential template information required by the executor to process requests. User_auth schedules the executor to implement basic authentication capabilities.
- SA
SAs are loaded by the System Ability Manager service to provide basic system capabilities for the OpenHarmony system.
- Kit
The kit provides basic application programming interfaces (APIs) for third-party applications.
- Inner API
Inner API is an API provided by OpenHarmony for system applications.
### 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.
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")
### 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.
## 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.
| AddExecutor(const ExecutorRegisterInfo& info, uint64_t& index, std::vector<uint8_t>& publicKey,<br> std::vector<uint64_t>& templateIds) | Adds an executor to obtain the authentication capability. |
| 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.|
| 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**. |
| DeleteUser(int32_t userId, const std::vector<uint8_t>& authToken,<br> std::vector<CredentialInfo>& deletedInfos) | Deletes a user PIN from User_auth. |
| EnforceDeleteUser(int32_t userId, std::vector<CredentialInfo>& deletedInfos) | Forcibly deletes a user. This API will be called when a user is deleted from the system. |
| GetCredential(int32_t userId, AuthType authType, std::vector<CredentialInfo>& infos) | Obtains user credential information by authentication type. |
| GetSecureInfo(int32_t userId, uint64_t& secureUid, std::vector<EnrolledInfo>& infos) | Obtains the secure user ID and the enrolled tag ID of each authentication type. |
| BeginAuthentication(uint64_t contextId, const AuthSolution& param,<br> std::vector<ScheduleInfo>& scheduleInfos) | Starts an authentication to generate the authentication scheme and scheduling information. |
| UpdateAuthenticationResult(uint64_t contextId, const std::vector<uint8_t>& scheduleResult,<br> AuthResultInfo& info) | Updates the authentication result to evaluate the authentication scheme. |
| 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. |
| 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:
└── user_auth_interface_service.cpp # Implementation of the APIs for obtaining the executor list
```
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.
structHdfUserAuthInterfaceHost{
structIDeviceIoServiceioService;
OHOS::sptr<OHOS::IRemoteObject>stub;
};
// Enable the IPC service to call the response API.
// Call HDF_INIT to register the driver entry with the HDF. When loading the driver, the HDF calls the Bind() function and then the Init() function. If the Init() function fails to be called, the HDF will call Release() to release driver resources and exit the driver model.
#ifndef __cplusplus
extern"C"{
#endif
HDF_INIT(g_userAuthInterfaceDriverEntry);
#ifndef __cplusplus
}
#endif
```
2. Register the executor. For details about the code, see [user_auth_interface_service.cpp](https://gitee.com/openharmony/drivers_peripheral/blob/master/user_auth/hdi_service/service/user_auth_interface_service.cpp).
3. Enroll user authentication data. For details about the code, see [user_auth_interface_service.cpp](https://gitee.com/openharmony/drivers_peripheral/blob/master/user_auth/hdi_service/service/user_auth_interface_service.cpp).
```c++
// Open a session for authentication credential management.
4. Perform the authentication. For details about the code, see [user_auth_interface_service.cpp](https://gitee.com/openharmony/drivers_peripheral/blob/master/user_auth/hdi_service/service/user_auth_interface_service.cpp).
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: