security_device_auth/README_zh.md

设备互信认证

• 简介

• 目录

• 说明

  • 接口说明

• 相关仓

简介

在OpenHarmony中，设备互信认证模块作为安全子系统的子模块，负责设备间可信关系的建立、维护、使用、撤销等全生命周期的管理，实现可信设备间的互信认证和安全会话密钥协商，是搭载OpenHarmony的设备进行可信互联的基础平台能力。

设备互信认证模块当前提供如下功能：

• 设备互信关系管理功能：统一管理设备互信关系的建立、维护、撤销过程；支持各个业务创建的设备互信关系的隔离和可控共享。
• 设备互信关系认证功能：提供认证设备间互信关系、进行安全会话密钥协商的能力，支持分布式软总线实现互信设备间的组网。

为实现上述功能，设备互信认证模块当前包含设备群组管理、设备群组认证和帐号无关点对点认证三个子模块，其部署逻辑如下图：

图 1 子系统架构图

其中，

• 设备群组管理服务：统一管理不同业务建立的本设备与其他设备间的互信关系，并对外提供设备互信关系的创建入口 ，完成信任建立后创建帐号无关设备群组，并将信任对象设备添加进群组；OpenHarmony上各业务可独立创建相互隔离的设备间可信关系。
• 设备群组认证服务：支持已建立可信关系的设备间完成互信关系的认证及会话密钥的协商。
• 帐号无关点对点设备互信认证：提供设备间基于共享秘密建立一对一互信关系的功能，并支持基于这种互信关系的认证密钥协商。
• 认证协议库：统一封装不同类型的认证协议，支持多种轻量级以及标准认证协议实现。

共享秘密的使用要求和约束：

业务在设备间建立账号无关点对点信任关系时，需要使用带外共享的秘密信息，该秘密信息在共享方式、长度、复杂度以及时效性上均需符合安全要求。系统会对共享秘密的长度做约束，如不满足，则无法进行账号无关点对点信任关系的建立，规则如下：

协议	共享秘密（PIN码）长度
EC-SPEKE	>=6bit
DL-SPEKE	>=6bit
ISO	>=128bit

目录

/base/security/device_auth
├── default_config               # 编译配置文件
├── frameworks                   # 设备互信认证IPC代码
├── interfaces                   # 对外接口目录
├── test                         # 设备互信认证的接口测试用例
├── common_lib                   # C语言公共基础库
├── deps_adapter                 # 依赖组件适配器代码
│   ├── key_management_adapter   # 密钥及算法适配层
│   └── os_adapter               # 系统能力适配层
└── services                     # 设备互信认证服务层代码
    ├── frameworks               # 设备互信认证框架层代码
    ├── data_manager             # 设备互信群组信息管理模块
    ├── identity_manager         # 认证凭据管理模块
    ├── legacy
    │   ├── authenticators       # 认证执行模块
    │   ├── group_auth           # 设备群组认证服务
    │   ├── group_manager        # 设备群组管理服务
    ├── creds_manager            # 凭据管理模块
    ├── mk_agree                 # 设备级主密钥协商
    ├── cred_manager             # 账号凭据插件管理模块
    ├── key_agree_sdk            # 密钥协商sdk
    ├── privacy_enhancement      # 隐私增强模块
    ├── session_manager          # 会话管理模块
    └── protocol                 # 认证协议库

说明

接口说明

设备互信认证组件中，设备群组管理服务负责将不同业务建立的设备间可信关系抽象成一个个可信群组，对外提供统一的接口，包含群组创建、删除、查询等功能；设备群组认证服务基于已经建立过可信关系的设备群组，提供设备可信认证与端到端会话密钥协商功能；同时提供群组无关，基于认证凭据的设备互信认证能力。

表 1 设备群组管理服务提供的API接口(DeviceGroupManager)功能介绍

接口名	描述
const DeviceGroupManager *GetGmInstance()	获取设备群组管理的实例。
int32_t RegCallback(const char *appId, const DeviceAuthCallback *callback)	注册业务的监听回调。
int32_t CreateGroup(int32_t osAccountId, int64_t requestId, const char *appId, const char *createParams)	创建一个可信设备群组。
int32_t DeleteGroup(int32_t osAccountId, int64_t requestId, const char *appId, const char *disbandParams)	删除一个可信设备群组。
int32_t AddMemberToGroup(int32_t osAccountId, int64_t requestId, const char *appId, const char *addParams)	添加成员到指定群组ID的可信设备群组。
int32_t DeleteMemberFromGroup(int32_t osAccountId, int64_t requestId, const char *appId, const char *deleteParams);	从指定可信设备群组里删除可信成员。
int32_t ProcessData(int64_t requestId, const uint8_t *data, uint32_t dataLen)	处理绑定或者解绑的数据。
int32_t GetGroupInfo(int32_t osAccountId, const char *appId, const char *queryParams, char **returnGroupVec, uint32_t *groupNum)	查询可信设备群组信息。

表 2 设备群组认证模块提供的API接口(GroupAuthManager)功能介绍

接口名	描述
const GroupAuthManager *GetGaInstance()	获取设备群组认证的实例。
int32_t AuthDevice(int32_t osAccountId, int64_t authReqId, const char *authParams, const DeviceAuthCallback *gaCallback)	认证可信设备。
int32_t ProcessData(int64_t authReqId, const uint8_t *data, uint32_t dataLen, const DeviceAuthCallback *gaCallback)	处理认证的数据。

表 3 基于认证凭据的设备互信认证能力相关API接口功能介绍

接口名	描述
int32_t StartAuthDevice(int64_t requestId, const char* authParams, const DeviceAuthCallback* callbak)	指定认证凭据，触发设备互信认证。
int32_t ProcessAuthDevice(int64_t requestId, const char* authParams, const DeviceAuthCallback* callbak)	响应认证请求，处理认证数据。
int32_t CancelAuthRequest(int64_t requestId, const char* authParams)	取消认证请求。

相关仓

安全子系统

security_device_auth