1# PIN Authentication (pinauth) 2 3 4 5## Introduction 6 7The PIN authentication (pinauth) module allows users to set and delete their Personal Information Numbers (PINs) and supports authentication of these PINs. Working with the basic framework of the User IAM subsystem, the pinauth module supports PIN change. 8 9pinauth is one of the basic user identity authentication executors of OpenHarmony. It registers resource information related to PIN authentication to 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. 10 11**Figure 1** pinauth architecture 12 13<img src="figures/pinauth_architecture.png" alt="pinauth_architecture" style="zoom:80%;" /> 14 15 16 17PINs are core assets in the system. The following security measures are taken in PIN authentication for security purposes: 18 19- The PIN input user interface (currently including the PIN setting and PIN authentication dialog boxes) is provided by the system-level application (<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. 20- 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. 21- 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> 22 23Note 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. 24 25Note 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. 26 27## Directory Structure 28 29```undefined 30//base/user_iam/pin_auth 31├── frameworks # Framework code 32├── hdi # APIs defined by device vendors for adaptation 33├── interfaces # Directory for storing external interfaces 34│ └── innerkits # Header files exposed to the internal subsystems 35├── sa_profile # Profile of the Service ability 36├── services # Implementation of the Service ability 37├── unittest # Directory for storing test code 38├── bundle.json # Component description file 39└── pinauth.gni # Build configuration 40``` 41 42 43## Usage 44 45### Available APIs 46 47**Table 1** APIs for managing input dialog boxes 48 49| API | Description | 50| ------ | -------------------------------- | 51| function registerInputer(inputer:IInputer) : boolean; | Registers the **inputer** callback with the pinauth Service ability. | 52| function unregisterInputer():void; | Unregisters the **inputer** callback from the pinauth Service ability.| 53 54**Table 2** APIs for transferring data 55 56| API| Description | 57| ------ | -------------------------------- | 58| onGetData : (callback:IInputData)=>void | Obtains the PIN data.| 59| onSetData:(pinSubType:AuthSubType, data:Uint8Array)=>void | Transfers the PIN data from the PIN input dialog box to the pinauth Service ability.| 60 61### Usage Guidelines 62 63- The APIs defined in the header file ```hdi\main\inc\pin_auth.h``` must be implemented in a secure environment. The PIN related information must be protected with the highest security level (TEE or security chip). 64 65## Repositories Involved 66 67[useriam_auth_executor_mgr](https://gitee.com/openharmony-sig/useriam_coauth) 68 69[useriam_user_idm](https://gitee.com/openharmony-sig/useriam_useridm) 70 71[useriam_user_auth](https://gitee.com/openharmony-sig/useriam_userauth) 72 73**[useriam_pin_auth](https://gitee.com/openharmony-sig/useriam_pinauth)** 74 75[useriam_faceauth](https://gitee.com/openharmony/useriam_faceauth) 76