README.md
1# Authentication Executor Management (auth_executor_mgr)
2
3
4
5## Introduction
6
7As a basic component of the User Identity & Access Management (IAM) subsystem, Authentication Executor Management (auth_executor_mgr) manages and schedules authentication resources in the system. Currently, password authentication and facial authentication are supported.
8
9The user authentication unit on the device is called authentication executor.
10
11The auth_executor_mgr module provides a set of resource management APIs. After implementing these APIs, the authentication executor can connect to auth_executor_mgr to provide authentication capabilities for the system.
12
13**Figure 1** auth_executor_mgr architecture
14
15<img src="figures/auth_executor_mgr_architecture.png" alt="auth_executor_mgr_architecture.png" style="zoom:80%;" />
16
17
18
19The OpenHarmony framework implements the auth_executor_mgr service and has encapsulated the collaborative scheduling and resource management APIs. Device vendors need to adapt some functions of the auth_executor_mgr component to meet higher security requirements. The APIs that need to be adapted by device vendors are defined in the IAM common HDI.
20
21## Directory Structure
22
23```undefined
24//base/user_iam/auth_executor_mgr
25├── common # Directory for storing the IAM common HDI
26├── frameworks # Framework code
27├── interfaces # Directory for storing external interfaces
28│ └── innerkits # Header files exposed to the internal subsystem
29├── sa_profile # Profile of the Service ability
30├── services # Implementation of the Service ability
31├── test # Directory for storing test code
32├── utils # Directory for storing utility code
33├── auth_executor_mgr.gni # Build configuration
34└── bundle.json # Component description file
35```
36
37
38## Usage
39
40### Available APIs
41
42**Table 1** APIs for managing authentication resources
43
44| API | Description |
45| ------ | -------------------------------- |
46| uint64_t Register(std::shared_ptr<AuthExecutor> executorInfo, std::shared_ptr<ExecutorCallback> callback); | Registers an authentication executor to transfer basic authentication information.|
47| void QueryStatus(AuthExecutor &executorInfo, std::shared_ptr<QueryCallback> callback); | Obtains the authentication executor status (whether the authentication executor has been registered).|
48
49**Table 2** APIs for executing authentication
50
51| API| Description |
52| ------ | -------------------------------- |
53| virtual void OnMessengerReady(const sptr<IExecutorMessenger> &messenger); | Notifies the authentication executor that the messenger is available and transfers the messenger for subsequent communication with the executor.|
54| virtual int32_t OnBeginExecute(uint64_t scheduleId, std::vector<uint8_t> &publicKey, std::shared_ptr<AuthAttributes> commandAttrs); | Instructs the authentication executor to perform authentication-related operations. The operation attributes are passed in by **commandAttrs**.|
55| virtual int32_t OnEndExecute(uint64_t scheduleId, std::shared_ptr<AuthAttributes> consumerAttr); | Instructs the authentication executor to complete this operation.|
56| virtual int32_t OnSetProperty(std::shared_ptr<AuthAttributes> properties); | Sets property information.|
57| virtual int32_t OnGetProperty(std::shared_ptr<AuthAttributes> conditions, std::shared_ptr<AuthAttributes> values); | Obtains property information.|
58
59**Table 3** APIs for managing the messenger
60
61| API | Description |
62| ------------------------------------------------------------ | ------------------------------------------------------------ |
63| virtual int32_t SendData(uint64_t scheduleId, uint64_t transNum, int32_t srcType, int32_t dstType, std::shared_ptr<AuthMessage> msg) override; | Sends a message from the authentication executor to the auth_executor_mgr. The message content is specified by the authentication executor, for example, a message indicating dark light during facial authentication.|
64| virtual int32_t Finish(uint64_t scheduleId, int32_t srcType, int32_t resultCode, std::shared_ptr<AuthAttributes> finalResult) override; | Sends a message from the authentication executor to the auth_executor_mgr to complete this operation. The message contains the result of the operation.|
65
66
67
68### Usage Guidelines
69
70- The auth_executor_mgr Service ability provides interconnection APIs for the authentication executors. The authentication executors call the related API to register with the auth_executor_mgr.
71- The APIs defined in the ```common\interface\coauth_interface.h``` header file must be implemented in a TEE. The authentication executor information cannot be tampered with, and the result returned by the authentication executor must be verified in the TEE.
72
73## Repositories Involved
74
75**[useriam_auth_executor_mgr](https://gitee.com/openharmony-sig/useriam_coauth)**
76
77[useriam_user_idm](https://gitee.com/openharmony-sig/useriam_useridm)
78
79[useriam_user_auth](https://gitee.com/openharmony-sig/useriam_userauth)
80
81[useriam_pin_auth](https://gitee.com/openharmony-sig/useriam_pinauth)
82
83[useriam_faceauth](https://gitee.com/openharmony/useriam_faceauth)
84
README_ZH.md
1# 认证执行器管理
2
3- [简介](#简介)
4- [目录](#目录)
5- [说明](#说明)
6 - [接口说明](#接口说明)
7 - [使用说明](#使用说明)
8- [相关仓](#相关仓)
9
10
11## 简介
12
13**认证执行器管理**（auth_executor_mgr）是用户IAM子系统的基础部件之一，提供系统内认证相关资源的统一管理和协同调度能力，当前支持口令认证和人脸认证的对接。
14
15我们将设备上的一个用户身份认证单元，称为**认证执行器**。
16
17认证执行器管理定义了一套**资源管理**接口，新增的认证执行器在实现了认证资源管理定义的接口后，可以对接到认证执行器管理模块，从而为系统提供相关身份认证能力。
18
19**图1** 认证执行器管理架构图
20
21<img src="figures/认证执行器管理架构图.png" alt="认证执行器管理架构图" style="zoom:80%;" />
22
23
24
25如图所示，OpenHarmony框架已经实现了认证执行器管理系统服务，并对上封装了协同调度和资源管理的接口，认证执行器管理部件内部分功能需要厂商适配来达到更高的安全性要求。需要南向厂商适配的接口，在用户IAM Common HDI中有定义。
26
27## 目录
28
29```undefined
30//base/user_iam/auth_executor_mgr
31├── common # 用户IAM子系统commonHDI存放目录
32├── frameworks # 框架代码
33├── interfaces # 对外接口存放目录
34│ └── innerkits # 对内部子系统暴露的头文件，供系统服务使用
35├── sa_profile # Service Ability 配置文件
36├── services # Service Ability 服务实现
37├── test # 测试代码存入目录
38├── utils # 工具代码存放目录
39├── auth_executor_mgr.gni # 构建配置
40└── bundle.json # 组件描述文件
41```
42
43
44## 说明
45
46### 接口说明
47
48**表1** 资源管理接口
49
50| 接口名 | 描述 |
51| ------ | -------------------------------- |
52| uint64_t Register(std::shared_ptr<AuthExecutor> executorInfo, std::shared_ptr<ExecutorCallback> callback); | 注册接口，执行器传入基本信息和实现的回调函数 |
53| void QueryStatus(AuthExecutor &executorInfo, std::shared_ptr<QueryCallback> callback); | 状态查询接口，查询当前执行器是否已经注册 |
54
55**表2** 执行器需要实现的回调接口
56
57| 接口名 | 描述 |
58| ------ | -------------------------------- |
59| virtual void OnMessengerReady(const sptr<IExecutorMessenger> &messenger); | 通知执行器信使可用，传入信使（用于后续与执行器通信） |
60| virtual int32_t OnBeginExecute(uint64_t scheduleId, std::vector<uint8_t> &publicKey, std::shared_ptr<AuthAttributes> commandAttrs); | 通知执行器开始执行认证相关操作，commandAttrs中传入本次操作的属性 |
61| virtual int32_t OnEndExecute(uint64_t scheduleId, std::shared_ptr<AuthAttributes> consumerAttr); | 通知执行器结束本次操作 |
62| virtual int32_t OnSetProperty(std::shared_ptr<AuthAttributes> properties); | 设置属性信息 |
63| virtual int32_t OnGetProperty(std::shared_ptr<AuthAttributes> conditions, std::shared_ptr<AuthAttributes> values); | 获取属性信息 |
64
65**表3** 信使函数
66
67| 接口名 | 描述 |
68| ------------------------------------------------------------ | ------------------------------------------------------------ |
69| virtual int32_t SendData(uint64_t scheduleId, uint64_t transNum, int32_t srcType, int32_t dstType, std::shared_ptr<AuthMessage> msg) override; | 发送消息，消息源为执行器，目的端为认证执行器管理，消息内容由执行器指定，比如返回人脸认证过程中的提示信息（光线过暗） |
70| virtual int32_t Finish(uint64_t scheduleId, int32_t srcType, int32_t resultCode, std::shared_ptr<AuthAttributes> finalResult) override; | 操作结束，消息源为执行器，目的端为认证执行器管理，消息内容为本次操作的最终结果 |
71
72
73
74### 使用说明
75
76- 认证执行器管理SA提供执行器对接接口，各身份认证执行器调用资源管理接口完成认证执行器的注册。
77- 需在可信执行环境内实现头文件```common\interface\coauth_interface.h``` 中定义的接口，保证认证执行器信息不可篡改，并在可信执行环境内校验认证执行器返回的结果。
78
79## 相关仓
80
81**[useriam_auth_executor_mgr](https://gitee.com/openharmony/useriam_auth_executor_mgr)**
82
83[useriam_user_idm](https://gitee.com/openharmony/useriam_user_idm)
84
85[useriam_user_auth](https://gitee.com/openharmony/useriam_user_auth)
86
87[useriam_pin_auth](https://gitee.com/openharmony/useriam_pin_auth)
88
89[useriam_faceauth](https://gitee.com/openharmony/useriam_faceauth)
