Personal Identification Number (PIN) authentication provides user authentication capabilities and applies to 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.
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 IAM framework(UserIAM) and PIN authentication system ability (SA). The PIN authentication capabilities include obtaining the PIN authentication executor list, executor information, anti-brute force information of the specified template, comparing the template list of the executor and that of UserIAM, enrolling or deleting PINs, and performing PIN authentication.
The identity authentication consists of UserIAM and basic authentication services (including PIN authentication and facial recognition). It supports basic functions such as setting and deleting user credentials, deletion, and performing authentication.
- Executor
The executor collects, processes, stores, and compares data for authentication. Each authentication service provides the executor capabilities, which are scheduled by UserIAM 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).
- 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: only 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.
- UserIAM 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 UserIAM and basic authentication services. Public keys need to be exchanged when the executor provided by a basic authentication service interworks with UserIAM.
- The executor uses the UserIAM public key to verify the scheduling instruction.
- UserIAM uses the executor public key to verify the authentication result accuracy and the integrity of the information exchanged with the executor.
- PIN 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.
- Data verification by the executor
UserIAM manages the mappings between user identities and credential IDs in a unified manner. When connecting to UserIAM, the executor obtains the template ID list from UserIAM, compares its template ID list with the template ID list obtained, and updates its template ID list accordingly.
### Working Principles
The pin_auth driver provides basic capabilities of PIN authentication for the upper-layer UserIAM and pin_auth service to ensure successful PIN authentication. You can develop drivers to call Hardware Device Interface (HDI) APIs based on the HDF and the chip you use.
**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")
### Constraints
PIN authentication must be implemented in a TEE, and the confidential information, such as PINs and credentials, must be stored in a TEE.
## Development Guidelines
### When to Use
The pin_auth driver provides basic capabilities of PIN authentication for the UserIAM and pin_auth service to ensure successful PIN authentication.
| GetExecutorList(std::vector<sptr<IExecutor>>& executorList) | Obtains the executor list. |
| GetExecutorInfo(ExecutorInfo& info) | Obtains information about an executor. |
| GetTemplateInfo(uint64_t templateId, TemplateInfo& info) | Obtains information about a template. |
| OnRegisterFinish(const std::vector<uint64_t>& templateIdList,<br>const std::vector<uint8_t>& frameworkPublicKey,<br>const std::vector<uint8_t>& extraInfo) | Obtains the public key and template list from UserIAM after the executor is registered successfully.|
| OnSetData(uint64_t scheduleId, uint64_t authSubType, <br>const std::vector<uint8_t> &data) | Called to return the subtype and anonymized data of PIN authentication. |
| IExecutorCallback::OnResult(int32_t code, const std::vector<uint8_t>& extraInfo) | Called to return the operation result.|
| IExecutorCallback::OnGetData(uint64_t scheduleId, const std::vector<uint8_t>& salt,<br> uint64_t authSubType)| Called to return the PIN information obtained. |
### How to Develop
The following uses the RK3568 platform as an example to demonstrate how to develop the pin_auth driver. <br/>The directory structure is as follows:
```
// drivers/peripheral/pin_auth
├── BUILD.gn # Build script
├── bundle.json # Module description file
└── hdi_service # Pin_auth driver implementation
├── BUILD.gn # Build script
├── inc # Header files
└── src
├── executor_impl.cpp # Implementation of authentication and enrollment APIs
└── pin_auth_interface_service.cpp # Implementation of the APIs for obtaining the executor list
```
The development procedure is as follows:
1. Develop the pin_auth driver based on the HDF. The **Bind()**, **Init()**, **Release()**, and **Dispatch()** functions are used. For details about the code, see [pin_auth_interface_driver.cpp](https://gitee.com/openharmony/drivers_peripheral/blob/master/pin_auth/hdi_service/src/pin_auth_interface_driver.cpp).
```c++
// Create the PinAuthInterfaceService object by using the custom HdfPinAuthInterfaceHost object, which consists of the IoService object and HDI service.
structHdfPinAuthInterfaceHost{
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.
HDF_INIT(g_pinauthinterfaceDriverEntry);
```
1. Obtain the executor list. For details about the code, see [pin_auth_interface_service.cpp](https://gitee.com/openharmony/drivers_peripheral/blob/master/pin_auth/hdi_service/src/pin_auth_interface_service.cpp).
1. Implement each function of the executor. For details about the code, see [executor_impl.cpp](https://gitee.com/openharmony/drivers_peripheral/blob/master/pin_auth/hdi_service/src/executor_impl.cpp).
// After the executor is successfully registered, obtain the public key and template ID list from UserIAM and save the public key obtained. The executor compares its template ID list with the template ID list obtained and updates its template ID list.
