当前位置：首页 > news >正文

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

news 2026/8/15 22:36:18

Wintun API 模块深度解析（文档二）：适配器生命周期与驱动管理

一、概述

本文档深入分析api模块中的适配器管理和驱动安装逻辑，主要涉及文件：

adapter.c/adapter.h
adapter_win7.h
driver.c/driver.h
registry.c/registry.h（辅助读取注册表）
resource.c/resource.h（提取嵌入式文件）

适配器管理是 Wintun 最核心的功能之一，涵盖了从创建、打开、关闭、删除到孤儿设备清理的全过程。驱动安装则负责在首次使用或版本更新时，将 Wintun 内核驱动（wintun.sys）和配套 INF/CAT 文件部署到系统。

二、驱动安装与版本管理（`driver.c`）

2.1 驱动版本检测

WintunGetRunningDriverVersion：通过NtQuerySystemInformation枚举已加载的内核模块，查找名为wintun.sys的驱动，然后读取其文件版本（通过GetFileVersionInfo）。若未加载，返回 0 并设置ERROR_FILE_NOT_FOUND。
内部辅助函数MaybeGetRunningDriverVersion(ReturnOneIfRunningInsteadOfVersion)支持仅检测是否存在（返回 1），用于等待驱动卸载。

2.2 驱动安装流程（`DriverInstall`）

此函数在WintunCreateAdapter中被调用（首次创建适配器时）。流程如下：

获取互斥锁：通过NamespaceTakeDriverInstallationMutex()确保同一时刻只有一个进程执行安装，避免竞争。
创建设备信息：使用SetupDiCreateDeviceInfoListExW创建网络设备类的一个临时设备信息元素，设置硬件 ID 为Wintun。
枚举已安装的兼容驱动：通过SetupDiBuildDriverInfoList获取系统中所有匹配Wintun硬件 ID 的驱动。
版本比较：遍历每个驱动信息，与 Wintun 内置驱动版本（从 INF 提取的WINTUN_INF_VERSION和WINTUN_INF_FILETIME）比较。如果现有驱动更新，则直接使用；如果内置驱动更新，则：
- 禁用所有使用当前驱动创建的 Wintun 适配器（调用DisableAllOurAdapters），等待驱动卸载（EnsureWintunUnloaded）。
- 调用SetupUninstallOEMInfW卸载旧驱动（SUOI_FORCEDELETE强制删除）。
- 继续寻找下一个驱动。
若没有找到可用驱动，则执行全新安装：
- 使用ResourceCreateTemporaryDirectory在%WINDIR%\Temp下创建随机临时目录。
- 根据本机架构（NativeMachine），从 DLL 资源中提取对应的wintun.sys、wintun.cat、wintun.inf到临时目录。
- 调用SetupCopyOEMInfW将 INF 复制到系统驱动存储（%SystemRoot%\INF），完成安装。
- 删除临时文件并移除目录。
保存上下文：将之前禁用的适配器列表通过输出参数DevInfoExistingAdaptersForCleanup和ExistingAdaptersForCleanup返回，由调用方在适配器创建完成后重新启用它们（通过DriverInstallDeferredCleanup）。

2.3 驱动卸载（`WintunDeleteDriver`）

首先调用AdapterCleanupOrphanedDevices清理所有孤儿适配器（无所有者进程）。
再次枚举匹配Wintun硬件 ID 的驱动，对每个驱动调用SetupUninstallOEMInfW移除。
此操作需获取驱动安装互斥锁，且仅在无适配器使用时成功。

2.4 版本比较逻辑

IsNewer函数通过比较FILETIME和 64 位版本号（高 16 位为主版本，其次为次版本，其次为构建号，低 16 位为修订）决定新旧。优先比较日期，再比较版本号。

三、适配器创建（`WintunCreateAdapter`）

这是最复杂的函数，需要处理 Windows 7/8/10 的不同 API，并支持 WOW64 代理。

3.1 前期准备

获取设备安装互斥锁（NamespaceTakeDeviceInstallationMutex）。
调用DriverInstall确保驱动已安装。
分配并初始化WINTUN_ADAPTER结构。

3.2 Windows 8+ 的软件设备创建路径

步骤：

生成实例 ID：若调用方提供了RequestedGUID，则直接使用；否则调用CoCreateGuid生成随机 GUID。将 GUID 转换为字符串作为设备实例 ID。
创建存根设备（Stub）：在 Windows 10 上，先通过SwDeviceCreate创建一个临时的存根设备，仅设置硬件 ID 为空字符串，并在其软件注册表项中写入SuggestedInstanceId（用于影响 NLA GUID）。然后立即关闭该存根。
- 此步骤的目的是为系统网络位置感知（NLA）提供确定的 GUID，避免每次创建新适配器都生成新的 NLA 条目。
创建主设备：再次调用SwDeviceCreate，传入实际的硬件 ID（WINTUN_HWID）和设备属性：
- DEVPKEY_Wintun_Name：用户指定的适配器名称（如 “Demo”）。
- DEVPKEY_Device_FriendlyName：隧道类型名称 + " Tunnel"。
- DEVPKEY_Device_DeviceDesc：同上。
- 设置标志SWDeviceCapabilitiesSilentInstall（静默安装）和SWDeviceCapabilitiesDriverRequired（需要驱动）。
等待设备创建完成：通过回调DeviceCreateCallback设置事件，然后等待。
等待接口可用：调用WaitForInterface，使用DevCreateObjectQuery查询设备接口（GUID_DEVINTERFACE_NET）是否已启用，超时 15 秒。这确保了驱动已正确加载并注册了设备接口。
打开设备信息：通过SetupDiOpenDeviceInfo打开该设备，然后调用PopulateAdapterData从注册表读取NetCfgInstanceId、NetLuidIndex、*IfType等关键信息。
设置网络连接名称：调用NciSetAdapterName（内部使用NciSetConnectionName）将网络连接显示名设置为用户指定的名称，若冲突则自动添加序号后缀。
Windows 7 特殊处理：若系统为 Windows 7，则路径不同（见下文）。

3.3 Windows 7 的专用创建路径

Windows 7 不支持SwDeviceCreate，因此 Wintun 使用传统的 Setup API 进行设备创建（参考adapter_win7.h中的CreateAdapterWin7函数）：

创建设备信息元素，设置硬件 ID 为Wintun。
构建兼容驱动列表，选中第一个匹配的驱动。
依次调用DIF_REGISTERDEVICE、DIF_REGISTER_COINSTALLERS、DIF_INSTALLINTERFACES、DIF_INSTALLDEVICE。
设置自定义属性DEVPKEY_Wintun_OwningProcess（包含进程 ID 和创建时间），用于孤儿设备清理。
等待设备接口可用（通过轮询检查注册表值和设备状态）。
返回设备实例 ID。

3.4 WOW64 代理调用

在 32 位进程运行于 64 位系统上时，直接调用 Setup API 会失败。因此，adapter.c中的AdapterRemoveInstance、AdapterEnableInstance、AdapterDisableInstance等函数会检查全局NativeMachine和IMAGE_FILE_PROCESS，若不同则通过rundll32.c中的辅助函数启动 64 位代理进程（setupapihost.dll）来执行操作。

代理调用的实现细节已在之前《setupapihost 深度解析》中详细说明，此处不再重复。

3.5 适配器打开（`WintunOpenAdapter`）

枚举所有网络设备，过滤枚举器为SWD\Wintun（Win8+）或ROOT\Wintun（Win7），查找DEVPKEY_Wintun_Name与给定名称匹配的设备。
获取设备实例 ID，打开设备信息，填充WINTUN_ADAPTER结构。
同样等待接口可用并填充数据。

3.6 适配器关闭（`WintunCloseAdapter`）

若适配器由CreateAdapter创建（具有SwDevice或通过 Windows 7 路径），则调用AdapterRemoveInstance删除设备。
否则只释放句柄，不删除（打开模式）。
释放内存后，触发异步孤儿设备清理（QueueUpOrphanedDeviceCleanupRoutine）。