首页/资讯中心/详情

分布式软总线认证模块架构与实现分析

分布式软总线认证模块架构与实现分析
📅 发布时间：2026/7/21 23:05:44

一、整体架构概述

软总线认证模块是OpenHarmony分布式通信的核心安全组件，位于foundation/communication/dsoftbus/core/authentication/目录下。该模块基于HiChain安全认证框架，实现了设备间的双向身份认证和会话密钥协商。

二、认证管理器 (AuthManager)

2.1 核心数据结构

auth_manager.h:L18-L33

typedef struct { int64_t authId; // 认证唯一标识 bool isServer; // 角色标志(服务器/客户端) uint64_t connId[AUTH_LINK_TYPE_MAX]; // 各链路连接ID AuthConnInfo connInfo[AUTH_LINK_TYPE_MAX]; // 连接信息 int64_t lastAuthSeq[AUTH_LINK_TYPE_MAX]; // 最近认证序列 SessionKeyList sessionKeyList; // 会话密钥列表 char udid[UDID_BUF_LEN]; // 设备唯一标识 char uuid[UUID_BUF_LEN]; // UUID SoftBusVersion version; // 协议版本 bool hasAuthPassed[AUTH_LINK_TYPE_MAX]; // 各链路认证状态 } AuthManager;

2.2 关键管理接口

创建认证管理器-NewAuthManager()

  • 根据authSeq和会话信息创建新的AuthManager实例
  • 客户端加入g_authClientList，服务器加入g_authServerList
  • 初始化会话密钥列表

删除认证管理器-DelAuthManager()

  • 支持按链路类型删除(type参数)
  • 仅删除单个链路时保留其他链路连接
  • 全部链路都无连接时才完全释放资源

会话密钥管理：

  • AuthManagerSetSessionKey()- 设置会话密钥
  • AuthManagerGetSessionKey()- 获取会话密钥
  • RemoveAuthSessionKeyByIndex()- 按索引删除密钥

2.3 双链表组织结构

auth_manager.c:L45-L46

static ListNode g_authClientList = { &g_authClientList, &g_authClientList }; static ListNode g_authServerList = { &g_authServerList, &g_authServerList };

三、认证会话与状态机 (AuthSessionFsm)

3.1 状态机定义

auth_session_fsm.h:L24-L30

typedef enum { STATE_SYNC_NEGOTIATION = 0, // 协商阶段 STATE_SYNC_DEVICE_ID, // 设备ID同步 STATE_DEVICE_AUTH, // 设备认证(HiChain) STATE_SYNC_DEVICE_INFO, // 设备信息同步 STATE_NUM_MAX } AuthFsmStateIndex;

3.2 状态转换图

3.3 状态处理函数

auth_session_fsm.c:L75-L99

static FsmState g_states[STATE_NUM_MAX] = { [STATE_SYNC_NEGOTIATION] = { .enter = SyncNegotiationEnter, .process = SyncNegotiationStateProcess, .exit = NULL, }, [STATE_SYNC_DEVICE_ID] = { .enter = SyncDevIdStateEnter, .process = SyncDevIdStateProcess, .exit = NULL, }, [STATE_DEVICE_AUTH] = { .enter = DeviceAuthStateEnter, .process = DeviceAuthStateProcess, .exit = NULL, }, [STATE_SYNC_DEVICE_INFO] = { .enter = NULL, .process = SyncDevInfoStateProcess, .exit = NULL, }, };

3.4 消息类型定义

auth_session_fsm.c:L36-L51

typedef enum { FSM_MSG_RECV_DEVICE_ID, // 接收设备ID FSM_MSG_RECV_AUTH_DATA, // 接收认证数据 FSM_MSG_RECV_TEST_AUTH_DATA, // 接收测试数据 FSM_MSG_SAVE_SESSION_KEY, // 保存会话密钥 FSM_MSG_AUTH_ERROR, // 认证错误 FSM_MSG_RECV_DEVICE_INFO, // 接收设备信息 FSM_MSG_RECV_CLOSE_ACK, // 接收关闭确认 FSM_MSG_AUTH_FINISH, // 认证完成 FSM_MSG_AUTH_TIMEOUT, // 认证超时 FSM_MSG_DEVICE_NOT_TRUSTED, // 设备不可信 FSM_MSG_DEVICE_DISCONNECTED, // 设备断开 FSM_MSG_STOP_AUTH_FSM, // 停止认证 } StateMessageType;

3.5 认证会话信息结构

auth_session_fsm.h:L53-L82

typedef struct { uint32_t requestId; bool isServer; uint64_t connId; AuthConnInfo connInfo; char udid[UDID_BUF_LEN]; char uuid[UUID_BUF_LEN]; char udidHash[SHA_256_HEX_HASH_LEN]; SoftBusVersion version; bool isSupportFastAuth; // 支持快速认证 bool isNeedFastAuth; // 需要快速认证 NormalizedType normalizedType; // 标准化类型 SessionKey *normalizedKey; // 标准化密钥 int64_t normalizedIndex; // 标准化索引 AuthStartState localState; // 本地认证状态 AuthStartState peerState; // 对方认证状态 // ... } AuthSessionInfo;

四、设备认证 (AuthDevice)

4.1 设备认证核心功能

auth_device.h:L19-L32

int32_t AuthDevicePostTransData(AuthHandle authHandle, const AuthTransData *dataInfo); int32_t AuthDeviceEncrypt(AuthHandle *authHandle, const uint8_t *inData, uint32_t inLen, ...); int32_t AuthDeviceDecrypt(AuthHandle *authHandle, const uint8_t *inData, uint32_t inLen, ...); int32_t AuthDeviceGetConnInfo(AuthHandle authHandle, AuthConnInfo *connInfo); void AuthDeviceNotTrust(const char *udid); // 标记设备不可信 int32_t AuthDirectOnlineCreateAuthManager(int64_t authSeq, const AuthSessionInfo *info);

4.2 认证限制机制

auth_device.c:L22-L90

设备认证失败后会触发限制机制，防止频繁重试：

#define DELAY_AUTH_TIME (8 * 1000L) // 8秒延迟 void AuthAddNodeToLimitMap(const char *udid, int32_t reason) { // 当reason为以下情况时加入限制map： // - SOFTBUS_AUTH_HICHAIN_LOCAL_IDENTITY_NOT_EXIST // - SOFTBUS_AUTH_HICHAIN_GROUP_NOT_EXIST // - SOFTBUS_AUTH_HICHAIN_NO_CANDIDATE_GROUP } bool IsNeedAuthLimit(const char *udidHash) { // 检查限制map，如果在8秒内则延迟认证 }

五、HiChain安全认证

5.1 HiChain概述

HiChain是设备认证的核心安全协议栈，基于PAKE(Password-Authenticated Key Exchange)协议族实现，支持：

  • P2P认证：设备间直接认证
  • 账户认证：支持华为账号体系
  • Mesh认证：多设备组网认证

5.2 核心接口

auth_hichain.h:L20-L40

int32_t HichainStartAuth(int64_t authSeq, const char *udid, const char *uid, int32_t userId); int32_t HichainProcessData(int64_t authSeq, const uint8_t *data, uint32_t len); void HichainCancelRequest(int64_t authReqId);

5.3 PAKE协议实现

pake_server.h:L20-L80

struct pake_server { struct key_agreement_server server_info; uint32_t key_length; struct hc_pin pin; struct hc_salt salt; struct hc_auth_id self_id; struct hc_auth_id peer_id; struct esk self_esk; // 临时私钥 struct pake_session_key session_key; // 会话密钥 struct pake_hmac_key hmac_key; // HMAC密钥 struct hc_session_key service_key; // 服务密钥 // ... };

5.4 HiChain回调机制

auth_hichain.c:L55-L90

static bool OnTransmit(int64_t authSeq, const uint8_t *data, uint32_t len) { // 将数据通过AuthSessionPostAuthData发送到对端 } static void OnSessionKeyReturned(int64_t authSeq, const uint8_t *sessionKey, uint32_t sessionKeyLen) { // 密钥协商成功后，保存会话密钥 (void)AuthSessionSaveSessionKey(authSeq, sessionKey, sessionKeyLen); } static void OnFinish(int64_t authSeq, int operationCode, const char *returnData) { // 认证完成处理 (void)AuthSessionHandleAuthFinish(authSeq); }

5.5 错误码转换

auth_hichain.c:L110-L135

HiChain错误码转换为SoftBus错误码：

#define HICHAIN_DAS_ERRCODE_MIN 0xF0000001 #define HICHAIN_DAS_ERRCODE_MAX 0xF00010FF #define HICHAIN_COMMON_ERRCODE_MIN 0x0001 #define HICHAIN_COMMON_ERRCODE_MAX 0xFFFF void GetSoftbusHichainAuthErrorCode(uint32_t hichainErrCode, uint32_t *softbusErrCode) { // 根据错误码范围进行转换 }

六、认证连接 (AuthConnection)

6.1 连接管理结构

auth_connection.h:L15-L35

typedef struct { void (*onConnectResult)(uint32_t requestId, uint64_t connId, int32_t result, const AuthConnInfo *connInfo); void (*onDisconnected)(uint64_t connId, const AuthConnInfo *connInfo); void (*onDataReceived)(uint64_t connId, const AuthConnInfo *connInfo, bool fromServer, const AuthDataHead *head, const uint8_t *data); } AuthConnListener;

6.2 连接ID生成

auth_connection.c:L65-L75

uint64_t GenConnId(int32_t connType, int32_t id) { uint64_t connId = (uint64_t)connType; connId = (connId << INT32_BIT_NUM) & MASK_UINT64_H32; connId |= (((uint64_t)id) & MASK_UINT64_L32); return connId; }

6.3 支持的链路类型

auth_common.h:L18-L30

typedef enum { DATA_TYPE_AUTH = 0xFFFF0001, // 设备认证数据 DATA_TYPE_DEVICE_INFO = 0xFFFF0002, // 设备信息同步 DATA_TYPE_DEVICE_ID = 0xFFFF0003, // 设备ID同步 DATA_TYPE_CONNECTION = 0xFFFF0004, // 连接数据 DATA_TYPE_CLOSE_ACK = 0xFFFF0005, // 关闭确认 DATA_TYPE_META_NEGOTIATION = 0xFFFF0006, // Meta协商 DATA_TYPE_DECRYPT_FAIL = 0xFFFF0007, // 解密失败 DATA_TYPE_META_DEVICE_INFO_ACK = 0xFFFF0008, DATA_TYPE_CANCEL_AUTH = 0xFFFF0009, } AuthDataType;

6.4 数据收发流程

ConnectAuthDevice() // 建立认证连接 PostAuthData() // 发送认证数据 AuthConnListener // 回调通知连接结果和数据接收

七、Meta认证与PTK

7.1 Meta认证管理

auth_meta_manager.h:L18-L35

int32_t AuthMetaInit(const AuthTransCallback *callback); int32_t AuthMetaStartVerify(uint32_t connectionId, const AuthKeyInfo *authKeyInfo, uint32_t requestId, int32_t callingPid, const AuthVerifyCallback *callBack); void AuthMetaReleaseVerify(int64_t authId); int32_t AuthMetaEncrypt(int64_t authId, const uint8_t *inData, uint32_t inLen, ...); int32_t AuthMetaDecrypt(int64_t authId, const uint8_t *inData, uint32_t inLen, ...);

7.2 PTK处理流程

auth_meta_ptk_proc.h:L18-L30

int32_t AuthGetPtkSyncInfoByAuthId(int64_t authId, bool *syncDone, int32_t *reason); int32_t AuthAddPtkSyncInfoForPendingList(AuthHandle authHandle, const NodeInfo *nodeInfo); int32_t AuthDelPtkSyncInfoFromPendingList(int64_t authId); int32_t AuthWaitingRequestCallback(int64_t authId); int32_t UpdateAuthSyncPtkInfoStatus(int64_t authId); int64_t GetAuthIdFromAuthSyncPtkInfo(const char *uuid);

7.3 PTK同步状态

Meta认证中的PTK(Peer Transaction Key)同步机制：

八、认证流程时序图

九、关键安全特性

9.1 密钥长度与算法

  • PAKE密钥长度：16字节(128位) - auth_hichain.c:L28
  • 会话密钥长度：16字节 - pake_server.h:L26
  • 支持快速认证：通过normalizedKey实现无PAKE协商的快速认证

9.2 认证超时机制

  • 认证总超时：30秒 - auth_common.c:L52
  • 各状态超时处理：
    • 协商/设备ID同步超时 →SOFTBUS_AUTH_SYNC_DEVICEID_TIMEOUT
    • 设备认证超时 →SOFTBUS_AUTH_HICHAIN_TIMEOUT
    • 设备信息同步超时 →SOFTBUS_AUTH_SYNC_DEVICEINFO_TIMEOUT

9.3 并发认证控制

  • AddConcurrentAuthRequest()- 添加并发认证请求
  • 同一UDID的多个认证请求会被队列管理

十、总结

软总线认证模块采用分层架构设计：

层级组件职责
管理层AuthManager维护已认证设备的会话和状态
会话层AuthSessionFsm管理认证流程的4状态状态机
协议层HiChainPAKE协议实现安全密钥协商
连接层AuthConnection底层连接和数据传输
Meta层AuthMetaManager元认证和PTK管理

该设计实现了：

  1. 多链路统一认证：支持WiFi/BLE/P2P等多种链路
  2. 快速认证：通过normalizedKey跳过PAKE协商
  3. 安全可靠：基于PAKE协议族，提供身份认证和密钥协商
  4. 高可用：支持并发认证请求和超时重试机制