windows 驱动实例分析系列: wireguard-nt驱动分析-api篇(二)

WireGuard-NT API 模块分析 - 第二部分配置管理、网络接口与日志系统1. 配置管理配置管理是 WireGuard 控制平面的核心功能负责将用户配置接口密钥、对等点、允许 IP 等转换为驱动内部数据结构并支持从驱动查询当前配置。1.1 数据结构映射API 模块与内核驱动共享相同的数据结构布局但定义在独立的头文件中wireguard.h和../driver/ioctl.h。configuration.c使用static_assert在编译时确保两边的结构完全一致防止因对齐或填充差异导致的错误。关键结构体对比API 结构体 (wireguard.h)驱动结构体 (ioctl.h)大小检查WIREGUARD_INTERFACEWG_IOCTL_INTERFACE完全一致WIREGUARD_PEERWG_IOCTL_PEER完全一致WIREGUARD_ALLOWED_IPWG_IOCTL_ALLOWED_IP完全一致WIREGUARD_ADAPTER_STATEWG_IOCTL_ADAPTER_STATE完全一致这些静态断言确保了在 Windows 平台上无论编译选项如何结构体内存布局都相同从而安全地通过DeviceIoControl在用户态和内核态之间传递二进制数据。1.2 配置设置 (WireGuardSetConfiguration)函数BOOL WINAPIWireGuardSetConfiguration(WIREGUARD_ADAPTER*Adapter,constWIREGUARD_INTERFACE*Config,DWORD Bytes);内部流程通过AdapterOpenDeviceObject获取设备对象句柄调用DeviceIoControl控制码为WG_IOCTL_SETlpInBuffer为NULL输入缓冲区不使用lpOutBuffer指向Config长度为Bytes检查操作结果关闭句柄返回状态特点Config是一个可变长结构包含固定头部以及紧随其后的PeersCount个WIREGUARD_PEER结构每个WIREGUARD_PEER又包含AllowedIPsCount个WIREGUARD_ALLOWED_IP结构用户需要构造完整的扁平内存布局并通过Bytes指示总长度内核驱动解析该缓冲区执行原子配置更新标志位语义WIREGUARD_INTERFACE_FLAGWIREGUARD_INTERFACE_REPLACE_PEERS删除所有现有对等点然后添加新列表WIREGUARD_INTERFACE_HAS_PUBLIC_KEY/HAS_PRIVATE_KEY/HAS_LISTEN_PORT指示哪些字段有效WIREGUARD_PEER_FLAGWIREGUARD_PEER_REPLACE_ALLOWED_IPS对该对等点替换所有允许 IPWIREGUARD_PEER_REMOVE删除该对等点WIREGUARD_PEER_UPDATE_ONLY仅更新已存在的对等点不新增1.3 配置获取 (WireGuardGetConfiguration)函数BOOL WINAPIWireGuardGetConfiguration(WIREGUARD_ADAPTER*Adapter,WIREGUARD_INTERFACE*Config,DWORD*Bytes);流程打开设备对象句柄调用DeviceIoControl控制码WG_IOCTL_GETlpInBuffer为NULLlpOutBuffer指向Config输入*Bytes表示缓冲区大小返回时Bytes被更新为实际写入的字节数如果缓冲区不足返回FALSEGetLastError为ERROR_MORE_DATABytes包含所需大小注意调用者应先以较小的缓冲区尝试若返回ERROR_MORE_DATA则重新分配足够内存再调用。1.4 适配器状态管理设置状态 (WireGuardSetAdapterState)BOOL WINAPIWireGuardSetAdapterState(WIREGUARD_ADAPTER*Adapter,WIREGUARD_ADAPTER_STATE State)允许的状态WIREGUARD_ADAPTER_STATE_UP启用适配器创建 UDP 套接字开始加密通信WIREGUARD_ADAPTER_STATE_DOWN禁用适配器关闭套接字停止通信内部通过WG_IOCTL_SET_ADAPTER_STATE控制码传递状态值。获取状态 (WireGuardGetAdapterState)BOOL WINAPIWireGuardGetAdapterState(WIREGUARD_ADAPTER*Adapter,WIREGUARD_ADAPTER_STATE*State)传递WG_IOCTL_ADAPTER_STATE_QUERY作为输入返回当前状态。2. 网络接口操作2.1 LUID 获取 (WireGuardGetAdapterLUID)VOID WINAPIWireGuardGetAdapterLUID(WIREGUARD_ADAPTER*Adapter,NET_LUID*Luid)从适配器结构中提取LuidIndex和IfType组合成完整的NET_LUID。该 LUID 可用于后续的网络 API如ConvertInterfaceLuidToIndex、GetAdapterIndex等。2.2 设备对象句柄 (AdapterOpenDeviceObject)HANDLE WINAPIAdapterOpenDeviceObject(constWIREGUARD_ADAPTER*Adapter)使用CreateFileW打开Adapter-InterfaceFilename如\\.\GLOBALROOT\Device\WireGuard-0返回句柄用于DeviceIoControl通信。该函数是配置操作的基础。2.3 网络连接名称设置 (NciSetAdapterName)WireGuard 适配器在网络连接面板Network Connections中显示的名称需要与内核配置的名称一致。由于 Windows 的网络连接名称管理NCINetwork Connection Interface是半文档化的该函数实现了健壮的命名处理。名称冲突处理策略BOOLNciSetAdapterName(GUID*Guid,LPCWSTR Name)尝试直接调用NciSetConnectionName设置名称如果返回ERROR_DUP_NAME名称已存在a. 获取占用该名称的适配器的 GUIDConvertInterfaceAliasToGuidb. 尝试为该冲突适配器分配一个新名称在原名称后添加数字后缀c. 如果成功重命名冲突适配器则再次尝试设置当前适配器的请求名称如果仍冲突为当前适配器自动添加数字后缀如 “WireGuard Tunnel 1”最多尝试 1000 次避免死循环辅助函数RenameByNetGUID通过SetupDiSetDeviceProperty设置DEVPKEY_WireGuard_Name属性来重命名设备ConvertInterfaceAliasToGuid使用ConvertInterfaceAliasToLuidConvertInterfaceLuidToGuid转换别名到 GUID3. 日志系统3.1 日志架构日志系统由三部分组成用户态回调应用层通过WireGuardSetLogger注册回调函数API 模块的日志转发logger.c实现日志收集线程从驱动读取日志条目内核驱动的日志生成驱动内部产生带时间戳的日志消息通过控制设备传递3.2 日志回调注册 (WireGuardSetLogger)VOID WINAPIWireGuardSetLogger(WIREGUARD_LOGGER_CALLBACK NewLogger)全局变量Logger指向当前回调函数如果NewLogger为NULL使用默认的NopLogger空操作回调函数类型typedefVOID(CALLBACK*WIREGUARD_LOGGER_CALLBACK)(WIREGUARD_LOGGER_LEVEL Level,DWORD64 Timestamp,LPCWSTR Message);3.3 适配器日志控制 (WireGuardSetAdapterLogging)BOOL WINAPIWireGuardSetAdapterLogging(WIREGUARD_ADAPTER*Adapter,WIREGUARD_ADAPTER_LOG_STATE LogState)允许的状态WIREGUARD_ADAPTER_LOG_OFF停止日志收集关闭读取线程WIREGUARD_ADAPTER_LOG_ON启用日志消息不带前缀WIREGUARD_ADAPTER_LOG_ON_WITH_PREFIX启用日志每条消息前添加接口索引如 0: 内部实现如果当前状态与请求状态相同直接返回更新Adapter-LogState使用原子操作WriteULongNoFence关闭日志如果从开启变为关闭且存在日志线程调用CancelSynchronousIo取消阻塞的DeviceIoControl等待线程退出最多 100ms 超时循环取消关闭线程句柄开启日志如果从关闭变为开启且没有日志线程创建LogReaderThread线程传入适配器句柄3.4 日志读取线程 (LogReaderThread)该线程循环运行负责从驱动读取日志行并转发给用户回调。工作流程无限循环 1. 检查 LogState 是否为 OFF若是则退出 2. 调用 DeviceIoControl(WG_IOCTL_READ_LOG_LINE) - 阻塞等待直到有日志行或设备关闭 - 返回 WG_IOCTL_LOG_ENTRY 结构 3. 解析日志级别Entry.Msg[0] 为 1/2/3 4. 如果需要前缀获取 IfIndex若未获取通过 LUID 转换 5. 将 UTF-8 消息转换为宽字符MultiByteToWideChar 6. 调用 Logger 回调 7. 如果 DeviceIoControl 失败 - 若错误为 ERROR_OPERATION_ABORTED被取消等待 5 秒后重新打开 - 否则尝试最多 10 次重新打开设备句柄每秒一次 - 若仍失败设置 LogState OFF 并退出日志条目结构 (WG_IOCTL_LOG_ENTRY)typedefstruct_WG_IOCTL_LOG_ENTRY{DWORD64 Timestamp;// 100ns 间隔自 1601-01-01CHAR Msg[512];// 第一个字节为级别字符后续为 UTF-8 消息}WG_IOCTL_LOG_ENTRY;级别映射1→WIREGUARD_LOG_ERR2→WIREGUARD_LOG_WARN3→WIREGUARD_LOG_INFO3.5 日志辅助函数logger.h和logger.c提供了丰富的日志工具函数函数用途LoggerLog直接记录一条宽字符串日志LoggerLogV/LoggerLogFmt格式化日志记录LoggerError记录错误码和前缀转换 SetupAPI 错误码LoggerErrorV/LoggerErrorFmt格式化错误日志LoggerLastErrorV/LoggerLastErrorFmt自动获取GetLastError()并记录LOG/LOG_ERROR/LOG_LAST_ERROR宏简化调用特殊处理LoggerError会尝试将错误码作为 HRESULT 解析使用HRESULT_FROM_SETUPAPI获取系统消息日志消息会截断到 0x400 个宽字符溢出处添加水平省略号\u2026所有日志函数都保持GetLastError不变即记录日志不影响错误码3.6 内存分配器logger.h中定义了一套带日志的内存分配宏#defineAlloc(Size)LoggerAlloc(__L(__FUNCTION__),0,Size)#defineZalloc(Size)LoggerAlloc(__L(__FUNCTION__),HEAP_ZERO_MEMORY,Size)#defineFree(Ptr)HeapFree(ModuleHeap,0,Ptr)这些分配器在失败时会自动记录错误日志方便调试内存不足问题。所有 API 模块的内存分配都通过ModuleHeap进行进程私有堆便于隔离和泄漏检测。4. 与其他模块的交互4.1 与驱动交互所有配置操作最终通过DeviceIoControl与内核驱动通信。控制码定义在../driver/ioctl.h中控制码功能WG_IOCTL_SET设置完整配置WG_IOCTL_GET获取当前配置WG_IOCTL_SET_ADAPTER_STATE设置/查询适配器状态WG_IOCTL_READ_LOG_LINE读取日志行阻塞4.2 与 SetupAPI 交互设备创建通过SwDeviceCreateWindows 软件设备 API设备属性操作通过SetupDiSetDevicePropertyW/SetupDiGetDevicePropertyW设备枚举通过SetupDiGetClassDevsExW设备移除、启用/禁用通过SetupDiCallClassInstaller4.3 与 NCI 交互NciSetConnectionName和NciGetConnectionName通过nci.def定义的延迟导入函数调用系统nci.dllNetwork Connection Interface。该 DLL 是 Windows 未公开的组件用于管理网络连接文件夹中的连接名称和图标。5. 日志资源管理5.1 线程安全LogState使用无栅栏原子操作ReadULongNoFence/WriteULongNoFence更新因为线程间不需要严格的内存排序只需确保值的可见性日志回调可能被多个线程并发调用包括主线程和日志线程应用层回调需自行处理同步5.2 资源清理在WireGuardCloseAdapter中调用WireGuardSetAdapterLogging(Adapter, WIREGUARD_ADAPTER_LOG_OFF)停止日志线程线程关闭后会等待线程退出确保没有悬空句柄5.3 错误恢复如果设备被意外移除日志线程尝试重新打开设备句柄若 10 次重试失败自动关闭日志避免无限循环