security_device_auth/README.md

deviceauth

• Introduction

• Directory Structure

• Usage

  • Available APIs

• Repositories Involved

Introduction

The device authentication module belongs to the security subsystem of OpenHarmony. It manages the entire lifecycle of trust relationships between devices, including establishment, maintenance, use, and cancellation, and implements authentication and secure session key exchange between trusted devices. It provides basic capabilities for trusted interconnections between devices that run OpenHarmony.

The device authentication module provides the following capabilities:

• Device trust relationship management: manages the establishment, maintenance, and cancellation of trust relationships between devices in a unified manner; allows the isolation and controllable sharing of trust relationships created by different services.
• Device trust relationship authentication: authenticates trust relationships between devices, allows trusted devices to exchange secure session keys with each other, and sets up connections between trusted devices through the DSoftBus.

The device authentication module consists of three submodules: device group management, device group authentication, and account-irrelevant P2P device authentication. The following figure shows the logical architecture of the device authentication module.

Figure 1 Architecture of the device authentication module

In the architecture:

• Device group management: allows you to manage the trust relationships between the local device and other devices created by different services in a unified manner, create trust relationships between devices using the provided APIs, create an account-irrelevant device group, add trusted devices to the group, and create a trust relationship between isolated devices.
• Device group authentication: allows devices to authenticate the trust relationships that have been established between them and exchange session keys.
• Account-irrelevant P2P device authentication: allows two devices to establish a trust relationship based on a shared secret, and exchange a session key for secure communication based on the trusted relationship.

Directory Structure

/base/security/device_auth
├── frameworks                   # Device authentication framework code
├── hals                         # HAL code for the tool library
│   ├── inc                      # Tool library header files
│   └── src                      # Tool library source files
├── interfaces                   # APIs exposed externally
└── services                     # Device authentication services
    ├── common                   # Common code
    ├── group_auth               # Device group authentication
    ├── group_manager            # Device group management
    ├── module                   # Authenticator module (including the account-irrelevant P2P device authenticator)
    └── session                  # Scheduling and session management module

Usage

Available APIs

The device group management sub-module abstracts trust relationships established by different services between devices into trust groups and provides unified APIs for creating, deleting, and querying groups. The device group authentication sub-module provides trusted device authentication and end-to-end session key exchange based on the trust groups.

Table 1 APIs in DeviceGroupManager

API	Description
const DeviceGroupManager *GetGmInstance()	Obtains a DeviceGroupManager instance.
int32_t RegCallback(const char *appId, const DeviceAuthCallback *callback)	Registers a callback.
int32_t CreateGroup(int64_t requestId, const char *appId, const char *createParams)	Creates a group of trusted devices.
int32_t DeleteGroup(int64_t requestId, const char *appId, const char *disbandParams)	Deletes a group of trusted devices.
int32_t AddMemberToGroup(int64_t requestId, const char *appId, const char *addParams)	Adds a member to a specified group.
int32_t DeleteMemberFromGroup(int64_t requestId, const char *appId, const char *deleteParams);	Deletes a member from a specified group.
int32_t ProcessData(int64_t requestId, const uint8_t *data, uint32_t dataLen)	Processes data that is bound or unbound.
int32_t GetGroupInfo(const char *appId, const char *queryParams, char **returnGroupVec, uint32_t *groupNum)	Obtains information about a trusted group of devices.

Table 2 APIs in GroupAuthManager

API	Description
const GroupAuthManager *GetGaInstance()	Obtains a GroupAuthManager instance.
int32_t AuthDevice(int64_t authReqId, const char *authParams, const DeviceAuthCallback *gaCallback)	Authenticates a peer device.
int32_t ProcessData(int64_t authReqId, const uint8_t *data, uint32_t dataLen, const DeviceAuthCallback *gaCallback)	Processes authentication data.

Repositories Involved

Security subsystem

security_device_auth