一、整体架构概述
软总线认证模块是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
- 协商/设备ID同步超时 →
9.3 并发认证控制
AddConcurrentAuthRequest()- 添加并发认证请求- 同一UDID的多个认证请求会被队列管理
十、总结
软总线认证模块采用分层架构设计：
| 层级 | 组件 | 职责 |
|---|---|---|
| 管理层 | AuthManager | 维护已认证设备的会话和状态 |
| 会话层 | AuthSessionFsm | 管理认证流程的4状态状态机 |
| 协议层 | HiChain | PAKE协议实现安全密钥协商 |
| 连接层 | AuthConnection | 底层连接和数据传输 |
| Meta层 | AuthMetaManager | 元认证和PTK管理 |
该设计实现了：
- 多链路统一认证：支持WiFi/BLE/P2P等多种链路
- 快速认证 ：通过
normalizedKey跳过PAKE协商 - 安全可靠：基于PAKE协议族，提供身份认证和密钥协商
- 高可用：支持并发认证请求和超时重试机制