README.md
1# PIN Authentication (pinauth)
2
3
4## Introduction
5
6The PIN authentication (pinauth) module supports the setting, deletion, and authentication of user PINs. Working with the User IAM subsystem framework, the pinauth module supports PIN change.
7
8pinauth is one of the basic user identity authentication executors of OpenHarmony. It registers PIN authentication resource information with the collaborative authentication framework based on the resource registration interface defined by collaborative authentication, and implements PIN setting, deletion, and authentication based on the scheduling of the collaborative authentication framework.
9
10**Figure 1** pinauth architecture
11
12<img src="figures/pinauth_architecture.png" alt="pinauth_architecture" style="zoom:80%;" />
13
14
15
16PINs are core assets in the system. The following security measures are taken in PIN authentication for security purposes:
17
18- The PIN input user interface (currently including the PIN setting and PIN authentication dialog boxes) is provided by system applications (<sup>NOTE 1</sup>). The dialog boxes involved in user settings are provided by the **Settings** application, and the PIN input dialog boxes involved in the screen unlock authentication are provided by the **Lock screen** application.
19- Password data transmission: The raw PIN data is not transmitted across devices. After a user PIN is entered in the PIN input dialog box, the raw PIN data entered is transmitted to the pinauth Service ability only after unidirectional processing in the input model management innerAPI.
20- Secure storage and comparison of PIN data: The pinauth HDI defines the adaptation interfaces for device vendors. Device vendors can implement secure PIN comparison and storage in a TEE. <sup>NOTE 2</sup>
21
22**NOTE 1**: To implement the PIN input dialog box, the application needs to register the PIN input dialog box with the pinauth Service ability through the input dialog box management API. The input box management API requires a high-level access permission and can be invoked only by system users.
23
24**NOTE 2**: The OpenHarmony framework provides pure software implementation of PIN authentication for developers to demonstrate the PIN authentication function. The pure software implementation does not include the secure storage capability.
25
26## Directory Structure
27
28```undefined
29//base/useriam/pin_auth
30├── frameworks # Framework code
31├── interfaces # APIs exposed externally
32│ └── inner_api # Header file exposed to internal subsystems for system abilities
33├── sa_profile # Service ability profile (configuration)
34├── services # Implementation fo the Service ability
35├── unittest # Directory for storing test code
36├── bundle.json # Component description file
37└── pinauth.gni # Build configuration
38```
39
40
41## Usage
42
43### Available APIs
44
45**Table 1** APIs for managing input dialog boxes
46
47| API | Description |
48| ------ | -------------------------------- |
49| function registerInputer(inputer:IInputer) : boolean; | Registers the **inputer** callback with the pinauth Service ability. |
50| function unregisterInputer():void; | Unregisters the **inputer** callback from the pinauth Service ability.|
51
52**Table 2** APIs for transferring data
53
54| API| Description |
55| ------ | -------------------------------- |
56| onGetData: (callback:IInputData)=>void | **inputer** callback invoked by the pinauth Service ability to obtain the PIN data. |
57| onSetData: (pinSubType:AuthSubType, data:Uint8Array)=>void | **inputerdata** callback invoked to transfer the PIN data from the PIN input dialog box to the pinauth Service ability. |
58
59### Usage Guidelines
60
61The interfaces defined in **driver\interface\pin_auth\IExecutor.idl** must be implemented in a secure environment (trusted execution environment or security chip) to ensure protection of the highest security level on user PIN information.
62
63## Repositories Involved
64
65[useriam_user_auth_framework](https://gitee.com/openharmony/useriam_user_auth_framework)
66
67[useriam_face_auth](https://gitee.com/openharmony/useriam_face_auth)
68
69**[useriam_pin_auth](https://gitee.com/openharmony/useriam_pin_auth)**
70
71[drivers_peripheral](https://gitee.com/openharmony/drivers_peripheral)
72
73[drivers_interface](https://gitee.com/openharmony/drivers_interface)
74
