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

一、整体架构概述软总线认证模块是OpenHarmony分布式通信的核心安全组件位于foundation/communication/dsoftbus/core/authentication/目录下。该模块基于HiChain安全认证框架实现了设备间的双向身份认证和会话密钥协商。二、认证管理器 (AuthManager)2.1 核心数据结构auth_manager.h:L18-L33typedef 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-L46static ListNode g_authClientList { g_authClientList, g_authClientList }; static ListNode g_authServerList { g_authServerList, g_authServerList };三、认证会话与状态机 (AuthSessionFsm)3.1 状态机定义auth_session_fsm.h:L24-L30typedef 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-L99static 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-L51typedef 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-L82typedef 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-L32int32_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-L40int32_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-L80struct 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-L90static 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-L135HiChain错误码转换为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-L35typedef 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-L75uint64_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-L30typedef 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认证与PTK7.1 Meta认证管理auth_meta_manager.h:L18-L35int32_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-L30int32_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_TIMEOUT9.3 并发认证控制AddConcurrentAuthRequest()- 添加并发认证请求同一UDID的多个认证请求会被队列管理十、总结软总线认证模块采用分层架构设计层级组件职责管理层AuthManager维护已认证设备的会话和状态会话层AuthSessionFsm管理认证流程的4状态状态机协议层HiChainPAKE协议实现安全密钥协商连接层AuthConnection底层连接和数据传输Meta层AuthMetaManager元认证和PTK管理该设计实现了多链路统一认证支持WiFi/BLE/P2P等多种链路快速认证通过normalizedKey跳过PAKE协商安全可靠基于PAKE协议族提供身份认证和密钥协商高可用支持并发认证请求和超时重试机制